uni-app官网:https://uniapp.dcloud.io/collocation/pages
pages.json
文件用来对 uni-app 进行全局配置,决定页面文件的路径、窗口样式、原生的导航栏、底部的原生tabbar 等。
它类似微信小程序中app.json
的页面管理部分。注意定位权限申请等原属于app.json
的内容,在uni-app中是在manifest中配置。
配置项列表
1、pages
uni-app
通过 pages 节点配置应用由哪些页面组成,pages 节点接收一个数组,数组每个项都是一个对象,其属性值如下:
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
path | String | 配置页面路径 | |
style | Object | 配置页面窗口表现,配置项参考下方 pageStyle |
Tips:
- pages节点的第一项为应用入口页(即首页)
- 应用中新增/减少页面,都需要对 pages 数组进行修改
- 文件名不需要写后缀,框架会自动寻找路径下的页面资源
启动模式配置,仅开发期间生效,用于模拟直达页面的场景,如:小程序转发后,用户点击所打开的页面。
属性说明:
属性 | 类型 | 是否必填 | 描述 |
---|---|---|---|
current | Number | 是 | 当前激活的模式,list节点的索引值 |
list | Array | 是 | 启动模式列表 |
list说明:
属性 | 类型 | 是否必填 | 描述 |
---|---|---|---|
name | String | 是 | 启动模式名称 |
path | String | 是 | 启动页面路径 |
query | String | 否 | 启动参数,可在页面的 onLoad 函数里获得 |
用于设置应用的状态栏、导航条、标题、窗口背景色等。
属性 | 类型 | 默认值 | 描述 | 平台差异说明 |
---|---|---|---|---|
navigationBarBackgroundColor | HexColor | #F7F7F7 | 导航栏背景颜色(同状态栏背景色) | APP与H5为#F7F7F7,小程序平台请参考相应小程序文档 |
navigationBarTextStyle | String | white | 导航栏标题颜色及状态栏前景颜色,仅支持 black/white | |
navigationBarTitleText | String | 导航栏标题文字内容 | ||
navigationStyle | String | default | 导航栏样式,仅支持 default/custom。custom即取消默认的原生导航栏,需看使用注意 | 微信小程序 7.0+、百度小程序、H5、App(2.0.3+) |
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 | 导航栏图片地址(替换当前文字标题),支付宝小程序内必须使用https的图片链接地址 | 支付宝小程序、H5、APP | |
transparentTitle | String | none | 导航栏整体(前景、背景)透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明 | 支付宝小程序、H5、APP |
titlePenetrate | String | NO | 导航栏点击穿透 | 支付宝小程序、H5 |
pageOrientation | String | portrait | 横屏配置,屏幕旋转设置,仅支持 auto / portrait / landscape 详见 响应显示区域变化 | App 2.4.7+、微信小程序 |
animationType | String | pop-in | 窗口显示的动画效果,详见:窗口动画 | App |
animationDuration | Number | 300 | 窗口显示动画的持续时间,单位为 ms | App |
app-plus | Object | 设置编译到 App 平台的特定样式,配置项参考下方 app-plus | App | |
h5 | Object | 设置编译到 H5 平台的特定样式,配置项参考下方 H5 | H5 | |
mp-alipay | Object | 设置编译到 mp-alipay 平台的特定样式,配置项参考下方 MP-ALIPAY | 支付宝小程序 | |
mp-weixin | Object | 设置编译到 mp-weixin 平台的特定样式 | 微信小程序 | |
mp-baidu | Object | 设置编译到 mp-baidu 平台的特定样式 | 百度小程序 | |
mp-toutiao | Object | 设置编译到 mp-toutiao 平台的特定样式 | 字节跳动小程序 | |
mp-qq | Object | 设置编译到 mp-qq 平台的特定样式 | QQ小程序 | |
usingComponents | Object | 引用小程序组件,参考 小程序组件 | ||
renderingMode | String | 同层渲染,webrtc(实时音视频) 无法正常时尝试配置 seperated 强制关掉同层 | 微信小程序 | |
leftWindow | Boolean | true | 当存在 leftWindow 时,默认是否显示 leftWindow | H5 |
topWindow | Boolean | true | 当存在 topWindow 时,默认是否显示 topWindow | H5 |
rightWindow | Boolean | true | 当存在 rightWindow 时,默认是否显示 rightWindow | H5 |
rpxCalcMaxDeviceWidth | Number | 960 | rpx 计算所支持的最大设备宽度,单位 px | App、H5(2.8.12+) |
rpxCalcBaseDeviceWidth | Number | 375 | rpx 计算使用的基准设备宽度,设备实际宽度超出 rpx 计算所支持的最大设备宽度时将按基准宽度计算,单位 px | App、H5(2.8.12+) |
rpxCalcIncludeWidth | Number | 750 | rpx 计算特殊处理的值,始终按实际的设备宽度计算,单位 rpx | App、H5(2.8.12+) |
maxWidth | Number | 1190 | 单位px,当浏览器可见区域宽度大于maxWidth时,两侧留白,当小于等于maxWidth时,页面铺满;不同页面支持配置不同的maxWidth;maxWidth = leftWindow(可选)+page(页面主体)+rightWindow(可选) | H5(2.9.9+) |
注意
- 支付宝小程序使用
titleImage
时必须使用https
的图片链接地址,需要真机调试才能看到效果,支付宝开发者工具内无效果 globalStyle
中设置的titleImage
也会覆盖掉pages
->style
内的设置文字标题- 使用
maxWidth
时,页面内fixed元素需要使用--window-left,--window-right来保证布局位置正确
4、tabBar
如果应用是一个多 tab 应用,可以通过 tabBar 配置项指定一级导航栏,以及 tab 切换时显示的对应页。
在 pages.json 中提供 tabBar 配置,不仅仅是为了方便快速开发导航,更重要的是在App和小程序端提升性能。在这两个平台,底层原生引擎在启动时无需等待js引擎初始化,即可直接读取 pages.json 中配置的 tabBar 信息,渲染原生tab。
Tips
- 当设置 position 为 top 时,将不会显示 icon
- tabBar 中的 list 是一个数组,只能配置最少2个、最多5个 tab,tab 按数组的顺序排序。
- tabbar 切换第一次加载时可能渲染不及时,可以在每个tabbar页面的onLoad生命周期里先弹出一个等待雪花(hello uni-app使用了此方式)
- tabbar 的页面展现过一次后就保留在内存中,再次切换 tabbar 页面,只会触发每个页面的onShow,不会再触发onLoad。
- 顶部的 tabbar 目前仅微信小程序上支持。需要用到顶部选项卡的话,建议不使用 tabbar 的顶部设置,而是自己做顶部选项卡,可参考 hello uni-app->模板->顶部选项卡。
属性说明:
属性 | 类型 | 必填 | 默认值 | 描述 | 平台差异说明 |
---|---|---|---|---|---|
color | HexColor | 是 | tab 上的文字默认颜色 | ||
selectedColor | HexColor | 是 | tab 上的文字选中时的颜色 | ||
backgroundColor | HexColor | 是 | tab 的背景色 | ||
borderStyle | String | 否 | black | tabbar 上边框的颜色,可选值 black/white | App 2.3.4+ 支持其他颜色值、H5 3.0.0+ |
blurEffect | String | 否 | none | iOS 高斯模糊效果,可选值 dark/extralight/light/none(参考:使用说明) | App 2.4.0+ 支持、H5 3.0.0+(只有最新版浏览器才支持) |
list | Array | 是 | tab 的列表,详见 list 属性说明,最少2个、最多5个 tab | ||
position | String | 否 | bottom | 可选值 bottom、top | top 值仅微信小程序支持 |
fontSize | String | 否 | 10px | 文字默认大小 | App 2.3.4+、H5 3.0.0+ |
iconWidth | String | 否 | 24px | 图标默认宽度(高度等比例缩放) | App 2.3.4+、H5 3.0.0+ |
spacing | String | 否 | 3px | 图标和文字的间距 | App 2.3.4+、H5 3.0.0+ |
height | String | 否 | 50px | tabBar 默认高度 | App 2.3.4+、H5 3.0.0+ |
midButton | Object | 否 | 中间按钮 仅在 list 项为偶数时有效 | App 2.3.4+、H5 3.0.0+ |
其中 list 接收一个数组,数组中的每个项都是一个对象,其属性值如下:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
pagePath | String | 是 | 页面路径,必须在 pages 中先定义 |
text | String | 是 | tab 上按钮文字,在 App 和 H5 平台为非必填。例如中间可放一个没有文字的+号图标 |
iconPath | String | 否 | 图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px,当 postion 为 top 时,此参数无效,不支持网络图片,不支持字体图标 |
selectedIconPath | String | 否 | 选中时的图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px ,当 postion 为 top 时,此参数无效 |
midButton 属性说明
属性 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
width | String | 否 | 80px | 中间按钮的宽度,tabBar 其它项为减去此宽度后平分,默认值为与其它项平分宽度 |
height | String | 否 | 50px | 中间按钮的高度,可以大于 tabBar 高度,达到中间凸起的效果 |
text | String | 否 | 中间按钮的文字 | |
iconPath | String | 否 | 中间按钮的图片路径 | |
iconWidth | String | 否 | 24px | 图片宽度(高度等比例缩放) |
backgroundImage | String | 否 | 中间按钮的背景图片路径 |
5、easycom
HBuilderX 2.5.5
起支持easycom
组件模式。
传统vue组件,需要安装、引用、注册,三个步骤后才能使用组件。easycom
将其精简为一步。 只要组件安装在项目的components目录下,并符合components/组件名称/组件名称.vue
目录结构。就可以不用引用、注册,直接在页面中使用。 如下:
<template>
<view class="container">
<uni-list>
<uni-list-item title="第一行"></uni-list-item>
<uni-list-item title="第二行"></uni-list-item>
</uni-list>
</view>
</template>
<script>
// 这里不用import引入,也不需要在components内注册uni-list组件。template里就可以直接用
export default {
data() {
return {
}
}
}
</script>
uni-app 2.9+ 新增 leftWindow, topWindow, rightWindow 配置。用于解决宽屏适配问题。
以现有的手机应用为mainWindow,在左、上、右,可以追加新的页面显示窗体。
整体的宽屏适配思路,参考单独的宽屏适配指南
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
path | String | 配置页面路径 | |
style | Object | 配置页面窗口表现,配置项参考下方 pageStyle | |
matchMedia | Object | 配置显示该窗口的规则,配置项参考下方 matchMedia |
注意
- 目前 style 节点仅支持配置 width,height 等 css 样式相关属性
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
minWidth | Number | 768 | 当设备可见区域宽度 >= minWidth 时,显示该 window |
通过matchMedia的调节,可以自适应在不同屏幕上显示指定的window。
{
"pages": [
{
"path": "pages/login/login",
"style": {
"topWindow": false // 当前页面不显示 topWindow
"leftWindow": false // 当前页面不显示 leftWindow
"rightWindow": false // 当前页面不显示 rightWindow
}
}
],
"topWindow": {
"path": "responsive/top-window.vue", // 指定 topWindow 页面文件
"style": {
"height": "44px"
}
},
"leftWindow": {
"path": "responsive/left-window.vue", // 指定 leftWindow 页面文件
"style": {
"width": "300px"
}
},
"rightWindow": {
"path": "responsive/right-window.vue", // 指定 rightWindow 页面文件
"style": {
"width": "300px" // 页面宽度
},
"matchMedia": {
"minWidth": 768 //生效条件,当窗口宽度大于768px时显示
}
}
}
具体写法如下:
{ "pages": [{ "path": "pages/component/index",//页面路径 "style": { "navigationBarTitleText": "组件" } }, { "path": "pages/API/index", "style": { "navigationBarTitleText": "接口" } }, { "path": "pages/component/view/index", "style": { "navigationBarTitleText": "view" } }], "condition": { //模式配置,仅开发期间生效 "current": 0, //当前激活的模式(list 的索引项) "list": [{ "name": "test", //模式名称 "path": "pages/component/view/index" //启动页面,必选 }] }, "globalStyle": { "navigationBarTextStyle": "black", "navigationBarTitleText": "演示", "navigationBarBackgroundColor": "#F8F8F8", "backgroundColor": "#F8F8F8", "usingComponents":{ "collapse-tree-item":"/components/collapse-tree-item" }, "renderingMode": "seperated", // 仅微信小程序,webrtc 无法正常时尝试强制关闭同层渲染 "pageOrientation": "portrait", //横屏配置,全局屏幕旋转设置(仅 APP/微信/QQ小程序),支持 auto / portrait / landscape "rpxCalcMaxDeviceWidth": 960, "rpxCalcBaseDeviceWidth": 375, "rpxCalcIncludeWidth": 750 }, "tabBar": { "color": "#7A7E83", "selectedColor": "#3cc51f", "borderStyle": "black", "backgroundColor": "#ffffff", "height": "50px", "fontSize": "10px", "iconWidth": "24px", "spacing": "3px", "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": "接口" }], "midButton": { "width": "80px", "height": "50px", "text": "文字", "iconPath": "static/image/midButton_iconPath.png", "iconWidth": "24px", "backgroundImage": "static/image/midButton_backgroundImage.png" } }, "easycom": { "autoscan": true, //是否自动扫描组件 "custom": {//自定义扫描规则 "^uni-(.*)": "@/components/uni-$1.vue" } }, "topWindow": { "path": "responsive/top-window.vue", "style": { "height": "44px" } }, "leftWindow": { "path": "responsive/left-window.vue", "style": { "width": "300px" } }, "rightWindow": { "path": "responsive/right-window.vue", "style": { "width": "300px" }, "matchMedia": { "minWidth": 768 } } }