# 全局配置

小程序根目录下的 app.json 文件用来对 QQ 小程序进行全局配置，决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。

# 配置示例

以下是一个包含了部分常用配置选项的 app.json ：

{
  "pages": ["pages/index/index", "pages/logs/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志"
      }
    ]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "debug": true,
  "navigateToMiniProgramAppIdList": ["qqe5f52902cf4de896"],
  "groupIdList": ["123456", "34356576", "457658769"]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# app.json 配置项列表

属性	类型	必填	描述
pages	String Array	是	页面路径列表
window	Object	否	全局的默认窗口表现
tabBar	Object	否	底部 `tab` 栏的表现
networkTimeout	Object	否	网络超时时间
debug	Boolean	否	是否开启 debug 模式，默认关闭
subpackages	Object Array	否	分包结构配置
workers	String	否	`Worker` 代码放置的目录
requiredBackgroundModes	String Array	否	需要在后台使用的能力，如「音乐播放」 preloadRule
navigateToMiniProgramAppIdList	String Array	否	需要跳转的小程序列表，详见 qq.navigateToMiniProgram
groupIdList	String Array	否	需要打开群资料卡的群号列表，详见button
permission	Object	否	小程序接口权限相关设置
darkmode	Boolean	否	为 `true` 时允许通过 `qq.getSystemInfo` 获取当前手 Q 是否为夜间模式
resizable	Boolean	否	PC 小程序是否支持用户任意改变窗口大小（包括最大化窗口）；iPad 小程序是否支持屏幕旋转。默认关闭

# pages

用于指定小程序由哪些页面组成，每一项都对应一个页面的路径+文件名信息。文件名不需要写文件后缀，框架会自动去寻找对于位置的 .json, .js, .qml, .qss 四个文件进行处理。

数组的第一项代表小程序的初始页面（首页）。小程序中新增/减少页面，都需要对 pages 数组进行修改。

如开发目录为：

├── app.js
├── app.json
├── app.qss
├── pages
│   │── index
│   │   ├── index.qml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.qss
│   └── logs
│       ├── logs.qml
│       ├── logs.json
│       └── logs.js
└── utils

1
2
3
4
5
6
7
8
9
10
11
12
13
14

则需要在 app.json 中写

{
  "pages": ["pages/index/index", "pages/logs/logs"]
}

1
2
3

# window

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

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如 `#000000`
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持 `black` / `white`
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持以下值： `default` 默认样式 `custom` 自定义导航栏，只保留右上角胶囊按钮。参见注 2。
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 `dark` / `light`
backgroundColorTop	String	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	String	#ffffff	底部窗口的背景色，仅 iOS 支持
enablePullDownRefresh	Boolean	false	是否开启当前页面的下拉刷新。详见 Page.onPullDownRefresh
pageOrientation	String	portrait	屏幕旋转设置，支持 `auto` / `portrait` / `landscape` 。详见响应显示区域变化

注 1：HexColor（十六进制颜色值），如"#ff00ff"
注 2：关于navigationStyle

如 app.json ：

{
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "QQ接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
  }
}

1
2
3
4
5
6
7
8
9

提示

PC程序窗体顶部会预留一个10px高度的窗口拖拽条，该条默认显示为白色，如果全局或当前页面设置了navigationBarBackgroundColor字段，则该拖拽条会使用navigationBarBackgroundColor指定的色值。

# 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
position	String	否	bottom	tabBar 的位置，仅支持 `bottom` / `top`
custom	Boolean	否	false	自定义 tabBar，见详情

其中 list 接受一个数组，只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序，每个项都是一个对象，其属性值如下：

属性	类型	必填	说明
pagePath	String	是	页面路径，必须在 pages 中先定义
text	String	是	tab 上按钮文字
iconPath	String	否	图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px，不支持网络图片。当 `postion` 为 `top` 时，不显示 icon。
selectedIconPath	String	否	选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px，不支持网络图片。当 `postion` 为 `top` 时，不显示 icon。

# networkTimeout

各类网络请求的超时时间，单位均为毫秒。

属性	类型	必填	默认值	说明
request	Number	否	60000	qq.request 的超时时间，单位：毫秒。
connectSocket	Number	否	60000	qq.connectSocket 的超时时间，单位：毫秒。
uploadFile	Number	否	60000	qq.uploadFile 的超时时间，单位：毫秒。
downloadFile	Number	否	60000	qq.downloadFile 的超时时间，单位：毫秒。

# debug

可以在开发者工具中开启 debug 模式，在开发者工具的控制台面板，调试信息以 info 的形式给出，其信息有 Page 的注册，页面路由，数据更新，事件触发等。可以帮助开发者快速定位一些常见的问题。

# subpackages

启用分包加载时，声明项目分包结构。

写成 subPackages 也支持。

# workers

使用 Worker 处理多线程任务时，设置 Worker 代码放置的目录

# requiredBackgroundModes

申明需要后台运行的能力，类型为数组。目前支持以下项目：

audio: 后台音乐播放

如：

{
  "pages": ["pages/index/index"],
  "requiredBackgroundModes": ["audio"]
}

1
2
3
4

注：在此处申明了后台运行的接口，开发版和体验版上可以直接生效，正式版还需通过审核。

# preloadRule

声明分包预下载的规则。

# navigateToMiniProgramAppIdList

当小程序需要使用 qq.navigateToMiniProgram 接口跳转到其他小程序时，需要先在配置文件中声明需要跳转的小程序 appId 列表，最多允许填写 10 个。

# groupIdList

当小程序中使用button组件打开群资料卡时使用，需要先在配置文件中声明需要跳转的小程序 groupId 列表，最多允许填写 10 个。

# permission

小程序接口权限相关设置。字段类型为 Object，结构为：

属性	类型	必填	默认值	描述
scope.userLocation	PermissionObject	否		位置相关权限声明

PermissionObject 结构

属性	类型	必填	默认值	说明
desc	string	是		小程序获取权限时展示的接口用途说明。最长 30 个字符

如：

{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序位置接口的效果展示"
    }
  }
}

1
2
3
4
5
6
7
8

← 目录结构页面配置 →