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

wx.onThemeChange(function listener)

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

微信小程序插件：不支持

相关文档: DarkMode 适配指南

功能描述

监听系统主题改变事件。该事件与 App.onThemeChange 的回调时机一致。

参数

function listener

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

参数

Object res

属性类型说明

theme string 系统当前的主题，取值为light或dark

合法值	说明
dark	深色主题
light	浅色主题

注意

只有在全局配置”darkmode”: true时才会触发此事件。

wx.onUnhandledRejection(function listener)

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

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

监听未处理的 Promise 拒绝事件。该事件与 App.onUnhandledRejection 的回调时机与参数一致。

参数

function listener

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

参数

Object res

属性	类型	说明
reason	string	拒绝原因，一般是一个 Error 对象
promise	Promise.`<any>`	被拒绝的 Promise 对象

注意

所有的 unhandledRejection 都可以被这一监听捕获，但只有 Error 类型的才会在微信小程序后台触发报警。

wx.postMessageToReferrerMiniProgram(Object object)

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

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

向跳转的源微信小程序发送消息，源微信小程序可在 wx.onShow 或 wx.getEnterOptionsSync 中通过 extraData 接收消息。

参数

Object object

属性	类型	默认值	必填	说明
extraData	Object		否	需要返回的数据

多次调用会覆盖之前传递的消息，通过 wx.navigateBackMiniProgram 传递 extraData 也会覆盖消息。

在触发返回后传递的消息不会被收到。

如果没有源微信小程序能够收到消息，会抛出 no referrer 错误。

wx.postMessageToReferrerPage(Object object)

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

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

向跳转的源页面发送消息。

参数

Object object

属性	类型	默认值	必填	说明
extraData	Object		否	需要返回的数据

多次调用会覆盖之前传递的消息，通过 wx.navigateBackMiniProgram 传递 extraData 也会覆盖消息。

在触发返回后传递的消息不会被收到。

如果没有源页面能够收到消息，会抛出 no referrer 错误。

微信小程序 wx.getApiCategory()

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

微信小程序插件：不支持

功能描述

获取当前 API 类别

返回值

string

API 类别

不同 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`

wx.getEnterOptionsSync()

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

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

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

获取本次微信小程序启动时的参数。如果当前是冷启动，则返回值与 App.onLaunch 的回调参数一致；如果当前是热启动，则返回值与 App.onShow 一致。

返回值

Object

启动参数

属性类型说明最低版本

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.getLaunchOptionsSync()

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

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

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

获取微信小程序启动时的参数。与 App.onLaunch 的回调参数一致。

返回值

Object

启动参数

属性类型说明最低版本

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	公众号模板消息	来源公众号
1069	移动应用	来源App

不同 apiCategory 场景下的 API 限制

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

	nativeFunctionalized	browseOnly	embedded
navigateToMiniProgram	`X`	`X`
openSetting		`X`
`<button open-type="share">`	`X`	`X`	`X`
`<button open-type="feedback">`		`X`
`<button open-type="open-setting">`		`X`
openEmbeddedMiniProgram	`X`	`X`	`X`

注意

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

wx.offApiCategoryChange(function listener)

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

微信小程序插件：不支持

功能描述

移除 API 类别变化事件的监听函数

参数

function listener

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

示例代码

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

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

wx.onApiCategoryChange(function listener)

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

微信小程序插件：不支持

功能描述

监听 API 类别变化事件

参数

function listener

API 类别变化事件的监听函数

参数

Object res

属性

类型

说明

apiCategory

number

API 类别

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

不同 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`

示例代码

const func = function (res) {
  console.log(res.apiCategory)
}
wx.onApiCategoryChange(func)
// 取消监听
wx.offApiCategoryChange(func)