获取当前页面栈。数组中第一个元素为首页，最后一个元素为当前页面。
注意事项
- 不要尝试修改页面栈，否则会导致路由以及页面状态错误。
- 不要在
App.onLaunch的时候调用getCurrentPages()，因为此时page还没有生成。
分类： 框架
Page(Object object)
注册微信小程序中的一个页面。接受一个 Object 类型参数，用于指定页面的初始数据、生命周期回调、事件处理函数等。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| data | Object | 页面的初始数据 | ||
| options | Object | 页面的组件选项，同 Component 构造器 中的 options ，需要基础库版本 ‘2.10.1’ | ||
| behaviors | String Array | 类似于 mixins 和 traits 的组件间代码复用机制，参见 behaviors，需要基础库版本 ‘2.9.2’ | ||
| onLoad | function | 生命周期回调—监听页面加载 | ||
| onShow | function | 生命周期回调—监听页面显示 | ||
| onReady | function | 生命周期回调—监听页面初次渲染完成 | ||
| onHide | function | 生命周期回调—监听页面隐藏 | ||
| onUnload | function | 生命周期回调—监听页面卸载 | ||
| onRouteDone | function | 生命周期回调—监听路由动画完成 | ||
| onPullDownRefresh | function | 监听用户下拉动作 | ||
| onReachBottom | function | 页面上拉触底事件的处理函数 | ||
| onShareAppMessage | function | 用户点击右上角转发 | ||
| onShareTimeline | function | 用户点击右上角转发到朋友圈 | ||
| onAddToFavorites | function | 用户点击右上角收藏 | ||
| onPageScroll | function | 页面滚动触发事件的处理函数 | ||
| onResize | function | 页面尺寸改变时触发，详见 响应显示区域变化 | ||
| onTabItemTap | function | 当前是 tab 页时，点击 tab 时触发 | ||
| onSaveExitState | function | 页面销毁前保留状态回调 | ||
| 其他 | any | 开发者可以添加任意的函数或数据到 Object 参数中，在页面的函数中用 this 可以访问。这部分属性会在页面实例创建时进行一次深拷贝。 |
示例代码
//index.js
Page({
data: {
text: "This is page data."
},
onLoad: function(options) {
// Do some initialize when page load.
},
onShow: function() {
// Do something when page show.
},
onReady: function() {
// Do something when page ready.
},
onHide: function() {
// Do something when page hide.
},
onUnload: function() {
// Do something when page close.
},
onPullDownRefresh: function() {
// Do something when pull down.
},
onReachBottom: function() {
// Do something when page reach bottom.
},
onShareAppMessage: function () {
// return custom share data when user share.
},
onPageScroll: function() {
// Do something when page scroll
},
onResize: function() {
// Do something when page resize
},
onTabItemTap(item) {
console.log(item.index)
console.log(item.pagePath)
console.log(item.text)
},
// Event handler.
viewTap: function() {
this.setData({
text: 'Set some data for updating view.'
}, function() {
// this is setData callback
})
},
customData: {
hi: 'MINA'
}
})
data
data 是页面第一次渲染使用的初始数据。
页面加载时，data 会以 JSON 字符串的形式从逻辑层传到渲染层，所以 data 中的数据必须是能转成 JSON 的类型：字符串、数字、布尔值、对象、数组。
渲染层可以通过 WXML 对数据进行绑定。
示例代码：
在开发者工具中预览效果
<view>{{text}}</view>
<view>{{array[0].msg}}</view>
Page({
data: {
text: 'init data',
array: [{msg: '1'}, {msg: '2'}]
}
})
生命周期回调函数
生命周期的触发以及页面的路由方式详见
onLoad(Object query)
页面加载时触发。一个页面只会调用一次，可以在 onLoad 的参数中获取打开当前页面路径中的参数。
参数：
| 名称 | 类型 | 说明 |
|---|---|---|
| query | Object | 打开当前页面路径中的参数 |
onShow()
页面显示或切入前台时触发。
onReady()
页面初次渲染完成时触发。一个页面只会调用一次，表示页面已经准备好，可以和视图层进行交互。
注意：对界面内容进行设置的 API 如 wx.setNavigationBarTitle，请在 onReady 之后进行。详见生命周期
onHide()
页面隐藏或切入后台时触发。例如使用 wx.navigateTo 或底部 tab 切换到其他页面，微信小程序切入后台等。
onUnload()
页面卸载时触发。例如使用 wx.redirectTo 或 wx.navigateBack 切换到其他页面时。
onRouteDone()
路由动画完成时触发。例如 wx.navigateTo 页面完全推入后，或 wx.navigateBack 页面完全恢复时。
页面事件处理函数
onPullDownRefresh()
监听用户下拉刷新事件。
- 需要在
app.json的window选项中或页面配置中开启enablePullDownRefresh。 - 可以通过 wx.startPullDownRefresh 触发下拉刷新，调用后会触发下拉刷新动画，效果与用户手动下拉刷新一致。
- 当处理完数据刷新后，wx.stopPullDownRefresh 可以停止当前页面的下拉刷新。
onReachBottom()
监听用户上拉触底事件。
- 可以在
app.json的window选项中或页面配置中设置触发距离onReachBottomDistance。 - 在触发距离内滑动期间，本事件只会被触发一次。
onPageScroll(Object object)
监听用户滑动页面事件。
参数 Object object:
| 属性 | 类型 | 说明 |
|---|---|---|
| scrollTop | Number | 页面在垂直方向已滚动的距离（单位 px） |
注意：请只在需要的时候才在 page 中定义此方法，不要定义空方法。以减少不必要的事件派发对渲染层-逻辑层通信的影响。 注意：请避免在 onPageScroll 中过于频繁的执行 setData 等引起逻辑层-渲染层通信的操作。尤其是每次传输大量数据，会影响通信耗时。
onAddToFavorites(Object object)
本接口为 Beta 版本，安卓 7.0.15 版本起支持，暂只在安卓平台支持
监听用户点击右上角菜单“收藏”按钮的行为，并自定义收藏内容。
参数 Object object:
| 参数 | 类型 | 说明 |
|---|---|---|
| webViewUrl | String | 页面中包含web-view组件时，返回当前web-view的url |
此事件处理函数需要 return 一个 Object，用于自定义收藏内容：
| 字段 | 说明 | 默认值 |
|---|---|---|
| title | 自定义标题 | 页面标题或账号名称 |
| imageUrl | 自定义图片，显示图片长宽比为 1：1 | 页面截图 |
| query | 自定义query字段 | 当前页面的query |
示例代码
Page({
onAddToFavorites(res) {
// webview 页面返回 webViewUrl
console.log('webViewUrl: ', res.webViewUrl)
return {
title: '自定义标题',
imageUrl: 'http://demo.png',
query: 'name=xxx&age=xxx',
}
}
})
onShareAppMessage(Object object)
监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为，并自定义转发内容。
注意：只有定义了此事件处理函数，右上角菜单才会显示“转发”按钮
参数 Object object:
| 参数 | 类型 | 说明 | 最低版本 |
|---|---|---|---|
| from | String | 转发事件来源。button：页面内转发按钮；menu：右上角转发菜单 | ‘1.2.4’ |
| target | Object | 如果 from 值是 button，则 target 是触发这次转发事件的 button，否则为 undefined | ‘1.2.4’ |
| webViewUrl | String | 页面中包含web-view组件时，返回当前web-view的url | ‘1.6.4’ |
此事件处理函数需要 return 一个 Object，用于自定义转发内容，返回内容如下：
自定义转发内容 基础库 ‘2.8.1’ 起，分享图支持云图片。
| 字段 | 说明 | 默认值 | 最低版本 |
|---|---|---|---|
| title | 转发标题 | 当前微信小程序名称 | |
| path | 转发路径 | 当前页面 path ，必须是以 / 开头的完整路径 | |
| imageUrl | 自定义图片路径，可以是本地文件路径、代码包文件路径或者网络图片路径。支持PNG及JPG。显示图片长宽比是 5:4。 | 使用默认截图 | ‘1.5.0’ |
| promise | 如果该参数存在，则以 resolve 结果为准，如果三秒内不 resolve，分享会使用上面传入的默认参数 | ‘2.12.0’ |
示例代码
在开发者工具中预览效果
Page({
onShareAppMessage() {
const promise = new Promise(resolve => {
setTimeout(() => {
resolve({
title: '自定义转发标题'
})
}, 2000)
})
return {
title: '自定义转发标题',
path: '/page/user?id=123',
promise
}
}
})
onShareTimeline()
基础库 ‘2.11.3’ 开始支持，低版本需做兼容处理。
详见分享到朋友圈
监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。
注意：只有定义了此事件处理函数，右上角菜单才会显示“分享到朋友圈”按钮
自定义转发内容
事件处理函数返回一个 Object，用于自定义分享内容，不支持自定义页面路径，返回内容如下：
| 字段 | 说明 | 默认值 | 最低版本 |
|---|---|---|---|
| title | 自定义标题，即朋友圈列表页上显示的标题 | 当前微信小程序名称 | |
| query | 自定义页面路径中携带的参数，如 path?a=1&b=2 的 “?” 后面部分 | 当前页面路径携带的参数 | |
| imageUrl | 自定义图片路径，可以是本地文件或者网络图片。支持 PNG 及 JPG，显示图片长宽比是 1:1。 | 默认使用微信小程序 Logo | |
| promise | 如果该参数存在，则以 resolve 结果为准，如果三秒内不 resolve，分享会使用上面传入的默认参数 | ‘3.12.0’ |
示例代码
Page({
onShareTimeline() {
const promise = new Promise(resolve => {
setTimeout(() => {
resolve({
title: '自定义转发标题'
})
}, 2000)
})
return {
title: '自定义转发标题',
query: 'id=123',
imageUrl: '/images/share.png',
promise
}
}
})
onResize(Object object)
基础库 ‘2.4.0’ 开始支持，低版本需做兼容处理。
页面尺寸改变时触发。详见 响应显示区域变化
onTabItemTap(Object object)
基础库 ‘1.9.0’ 开始支持，低版本需做兼容处理。
点击 tab 时触发
Object 参数说明：
| 参数 | 类型 | 说明 | 最低版本 |
|---|---|---|---|
| index | String | 被点击tabItem的序号，从0开始 | ‘1.9.0’ |
| pagePath | String | 被点击tabItem的页面路径 | ‘1.9.0’ |
| text | String | 被点击tabItem的按钮文字 | ‘1.9.0’ |
示例代码：
Page({
onTabItemTap(item) {
console.log(item.index)
console.log(item.pagePath)
console.log(item.text)
}
})
onSaveExitState()
基础库 ‘2.7.4’ 开始支持，低版本需做兼容处理。
每当微信小程序可能被销毁之前，页面回调函数 onSaveExitState 会被调用，可以进行退出状态的保存。
组件事件处理函数
Page 中还可以定义组件事件处理函数。在渲染层的组件中加入事件绑定，当事件被触发时，就会执行 Page 中定义的事件处理函数。
示例代码：
在开发者工具中预览效果
<view bindtap="viewTap"> click me </view>
Page({
viewTap: function() {
console.log('view tap')
}
})
Page.route
基础库 ‘1.2.0’ 开始支持，低版本需做兼容处理。
到当前页面的路径，类型为String。
Page({
onShow: function() {
console.log(this.route)
}
})
Page.prototype.setData(Object data, Function callback)
setData 函数用于将数据从逻辑层发送到视图层（异步），同时改变对应的 this.data 的值（同步）。
参数说明
| 字段 | 类型 | 必填 | 描述 | 最低版本 |
|---|---|---|---|---|
| data | Object | 是 | 这次要改变的数据 | |
| callback | Function | 否 | setData引起的界面更新渲染完毕后的回调函数 | ‘1.5.0’ |
Object 以 key: value 的形式表示，将 this.data 中的 key 对应的值改变成 value。
其中 key 可以以数据路径的形式给出，支持改变数组中的某一项或对象的某个属性，如 array[2].message，a.b.c.d，并且不需要在 this.data 中预先定义。
注意：
- 直接修改 this.data 而不调用 this.setData 是无法改变页面的状态的，还会造成数据不一致。
- 仅支持设置可 JSON 化的数据。
- 单次设置的数据不能超过1024kB，请尽量避免一次设置过多的数据。
- 请不要把 data 中任何一项的 value 设为
undefined，否则这一项将不被设置并可能遗留一些潜在问题。
示例代码：
在开发者工具中预览效果
<!--index.wxml-->
<view>{{text}}</view>
<button bindtap="changeText"> Change normal data </button>
<view>{{num}}</view>
<button bindtap="changeNum"> Change normal num </button>
<view>{{array[0].text}}</view>
<button bindtap="changeItemInArray"> Change Array data </button>
<view>{{object.text}}</view>
<button bindtap="changeItemInObject"> Change Object data </button>
<view>{{newField.text}}</view>
<button bindtap="addNewField"> Add new data </button>
// index.js
Page({
data: {
text: 'init data',
num: 0,
array: [{text: 'init data'}],
object: {
text: 'init data'
}
},
changeText: function() {
// this.data.text = 'changed data' // 不要直接修改 this.data
// 应该使用 setData
this.setData({
text: 'changed data'
})
},
changeNum: function() {
// 或者，可以修改 this.data 之后马上用 setData 设置一下修改了的字段
this.data.num = 1
this.setData({
num: this.data.num
})
},
changeItemInArray: function() {
// 对于对象或数组字段，可以直接修改一个其下的子字段，这样做通常比修改整个对象或数组更好
this.setData({
'array[0].text':'changed data'
})
},
changeItemInObject: function(){
this.setData({
'object.text': 'changed data'
});
},
addNewField: function() {
this.setData({
'newField.text': 'new data'
})
}
})
页面间通信
基础库 ‘2.7.3’ 开始支持，低版本需做兼容处理。
如果一个页面由另一个页面通过 wx.navigateTo 打开，这两个页面间将建立一条数据通道：
- 被打开的页面可以通过
this.getOpenerEventChannel()方法来获得一个EventChannel对象； wx.navigateTo的success回调中也包含一个EventChannel对象。
这两个 EventChannel 对象间可以使用 emit 和 on 方法相互发送、监听事件。
在开发者工具中预览效果
获取应用实例对象
获取到微信小程序全局唯一的 App 实例。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| allowDefault | boolean | false | 否 | 在 App 未定义时返回默认实现。当App被调用时，默认实现中定义的属性会被覆盖合并到App中。一般用于独立分包 | ‘2.2.4’ |
示例代码
// other.js
var appInstance = getApp()
console.log(appInstance.globalData) // I am global data
注意事项
- 不要在定义于
App()内的函数中，或调用App前调用getApp()，使用this就可以拿到 app 实例。 - 通过
getApp()获取实例之后，不要私自调用生命周期函数。
App(Object object)
注册微信小程序。接受一个 Object 参数，其指定微信小程序的生命周期回调等。
App() 必须在 app.js 中调用，必须调用且只能调用一次。不然会出现无法预期的后果。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
|---|---|---|---|---|---|
| onLaunch | function | 否 | 生命周期回调——监听微信小程序初始化。 | ||
| onShow | function | 否 | 生命周期回调——监听微信小程序启动或切前台。 | ||
| onHide | function | 否 | 生命周期回调——监听微信小程序切后台。 | ||
| onError | function | 否 | 错误监听函数。 | ||
| onPageNotFound | function | 否 | 页面不存在监听函数。 | ‘1.9.90’ | |
| onUnhandledRejection | function | 否 | 未处理的 Promise 拒绝事件监听函数。 | ‘2.10.0’ | |
| onThemeChange | function | 否 | 监听系统主题变化 | ‘2.11.0’ | |
| 其他 | any | 否 | 开发者可以添加任意的函数或数据变量到 Object 参数中，用 this 可以访问 |
关于微信小程序前后台的定义和微信小程序的运行机制，请参考运行机制章节。
onLaunch(Object object)
微信小程序初始化完成时触发，全局只触发一次。参数也可以使用 wx.getLaunchOptionsSync 获取。
参数：与 wx.getLaunchOptionsSync 一致
onShow(Object object)
微信小程序启动，或从后台进入前台显示时触发。也可以使用 wx.onAppShow 绑定监听。
参数：与 wx.onAppShow 一致
onHide()
微信小程序从前台进入后台时触发。也可以使用 wx.onAppHide 绑定监听。
参数：与 wx.onAppHide 一致
onError(String error)
微信小程序发生脚本错误或 API 调用报错时触发。也可以使用 wx.onError 绑定监听。
参数：与 wx.onError 一致
onPageNotFound(Object object)
基础库 ‘1.9.90’ 开始支持，低版本需做兼容处理。
微信小程序要打开的页面不存在时触发。也可以使用 wx.onPageNotFound 绑定监听。注意事项请参考 wx.onPageNotFound。
参数：与 wx.onPageNotFound 一致
示例代码：
App({
onPageNotFound(res) {
wx.redirectTo({
url: 'pages/...'
}) // 如果是 tabbar 页面，请使用 wx.switchTab
}
})
onUnhandledRejection(Object object)
基础库 ‘2.10.0’ 开始支持，低版本需做兼容处理。
微信小程序有未处理的 Promise 拒绝时触发。也可以使用 wx.onUnhandledRejection 绑定监听。注意事项请参考 wx.onUnhandledRejection。
参数：与 wx.onUnhandledRejection 一致
onThemeChange(Object object)
基础库 ‘2.11.0’ 开始支持，低版本需做兼容处理。
系统切换主题时触发。也可以使用 wx.onThemeChange 绑定监听。
参数：与 wx.onThemeChange 一致
示例代码
App({
onLaunch (options) {
// Do something initial when launch.
},
onShow (options) {
// Do something when show.
},
onHide (options) {
// Do something when hide.
},
onError (msg) {
console.log(msg)
},
globalData: 'I am global data'
})
场景值列表
关于场景值的详细说明和获取方式请参考 指南-场景值
| 场景值ID | 说明 | 图例 |
|---|---|---|
| 1000 | 其他 | / |
| 1001 | 发现页微信小程序「最近使用」列表（基础库2.2.4-2.29.0版本包含「我的微信小程序」列表，2.29.1版本起仅为「最近使用」列表） | / |
| 1005 | 微信首页顶部搜索框的搜索结果页 |  |
| 1006 | 发现栏微信小程序主入口搜索框的搜索结果页 |  |
| 1007 | 单人聊天会话中的微信小程序消息卡片 |  |
| 1008 | 群聊会话中的微信小程序消息卡片 |  |
| 1010 | 收藏夹 |  |
| 1011 | 扫描二维码 |  |
| 1012 | 长按图片识别二维码 |  |
| 1013 | 扫描手机相册中选取的二维码 |  |
| 1014 | 微信小程序订阅消息（与1107相同） |  |
| 1017 | 前往微信小程序体验版的入口页 |  |
| 1019 | 微信钱包（微信客户端7.0.0版本改为支付入口） |  |
| 1020 | 公众号 profile 页相关微信小程序列表（已废弃） |  |
| 1022 | 聊天顶部置顶微信小程序入口（微信客户端6.6.1版本起废弃） | / |
| 1023 | 安卓系统桌面图标 |  |
| 1024 | 微信小程序 profile 页 |  |
| 1025 | 扫描一维码 |  |
| 1026 | 发现栏微信小程序主入口，「附近的微信小程序」列表 |  |
| 1027 | 微信首页顶部搜索框搜索结果页「使用过的微信小程序」列表 |  |
| 1028 | 我的卡包 |  |
| 1029 | 微信小程序中的卡券详情页 |  |
| 1030 | 自动化测试下打开微信小程序 | / |
| 1031 | 长按图片识别一维码 |  |
| 1032 | 扫描手机相册中选取的一维码 |  |
| 1034 | 微信支付完成页 |  |
| 1035 | 公众号自定义菜单 |  |
| 1036 | App 分享消息卡片 |  |
| 1037 | 微信小程序打开微信小程序 |  |
| 1038 | 从另一个微信小程序返回 |  |
| 1039 | 摇电视 |  |
| 1042 | 添加好友搜索框的搜索结果页 |  |
| 1043 | 公众号模板消息 |  |
| 1044 | 带 shareTicket 的微信小程序消息卡片 详情 |  |
| 1045 | 朋友圈广告 |  |
| 1046 | 朋友圈广告详情页 |  |
| 1047 | 扫描微信小程序码 |  |
| 1048 | 长按图片识别微信小程序码 |  |
| 1049 | 扫描手机相册中选取的微信小程序码 |  |
| 1052 | 卡券的适用门店列表 |  |
| 1053 | 搜一搜的结果页 |  |
| 1054 | 顶部搜索框微信小程序快捷入口（微信客户端版本6.7.4起废弃） | / |
| 1056 | 聊天顶部音乐播放器右上角菜单 |  |
| 1057 | 钱包中的银行卡详情页 |  |
| 1058 | 公众号文章 |  |
| 1059 | 体验版微信小程序绑定邀请页 | / |
| 1060 | 微信支付完成页（与1034相同） | / |
| 1064 | 微信首页连Wi-Fi状态栏 |  |
| 1065 | URL scheme 详情 | / |
| 1067 | 公众号文章广告 |  |
| 1068 | 附近微信小程序列表广告（已废弃） | / |
| 1069 | 移动应用通过openSDK进入微信，打开微信小程序 |  |
| 1071 | 钱包中的银行卡列表页 |  |
| 1072 | 二维码收款页面 |  |
| 1073 | 客服消息列表下发的微信小程序消息卡片 |  |
| 1074 | 公众号会话下发的微信小程序消息卡片 |  |
| 1077 | 摇周边 |  |
| 1078 | 微信连Wi-Fi成功提示页 |  |
| 1079 | 微信游戏中心 |  |
| 1081 | 客服消息下发的文字链 |  |
| 1082 | 公众号会话下发的文字链 |  |
| 1084 | 朋友圈广告原生页 |  |
| 1088 | 会话中查看系统消息，打开微信小程序 | / |
| 1089 | 微信聊天主界面下拉，「最近使用」栏（基础库2.2.4-2.29.0版本包含「我的微信小程序」栏，2.29.1版本起仅为「最近使用」栏） |  |
| 1090 | 长按微信小程序右上角菜单唤出最近使用历史 |  |
| 1091 | 公众号文章商品卡片 |  |
| 1092 | 城市服务入口 |  |
| 1095 | 微信小程序广告组件 |  |
| 1096 | 聊天记录，打开微信小程序 |  |
| 1097 | 微信支付签约原生页，打开微信小程序 |  |
| 1099 | 页面内嵌插件 | / |
| 1100 | 红包封面详情页打开微信小程序 |  |
| 1101 | 远程调试热更新（开发者工具中，预览 -> 自动预览 -> 编译并预览） |  |
| 1102 | 公众号 profile 页服务预览 |  |
| 1103 | 发现页微信小程序「我的微信小程序」列表（基础库2.2.4-2.29.0版本废弃，2.29.1版本起生效） | / |
| 1104 | 微信聊天主界面下拉，「我的微信小程序」栏（基础库2.2.4-2.29.0版本废弃，2.29.1版本起生效） | / |
| 1106 | 聊天主界面下拉，从顶部搜索结果页，打开微信小程序 | / |
| 1107 | 订阅消息，打开微信小程序 | / |
| 1113 | 安卓手机负一屏，打开微信小程序（三星） | / |
| 1114 | 安卓手机侧边栏，打开微信小程序（三星） | / |
| 1119 | 【企业微信】工作台内打开微信小程序 |  |
| 1120 | 【企业微信】个人资料页内打开微信小程序 |  |
| 1121 | 【企业微信】聊天加号附件框内打开微信小程序 |  |
| 1124 | 扫“一物一码”打开微信小程序 | / |
| 1125 | 长按图片识别“一物一码” | / |
| 1126 | 扫描手机相册中选取的“一物一码” | / |
| 1129 | 微信爬虫访问 | / |
| 1131 | 浮窗（8.0版本起仅包含被动浮窗） | / |
| 1133 | 硬件设备打开微信小程序 详情 | / |
| 1135 | 微信小程序profile页相关微信小程序列表，打开微信小程序 |  |
| 1144 | 公众号文章 – 视频贴片 |  |
| 1145 | 发现栏 – 发现微信小程序 |  |
| 1146 | 打开地理位置信息，进入出行类微信小程序 |  |
| 1148 | 卡包中的交通卡，打开微信小程序 | / |
| 1150 | 扫一扫商品条码后，在结果页打开微信小程序 |  |
| 1151 | 发现栏中的“我的订单” |  |
| 1152 | 订阅号视频中打开微信小程序 |  |
| 1153 | “识物”功能的结果页中打开微信小程序 |  |
| 1154 | 在朋友圈内打开“单页模式” |  |
| 1155 | 通过“单页模式”打开微信小程序 |  |
| 1157 | 服务号会话页面中打开微信小程序 |  |
| 1158 | 群工具中打开微信小程序 |  |
| 1160 | 群待办 |  |
| 1167 | H5 页面通过开放标签打开微信小程序 详情 | / |
| 1168 | 移动应用或网站应用直接运行微信小程序 | / |
| 1169 | 发现栏中微信小程序的主入口，以及各个生活服务入口（例如快递服务、出行服务等） |  |
| 1171 | 微信运动记录（仅限安卓系统） |  |
| 1173 | 聊天中的素材通过微信小程序打开 详情 |  |
| 1175 | 视频号主页的商店入口 |  |
| 1176 | 视频号直播间中，主播打开微信小程序 |  |
| 1177 | 视频号直播中的商品 |  |
| 1178 | 在电脑上打开手机上正在使用的微信小程序 |  |
| 1179 | 通过#话题页打开微信小程序 |  |
| 1181 | 网站应用打开PC版微信小程序 | / |
| 1183 | PC微信 – 微信小程序面板 – 发现微信小程序 – 搜索 |  |
| 1184 | 视频号链接打开微信小程序 |  |
| 1185 | 群公告 |  |
| 1186 | 收藏中的笔记 |  |
| 1187 | 浮窗（从8.0版本开始）或星标 |  |
| 1189 | 表情雨广告 |  |
| 1191 | 视频号活动 |  |
| 1192 | 企业微信联系人的个人资料页 |  |
| 1193 | 视频号主页的服务菜单中打开微信小程序 |  |
| 1194 | URL Link 详情 | / |
| 1195 | 视频号主页的商品标签页 |  |
| 1196 | 个人状态中打开微信小程序 |  |
| 1197 | 视频号主播从直播间返回小游戏 |  |
| 1198 | 视频号开播界面中打开小游戏 |  |
| 1200 | 视频号广告中打开微信小程序 |  |
| 1201 | 视频号广告详情页中打开微信小程序 |  |
| 1202 | 企业微信客服号会话中打开微信小程序卡片 |  |
| 1203 | 微信小程序压测工具的请求 | / |
| 1206 | 视频号小游戏直播间中打开小游戏 |  |
| 1207 | 企业微信客服号会话中打开微信小程序文字链接 |  |
| 1208 | 聊天中打开商品卡片 |  |
| 1212 | 青少年模式申请页面中打开微信小程序 |  |
| 1215 | 广告预约中打开微信小程序 | / |
| 1216 | 视频号订单中心打开微信小程序 |  |
| 1217 | 蓝牙设备后台唤醒微信小程序 | / |
| 1218 | 微信键盘预览打开微信小程序 | / |
| 1219 | 视频号直播间小游戏一键上车 |  |
| 1220 | 发现页设备卡片打开微信小程序 |  |
| 1223 | 安卓桌面Widget打开微信小程序 |  |
| 1224 | “微信小程序商家助手”功能打开微信小程序 | / |
| 1225 | 音视频通话打开微信小程序 |  |
| 1226 | 聊天消息在设备打开后打开微信小程序 |  |
| 1228 | 视频号原生广告组件打开微信小程序 |  |
| 1230 | 订阅号H5广告进入微信小程序 |  |
| 1231 | 动态消息提醒入口打开微信小程序 |  |
| 1232 | 搜一搜竞价广告打开微信小程序 |  |
| 1233 | 微信小程序搜索页人气游戏模块打开小游戏 |  |
| 1238 | 看一看信息流广告打开微信小程序 |  |
| 1239 | 视频号小游戏直播间气泡浮窗打开小游戏 | / |
| 1242 | 微信小程序发现页门店快送模块频道页进入微信小程序 |  |
| 1243 | 微信小程序发现页门店快送模块商品聚合页进入微信小程序 | / |
| 1244 | #tag搜索结果页打开微信小程序 | / |
| 1245 | 微信小程序发现页门店快送搜索结果页进入微信小程序 |  |
| 1248 | 通过微信小程序账号迁移进入微信小程序 | / |
| 1252 | 搜一搜微信小程序搜索页「小功能」模块进入微信小程序 |  |
| 1254 | 发现页「动态」卡片 打开微信小程序 |  |
| 1255 | 发现页「我的」卡片 打开微信小程序 | / |
| 1256 | PC端微信小程序面板「最近使用」列表 |  |
| 1257 | PC端微信小程序面板「我的微信小程序」列表 | |
| 1258 | PC端微信小程序面板「为电脑端优化」模块 | |
| 1259 | PC端微信小程序面板「小游戏专区」模块 | |
| 1260 | PC端微信小程序面板「推荐在电脑端使用」列表 | |
| 1261 | 公众号返佣商品卡片 |  |
| 1265 | 微信小程序图片详情页打开微信小程序 |  |
| 1266 | 微信小程序图片长按半屏入口打开微信小程序 |  |
| 1267 | 微信小程序图片会话角标打开微信小程序 |  |
| 1271 | 微信聊天主界面下拉，「我的常用微信小程序」栏 | |
| 1272 | 发现页「游戏」服务标签打开微信小程序 |  |
| 1273 | 发现页「常用的微信小程序」列表 |  |
| 1274 | 优量汇广告打开微信小程序 | / |
| 1275 | 发现页短剧卡片打开微信小程序 | / |
| 1276 | 发现页短剧卡片二级聚合页打开微信小程序 | / |
| 1277 | 发现页短剧卡片搜索结果页打开微信小程序 | / |
| 1278 | 发现页「发现微信小程序」列表打开微信小程序 | / |
| 1279 | 发现页「发现微信小程序」合集页打开微信小程序 | / |
| 1280 | 下拉任务栏微信小程序垂搜「建议使用」打开微信小程序 | / |
| 1281 | 下拉任务栏微信小程序垂搜「发现微信小程序」打开微信小程序 | / |
| 1282 | 听一听播放器打开微信小程序 |  |
| 1285 | 发现页「发现微信小程序」短剧合集打开微信小程序 | / |
| 1286 | 明文scheme打开微信小程序 | / |
| 1287 | 公众号短剧贴片打开微信小程序 | / |
| 1292 | 发现页「发现微信小程序」POI详情页打开微信小程序 | / |
| 1293 | 发现页短剧卡片追剧页打开微信小程序 | / |
| 1295 | 下拉任务栏微信小程序垂搜「发现微信小程序」广告打开微信小程序 | / |
| 1296 | 视频号付费短剧气泡打开微信小程序 | / |
| 1297 | 发现-微信小程序-搜索「发现微信小程序」打开微信小程序 | / |
| 1298 | 下拉任务栏微信小程序垂搜「发现微信小程序」打开的合集访问微信小程序 | / |
| 1299 | 下拉任务栏微信小程序垂搜「发现微信小程序」POI详情页打开微信小程序 | / |
| 1300 | 发现-微信小程序-搜索「发现微信小程序」打开的合集访问微信小程序 | / |
| 1301 | 发现-微信小程序-搜索「发现微信小程序」poi 详情页打开微信小程序 | / |
| 1302 | PC端面板「发现微信小程序」 | / |
| 1303 | 发现页短剧卡片视频流打开微信小程序 | / |
| 1304 | 手机负一屏打开微信小程序（比如oppo手机） | / |
| 1305 | 公众号播放结束页打开微信小程序 | / |
| 1306 | 公众号短剧固定选集入口打开微信小程序 | / |
| 1307 | 发现页附近服务境外专区打开微信小程序 |  |
| 1308 | PC端面板小游戏专区页面 | / |
| 1311 | 公众号文章打开小游戏CPS卡片 | / |
| 1313 | PC OpenSDK打开微信小程序 | / |
| 1325 | 聊天工具模式分享的表情包消息角标打开微信小程序 | / |
| 1326 | 聊天工具模式分享的角标打开微信小程序 | / |
| 1327 | 聊天工具模式分享的文本消息角标打开微信小程序 | / |
| 1328 | 聊天工具模式分享的文本消息超链接打开微信小程序 | / |
| 1336 | 小店打开微信小程序关联会员身份 | / |
| 1337 | 小店确认订单页跳微信小程序使用会员权益 | / |
| 1340 | 微信小程序profile-热门商品入口打开微信小程序 | / |
| 1346 | PC OpenSDK分享微信小程序卡片 | / |
页面配置
app.json 中的部分配置，也支持对单个页面进行配置，可以在页面对应的 .json 文件来对本页面的表现进行配置。
页面中配置项在当前页面会覆盖 app.json 中相同的配置项（样式相关的配置项属于 app.json 中的 window 属性，但这里不需要额外指定 window 字段），具体的取值和含义可参考全局配置文档中说明。
文件内容为一个 JSON 对象，有以下属性：
配置项
| 属性 | 类型 | 默认值 | 描述 | 最低版本 |
|---|---|---|---|---|
| navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色，如 #000000 | |
| navigationBarTextStyle | string | white | 导航栏标题、状态栏颜色，仅支持 black / white | |
| navigationBarTitleText | string | 导航栏标题文字内容 | ||
| navigationStyle | string | default | 导航栏样式，仅支持以下值：default 默认样式custom 自定义导航栏，只保留右上角胶囊按钮。 | iOS/Android 微信客户端 7.0.0，Windows/Mac 端基础库 >= v3.6.1 |
| homeButton | boolean | false | 在非首页、非页面栈最底层页面或非tabbar内页面中的导航栏展示home键 | 微信客户端 8.0.24 |
| backgroundColor | HexColor | #ffffff | 窗口的背景色 | |
| backgroundColorContent | HexColor | #RRGGBBAA | 页面容器背景色，点击查看设置背景色详情 | |
| backgroundTextStyle | string | dark | 下拉 loading 的样式，仅支持 dark / light | |
| backgroundColorTop | string | #ffffff | 顶部窗口的背景色，仅 iOS 支持 | 微信客户端 6.5.16 |
| backgroundColorBottom | string | #ffffff | 底部窗口的背景色，仅 iOS 支持 | 微信客户端 6.5.16 |
| enablePullDownRefresh | boolean | false | 是否开启当前页面下拉刷新。 详见 Page.onPullDownRefresh | |
| onReachBottomDistance | number | 50 | 页面上拉触底事件触发时距页面底部距离，单位为px。 详见 Page.onReachBottom | |
| pageOrientation | string | portrait | 屏幕旋转设置，支持 auto / portrait / landscape 详见 响应显示区域变化 | ‘2.4.0’ (auto) / ‘2.5.0’ (landscape) |
| disableScroll | boolean | false | 设置为 true 则页面整体不能上下滚动。只在页面配置中有效，无法在 app.json 中设置 | |
| usingComponents | Object | 否 | 页面自定义组件配置 | ‘1.6.3’ |
| initialRenderingCache | string | 页面初始渲染缓存配置，支持 static / dynamic / capture | ‘2.11.1’ | |
| style | string | default | 启用新版的组件样式 | ‘2.10.2’ |
| singlePage | Object | 否 | 单页模式相关配置 | ‘2.12.0’ |
| restartStrategy | string | homePage | 重新启动策略配置 | ‘2.8.0’ |
| handleWebviewPreload | string | static | 控制预加载下个页面的时机。支持 static / manual / auto | ‘2.15.0’ |
| visualEffectInBackground | string | 否 | 切入系统后台时，隐藏页面内容，保护用户隐私。支持 hidden / none，若对页面单独设置则会覆盖全局的配置，详见 全局配置 | ‘2.15.0’ |
| enablePassiveEvent | Object或boolean | 否 | 事件监听是否为 passive，若对页面单独设置则会覆盖全局的配置，详见 全局配置 | ‘2.24.1’ |
| renderer | string | 否 | 渲染后端 | ‘2.30.4’ |
| rendererOptions | Object | 否 | 渲染后端选项，详情相关文档 | ‘3.1.0’ |
| componentFramework | string | 否 | 组件框架，详情相关文档 | ‘2.30.4’ |
- 注：并不是所有
app.json中的配置都可以在页面覆盖或单独指定，仅限于本文档包含的选项。 - 注：iOS/Android 客户端 7.0.0 以下版本，
navigationStyle只在app.json中生效。
配置示例
{
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
全局配置
微信小程序根目录下的 app.json 文件用来对微信小程序进行全局配置。文件内容为一个 JSON 对象，有以下属性：
配置项
| 属性 | 类型 | 必填 | 描述 | 最低版本 |
|---|---|---|---|---|
| entryPagePath | string | 否 | 微信小程序默认启动首页 | |
| 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[] | 否 | 需要在后台使用的能力，如「音乐播放」 | |
| requiredPrivateInfos | string[] | 否 | 调用的地理位置相关隐私接口 | |
| plugins | Object | 否 | 使用到的插件 | ‘1.9.6’ |
| preloadRule | Object | 否 | 分包预下载规则 | ‘2.3.0’ |
| resizable | boolean | 否 | PC 微信小程序是否支持用户任意改变窗口大小（包括最大化窗口）；iPad 微信小程序是否支持屏幕旋转。默认关闭 | ‘2.3.0’ |
| usingComponents | Object | 否 | 全局自定义组件配置 | 开发者工具 1.02.1810190 |
| permission | Object | 否 | 微信小程序接口权限相关设置 | 微信客户端 7.0.0 |
| sitemapLocation | string | 是 | 指明 sitemap.json 的位置 | |
| style | string | 否 | 指定使用升级后的weui样式 | ‘2.8.0’ |
| useExtendedLib | Object | 否 | 指定需要引用的扩展库 | ‘2.2.1’ |
| entranceDeclare | Object | 否 | 微信消息用微信小程序打开 | 微信客户端 7.0.9 |
| darkmode | boolean | 否 | 微信小程序支持 DarkMode | ‘2.11.0’ |
| themeLocation | string | 否 | 指明 theme.json 的位置，darkmode为true为必填 | 开发者工具 1.03.2004271 |
| lazyCodeLoading | string | 否 | 配置自定义组件代码按需注入 | ‘2.11.1’ |
| singlePage | Object | 否 | 单页模式相关配置 | ‘2.12.0’ |
| supportedMaterials | Object | 否 | 聊天素材微信小程序打开相关配置 | ‘2.14.3’ |
| serviceProviderTicket | string | 否 | 定制化型服务商票据 | |
| embeddedAppIdList | string[] | 否 | 半屏微信小程序 appId | ‘2.20.1’ |
| halfPage | Object | 否 | 视频号直播半屏场景设置 | ‘2.18.0’ |
| debugOptions | Object | 否 | 调试相关配置 | ‘2.22.1’ |
| enablePassiveEvent | Object或boolean | 否 | touch 事件监听是否为 passive | ‘2.24.1’ |
| resolveAlias | Object | 否 | 自定义模块映射规则 | |
| renderer | string | 否 | 全局默认的渲染后端 | ‘2.30.4’ |
| rendererOptions | Object | 否 | 渲染后端选项 | ‘2.31.1’ |
| componentFramework | string | 否 | 组件框架，详见相关文档 | ‘2.30.4’ |
| miniApp | Object | 否 | 多端模式场景接入身份管理服务时开启微信小程序授权页相关配置，详见相关文档 | |
| static | Object | 否 | 正常情况下默认所有资源文件都被打包发布到所有平台，可以通过 static 字段配置特定每个目录/文件只能发布到特定的平台(多端场景) 相关文档 | |
| convertRpxToVw | boolean | 否 | 配置是否将 rpx 单位转换为 vw 单位，开启后能修复某些 rpx 下的精度问题 | ‘3.3.0’ |
| chatTools | Object | 否 | 聊天工具分包配置 | ‘3.7.8’ |
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
用于设置微信小程序的状态栏、导航条、标题、窗口背景色。
| 属性 | 类型 | 默认值 | 描述 | 最低版本 |
|---|---|---|---|---|
| navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色，如 #000000 | |
| navigationBarTextStyle | string | white | 导航栏标题、状态栏颜色，仅支持 black / white | |
| navigationBarTitleText | string | 导航栏标题文字内容 | ||
| navigationStyle | string | default | 导航栏样式，仅支持以下值：default 默认样式custom 自定义导航栏，只保留右上角胶囊按钮。参见注 2。 | iOS/Android 微信客户端 6.6.0，Windows/Mac 微信基础库 3.6.1 |
| homeButton | boolean | false | 在非首页、非页面栈最底层页面或非tabbar内页面中的导航栏展示home键 | 微信客户端 8.0.24 |
| backgroundColor | HexColor | #ffffff | 窗口的背景色 | |
| backgroundTextStyle | string | dark | 下拉 loading 的样式，仅支持 dark / light | |
| backgroundColorTop | string | #ffffff | 顶部窗口的背景色，仅 iOS 支持 | 微信客户端 6.5.16 |
| backgroundColorBottom | string | #ffffff | 底部窗口的背景色，仅 iOS 支持 | 微信客户端 6.5.16 |
| enablePullDownRefresh | boolean | false | 是否开启全局的下拉刷新。 详见 Page.onPullDownRefresh | |
| onReachBottomDistance | number | 50 | 页面上拉触底事件触发时距页面底部距离，单位为 px。 详见 Page.onReachBottom | |
| pageOrientation | string | portrait | 屏幕旋转设置，支持 auto / portrait / landscape 详见 响应显示区域变化 | ‘2.4.0’ (auto) / ‘2.5.0’ (landscape) |
| restartStrategy | string | homePage | 重新启动策略配置 | ‘2.8.0’ |
| initialRenderingCache | string | 页面初始渲染缓存配置，支持 static / dynamic | ‘2.11.1’ | |
| visualEffectInBackground | string | none | 切入系统后台时，隐藏页面内容，保护用户隐私。支持 hidden / none | ‘2.15.0’ |
| handleWebviewPreload | string | static | 控制预加载下个页面的时机。支持 static / manual / auto | ‘2.15.0’ |
- 注 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（不代表最低版本，只供调试用）可方便切到旧视觉
- iOS/Android 客户端 7.0.0 以下版本，
restartStrategy
基础库 ‘2.8.0’ 开始支持，低版本需做兼容处理。
重新启动策略配置
| 可选值 | 含义 |
|---|---|
| homePage | （默认值）如果从这个页面退出微信小程序，下次将从首页冷启动 |
| homePageAndLatestPage | 如果从这个页面退出微信小程序，下次冷启动后立刻加载这个页面，页面的参数保持不变（不可用于 tab 页） |
如：
{
"window": {
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "微信接口功能演示",
"backgroundColor": "#eeeeee",
"backgroundTextStyle": "light"
}
}
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，不支持网络图片。 当 position 为 top 时，不显示 icon。 |
| selectedIconPath | string | 否 | 选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81px * 81px，不支持网络图片。 当 position 为 top 时，不显示 icon。 |
networkTimeout
各类网络请求的超时时间，单位均为毫秒。
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| request | number | 否 | 60000 | wx.request 的超时时间，单位：毫秒。 |
| connectSocket | number | 否 | 60000 | wx.connectSocket 的超时时间，单位：毫秒。 |
| uploadFile | number | 否 | 60000 | wx.uploadFile 的超时时间，单位：毫秒。 |
| downloadFile | number | 否 | 60000 | wx.downloadFile 的超时时间，单位：毫秒。 |
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，结构为：
| 属性 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| scope.userLocation | PermissionObject | 否 | 位置相关权限声明 |
PermissionObject 结构
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| desc | string | 是 | 微信小程序获取权限时展示的接口用途说明。最长 30 个字符 |
如：
{
"pages": ["pages/index/index"],
"permission": {
"scope.userLocation": {
"desc": "你的位置信息将用于微信小程序位置接口的效果展示" // 高速公路行驶持续后台定位
}
}
}
sitemapLocation
指明 sitemap.json 的位置；默认为 ‘sitemap.json’ 即在 app.json 同级目录下名字的 sitemap.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) 后打开会进入单页模式
单页模式相关配置
| 属性 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| navigationBarFit | String | 否 | 默认自动调整，若原页面是自定义导航栏，则为 float，否则为 squeezed | 导航栏与页面的相交状态，值为 float 时表示导航栏浮在页面上，与页面相交；值为 squeezed 时表示页面被导航栏挤压，与页面不相交 |
embeddedAppIdList
指定微信小程序可通过wx.openEmbeddedMiniProgram打开的微信小程序名单。
{
"embeddedAppIdList": ["wxe5f52902cf4de896"]
}
halfPage
| 属性 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| firstPageNavigationStyle | string | 否 | 视频号直播打开的第一个页面的全屏状态使用自定义顶部，支持 default / custom |
{
"halfPage": {
"firstPageNavigationStyle": "custom"
}
}
debugOptions
微信小程序调试相关配置项
| 属性 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| enableFPSPanel | boolean | 否 | false | 是否开启 FPS 面板 |
{
"debugOptions": {
"enableFPSPanel": "false"
}
}
enablePassiveEvent
touch 相关事件默认的 passive 为 false。如果微信小程序不使用 catchtouch* 事件时，可以通过这个选项将 passive 置为 true，以提高滚动性能。具体原理可参考MDN。
可以直接设置这个选项为 true，也可以分别控制某个事件。
{
"enablePassiveEvent": true
}
| 属性 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| touchstart | boolean | 否 | false | 是否设置 touchstart 事件为 passive |
| touchmove | boolean | 否 | false | 是否设置 touchmove 事件为 passive |
| wheel | boolean | 否 | false | 是否设置 wheel 事件为 passive |
{
"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.jssubBUtils/mod.js->subpackageB/utils/mod.js
- 如果在 project.config.json 中指定了 miniprogramRoot，则
/*指代的根目录是 miniprogramRoot 对应的路径，而不是开发者工具项目的根目录
renderer
指定微信小程序全局的默认渲染后端。
可选值：webview, skyline
默认值：webview
rendererOptions
微信小程序渲染后端的相关配置选项
| 属性 | 类型 |
|---|---|
| skyline | SkylineOptions |
SkylineOptions
Skyline 渲染引擎的相关配置项
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| defaultDisplayBlock | boolean | false | 开启默认 Block 布局 |
| defaultContentBox | boolean | false | 开启默认 ContentBox 盒模型 |
| tagNameStyleIsolation | string | ‘isolated’ | 开启 tag 选择器全局匹配 |
| enableScrollViewAutoSize | boolean | false | 开启scroll-view自动撑开 |
| disableABTest | boolean | false | 关闭 Skyline AB 实验 |
{
"rendererOptions": {
"skyline": {
"disableABTest": true,
"defaultDisplayBlock": true,
"defaultContentBox": true,
"tagNameStyleIsolation": "legacy",
"enableScrollViewAutoSize": true,
}
}
}
componentFramework
指定微信小程序使用的组件框架
可选值：exparser, glass-easel
默认值：exparser
chatTools
指定聊天工具对应的独立分包
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| root | string | 是 | 分包根目录 |
| entryPagePath | string | 是 | 聊天工具启动路径 |
| desc | string | 是 | 聊天工具描述 |
| scopes | string[] | 否 | 分包中会使用的scope权限 |
{
"chatTools": [
{
"root": "packageChatTool",
"entryPagePath": "pages/activity_create/index",
"desc": "群签到工具",
"scopes": [
"scope.userLocation"
]
}
]
}
配置示例
{
"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,
}