微信小程序 – 第 3 页 – 微信小程序开发指南

wx.offPageNotFound(function listener)

基础库 2.1.2 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

移除微信小程序要打开的页面不存在事件的监听函数

参数

function listener

onPageNotFound 传入的监听函数。不传此参数则移除所有监听函数。

示例代码

const listener = function (res) { console.log(res) }

wx.onPageNotFound(listener)
wx.offPageNotFound(listener) // 需传入与监听时同一个的函数对象

wx.offThemeChange(function listener)

基础库 2.11.0 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

相关文档: DarkMode 适配指南

功能描述

移除系统主题改变事件的监听函数

参数

function listener

onThemeChange 传入的监听函数。不传此参数则移除所有监听函数。

示例代码

const listener = function (res) { console.log(res) }

wx.onThemeChange(listener)
wx.offThemeChange(listener) // 需传入与监听时同一个的函数对象

wx.offUnhandledRejection(function listener)

基础库 2.10.0 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

移除未处理的 Promise 拒绝事件的监听函数

参数

function listener

onUnhandledRejection 传入的监听函数。不传此参数则移除所有监听函数。

示例代码

const listener = function (res) { console.log(res) }

wx.onUnhandledRejection(listener)
wx.offUnhandledRejection(listener) // 需传入与监听时同一个的函数对象

wx.onAppHide(function listener)

基础库 2.1.2 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

监听微信小程序切后台事件。该事件与 App.onHide 的回调参数一致。

参数

function listener

微信小程序切后台事件的监听函数

参数

Object options

切后台参数

属性

类型

说明

最低版本

reason

number

原因

3.5.7

合法值	说明
0	用户退出微信小程序
1	进入其他微信小程序
2	打开原生功能页
3	其他

wx.onAppShow(function listener)

基础库 2.1.2 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

监听微信小程序切前台事件。该事件与 App.onShow 的回调参数一致。

参数

function listener

微信小程序切前台事件的监听函数

参数

Object options

启动参数

属性类型说明最低版本

path string 启动微信小程序的路径 (代码包路径)

scene number 启动微信小程序的场景值

query Record. 启动微信小程序的 query 参数

shareTicket string shareTicket，详见获取更多转发信息

referrerInfo Object 来源信息。从另一个微信小程序、公众号或 App 进入微信小程序时返回。否则返回 {}。(参见后文注意)

	结构属性	类型	说明
	appId	string	来源微信小程序、公众号或 App 的 appId
	extraData	Object	来源微信小程序传过来的数据，scene=1037或1038时支持

forwardMaterials Array.<Object> 打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数

结构属性	类型	说明
type	string	文件的mimetype类型
name	string	文件名
path	string	文件路径（如果是webview则是url）
size	number	文件大小

chatType number 从微信群聊/单聊打开微信小程序时，chatType 表示具体微信群聊/单聊类型

合法值	说明
1	微信联系人单聊
2	企业微信联系人单聊
3	普通微信群聊
4	企业微信互通群聊

hostExtraData Object 宿主传递的数据，第三方 app 中运行微信小程序时返回

	结构属性	类型	说明
	host_scene	string	宿主app对应的场景值

apiCategory string API 类别 2.20.0

合法值	说明
default	默认类别
nativeFunctionalized	原生功能化，视频号直播商品、商品橱窗等场景打开的微信小程序
browseOnly	仅浏览，朋友圈快照页等场景打开的微信小程序
embedded	内嵌，通过打开半屏微信小程序能力打开的微信小程序
chatTool	聊天工具，通过打开聊天工具能力打开的微信小程序

返回有效 referrerInfo 的场景

场景值	场景	appId含义
1020	公众号 profile 页相关微信小程序列表	来源公众号
1035	公众号自定义菜单	来源公众号
1036	App 分享消息卡片	来源App
1037	微信小程序打开微信小程序	来源微信小程序
1038	从另一个微信小程序返回	来源微信小程序
1043	公众号模板消息	来源公众号

不同 apiCategory 场景下的 API 限制

