--- title: app.json 全局配置 summary: "介绍 app.json 全局配置文件，包括页面路径、窗口样式、tabBar、主题及分包等配置项。" questions: - app.json 文件的作用是什么？ - pages 数组如何配置？未指定 entryPagePath 时首页如何确定？ - window 配置项中有哪些属性可以设置？ - 如何配置自定义导航栏？ - darkmode 支持哪些配置值？各值的效果是什么？ - themeLocation 配置的作用是什么？如何使用主题变量？ - tabBar 的 list 数组有什么限制？每项包含哪些属性？ - usingComponents 支持哪些路径引用方式？ - boardMenus 自定义菜单项如何配置？ --- # app.json 全局配置 小程序根目录下的 app.json 文件用来对小程序进行全局配置，决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。 以下是一个基本配置示例： ```json { "themeLocation": "theme.json", "pages": ["pages/page1/index", "pages/page2/index"], "window": { "navigationBarBackgroundColor": "#ffffff" } } ``` 完整配置项如下： | 属性 | 类型 | 必填 | 描述 | 基础库 | | --------------- | -------------------------------------- | ---- | ---------------------- | ---------------------------------------------------- | | entryPagePath | string | 否 | 小程序默认启动页面 | | | pages | Array | 是 | 设置页面路径 | | | window | Object | 否 | 设置小程序窗口表现 | | | darkmode | boolean \| 'auto' \| 'dark' \| 'light' | 否 | 主题配置, 默认值: true | 2.14.0 开始支持布尔值配置，2.22.0 开始支持字符串配置 | | themeLocation | string | 否 | 主题配置文件相对路径 | | | tabBar | Object | 否 | 设置底部 tabbar 的表现 | | | usingComponents | Object | 否 | 定义全局自定义组件 | | | usingPlugins | Array | 否 | 定义全局插件 | 2.18.0 | | subPackages | Array | 否 | 分包配置 | 2.27.0 | | preloadRule | Object | 否 | 预加载规则 | 2.27.0 | | pagesRedirect | Object | 否 | 页面重定向 | 2.27.0 | ### entryPagePath 指定小程序的默认启动路径（首页），必须是 pages 中的其中一项目。如果不填，将默认为 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` 中应当如下配置： ```json { "pages": ["pages/index/index", "pages/logs/logs"] } ``` > 配置中路径不需要添加 `/` 前缀，默认以当前配置文件（app.json）所在目录为基准。 ### window 用于设置小程序的状态栏、导航条、标题、窗口背景色。 | 属性 | 类型 | 默认值 | 描述 | | ---------------------------- | -------- | -------- | ------------------------------------------------------------------------------ | | 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` 自定义导航栏，只保留右上角胶囊按钮。 | | hideMenuButton | boolean | false | 是否隐藏右上角胶囊按钮 | | onReachBottomDistance | number | 50 | 页面上拉触底事件触发时距页面底部距离，单位为 px。 | | boardMenus | array[] | | 自定义菜单配置, 容器版本 ≥ 2.3.0 | | pageOrientation | string | portrait | 屏幕旋转设置，默认值为`portrait`（竖屏），可选`landscape`（横屏）, `auto` 自动 | 其中 `navigationBarBackgroundColor`、`navigationBarTextStyle`、`backgroundColor`、 `backgroundTextStyle`、`backgroundColorTop` 和 `backgroundColorBottom` 支持主题变量配置。如配置了 `themeLocation` 主题配置文件后，可使用其中声明的变量。 示例： ```json { "window": { "navigationBarBackgroundColor": "#ffffff", "navigationBarTextStyle": "black", "navigationBarTitleText": "接口功能演示", "backgroundColor": "@bgColor", "backgroundTextStyle": "light", "disableScroll": true } } ``` #### boardMenus 自定义菜单项目 - `key`：菜单项的 key 值，必须唯一。 - `text`：菜单项的标题，支持多语言。 - `iconPath`：菜单项的图标路径，不支持网络图片，支持主题变量配置。 ```json { "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')" } ] } } ``` ### tabBar 如果小程序是一个多 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 | | custom | Boolean | 否 | false | 是否使用自定义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` 主题配置文件后，可使用其中声明的变量。 ### darkmode > 如无特殊需求，建议跟随 App 主题色对应实现小程序的深浅色系，而不是通过 `darkmode` 来控制主题。 默认为 `true` 当设置为 `false` 时，小程序不支持暗黑模式，且不会触发 `onThemeChange` 事件。 在 **小程序基础库 2.22.0** 及 **App 基线 6.0.0** 以后，开始支持设置 `auto`、`dark`、`light` 三种模式： - `auto` 模式下，小程序会根据系统设置自动切换主题，即等同于原先的 `true` 配置。 - `light` 模式下，小程序会强制使用亮色模式，即小程序自身的胶囊、获取到的 `--app-B1` 等 App 主题色变量都会固定使用 App 浅色系配色。 - `dark` 模式下，小程序会强制使用暗黑模式，即小程序自身的胶囊、获取到的 `--app-B1` 等 App 主题色变量都会固定使用 App 深色系配色。 css 选择器 `@media (prefers-color-scheme: dark)` 不受影响，仍然会生效。 `:root[theme='dark']` 选择器仅在 `darkmode` 为 `true` 、`dark` 或 `auto` 时生效。 ### themeLocation 配置了 `themeLocation` 之后，自动支持主题配置。使用相对于 `app.json` 路径，定义 `light` 和 `dark` 主题变量信息。可使用到 `window` 和 `tabBar` 支持的字段中。 ```json { "themeLocation": "./theme.json" } ``` 格式如下： ```json { "light": { "bgColor": "#ffffff" }, "dark": { "bgColor": "#1f1f1f" } } ``` 声明主题字段变量后，可通过 `@` 符号拼接应用到 `app.json` 配置中。 ### usingComponents 声明全局自定义组件，当一个组件被多个页面所引用时，避免重复在页面配置中声明，可使用全局声明的形式。组件路径支持： 1. 绝对路径形式，以 `/` 开头，表示小程序源码目录； 2. 相对路径形式，以 `.` 开头，基于当前 json 文件所在目录； 3. npm 三方包。 ```json { "usingComponents": { "foo": "/absolute/foo/index", // 绝对路径 "foo": "./relative/foo/index", // 相对路径 "foo": "package/es/foo/index" // npm 三方包 } } ``` **注意**：路径地址必须精确到文件名，不可省略缺省 `index`。 ### usingPlugins ```json { "usingPlugins": ["rjs://echarts"] } ``` 声明全局插件，具体请查看[插件系统](/cn/miniapp/develop/miniapp/framework/plugin/intro) ### subPackages 配置小程序分包加载，详见[分包加载](/cn/miniapp/develop/miniapp/guide/ability/sub-packages)