文档

# 全局配置

小程序根目录下的 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

声明分包预下载的规则。

当小程序需要使用 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

← 页面配置 →