配置小程序

pages.json  文件用来对 小程序项目 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生 tabbar 等。

它类似微信小程序中app.json的页面管理部分。注意定位权限申请等原属于app.json的内容，在我们小程序项目中是在 manifest.json 中配置。

{
    "pages": [
        {
            "path": "pages/index/index"
        }
    ],
    "globalStyle": {
        "navigationBarTextStyle": "black",
        "navigationBarBackgroundColor": "#F8F8F8"
    }
}

配置项列表

属性	类型	必填	描述
pages	Object	是	设置页面路径及窗口表现
globalStyle	Object	否	设置默认页面的窗口表现
easycom	Object	否	组件自动引入规则
tabBar	Object	否	设置底部 tab 的表现
ext	Object	否	设置额外扩展配置，如 PC 首页

globalStyle

用于设置应用的状态栏、导航条、标题、窗口背景色等。

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor	#F7F7F7	导航栏背景颜色（同状态栏背景色）
navigationBarTextStyle	String	white	导航栏标题颜色及状态栏前景颜色，仅支持 black/white
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持 default/custom。custom 即取消默认的原生导航栏
backgroundColor	HexColor	#ffffff	下拉/上拉显示出来的窗口的背景色
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark / light
enablePullDownRefresh	Boolean	false	是否开启下拉刷新，详见页面生命周期
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位只支持 px
backgroundColorTop	HexColor	#ffffff	顶部窗口的背景色（bounce 回弹区域） - ios
backgroundColorBottom	HexColor	#ffffff	底部窗口的背景色（bounce 回弹区域） - ios
titleImage	String		导航栏图片地址（替换当前文字标题）
transparentTitle	String	none	导航栏整体（前景、背景）透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明
pageOrientation	String	auto	横屏配置，屏幕旋转设置，仅支持 auto / portrait(竖屏) / landscape(横屏)
animationType	String	pop-in	窗口显示的动画效果
animationDuration	Number	300	窗口显示动画的持续时间，单位为 ms
rpxCalcMaxDeviceWidth	Number	960	rpx 计算所支持的最大设备宽度，单位 px
rpxCalcBaseDeviceWidth	Number	375	rpx 计算使用的基准设备宽度，设备实际宽度超出 rpx 计算所支持的最大设备宽度时将按基准宽度计算，单位 px
rpxCalcIncludeWidth	Number	750	rpx 计算特殊处理的值，始终按实际的设备宽度计算，单位 rpx

如：

{
    "globalStyle": {
        "navigationBarTextStyle": "black",
        "navigationBarTitleText": "演示",
        "navigationBarBackgroundColor": "#F8F8F8",
        "backgroundColor": "#F8F8F8",
        "pageOrientation": "portrait", //横屏配置，支持 auto / portrait / landscape
        "rpxCalcMaxDeviceWidth": 960,
        "rpxCalcBaseDeviceWidth": 375,
        "rpxCalcIncludeWidth": 750
    }
}

pages

通过 pages 节点配置应用由哪些页面组成，pages 节点接收一个数组，数组每个项都是一个对象，其属性值如下：

属性	类型	默认值	描述
path	String		配置页面路径
style	Object		配置页面窗口表现

Tips：

• pages 节点的第一项为应用入口页（即首页）
• 应用中新增/减少页面，都需要对 pages 数组进行修改
• 文件名不需要写后缀，框架会自动寻找路径下的页面资源

代码示例：

开发目录为：

┌─pages
│  ├─index
│  │  └─index.vue
│  └─login
│     └─login.vue
├─static
├─main.js
├─App.vue
├─manifest.json
└─pages.json

则需要在 pages.json 中填写

{
    "pages": [
        {
            "path": "pages/index/index",
            "style": { ... }
        }, {
            "path": "pages/login/login",
            "style": { ... }
        }
    ]
}

style

用于设置每个页面的状态栏、导航条、标题、窗口背景色等。

