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

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 进行判断。

国际化友好适配指南

随着外国用户来华数量日益增长，部分微信小程序存在手机号、证件、语言等限制，导致外国人用不了或用不好微信小程序。为改善外国用户体验，请开发者完成微信小程序国际化友好适配。

【优化项】

账号体系适配（必需）：登录、购票链路兼容非 +86 国际手机号，放开国内 11 位手机号格式校验，或新增邮箱登录通道。
信息录入适配（必需）：实名、购票信息录入支持护照等境外身份证件，放宽姓名字符输入校验限制。
多语言适配（重点）：微信小程序已支持 18 种语言翻译，请关注翻译后页面及文本是否适配；为确保开发者微信小程序中的专有名词（如品牌名、产品词）翻译准确，请在微信小程序后台维护翻译词库。
双语物料：参照平台中英双语物料规范更新线下物料，优化外国用户扫码使用体验。

推荐使用国际化适配 Skill 快速定位代码优化项

使用指引：微信小程序国际化适配 Skill

SkillHub：微信小程序国际化适配Skill — SkillHub

ClawHub：微信小程序国际化适配Skill — ClawHub

如有额外产品优化诉求或其他需求/反馈、技术问题可随时联系邮箱 miniprogram_global@tencent.com。

1. 账号体系适配（必需）

注册登录和购票页面兼容非 +86 国际手机号和放宽 11 位手机号校验规则、或支持邮箱登录、或接入微信小程序手机号快速验证组件；

1.1. 兼容非 +86 国际手机号

手机号是来华旅游场景下（如景区门票预订、餐厅点餐、酒店入住等）关键的履约信息。建议开发者通过平台手机号快速验证组件或自行搭建手机号验证码通道形式收集用户手机号，以适配入境用户的使用习惯。

1.1.1. 国际手机号授权的接入方案

接入方式	接入方式说明
接入“手机号快速验证”组件（推荐）	微信平台已对非个人主体且完成认证的微信小程序开放手机号快速验证组件服务，旨在帮助开发者向用户发起手机号申请。具体内容参照指引：手机号快速验证组件 \| 微信开放文档
开发者自行搭建手机号验证码通道	开发者也可在微信小程序前端自行开发手机号填写及验证码发送的流程，以完成信息收集。若涉及国际手机号的短信验证码下发，建议重点关注跨国发送的到达率。建议接入支持全球发送的国际短信服务商：保障验证码能穿透境外运营商网络。建议提供备选验证方案，例如：上行短信验证：允许用户主动发送特定代码到指定号码来完成验证。语音验证：通过电话语音播报的方式告知用户验证码。

接入方式

接入方式说明

接入“手机号快速验证”组件（推荐）

微信平台已对非个人主体且完成认证的微信小程序开放手机号快速验证组件服务，旨在帮助开发者向用户发起手机号申请。
具体内容参照指引：手机号快速验证组件 | 微信开放文档

开发者自行搭建手机号验证码通道

开发者也可在微信小程序前端自行开发手机号填写及验证码发送的流程，以完成信息收集。
若涉及国际手机号的短信验证码下发，建议重点关注跨国发送的到达率。

建议接入支持全球发送的国际短信服务商：保障验证码能穿透境外运营商网络。
建议提供备选验证方案，例如：
- 上行短信验证：允许用户主动发送特定代码到指定号码来完成验证。
- 语音验证：通过电话语音播报的方式告知用户验证码。

无论是直接获取微信绑定的手机号还是用户手动填写，底层系统均需支持国际号码格式。

1.1.2. 国际手机号的兼容逻辑

兼容方式	说明
兼容国际区号	放宽对于手机号国际区号的限制，允许用户在前端选择非 +86 开头的手机号进行填写。
兼容国际号码位数	放宽对于“手机号必须为11位”的校验逻辑，避免境外手机号因长度问题被判定为错误手机号。

1.2 兼容邮箱登录验证

鉴于国际短信在跨国漫游场景下可能存在拦截或延迟，且海外用户具有高频使用电子邮箱的习惯，建议在手机号登录之外，增设“邮箱+验证码”或“邮箱+密码”的辅助验证/信息收集选项，确保在短信无法送达时，用户仍可通过邮箱完成身份验证并使用服务。

二、信息录入适配（必需）

实名认证和购票信息支持护照等境外证件、放宽姓名输入校验规则；

在实名认证、物流填写、票务预订等场景中，若表单字段限制过严（例如：仅限汉字、仅支持身份证等），将导致境外用户无法录入有效信息。开发者可从以下方向开展适配优化。

优化方向	说明
证件类型适配	在涉及实名制的业务场景中，在“居民身份证”之外，增设“护照”、“外国人永久居留身份证”等选项，并适配相应的证件号码校验规则。
姓名输入规则放宽	取消“仅限汉字”的输入限制，允许输入英文字母及空格。增加字符长度上限：考虑到外籍人士姓名音译或原名较长，建议姓名字段长度限制放宽至50个字符以上，避免截断。

三、多语言适配（重点）

微信小程序已支持 18 种语言翻译，请关注翻译的页面及文本适配，避免译文溢出或显示不全；为确保开发者微信小程序中专有名词（如品牌名、产品词）翻译准确，请在微信小程序后台维护翻译词库；开发者也可自行适配多语言界面；

