微信 JS-SDK 说明文档

2023-10-07 08:41:28

概述

微信JS-SDK是微信公众平台面向网页开发者提供的基于微信内的网页开发工具包。

通过使用微信JS-SDK，网页开发者可借助微信高效地使用拍照、选图、语音、位置等手机系统的能力，同时可以直接使用微信分享、扫一扫、卡券、支付等微信特有的能力，为微信用户提供更优质的网页体验。

此文档面向网页开发者介绍微信JS-SDK如何使用及相关注意事项。

JSSDK使用步骤

步骤一：绑定域名

先登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”。

备注：登录后可在“开发者中心”查看对应的接口权限。

步骤二：引入JS文件

在需要调用JS接口的页面引入如下JS文件，（支持https）：http://res.wx.qq.com/open/js/jweixin-1.6.0.js

如需进一步提升服务稳定性，当上述资源不可访问时，可改访问：http://res2.wx.qq.com/open/js/jweixin-1.6.0.js （支持https）。

备注：支持使用 AMD/CMD 标准模块加载方法加载

步骤三：通过config接口注入权限验证配置

所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用（同一个url仅需调用一次，对于变化url的SPA的web app可在每次url变化时进行调用,目前Android微信客户端不支持pushState的H5新特性，所以使用pushState来实现web app的页面会导致签名失败，此问题会在Android6.2中修复）。

wx.config({
  debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
  appId: '', // 必填，公众号的唯一标识
  timestamp: , // 必填，生成签名的时间戳
  nonceStr: '', // 必填，生成签名的随机串
  signature: '',// 必填，签名
  jsApiList: [] // 必填，需要使用的JS接口列表
});

签名算法见文末的附录1，所有JS接口列表见文末的附录2

注意：如果使用的是小程序云开发静态网站托管的域名的网页，可以免鉴权直接跳任意合法合规小程序，调用 wx.config 时 appId 需填入非个人主体的已认证小程序，不需计算签名，timestamp、nonceStr、signature 填入非空任意值即可。

步骤四：通过ready接口处理成功验证

wx.ready(function(){
  // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});

步骤五：通过error接口处理失败验证

wx.error(function(res){
  // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
});

接口调用说明

所有接口通过wx对象(也可使用jWeixin对象)来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：

success：接口调用成功时执行的回调函数。
fail：接口调用失败时执行的回调函数。
complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。
cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。
trigger: 监听Menu中的按钮点击时触发的方法，该方法仅支持Menu中的相关接口。
备注：不要尝试在trigger中使用ajax异步请求修改本次分享的内容，因为客户端分享操作是一个同步操作，这时候使用ajax的回包会还没有返回。

以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：

调用成功时：“xxx:ok” ，其中xxx为调用的接口名

用户取消时：“xxx:cancel”，其中xxx为调用的接口名

调用失败时：其值为具体错误信息

>>> JS-SDK说明文档

模拟JSSDK权限校验

通过 web 开发者工具，可以模拟 JSSDK 在微信客户端中的请求，并直观地看到鉴权结果和 log。以微信 JSSDK DEMO 页面为例：
https://www.weixinsxy.com/jssdk/

在调试器中打开该 URL，可以方便地在右侧的 JS-SDK Tab 中看到当前页面 wx.config 的校验情况和 JSSDK 的调用 log。如下是校验通过的页面：

在控制台里会显示当前页面拥有权限的 JS-SDK 列表。

如下是校验未通过的页面：

结合左侧的微信 Webview 模拟器，可以直观地调试 JSSDK 的效果，能够在console栏里看到调用的API的结果。

注意：0.7.0 及以后版本的微信 web 开发者工具支持卡券 JSSDK 的调试，但对于希望调试的卡券公众号，我们要求开发者微信号与之建立绑定关系，绑定流程同授权登录一致。

URL收藏与二维码预览

为了方便开发者快速打开要调试的网页，开发者工具有两个方便的小功能：

URL收藏

类似浏览器里的书签功能，你可以把你经常需要调试的网页通过点击URL地址栏上的星星的icon将其收藏。

收藏之后你可以在收藏夹里看到所收藏的URL：

取消收藏也很简单，在已经收藏的URL的星星上再点击一次就可以取消收藏。

二维码预览

为了方便开发者快速通过手机打开网页预览效果，可以通过点击「预览」按钮给出当前网页的二维码：

移动调试

注意：移动调试仅支持0.5.0 - 0.7.0版本的开发者工具。1.x版本的开发者工具不支持此功能！

移动端网页的表现，通常和桌面浏览器上有所区别，包括样式的呈现、脚本的逻辑等等，这会给开发者带来一定的困扰。现在，微信安卓客户端 webview 已经开始全面升级至 X5 Blink 内核，新的内核无论在渲染能力、API 支持还是在开发辅助上都有很大进步。通过微信 web 开发者工具中的远程调试功能，实时映射手机屏幕到微信 web 开发者工具上，将帮助开发者更高效地调试 X5 Blink 内核的网页，具体步骤如下：

（1）准备工作

安装0.5.0或以上版本的微信 web 开发者工具

确认移动设备是否支持远程调试功能

打开微信 web 开发者工具，选择“移动调试”tab，点击验证移动设备是否支持。随后使用移动设备扫描弹出的二维码，在设备上即可获得支持信息。

打开移动设备中的 USB 调试功能

1.打开移动设备，进入“设置”->“开发人员选项”

2.勾选“USB 调试功能”

需要注意的是，Android 4.2 之后的设备，开发人员选项默认是隐藏的，通过以下步骤可以打开：

1.打开移动设备，进入“设置”->“关于手机”

2.找到并单击“内部版本号”7次

安装移动设备 USB 驱动
通常开发者可以在移动设备厂商的官网中下载到相关驱动，或者使用<a href=“http://m.qq.com/ “腾讯手机管家”” target="_blank">腾讯手机管家来安装设备驱动。

打开 X5 Blink 内核的 inspector 功能
打开微信 web 开发者工具，选择“移动调试”tab ，使用设备扫描“调试步骤”中的二维码。

如下图，勾选“是否打开 TBS 内核 Inspector 调试功能”，并重启微信。

（2）开始调试

使用 USB 数据线连接移动设备与 PC 或者 Mac 后，点击打开微信 web 开发者工具“移动调试”tab，选择 X5 Blink 调试功能，将会打开一个新窗口，在微信中访问任意网页即可开始调试。关于 X5 Blink 内核更多信息，可以查看官网介绍。

在所有准备工作都完成的情况下，窗口中可以看到当前设备的基本信息：

点击任意页面的“inspect”，打开新窗口，开发者会看到熟悉的调试界面：

点击上图右上角的“手机”图标，将启用屏幕映射功能：

微信 web 开发者工具集成的移动调试功能，基于 weinre 并做了一些改进，相比直接使用 weinre 有两个优点：

1.无须手工在页面中加入 weinre 调试脚本

2.可以在 weinre 的网络请求页卡中，看到完整的 http 请求 log，非局限于 ajax 请求

如下图所示：

注意，移动调试功能暂不支持 https。

Chrome DevTools

微信 web 开发者工具集成了 Chrome DevTools。同之前在 PC 上的调试体验一致，可以快速上手。