全局配置 ¶

更新: 2021 年 12 月 25 日

小程序根目录下的 app.json 文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象，有以下属性：

配置项

属性	类型	必填	描述	最低版本
pages	string[]	是	页面路径列表
window	Object	否	全局的默认窗口表现
tabBar	Object	否	底部 tab 栏的表现
networkTimeout	Object	否	网络超时时间
debug	boolean	否	是否开启 debug 模式，默认关闭
functionalPages	boolean	否	是否启用插件功能页，默认关闭	2.1.0
subpackages	Object[]	否	分包结构配置	1.7.3
workers	string	否	Worker 代码放置的目录	1.9.90
requiredBackgroundModes	string[]	否	需要在后台使用的能力，如「音乐播放」
plugins	Object	否	使用到的插件	1.9.6
preloadRule	Object	否	分包预下载规则	2.3.0
resizable	boolean	否	iPad 小程序是否支持屏幕旋转，默认关闭	2.3.0
navigateToMiniProgramAppIdList	string[]	否	需要跳转的小程序列表，详见 wx.navigateToMiniProgram	2.4.0
usingComponents	Object	否	全局自定义组件配置	开发者工具 1.02.1810
permission	Object	否	小程序接口权限相关设置	微信客户端 7.0.0

pages¶

pages¶

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

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

如开发目录为:

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils

则需要在 app.json 中写

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

window¶

window

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

Object Properties

navigationBarBackgroundColor (HexColor) – 导航栏背景颜色 1，如 #000000 (#000000)
navigationBarTextStyle (string) – 导航栏标题颜色，仅支持 black/white (white)
navigationBarTitleText (string) – 导航栏标题文字内容
navigationStyle (string) – 导航栏样式，仅支持以下值： default 默认样式 custom 自定义导航栏，只保留右上角胶囊按钮 2 。微信客户端 6.6.0 (default)
backgroundColor (HexColor) – 窗口的背景色 1 (#ffffff)
backgroundTextStyle (string) – 下拉 loading 的样式，仅支持 dark / light (dark)
backgroundColorTop (string) – 顶部窗口的背景色，仅 iOS 支持微信客户端 6.5.16 (#ffffff)
backgroundColorBottom (string) – 底部窗口的背景色，仅 iOS 支持微信客户端 6.5.16 (#ffffff)
enablePullDownRefresh (boolean) – 是否开启全局的下拉刷新。详见 Page.onPullDownRefresh (false)
onReachBottomDistance (int) – 页面上拉触底事件触发时距页面底部距离，单位为px。详见 Page.onReachBottom (50)
pageOrientation (string) – 屏幕旋转设置，支持 auto/portrait/landscape 详见响应显示区域变化 2.4.0 (auto) / 2.5.0 (landscape) (portrait)

示例

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

JSON Example

{
    "navigationBarBackgroundColor": "{HexColor object}",
    "navigationBarTextStyle": "yxQRkiYcZChRQVoUnpbT",
    "navigationBarTitleText": "PlMfvqCVTpIgoUFVeuwv",
    "navigationStyle": "UtRHxLhDIeQUQVSWTQNZ",
    "backgroundColor": "{HexColor object}",
    "backgroundTextStyle": "IELSsewxMSWTUHMjjVoB",
    "backgroundColorTop": "JwtLZmFnsoaXtgeYsNTI",
    "backgroundColorBottom": "GslgreRZmHTlIMieJiBY",
    "enablePullDownRefresh": true,
    "onReachBottomDistance": 7013,
    "pageOrientation": "ObbYMNXIZuKoiNVVyQzD"
}

1(1,2)

HexColor（十六进制颜色值），如”#ff00ff”

2

关于navigationStyle

客户端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。
客户端 6.7.2 版本开始，navigationStyle: custom 对 <web-view> 组件无效
开启 custom 后，低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0（不代表最低版本，只供调试用）可方便切到旧视觉

tabBar¶

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，见详情 2.5.0

其中 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¶

networkTimeout¶

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

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

debug¶

debug¶

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

functionalPages¶

functionalPages¶

2.1.0 新版功能: 低版本需做兼容处理。

插件所有者小程序需要设置这一项来启用插件功能页。

subpackages¶

subpackages¶

微信客户端 6.6.0 ，

1.7.3 新版功能: 及以上版本支持

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

写成 subPackages 也支持。

workers¶

workers¶

1.9.90 新版功能: 低版本需做兼容处理。

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

requiredBackgroundModes¶

requiredBackgroundModes¶

微信客户端 6.7.2 及以上版本支持

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

audio: 后台音乐播放

如：

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

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

plugins¶

plugins¶

1.9.6 新版功能: 低版本需做兼容处理。

声明小程序需要使用的插件。

preloadRule¶

preloadRule¶

2.3.0 新版功能: 低版本需做兼容处理。

声明分包预下载的规则。

resizable¶

resizable¶

2.3.0 新版功能: 低版本需做兼容处理。

在 iPad 上运行的小程序可以设置支持屏幕旋转。

navigateToMiniProgramAppIdList¶

navigateToMiniProgramAppIdList¶

2.4.0 新版功能: 低版本需做兼容处理。

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

usingComponents¶

usingComponents¶

开发者工具 1.02.1810190 及以上版本支持

在此处声明的自定义组件视为全局自定义组件，在小程序内的页面或自定义组件中可以直接使用而无需再声明。

permission¶

permission¶

微信客户端 7.0.0 及以上版本支持

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

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

PermissionObject 结构

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

如：

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

配置示例¶

{
  "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": ["wxe5f52902cf4de896"]
}

待处理

2021 年 12 月 25 日研究输出json格式

目录

上一个主题

下一个主题

本页

全局配置 ¶

pages¶

window¶

tabBar¶

networkTimeout¶

debug¶

functionalPages¶

subpackages¶

workers¶

requiredBackgroundModes¶

plugins¶

preloadRule¶

resizable¶

navigateToMiniProgramAppIdList¶

usingComponents¶

permission¶

配置示例¶

全局配置¶

pages¶

window¶

tabBar¶

networkTimeout¶

debug¶

functionalPages¶

subpackages¶

workers¶

requiredBackgroundModes¶

plugins¶

preloadRule¶

resizable¶

navigateToMiniProgramAppIdList¶

usingComponents¶

permission¶

配置示例¶

全局配置 ¶