页面中配置项会覆盖 globalStyle 中相同的配置项

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor	#F8F8F8	导航栏背景颜色（同状态栏背景色）
navigationBarTextStyle	String	black	导航栏标题颜色及状态栏前景颜色，仅支持 black/white
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持 default/custom。custom 即取消默认的原生导航栏，
disableScroll	Boolean	false	设置为 true 则页面整体不能上下滚动（bounce 效果），只在页面配置中有效，在 globalStyle 中设置无效
backgroundColor	HexColor	#ffffff	iOS 回弹区域窗口的背景色
enablePullDownRefresh	Boolean	false	是否开启下拉刷新，页面生命周期。
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark/light
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位只支持 px，页面生命周期。
backgroundColorTop	HexColor	#ffffff	iOS 顶部窗口的背景色（bounce 回弹区域）
backgroundColorBottom	HexColor	#ffffff	iOS 底部窗口的背景色（bounce 回弹区域）
disableSwipeBack	Boolean	false	是否禁用滑动返回 (iOS
titleImage	String		导航栏图片地址（替换当前文字标题位置）
transparentTitle	String	none	导航栏透明设置。支持 none 不透明 / always 一直透明 / auto 滑动自适应 (注意导航栏不占位)

自定义导航栏

如何取消原生导航栏？或自定义导航

单独页面去除

{
    "path": "pages/index/index",
    "style": {
        "navigationStyle": "custom"
    }
}

整个 APP 去除

{
    "globalStyle": {
        "navigationStyle": "custom"
    }
}

当 navigationStyle 设为 custom 时，原生导航栏不显示，此时要注意几个问题：

小程序页面手机顶部状态栏区域会被页面内容覆盖。这是因为窗体是沉浸式的原因，即全屏可写内容。小程序提供了状态栏高度的 css 变量--status-bar-height， 如果需要把状态栏的位置从前景部分让出来，可写一个占位 view，高度设为 css 变量。

<template>
    <view>
        <view class="status_bar">
            <!-- 这里是状态栏 -->
        </view>
        <view> 状态栏下的文字 </view>
    </view>
</template>
<style>
.status_bar {
    height: var(--status-bar-height);
    width: 100%;
}
</style>

iOS 底部安全区

iPhone 一些机型中，页面底部是有安全区的， safe-area-inset-bottom，如果页面中底部元素是需要与底部安全区间隔开，可以参考如下：

// page 或 底部元素设置 CSS 样式
.xx-footer {
    padding-bottom: constant(safe-area-inset-bottom);
    padding-bottom: env(safe-area-inset-bottom);
}

// 或者. 在底部放置一个占位元素，样式名为 app-bottom-block
.app-bottom-block {
    height: constant(safe-area-inset-bottom);
    height: env(safe-area-inset-bottom);
}

easycom

传统 vue 组件，需要安装、引用、注册，三个步骤后才能使用组件。

easycom 将其精简为一步。 只要组件安装在项目的 components 目录下，并符合 components/组件名称/组件名称.vue 目录结构。就可以不用引用、注册，直接在页面中使用。

easycom是自动开启的，不需要手动开启，有需求时可以在pages.json的easycom节点进行个性化设置，如关闭自动扫描，或自定义扫描匹配组件的策略。

设置参数如下：

属性	类型	默认值	描述
autoscan	Boolean	true	是否开启自动扫描，开启后将会自动扫描符合components/组件名称/组件名称.vue目录结构的组件
custom	Object	-	以正则方式自定义组件匹配规则。如果autoscan不能满足需求，可以使用custom自定义匹配规则

自定义 easycom 配置的示例

如果需要匹配 node_modules 内的 vue 文件，需要使用packageName/path/to/vue-file-$1.vue形式的匹配规则，其中packageName为安装的包名，/path/to/vue-file-$1.vue为 vue 文件在包内的路径。

{
    "easycom": {
        "autoscan": true,
        "custom": {
            "^bz-(.*)": "@/components/bz-$1.vue", // 匹配components目录内的vue文件
            "^vue-file-(.*)": "packageName/path/to/vue-file-$1.vue" // 匹配node_modules内的vue文件
        }
    }
}

说明

• easycom方式引入的组件无需在页面内import，也不需要在components内声明，即可在任意页面使用
• easycom方式引入组件不是全局引入，而是局部引入。只有加载相应页面才会加载使用的组件
• 在组件名完全一致的情况下，easycom引入的优先级低于手动引入（区分连字符形式与驼峰形式）
• 考虑到编译速度，直接在pages.json内修改easycom不会触发重新编译，需要改动页面内容触发。
• nvue页面里引用.vue后缀的组件，会按照 nvue 方式使用原生渲染，其中不支持的 css 会被忽略掉。这种情况同样支持 easycom

tabBar

如果应用是一个多 tab 应用，可以通过 tabBar 配置项指定一级导航栏，以及 tab 切换时显示的对应页。

在 pages.json 中提供 tabBar 配置，不仅仅是为了方便快速开发导航，更重要的是在小程序端提升性能。底层原生引擎在启动时无需等待 js 引擎初始化，即可直接读取 pages.json 中配置的 tabBar 信息，渲染原生 tab。

Tips

• tabBar 中的 list 是一个数组，只能配置最少 2 个、最多 5 个 tab，tab 按数组的顺序排序。
• tabbar 切换第一次加载时可能渲染不及时，可以在每个 tabbar 页面的 onLoad 生命周期里先弹出一个等待
• tabbar 的页面展现过一次后就保留在内存中，再次切换 tabbar 页面，只会触发每个页面的 onShow，不会再触发 onLoad。

属性说明：

属性	类型	必填	默认值	描述
color	HexColor	是		tab 上的文字默认颜色
selectedColor	HexColor	是		tab 上的文字选中时的颜色
backgroundColor	HexColor	是		tab 的背景色
borderStyle	String	否	black	tabbar 上边框的颜色，可选值 black/white，也支持其他颜色值
blurEffect	String	否	none	iOS 高斯模糊效果，可选值 dark/extralight/light/none
list	Array	是		tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab
fontSize	String	否	10px	文字默认大小
iconWidth	String	否	24px	图标默认宽度（高度等比例缩放）
spacing	String	否	3px	图标和文字的间距
height	String	否	50px	tabBar 默认高度
midButton	Object	否		中间按钮 仅在 list 项为偶数时有效

其中 list 接收一个数组，数组中的每个项都是一个对象，其属性值如下：

属性	类型	必填	说明
pagePath	String	是	页面路径，必须在 pages 中先定义
text	String	是	tab 上按钮文字，在 App 和 H5 平台为非必填。例如中间可放一个没有文字的+号图标
iconPath	String	否	图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px，当 position 为 top 时，此参数无效，不支持网络图片，不支持字体图标
selectedIconPath	String	否	选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px ，当 position 为 top 时，此参数无效
visible	Boolean	否	该项是否显示，默认显示
iconfont	Object	否	字体图标，优先级高于 iconPath

midButton 属性说明

注意

• PC 场景（IDE 场景）暂不支持，安卓和 iOS 可用

属性	类型	必填	默认值	描述
width	String	否	80px	中间按钮的宽度，tabBar 其它项为减去此宽度后平分，默认值为与其它项平分宽度
height	String	否	50px	中间按钮的高度，可以大于 tabBar 高度，达到中间凸起的效果
text	String	否		中间按钮的文字
iconPath	String	否		中间按钮的图片路径
iconWidth	String	否	24px	图片宽度（高度等比例缩放）
backgroundImage	String	否		中间按钮的背景图片路径
iconfont	Object	否		字体图标，优先级高于 iconPath

midButton 没有 pagePath，需监听点击事件，自行处理点击后的行为逻辑。监听点击事件为调用 API：bz.onTabBarMidButtonTap

bz.onTabBarMidButtonTap(() => {
    bz.showModal({
        title: '触发中间按钮'
    })
})

iconfont 参数说明：

属性	类型	说明
text	String	字库 Unicode 码
selectedText	String	选中后字库 Unicode 码
fontSize	String	字体图标字号(px)
color	String	字体图标颜色
selectedColor	String	字体图标选中颜色

代码示例

{
    "tabBar": {
        "color": "#7A7E83",
        "selectedColor": "#3cc51f",
        "borderStyle": "black",
        "backgroundColor": "#ffffff",
        "list": [
            {
                "pagePath": "pages/component/index",
                "iconPath": "static/image/icon_component.png",
                "selectedIconPath": "static/image/icon_component_HL.png",
                "text": "组件"
            },
            {
                "pagePath": "pages/API/index",
                "iconPath": "static/image/icon_API.png",
                "selectedIconPath": "static/image/icon_API_HL.png",
                "text": "接口"
            }
        ]
    }
}

注意：

• tabbar 的 item 点击事件见页面生命周期的 onTabItemTap。

• 代码跳转到 tabbar 页面，api 只能使用 bz.switchTab，不能使用 bz.navigateTo、bz.redirectTo；使用 navigator 组件跳转时必须设置 open-type="switchTab"

ext

小程序的扩展配置字段，目前可用的是 defaultPages ，用于区分在 PC 端宽屏小程序的首页，详见 PC 小程序

defaultPages 参数说明

属性	类型	必填	描述
sidebarMode	string	否	小窗口模式默认展示页面
PCMode	string	否	大窗口模式默认展示页面（仅工作台打开时生效）

完整配置举例

以下是一个举例配置选项的  pages.json ：

{
    "pages": [
        {
            "path": "pages/component/index",
            "style": {
                "navigationBarTitleText": "组件"
            }
        },
        {
            "path": "pages/API/index",
            "style": {
                "navigationBarTitleText": "接口"
            }
        },
        {
            "path": "pages/component/view/index",
            "style": {
                "navigationBarTitleText": "view"
            }
        }
    ],
    "globalStyle": {
        "navigationBarTextStyle": "black",
        "navigationBarTitleText": "演示",
        "navigationBarBackgroundColor": "#F8F8F8",
        "backgroundColor": "#F8F8F8",
        "rpxCalcMaxDeviceWidth": 960,
        "rpxCalcBaseDeviceWidth": 375,
        "rpxCalcIncludeWidth": 750
    },
    "tabBar": {
        "color": "#7A7E83",
        "selectedColor": "#3cc51f",
        "borderStyle": "black",
        "backgroundColor": "#ffffff",
        "height": "50px",
        "fontSize": "10px",
        "iconWidth": "24px",
        "spacing": "3px",
        "iconfontSrc": "static/iconfont.ttf", // app tabbar 字体.ttf文件路径
        "list": [
            {
                "pagePath": "pages/component/index",
                "iconPath": "static/image/icon_component.png",
                "selectedIconPath": "static/image/icon_component_HL.png",
                "text": "组件",
                "iconfont": {
                    // 优先级高于 iconPath，该属性依赖 tabbar 根节点的 iconfontSrc
                    "text": "\ue102",
                    "selectedText": "\ue103",
                    "fontSize": "17px",
                    "color": "#000000",
                    "selectedColor": "#0000ff"
                }
            },
            {
                "pagePath": "pages/API/index",
                "iconPath": "static/image/icon_API.png",
                "selectedIconPath": "static/image/icon_API_HL.png",
                "text": "接口"
            }
        ],
        "midButton": {
            "width": "80px",
            "height": "50px",
            "text": "文字",
            "iconPath": "static/image/midButton_iconPath.png",
            "iconWidth": "24px",
            "backgroundImage": "static/image/midButton_backgroundImage.png"
        }
    },
    "easycom": {
        "autoscan": true, //是否自动扫描组件
        "custom": {
            //自定义扫描规则
            "^bz-(.*)": "@boss/kz-mp-ui/packages/bz-$1/bz-$1.vue"
        }
    }
}