1. 绑定域名
登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”。
2. 引入JS文件
在需要调用JS接口的页面引入如下JS文件:http://res.wx.qq.com/open/js/jweixin-1.6.0.js (支持https)
如需进一步提升服务稳定性,当上述资源不可访问时,可改访问:http://res2.wx.qq.com/open/js/jweixin-1.6.0.js (支持https)
备注:支持使用 AMD/CMD 标准模块加载方法加载。
3. 通过config接口注入权限验证配置并申请所需开放标签
与使用JS-SDK配置方式相同,所有需要使用开放标签的页面必须先注入配置信息,并通过openTagList
字段申请所需要的开放标签,否则将无法使用(同一个url仅需调用一次)。开放标签的申请和JS接口的申请相互独立,因此是可以同时申请的。
wx.config({
debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来,若要查看传入的参数,可以在pc端打开,参数信息会通过log打出,仅在pc端时才会打印
appId: '', // 必填,公众号的唯一标识
timestamp: , // 必填,生成签名的时间戳
nonceStr: '', // 必填,生成签名的随机串
signature: '',// 必填,签名
jsApiList: [], // 必填,需要使用的JS接口列表
openTagList: [] // 可选,需要使用的开放标签列表,例如['wx-open-launch-app']
});
签名算法见JS-SDK说明文档的附录,所有开放标签列表见文末的附录1。
4. 通过ready接口处理成功验证
wx.ready(function () {
// config信息验证后会执行ready方法,所有接口调用都必须在config接口获得结果之后,config是一个客户端的异步操作,所以如果需要在页面加载时就调用相关接口,则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口,则可以直接调用,不需要放在ready函数中
});
5. 通过error接口处理失败验证
wx.error(function (res) {
// config信息验证失败会执行error函数,如签名过期导致验证失败,具体错误信息可以打开config的debug模式查看,也可以在返回的res参数中查看,对于SPA可以在这里更新签名
});
使用说明
所有开放标签都能像普通的HTML标签一样在页面中直接使用,不需要再进行额外的处理。
如果所使用的标签允许提供插槽,由于插槽中模版的样式是和页面隔离的,因此需要注意在插槽中定义模版的样式。插槽模版及样式均需要通过<template></template>
进行包裹。对于Vue等视图框架,为了避免template标签冲突的问题,可使用<script type="text/wxtag-template"></script>
进行代替,来包裹插槽模版和样式。另外,对于具名插槽还需要通过slot
属性声明插槽名称,下文标签插槽中的default插槽为默认插槽,可不声明插槽名称。
对于标签事件,均可通过event.detail
获得详细信息。如果无特殊说明,下文标签事件说明中的返回值均指代event.detail
中的内容。
另外,需要注意以下几点:
- 页面中与布局和定位相关的样式,如
position: fixed; top -100;
等,尽量不要写在插槽模版的节点中,请声明在标签或其父节点上; - 对于有CSP要求的页面,需要添加白名单
frame-src https://*.qq.com webcompt:
,才能在页面中正常使用开放标签。
开放标签
跳转小程序:wx-open-launch-weapp
用于页面中提供一个可跳转指定小程序的按钮。使用此标签后,用户需在网页内点击标签按钮方可跳转小程序。H5通过开放标签打开小程序的场景值为1167。
开放对象
- 已认证的服务号,服务号绑定“JS接口安全域名”下的网页可使用此标签跳转任意合法合规的小程序。
- 已认证的非个人主体的小程序,使用小程序云开发的静态网站托管绑定的域名下的网页,可以使用此标签跳转任意合法合规的小程序。
错误提示
若跳转时出现以下页面,表示网页绑定的服务号或小程序无权限,请检查是否符合上述开放对象条件。
属性
名称 | 必填 | 默认值 | 备注 |
username | 是 | | 所需跳转的小程序原始id,即小程序对应的以 |
path | 否 | | 所需跳转的小程序内页面路径及参数 |
插槽
名称 | 必填 | 默认值 | 备注 |
default | 是 | | 跳转按钮模版及样式 |
事件
名称 | 冒泡 | 返回值 | 备注 |
ready | 否 | | 标签初始化完毕,可以进行点击操作 |
launch | 否 | | 用户点击跳转按钮并对确认弹窗进行操作后触发 |
error | 否 | { errMsg: string } | 用户点击跳转按钮后出现错误 |
备注:error
事件返回值errMsg
说明如下。
errMsg | 说明 |
"launch:fail" | 跳转失败 |
用例
<wx-open-launch-weapp
id="launch-btn"
username="gh_xxxxxxxx"
path="pages/home/index?user=123&action=abc"
>
<template>
<style>.btn { padding: 12px }</style>
<button class="btn">打开小程序</button>
</template>
</wx-open-launch-weapp>
<script>
var btn = document.getElementById('launch-btn');
btn.addEventListener('launch', function (e) {
console.log('success');
});
btn.addEventListener('error', function (e) {
console.log('fail', e.detail);
});
</script>
跳转APP:wx-open-launch-app
用于页面中提供一个可跳转指定App的按钮。
属性
名称 | 必填 | 默认值 | 备注 |
appid | 是 | | 所需跳转的AppID |
extinfo | 否 | | 跳转所需额外信息 |
备注:对于extinfo
属性,用于携带额外信息,格式自定义,由跳转的App自⾏解析处理。对应iOS微信openSDK中的messageExt字段(LaunchFromWXReq.message.messageExt),或对应Android微信openSDK中的messageExt字段(ShowMessageFromWX.Req.message.messageExt)
插槽
名称 | 必填 | 默认值 | 备注 |
default | 是 | | 跳转按钮模版及样式 |
事件
名称 | 冒泡 | 返回值 | 备注 |
ready | 否 | | 标签初始化完毕,可以进行点击操作 |
launch | 否 | | 用户点击跳转按钮并对确认弹窗进行操作后触发 |
error | 否 | { errMsg: string } | 用户点击跳转按钮后出现错误 |
备注:error
事件返回值errMsg
说明如下。
errMsg | 说明 |
"launch:fail" | 调⽤失败,或安卓上该应用未安装,或iOS上用户在弹窗上点击确认但该应⽤未安装 |
"launch:fail_check fail" | 校验App跳转权限失败,请确认是否正确绑定AppID |
用例
<wx-open-launch-app
id="launch-btn"
appid="your-appid"
extinfo="your-extinfo"
>
<template>
<style>.btn { padding: 12px }</style>
<button class="btn">App内查看</button>
</template>
</wx-open-launch-app>
<script>
var btn = document.getElementById('launch-btn');
btn.addEventListener('launch', function (e) {
console.log('success');
});
btn.addEventListener('error', function (e) {
console.log('fail', e.detail);
});
</script>