全局配置
# 全局配置
小程序根目录下的 app.json
文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象,有以下属性:
# 配置项
# entryPagePath
指定小程序的默认启动路径(首页),常见情景是从微信聊天列表页下拉启动、小程序列表启动等。如果不填,将默认为 pages
列表的第一项。不支持带页面路径参数。
{
"entryPagePath": "pages/index/index"
}
# pages
用于指定小程序由哪些页面组成,每一项都对应一个页面的 路径(含文件名) 信息。文件名不需要写文件后缀,框架会自动去寻找对应位置的 .json
, .js
, .wxml
, .wxss
四个文件进行处理。
未指定 entryPagePath
时,数组的第一项代表小程序的初始页面(首页)。
小程序中新增/减少页面,都需要对 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
用于设置小程序的状态栏、导航条、标题、窗口背景色。
- 注 1:HexColor(十六进制颜色值),如"#ff00ff"
- 注 2:关于
navigationStyle
- iOS/Android 客户端 7.0.0 以下版本,
navigationStyle
只在app.json
中生效。 - iOS/Android 客户端 6.7.2 版本开始,
navigationStyle: custom
对 web-view 组件无效 - 开启 custom 后,低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0(不代表最低版本,只供调试用)可方便切到旧视觉
- Windows 客户端 3.0 及以上版本,为了给用户提供更符合桌面软件的使用体验,统一了小程序窗口的导航栏,
navigationStyle: custom
不再生效
- iOS/Android 客户端 7.0.0 以下版本,
# restartStrategy
基础库 2.8.0 开始支持,低版本需做兼容处理。
重新启动策略配置
如:
{
"window": {
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
}
# tabBar
如果小程序是一个多 tab 应用(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。
其中 list 接受一个数组,只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序,每个项都是一个对象,其属性值如下:
# networkTimeout
各类网络请求的超时时间,单位均为毫秒。
# debug
可以在开发者工具中开启 debug
模式,在开发者工具的控制台面板,调试信息以 info
的形式给出,其信息有 Page 的注册,页面路由,数据更新,事件触发等。可以帮助开发者快速定位一些常见的问题。
# functionalPages
基础库 2.1.0 开始支持,低版本需做兼容处理。
插件所有者小程序需要设置这一项来启用插件功能页。
# subpackages
微信客户端 6.6.0 ,基础库 1.7.3 及以上版本支持
启用分包加载时,声明项目分包结构。
写成 subPackages 也支持。
# workers
基础库 1.9.90 开始支持,低版本需做兼容处理。
使用 Worker 处理多线程任务时,设置 Worker
代码放置的目录
# requiredBackgroundModes
微信客户端 6.7.2 及以上版本支持
申明需要后台运行的能力,类型为数组。目前支持以下项目:
audio
: 后台音乐播放location
: 后台定位
如:
{
"pages": ["pages/index/index"],
"requiredBackgroundModes": ["audio", "location"]
}
注:在此处申明了后台运行的接口,开发版和体验版上可以直接生效,正式版还需通过审核。
# requiredPrivateInfos
自 2022 年 7 月 14 日后发布的小程序,使用以下8个地理位置相关接口时,需要声明该字段,否则将无法正常使用。2022 年 7 月 14 日前发布的小程序不受影响。
申明需要使用的地理位置相关接口,类型为数组。目前支持以下项目:
- getFuzzyLocation: 获取模糊地理位置
- getLocation: 获取精确地理位置
- onLocationChange: 监听实时地理位置变化事件
- startLocationUpdate: 接收位置消息(前台)
- startLocationUpdateBackground: 接收位置消息(前后台)
- chooseLocation: 打开地图选择位置
- choosePoi: 打开POI列表选择位置
- chooseAddress: 获取用户地址信息
如:
{
"pages": ["pages/index/index"],
"requiredPrivateInfos": [
"getLocation",
"onLocationChange",
"startLocationUpdateBackground"
"chooseAddress"
]
}
注:若使用以上接口,均需在小程序管理后台,「开发」-「开发管理」-「接口设置」中自助开通该接口权限。
# plugins
基础库 1.9.6 开始支持,低版本需做兼容处理。
声明小程序需要使用的插件。
# preloadRule
基础库 2.3.0 开始支持,低版本需做兼容处理。
声明分包预下载的规则。
# resizable
基础库 2.3.0 开始支持,低版本需做兼容处理。
在 iPad 上运行的小程序可以设置支持屏幕旋转。
在 PC 上运行的小程序,用户可以按照任意比例拖动窗口大小,也可以在小程序菜单中最大化窗口
# usingComponents
开发者工具 1.02.1810190 及以上版本支持
在 app.json 中声明的自定义组件视为全局自定义组件,在小程序内的页面或自定义组件中可以直接使用而无需再声明。建议仅在此声明几乎所有页面都会用到的自定义组件。
注1:全局自定义组件会视为被所有页面依赖,会在所有页面启动时进行初始化,影响启动性能且会占用主包大小。只被个别页面或分包引用的自定义组件应尽量在页面配置中声明。 注2:在全局声明使用率低的自定义组件会大幅影响按需注入的效果。
# permission
微信客户端 7.0.0 及以上版本支持
小程序接口权限相关设置。字段类型为 Object
,结构为:
PermissionObject 结构
如:
{
"pages": ["pages/index/index"],
"permission": {
"scope.userLocation": {
"desc": "你的位置信息将用于小程序位置接口的效果展示" // 高速公路行驶持续后台定位
}
}
}
# sitemapLocation
指明 sitemap.json 的位置;默认为 'sitemap.json' 即在 app.json 同级目录下名字的 sitemap.json
文件
# style
基础库 2.8.0 开始支持,低版本需做兼容处理。
微信客户端 7.0 开始,UI 界面进行了大改版。小程序也进行了基础组件的样式升级。app.json 中配置 "style": "v2"
可表明启用新版的组件样式。
本次改动涉及的组件有 button icon radio checkbox switch slider
。可前往小程序示例进行体验。
# useExtendedLib
基础库 2.2.1 开始支持,低版本需做兼容处理。
最新的 nightly 版开发者工具开始支持,同时基础库从支持 npm 的版本(2.2.1)起支持
指定需要引用的扩展库。目前支持以下项目:
kbone
: 多端开发框架weui
: WeUI 组件库
指定后,相当于引入了对应扩展库相关的最新版本的 npm 包,同时也不占用小程序的包体积。rc工具版本支持分包引用。用法如下:
{
"useExtendedLib": {
"kbone": true,
"weui": true
}
}
# entranceDeclare
微信客户端 7.0.9 及以上版本支持,iOS 暂不支持
聊天位置消息用打车类小程序打开,详情参考。
"entranceDeclare": {
"locationMessage": {
"path": "pages/index/index",
"query": "foo=bar"
}
}
# darkmode
开发者工具 1.03.2004271 及以上版本支持,基础库 2.11.0 及以上版本支持
微信iOS客户端 7.0.12 版本、Android客户端 7.0.13 版本正式支持 DarkMode,可通过配置"darkmode": true
表示当前小程序可适配 DarkMode,所有基础组件均会根据系统主题展示不同的默认样式,navigation bar 和 tab bar 也会根据开发者的配置自动切换。
配置后,请根据DarkMode 适配指南自行完成基础样式以外的适配工作。
{
"darkmode": true
}
# themeLocation
自定义 theme.json 的路径,当配置"darkmode":true
时,当前配置文件为必填项。
{
"themeLocation": "/path/to/theme.json"
}
# lazyCodeLoading
目前仅支持值 requiredComponents
,代表开启小程序「按需注入」特性。
{
"lazyCodeLoading": "requiredComponents"
}
# singlePage
基础库 2.11.3 及以上版本支持,目前分享到朋友圈 (Beta) 后打开会进入单页模式
单页模式相关配置
# embeddedAppIdList
指定小程序可通过wx.openEmbeddedMiniProgram打开的小程序名单。
{
"embeddedAppIdList": ["wxe5f52902cf4de896"]
}
# halfPage
{
"halfPage": {
"firstPageNavigationStyle": "custom"
}
}
# debugOptions
小程序调试相关配置项
{
"debugOptions": {
"enableFPSPanel": "custom"
}
}
# enablePassiveEvent
touch
相关事件默认的 passive
为 false。如果小程序不使用 catchtouch* 事件时,可以通过这个选项将 passive
置为 true
,以提高滚动性能。具体原理可参考MDN。
可以直接设置这个选项为 true
,也可以分别控制某个事件。
{
"enablePassiveEvent": true
}
{
"enablePassiveEvent": {
"touchstart": true
}
}
注意
开启了 enablePassiveEvent
之后,使用以下内置组件可能会导致出现非预期的行为,但不会导致页面白屏。
touchmove
设置为 true
,如下内置组件可能会出现非预期表现:
- movable-area
- movable-view
- video
- canvas(windows、mac 小程序)
- picker-view-column
wheel
设置为 true
,如下内置组件可能会出现非预期表现:
- swiper(mac 小程序)
- map
推荐在用到如上组件的页面中将对应事件的 enablePassiveEvent
设置为 false
以避免非预期行为。
自 2.25.1 之后,在页面/组件实例中新增 getPassiveEvent
/ setPassiveEvent
两个接口,用于在运行时获取/切换页面或组件所在页面的 passive
配置。
Component({
methods: {
getPassive() {
this.getPassiveEvent((passive) => {
const { touchstart, touchmove, wheel } = passive
})
},
setPassive() {
const passive {
touchstart: false,
touchmove: true,
wheel: false,
}
this.setPassiveEvent(passive)
}
}
})
# resolveAlias
使用 resolveAlias
配置项用来自定义模块路径的映射规则。
配置了之后,会对 require
里的模块路径进行规则匹配并映射成配置的路径。
如果命中多条映射规则,则取最长的命中规则。
{
"resolveAlias": {
"~/*": "/*",
"~/origin/*": "origin/*",
"@utils/*": "utils/*",
"subBUtils/*": "subpackageB/utils/*"
}
}
注意
resolveAlias
进行的是路径匹配,其中的 key 和 value 须以/*
结尾。
配置了上述路径映射规则,会做如下匹配并转换
~/mod.js
->mod.js
~/origin/mod.js
->origin/mod.js
@utils/mod.js
->utils/mod.js
subBUtils/mod.js
->subpackageB/utils/mod.js
- 如果在 project.config.json 中指定了 miniprogramRoot,则
/*
指代的根目录是 miniprogramRoot 对应的路径,而不是开发者工具项目的根目录
# renderer
指定小程序全局的默认渲染后端。
可选值:webview
, skyline
默认值:webview
# rendererOptions
小程序渲染后端的相关配置选项
# SkylineOptions
Skyline 渲染引擎的相关配置项
{
"rendererOptions": {
"skyline": {
"defaultDisplayBlock": true
}
}
}
# componentFramework
指定小程序使用的组件框架
可选值:exparser
, glass-easel
默认值:exparser
# 配置示例
{
"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,
}