全局配置

小程序根目录下的 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 小程序接口权限相关设置

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.js
└── utils
1
2
3
4
5
6
7
8
9
10
11
12
13

则需要在 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

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,不支持网络图片。

postiontop 时,不显示 icon。
selectedIconPath | String | 否 | 选中时的图片路径,icon 大小限制为40kb,建议尺寸为 81px * 81px,不支持网络图片。
postiontop 时,不显示 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