X 表示 API 被限制无法使用；不在表格中的 API 不限制。

	nativeFunctionalized	browseOnly	embedded	chatTool
openSetting		`X`
`<button open-type="share">`	`X`	`X`	`X`	`X`
`<button open-type="feedback">`		`X`
`<button open-type="open-setting">`		`X`
navigateToMiniProgram	`X`	`X`		`X`
openEmbeddedMiniProgram	`X`	`X`	`X`	`X`
openOfficialAccountArticle				`X`
openChannelsUserProfile				`X`
ad				`X`
ad-custom				`X`
微信小程序菜单分享				`X`

注意

部分版本在无referrerInfo的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。

wx.onAudioInterruptionBegin(function listener)

基础库 2.6.2 开始支持，低版本需做兼容处理。

微信小程序插件：支持，需要微信小程序基础库版本不低于 2.15.0

微信 Windows 版：支持

微信 Mac 版：支持

功能描述

监听音频因为受到系统占用而被中断开始事件。以下场景会触发此事件：闹钟、电话、FaceTime 通话、微信语音聊天、微信视频聊天、有声广告开始播放、实名认证页面弹出等。此事件触发后，微信小程序内所有音频会暂停。

参数

function listener

音频因为受到系统占用而被中断开始事件的监听函数

wx.onAudioInterruptionEnd(function listener)

基础库 2.6.2 开始支持，低版本需做兼容处理。

微信小程序插件：支持，需要微信小程序基础库版本不低于 2.15.0

微信 Windows 版：支持

微信 Mac 版：支持

功能描述

监听音频中断结束事件。在收到 onAudioInterruptionBegin 事件之后，微信小程序内所有音频会暂停，收到此事件之后才可再次播放成功

参数

function listener

音频中断结束事件的监听函数

wx.onError(function listener)

基础库 2.1.2 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

监听微信小程序错误事件。比如脚本错误或 API 调用报错等。这个事件与 App.onError 的回调时机和参数是一样的。

参数

function listener

微信小程序错误事件的监听函数

参数

object error

错误

属性	类型	说明
message	string	错误信息，包含堆栈

wx.onLazyLoadError(function listener)

基础库 2.24.3 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

相关文档: 分包异步化

功能描述

监听微信小程序异步组件加载失败事件。

参数

function listener

微信小程序异步组件加载失败事件的监听函数

参数

Object res

属性	类型	说明
type	string	‘subpackage’ 失败类型
subpackage	Array	异步组件所属的分包
errMsg	string	详细信息

注意

加载异步组件通常需要下载分包，若分包下载超时，则会触发 errMsg 为 “loadSubpackage: timeout” 的回调，默认超时等待时间为 10 秒。
可以通过第二个参数指定超时时间（单位：ms），该设置全局有效，多次指定超时时间则覆盖前面。
分包确认下载失败时，会再次触发 errMsg 为 “loadSubpackage: fail” 的回调。
若在页面中使用该接口进行监听，请确保在必要时手动调用 offLazyLoadError 取消监听，以避免非预期的内存泄漏。

wx.onPageNotFound(function listener)

基础库 2.1.2 开始支持，低版本需做兼容处理。

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

监听微信小程序要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致。

参数

function listener

微信小程序要打开的页面不存在事件的监听函数

参数

Object res

属性	类型	说明
path	string	不存在页面的路径 (代码包路径)
query	Record.	打开不存在页面的 query 参数
isEntryPage	boolean	是否本次启动的首个页面（例如从分享等入口进来，首个页面是开发者配置的分享页面）

注意

开发者可以在回调中进行页面重定向，但必须在回调中同步处理，异步处理（例如 setTimeout 异步执行）无效。
若开发者没有调用 wx.onPageNotFound 绑定监听，也没有声明 App.onPageNotFound，当跳转页面不存在时，将推入微信客户端原生的页面不存在提示页面。
如果回调中又重定向到另一个不存在的页面，将推入微信客户端原生的页面不存在提示页面，并且不再第二次回调。