小程序根目录下的 app.json 文件用来对小程序进行全局配置,决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。
以下是一个基本配置示例:
{
"themeLocation": "theme.json",
"pages": ["pages/page1/index", "pages/page2/index"],
"window": {
"navigationBarBackgroundColor": "#ffffff"
}
}
完整配置项如下:
属性 | 类型 | 必填 | 描述 | 基础库 |
---|---|---|---|---|
entryPagePath | string | 否 | 小程序默认启动页面 | |
pages | Array | 是 | 设置页面路径 | |
window | Object | 否 | 设置小程序窗口表现 | |
darkmode | boolean | 否 | 支持暗黑模式, 默认值: true | 2.14.0 |
themeLocation | string | 否 | 主题配置文件相对路径 | |
tabBar | Object | 否 | 设置底部 tabbar 的表现 | |
usingComponents | Object | 否 | 定义全局自定义组件 |
指定小程序的默认启动路径(首页),必须是 pages 中的其中一项目。如果不填,将默认为 pages 列表的第一项。不支持带页面路径参数。
用于指定小程序由哪些页面组成,每一项都对应一个页面的路径(不含文件后缀) 信息。框架会自动去加载同名的 .json
、.js
、.tyml
和 .tyss
等文件。未声明的页面文件不会打包到小程序应用当中。
未指定 entryPagePath
时,数组的第一项代表小程序的初始页面(首页)。
小程序中新增/减少页面,都需要对 pages
数组进行修改。
如开发目录为:
├── pages
│ ├──index
│ │ ├── index.json
│ │ ├── index.js
│ │ ├── index.tyml
│ │ └── index.tyss
│ └──logs
│ ├── logs.json
│ ├── logs.js
│ └── logs.tyml
├── app.json
├── app.js
└── app.tyss
app.json
中应当如下配置:
{
"pages": ["pages/index/index", "pages/logs/logs"]
}
配置中路径不需要添加
/
前缀,默认以当前配置文件(app.json)所在目录为基准。
用于设置小程序的状态栏、导航条、标题、窗口背景色。
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
backgroundColor | HexColor | #ffffff | 窗口的背景色 |
backgroundColorBottom | string | #ffffff | 底部窗口的背景色,仅 iOS 支持 |
backgroundColorTop | string | #ffffff | 顶部窗口的背景色,仅 iOS 支持 |
backgroundTextStyle | string | dark | 下拉 loading 的样式,仅支持 dark / light |
custom | Boolean | false | 自定义导航栏,只保留右上角胶囊按钮。 |
enablePullDownRefresh | boolean | false | 是否开启全局的下拉刷新。 |
navigationBarBackgroundColor | HexColor | #ffffff | 导航栏背景颜色,如 #000000 |
navigationBarTextStyle | string | black | 导航栏标题颜色,仅支持 black / white |
navigationBarTitleText | string | 导航栏标题文字内容 | |
navigationStyle | string | default | default 默认样式 custom 自定义导航栏,只保留右上角胶囊按钮。 |
onReachBottomDistance | number | 50 | 页面上拉触底事件触发时距页面底部距离,单位为 px。 |
boardMenus | array[] | 自定义菜单配置, 容器版本 ≥ 2.3.0 | |
pageOrientation | string | portrait | 屏幕旋转设置,默认值为portrait (竖屏),可选landscape (横屏), auto 自动 |
其中 navigationBarBackgroundColor
、navigationBarTextStyle
、backgroundColor
、 backgroundTextStyle
、backgroundColorTop
和 backgroundColorBottom
支持主题变量配置。如配置了 themeLocation
主题配置文件后,可使用其中声明的变量。
示例:
{
"window": {
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "接口功能演示",
"backgroundColor": "@bgColor",
"backgroundTextStyle": "light",
"disableScroll": true
}
}
自定义菜单项目
key
:菜单项的 key 值,必须唯一。text
:菜单项的标题,支持多语言。iconPath
:菜单项的图标路径,不支持网络图片,支持主题变量配置。{
"window": {
"boardMenus": [
{
"key": "home",
"iconPath": "@iconPath1",
"text": "版本1"
},
{
"key": "share",
"iconPath": "@selectedIconPath1",
"text": "tab1"
},
{
"key": "share",
"iconPath": "/assets/images/tab/component_selected.png",
"text": "@I18n.t('tab2')"
}
]
}
}
如果小程序是一个多 tab 应用(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。
属性 | 类型 | 必填 | 描述 | 描述 |
---|---|---|---|---|
color | HexColor | 是 | tab 上的文字默认颜色,仅支持十六进制颜色 | |
selectedColor | HexColor | 是 | tab 上的文字选中时的颜色,仅支持十六进制颜色 | |
backgroundColor | HexColor | 是 | tab 的背景色,仅支持十六进制颜色 | |
borderStyle | string | 否 | black | tabbar 上边框的颜色, 仅支持 black / white |
list | Array | 是 | tab 的列表,详见 list 属性说明,最少 2 个、最多 5 个 tab |
其中 color
、selectedColor
、backgroundColor
和 borderStyle
支持主题变量配置。如配置了 themeLocation
主题配置文件后,可使用其中声明的变量。
其中 list 接受一个数组,只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序,每个项都是一个对象,其属性值如下:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
pagePath | string | 是 | 页面路径,必须在 pages 中先定义 |
text | string | 是 | tab 上按钮文字 |
iconPath | string | 否 | 图片路径,icon 大小限制为 40kb,建议尺寸为 81x81 px,不支持网络图片。 |
selectedIconPath | string | 否 | 选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81x81 px,不支持网络图片。 |
其中 selectedIconPath
和 iconPath
支持主题变量配置。如配置了 themeLocation
主题配置文件后,可使用其中声明的变量。
是否支持暗黑模式,默认为 true
当设置为 false
时,小程序不支持暗黑模式,且不会触发 onThemeChange
事件。
css 选择器 @media (prefers-color-scheme: dark)
不受影响,仍然会生效。
:root[theme='dark']
选择器仅在 darkmode
为 true
时生效。
配置了 themeLocation
之后,自动支持主题配置。使用相对于 app.json
路径,定义 light
和 dark
主题变量信息。可使用到 window
和 tabBar
支持的字段中。
{
"themeLocation": "./theme.json"
}
格式如下:
{
"light": {
"bgColor": "#ffffff"
},
"dark": {
"bgColor": "#ffffff"
}
}
声明主题字段变量后,可通过 @
符号拼接应用到 app.json
配置中。
声明全局自定义组件,当一个组件被多个页面所引用时,避免重复在页面配置中声明,可使用全局声明的形式。组件路径支持:
/
开头,表示小程序源码目录;.
开头,基于当前 json 文件所在目录;{
"usingComponents": {
"foo": "/absolute/foo/index", // 绝对路径
"foo": "./relative/foo/index", // 相对路径
"foo": "package/es/foo/index" // npm 三方包
}
}
注意:路径地址必须精确到文件名,不可省略缺省 index
。
app.tyss
作为全局样式,作用于当前小程序的所有页面。有关样式 tyss
更详细的文档请参考 小程序样式。
注意:全局样式默认无法作用于自定义组件,需要配合自定义组件的样式配置。具体请参考文档 Component。