# 全局配置 本文介绍什么是全局配置，并提供小程序支持的全局配置项列表。 ## 功能简介 小程序根目录下的 app.json 文件用于对小程序进行全局配置。在该配置文件中，可指定页面文件的路径、全局样式、设置多 tab、设置 PC 小程序各种模式的默认启动页面等。 以下是一个包含了部分常用配置项的 app.json 文件内容： ```json { "pages": [ "pages/index/index", "pages/logs/index", "pages/home/index", "pages/help/index" ], "window": { "backgroundTextStyle":"light", "navigationBarBackgroundColor": "#fff", "navigationBarTitleText": "Mini App", "navigationBarTextStyle": "black" }, "tabBar": { "list": [{ "pagePath": "pages/home/index", "text": "主页" }, { "pagePath": "pages/help/index", "text": "帮助" }] } } ``` ## 全局配置项 配置项 | 类型 | 是否必填 | 描述 ---|---|---|--- entryPagePath | String | 否 | 小程序默认启动页面。 pages | String[] | 是 | 配置页面路径。 window | Object | 否 | 配置默认页面的窗口表现。 tabBar | Object | 否 | 配置底部 tab 的表现。 debug | Boolean | 否 | 配置是否开启 debug 模式 ext | Object | 否 | 提供额外配置参数给小程序使用 darkmode | Boolean | 否 | 设置为 true 时表示小程序支持 DarkMode。 themeLocation | String | 否 | [深色模式](https://open.feishu.cn/document/uYjL24iN/uQTM5UjL0ETO14CNxkTN/darkmode)变量配置文件的路径，相对于小程序根目录，darkmode 为 true 时为必填。 useExtendedLib | Object | 否 | 配置需要使用的扩展库。 networkTimeout | Object | 否 | 配置网络类API相关参数，包括 tt.request、tt.downloadFile、tt.uploadFile、tt.connectSocket。 如果小程序的页面栈的第一个页面不是 app.json 里 pages 里配置的第一个页面（首页），页面左上角会显示 Home 按钮（即返回首页按钮）。PC 小程序仅 window-semi 模式有效。 如果你的小程序支持在 PC 端运行，可以在 ext 里配置 PC 小程序的各种模式默认启动页面。配置完成后，在启动 PC 小程序时如果没设置启动页面，则程序将根据当前的模式，启动 ext 里配置的页面。具体示例如下： ```json { "pages": [ "pages/index/index", "pages/logs/index", "pages/order/index", "pages/chat/index" ], "ext": { "defaultPages": { "sidebarMode": "pages/order/index", "PCMode": "pages/chat/index" } } } ``` 如果你的 PC 小程序需要配置默认启动页面，则需要注意 defaultPages 中各模式配置的页面必须在 pages 中定义，否则编译过程会报错。 ### entryPagePath 指定小程序启动的默认页面。未配置时默认为 pages 列表的第一项。 ```json { "entryPagePath": "pages/index/index" } ``` ### pages 该字段用于配置小程序用到的所有页面路径，配置项的结构为`路径 + 文件名`。 - 配置项的第一个页面路径就是小程序启动展示的第一个页面。 - 需要保证单个页面的 `.json`、`.js`、`.ttml`、`.ttss` 资源都放在每个页面路径的首层。 示例配置： 如果开发目录如下所示。 ``` |____app.ttss |____app.json |____project.config.json |____pages | |____index | | |____index.js | | |____index.json | | |____index.ttml | | |____index.ttss |____app.js ``` 则相应的 app.json 中配置应如下所示。 ```json { "pages":[ "pages/index/index" ] } ``` ### window 该字段用于设置小程序的状态栏、导航栏、标题、窗口背景色。 属性 | 类型 | 默认值 | 描述 | 支持平台 ---|---|---|---|--- navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色。例如：#000000。 | iOS,Android navigationBarTextStyle | String | white | 导航栏标题颜色。取值：
- black
- white | iOS,Android navigationBarTitleText | String | \- | 导航栏标题文字内容。 | iOS,Android,PC transparentTitle | String | none | 导航栏透明设置。取值：
- always：一直透明
- auto：滑动自适应
- none（默认值）：不透明 | iOS,Android navigationStyle | String | default | 导航栏样式。取值：
- default：默认样式。
- custom：可自定义导航栏，只保留右上角胶囊状的按钮。 | iOS,Android,PC backgroundColor | HexColor | #ffffff | 窗口的背景色。例如：#ffffff。 | iOS,Android,PC(3.14.0+) backgroundTextStyle | String | dark | 下拉 loading 的样式。取值
- dark
- light | iOS,Android backgroundColorTop | String | #ffffff | 顶部窗口的背景色。例如：#ffffff。 | iOS backgroundColorBottom | String | #ffffff | 底部窗口的背景色。例如：#ffffff。 | iOS enablePullDownRefresh | Boolean | false | 是否开启下拉刷新。 | iOS,Android onReachBottomDistance | Number | 50 | 页面上拉触底事件触发时，距页面底部距离。单位：px | iOS,Android PCMode | Object | \- | PCMode 模式下特定的窗口配置，支持的属性与通用 window 配置属性一致，仅当在 ext 内配置了 defaultPages.PCMode 时生效。 | PC(3.14.0+) ### tabBar 如果小程序是一个多 tab 的应用（客户端窗口的底部或顶部存在 tab 栏可以切换页面），则可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。 属性 | 类型 | 是否必填 | 默认值 | 描述 | 支持平台 ---|---|---|---|---|--- color | HexColor | 是 | \- | tab 上的文字默认颜色 | iOS,Android,PC selectedColor | HexColor | 是 | \- | tab 上的文字选中时的颜色。 | iOS,Android,PC backgroundColor | HexColor | 是 | \- | tab 的背景色。 | iOS,Android,PC borderStyle | String | 否 | black | tabBar 上边框的颜色，仅支持：
- black(#E6E6E6)
- white(#FFFFFF) | iOS,Android,PC(3.14.0+) list | Array | 是 | \- | tab 的列表。列表中的 tab 至少 2 个, 至多 5 个，且按数组的顺序排序。每个 tab 都是一个对象（Object），Object 中的属性值可参见下文 list 中的 tab 属性表。 | iOS,Android,PC position | String | 否 | bottom | tab 栏的位置。可选值：bottom、top。 | PC PCMode | Object | 否 | \- | PCMode 模式下特定的 tabBar 配置，支持的属性与通用 tabBar 配置属性一致，仅当在 ext 内配置了 defaultPages.PCMode 时生效。 | PC(3.14.0+) #### list 中的 tab 属性表 属性 | 类型 | 是否必填 | 描述 ---|---|---|--- pagePath | string | 是 | 页面路径，必须先在 pages 中进行定义。 text | string | 是 | tab 上的按钮文字。 iconPath | string | 否 | 图片路径。icon 仅支持 png 格式的图片，大小限制为 40 kb，建议尺寸为 96 px * 96 px，不支持网络图片。 selectedIconPath | string | 否 | 选中时的图片路径。icon 仅支持 png 格式的图片，大小限制为 40 kb，建议尺寸为 96 px * 96 px，不支持网络图片。 ### debug 开启并显示 vConsole 的 debug 模式。在预览场景下可开启该参数用于查看 vconsole 的数据，该参数对线上正式版本的小程序无效。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/11cb873f99a8f9a544002dc71c7026d7_g4UHr2ES21.png?height=1166&lazyload=true&maxWidth=260&width=564) ### ext 小程序的扩展配置字段，目前可用的字段为 defaultPages，参数说明如下表。 #### defaultPages 参数说明 属性 | 类型 | 是否必填 | 描述 ---|---|---|--- sidebarMode | string | 否 | 小窗口模式默认展示的页面。小窗口模式包括：
- sidebar-semi：在聊天的侧边栏打开小窗口。
- window-semi：独立小窗口打开。飞书从 V3.33 版本开始支持此模式。 PCMode | string | 否 | 大窗口模式默认展示的页面。大窗口模式包括：
- appCenter：工作台中打开。
- feed：feed 模式打开。
- navApplication：导航栏模式打开。
- window：独立大窗口打开。 ### useExtendedLib 配置需要使用的拓展库，目前只支持[ChartSpace 图表组件库](https://open.feishu.cn/document/uYjL24iN/uUTM5UjL1ETO14SNxkTN/extension/visualization/chartspace) 。配置后，系统会将扩展库最新版本的 npm 包内置到小程序中。详细配置如下所示： ```json { "useExtendedLib": { "chartSpace": true } } ``` 在使用自定义组件的页面 JSON 中增加自定义组件配置。 ```json { "usingComponents": { "chart-space": "/lark-chartspace/index" } } ``` ### networkTimeout 配置网络类 API 的相关参数，可配置参数如下表所示。 属性 | 类型 | 是否必填 | 描述 ---|---|---|--- request | long | 否 | 自定义 tt.request 的 timeout 时间，可设置范围为 (0,60000), 默认值 60000, 单位：毫秒。 uploadFile | long | 否 | 自定义 tt.uploadFile 的 timeout 时间，可设置范围为 (0,60000), 默认值 60000, 单位：毫秒。 downloadFile | long | 否 | 自定义 tt.downloadFile 的 timeout 时间，可设置范围为 (0,60000), 默认值 60000, 单位：毫秒。 connectSocket | long | 否 | 自定义 tt.connectSocket 的 timeout 时间，可设置范围为 (0,60000), 默认值 60000, 单位：毫秒。 networkTimeout 设置对小程序全局生效，无法只对某个页面生效，也无法只对某次 API 调用生效。app.json 配置示例如下： ```json "networkTimeout": { "request": 10000, "connectSocket": 10000, "uploadFile": 10000, "downloadFile": 10000 } ```