3.1 平台翻译能力适配

平台已为用户提供微信小程序翻译功能，支持18种语言。开发者可通过以下方式优化用户翻译功能在微信小程序的使用体验：

多语言适配方式	适配方式说明
页面适配（高优）	考虑多语言的文本长度、词汇分界等差异，开发者在微信小程序页面设计上，需要关注并适配翻译后文本内容过长而“溢出”的异常情况。
文本规范（高优）	微信小程序翻译功能仅适用于文本翻译，无法识别图片中的文字。开发者在微信小程序页面设计上，避免使用图片代替文字，尽可能确保文本表达清晰、直观。
词库维护	为确保开发者微信小程序中专有名词（如品牌名、产品词）翻译准确，平台支持开发者在微信公众平台维护自身微信小程序的翻译词库（微信小程序名称、品牌词、产品词、专业词汇等） 1. 登录微信公众平台前往「基础功能-翻译」下载翻译词库文件模版，填写词库文件上传 2. 确认翻译词库内容无误后，点击【确认生效】，当前平台审核版本的词库将正式生效请注意： • 翻译词库文件模版如下 • 翻译词库Excel文件首列为微信小程序主语言，若微信小程序主语言为中文，则将中文放在A列；若微信小程序主语言为英文，则将英文放在A列，以此类推； • 若商户仅维护部分语言版本，在其余语言版本的翻译内容为空即可；
翻译动态适配	开发者可通过wx.onUserTriggerTranslation监听用户触发微信小程序的翻译功能事件，并动态将页面核心内容（品牌词、产品词等）调整为目标翻译语言，平台识别到该内容已经为目标翻译语言后，将不会二次翻译。示例： 1. 监听到用户开启翻译功能，目标语言为阿拉伯语 2. 开发者将页面内商品名称修改成阿拉伯语的专有词汇，其他内容不做翻译 3. 平台识别到商品名称已经是阿拉伯语，不做二次翻译，只翻译其他内容

微信小程序翻译功能说明

设置翻译语言：目标翻译语言默认为微信客户端使用的语言。若需要调整翻译语言，用户可进入“我” – “设置” – “通用” – “翻译”从语言列表中选择翻译语言。
打开微信小程序翻译：可使用两种方式（1）进入微信小程序，若右上角显示“翻译”气泡，点击“翻译”按钮；（2）点击微信小程序右上角的 “…” 按钮，在弹窗点击“翻译”按钮；
微信小程序翻译支持 18 种语言：简体中文、繁体中文（台湾）、繁体中文（香港）、英语、印度尼西亚语、马来语、西班牙语、韩语、意大利语、日语、葡萄牙语、俄语、泰语、越南语、阿拉伯语、土耳其语、德语、法语

3.2 开发者自行适配多语言界面

开发者可通过以下两种接口感知用户客户端语言/目标翻译语言，并自行适配多语言：

开发者可通过wx.getAppBaseInfo接口，根据返回的language字段，获取用户客户端语言版本，在微信小程序内适配用户语言，并内置多语言切换功能。
开发者可通过wx.onUserTriggerTranslation监听用户触发微信小程序的翻译功能事件，动态将页面的核心内容进行多语言适配。
若微信小程序的界面营销玩法较为复杂（如弹窗广告、裂变分享、积分任务）对于外国游客来说，理解成本极高且容易被视为干扰信息，同时可能造成页面自动翻译后的排版混乱。开发者可考虑通过识别系统语言实施差异化的微信小程序界面。

建议	说明
智能路由分流（核心逻辑）	• 开发者可通过 wx.getAppBaseInfo 接口获取用户客户端语言版本（language 字段） • 当检测到非中文语言环境时，微信小程序自动加载国际化界面
UI设计做减法	• 聚焦核心功能：针对国际版界面，可移除复杂的营销弹窗、会员任务体系及非必要的社交裂变入口，只保留点餐、购票、支付、客服、地图等微信小程序自身核心服务路径。 • 视觉通用化：增加通用图标与示意图的使用比例，减少对纯文本说明的依赖，降低跨文化理解门槛。

四、双语物料

平台提供中英双语微信小程序物料设计指引供商户更新线下物料，外国人线下扫码体验更友好；

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)

UpdateManager.onUpdateReady 监听函数

微信小程序插件：不支持

功能描述

监听微信小程序有版本更新事件。客户端主动触发下载（无需开发者触发），下载成功后回调

参数

function listener

微信小程序有版本更新事件的监听函数

示例代码

UpdateManager.onUpdateFailed 监听函数

微信小程序插件：不支持

功能描述

监听微信小程序更新失败事件。微信小程序有新版本时，客户端会自动触发下载（不需要开发者手动触发），如果下载失败（可能是网络原因等），就会触发这个回调函数。

参数

function listener

微信小程序更新失败事件的监听函数

示例代码

UpdateManager.onCheckForUpdate 监听函数

微信小程序插件：不支持

功能描述

监听向微信后台请求检查更新结果事件。微信在微信小程序每次启动（包括热启动）时自动检查更新，不需由开发者主动触发。

参数

function listener

向微信后台请求检查更新结果事件的监听函数

参数

Object res

属性	类型	说明
hasUpdate	boolean	是否有新版本