微信JSAPI

jf edited this page Apr 13, 2016 · 7 revisions

目前微信已出新的API文档,详情请访问:

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115&token=&lang=zh_CN

以下内容已过时,请参考新版的文档

使用前注意事项:

JS API建立在客户端浏览器内置JS对象WeixinJSBridge上。然而WeixinJSBridge并不是WebView一打开就有了,客户端需要初始化这个对象,当这个对象准备好的时候,客户端会抛出事件"WeixinJSBridgeReady"。因此,在调用WeixinJSBridge相关api时,需要做好WeixinJSBridge存在与否的判断:

if (typeof WeixinJSBridge == "object" && typeof WeixinJSBridge.invoke == "function") {
    callback();
} else {
    if (document.addEventListener) {
        document.addEventListener("WeixinJSBridgeReady", callback, false);
    } else if (document.attachEvent) {
        document.attachEvent("WeixinJSBridgeReady", callback);
        document.attachEvent("onWeixinJSBridgeReady", callback);
    }
}
//callback即为调用WeixinJSBridge的相关接口的函数

WeixinJSBridge提供的方法

方法名 用途 通用形式
invoke 调用指定API WeixinJSBridge.invoke("API名称", {调用参数}, <回调函数>);
on 监听事件 WeixinJSBridge.on("事件名称", <回调函数>);

invoke的回调函数中参数err_msg的一般返回值:

err_msg 说明
***:confirm 用户确定
***:cancel 用户取消
***:ok 成功
***:fail 失败
system:access_denied
access_control:not_allow
没有权限(你不在白名单内或在黑名单内)
system:function_not_exist 当前版本不支持或方法不存在

关于API的权限问题:

并不是所有的JS API都是开放的,大部分API还是需要通过申请权限后才能使用。权限申请请参考公众平台wiki

WeixinJSBridge.invoke API

hideOptionMenu 隐藏右上角菜单

条件:Ver4.5+

WeixinJSBridge.invoke('hideOptionMenu',{},function(res){
    //alert(res.err_msg);
});

showOptionMenu 显示右上角菜单

条件:Ver4.5+

WeixinJSBridge.invoke('showOptionMenu',{},function(res){
    //alert(res.err_msg);
});

getNetworkType 获取当前网络类型

条件:Ver4.5+

WeixinJSBridge.invoke('getNetworkType',{},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
network_type:fail 无网络
network_type:wifi wifi
network_type:2g 2g
network_type:3g+ 3g及以上

closeWindow 关闭当前网页窗口

条件:Ver4.5+

WeixinJSBridge.invoke('closeWindow',{},function(res){
    //alert(res.err_msg);
});

imagePreview 图片预览接口

条件:Ver4.2+

WeixinJSBridge.invoke('imagePreview', {
    current: 'http://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg', // 要预览urls中第几张图片的url
    urls: [ // 所有图片的url列表,数组格式
      'http://img1.gtimg.com/10/1048/104857/10485731_980x1200_0.jpg',
      'http://img1.gtimg.com/10/1048/104857/10485726_980x1200_0.jpg',
      'http://img1.gtimg.com/10/1048/104857/10485729_980x1200_0.jpg'
    ]     
  }, function(res){
    //alert(res.err_msg);
});

sendEmail 发邮件

条件:Ver5.0+

WeixinJSBridge.invoke('sendEmail',{
    'title': 'title', // 标题
    'content': 'content' // 正文
},function(res){
    // alert(res.err_msg);  
});

返回值:

err_msg 说明
send_email:title_link_empty 标题或内容为空
send_email:title_too_long 标题过长
send_email:cancelled 取消发送
send_email:saved 邮件被保存
send_email:sent 邮件发送
send_email:failed 邮件发送失败

addContact 添加好友

条件:Ver4.2+,白名单,Android

WeixinJSBridge.invoke('addContact',{
    'appid': 'wx1234567890', // 公众号appID
    'webtype': 1, // 添加联系人的场景,1表示企业联系人,现在只有1
    'username': 'username' // 添加联系人的微信号
},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
add_contact:added 已经是好友

sendAppMessage 发送给朋友

条件:Ver4.2+,白名单,需要在监听'menuitem:share:appmessage'的事件里的回调方法中调用

WeixinJSBridge.invoke('sendAppMessage',{
    'appid': 'wx1234567890', // 公众号appID
    'type': 'link', // 非必填,music,vido或link,默认为link。
    'data_url': '', // 非必填,连接地址,如音乐的mp3数据地址,供内置播放器使用
    'img_url': 'http://pnewsapp.tc.qq.com/newsapp_bt/0/9963967/640', // 缩略图地址
    'img_height':370, // 缩略图高度
    'img_width':550, // 缩略图宽度
    'link':'http://view.inews.qq.com/a/WXN2013101101385701', // 链接地址
    'desc':'desc', // 描述
    'title':'title' // 标题
},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
send_app_msg:title_desc_link_empty 标题描述链接其中一个为空
send_app_msg:title_too_long 标题过长
send_app_msg:desc_too_long 描述过长返回
send_app_msg:thumb_too_large 缩略图过大

shareTimeline 分享到朋友圈

条件:Ver4.2+,白名单,需要在监听'menuitem:share:timeline'的事件里的回调方法中调用

WeixinJSBridge.invoke('shareTimeline',{
    'appid': 'wx1234567890', // 公众号appID
    'title':'title', // 分享标题
    'desc':'desc', // 描述
    'link':'http://www.qq.com', // 点击后连接地址
    'img_width':550, // 图片宽度
    'img_height':370, // 图片高度
    'img_url': 'http://img1.gtimg.com/10/1048/104857/10485731_980x1200_0.jpg' // 分享到朋友圈的缩略图url
},function(res){
    //alert(res.err_msg);
});

scanQRCode 扫描二维码

条件:Ver4.2+,白名单

WeixinJSBridge.invoke('scanQRCode',{
    'appid': 'wx1234567890', // 公众号appID
    'desc' : 'desc', // 描述
    'needResult' : 1, // 非必填,扫码处理方式。1:直接返回扫描结果,0:扫码结果由微信处理。默认为0
    'scanType':['qrCode','barCode'] // 非必填,扫码类型,参数类型是数组,二维码是'qrCode',一维码是'barCode',默认全选
},function(res){
    alert(res.resultStr);
});

返回值:

返回值 说明
resultStr 用户扫码成功后此结果返回,示例:{"scan_code":{"scan_type":"qrcode","scan_result":"http://qq.com"}}

addEmoticon 添加收藏表情

条件:Ver4.3+,白名单

WeixinJSBridge.invoke('addEmoticon',{
    'appid': 'wx1234567890', // 公众号appID
    'url': 'http://xxx.png', // 表情图url。需为png,且大小在32k以下
    'thumb_url': 'http://xxx.png' // 缩略图url。需为png,且大小在32k以下。url与thumb_url不能相同
},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
add_emoticon:no_url url为空
add_emoticon:added 已添加过相同的表情
add_emoticon:count_extend 已添加数据超过上限
add_emoticon:download_failed 下载失败
add_emoticon:unsupported_type 不支持的文件类型

hasEmoticon 查询是否已收藏某表情

条件:Ver4.3+,白名单

WeixinJSBridge.invoke('hasEmoticon',{
    'appid': 'wx1234567890', // 公众号appID
    'url': 'http://xxx.png' // 表情图url
},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
has_emoticon:no_url url为空
has_emoticon:yes 已收藏
has_emoticon:no 未收藏

cancelAddEmoticon 取消添加某表情

条件:Ver4.3+,白名单

WeixinJSBridge.invoke('hasEmoticon',{
    'appid': 'wx1234567890', // 公众号appID
    'url': 'http://xxx.png' // 表情图url
},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
cancel_add_emoticon:no_url url为空
cancel_add_emoticon:added 已经添加成功,不能取消

getInstallState 获取某app是否已安装

条件:Ver4.5+,白名单

WeixinJSBridge.invoke('getInstallState',{
    'appid': 'wx1234567890', // 公众号appID
    'packageUrl': 'com.tencent.news://xxx', // IOS必填,xxxx:// 开头的一个scheme
    'packageName':'com.tencent.news' // android必填,包名
},function(res){
    // alert(res.err_msg);
});

返回值:

err_msg 说明
missing arguments 缺少输入参数
get_install_state:yes_[version] 已安装,其中Android会返回version

launch3rdApp 启动第三方app(一)

条件:Ver5.0.4+,白名单

WeixinJSBridge.invoke('launch3rdApp',{
    'appID': 'wx1234567890', // 公众号appID
    'messageExt': 'from=weixin_webview', // iOS使用此参数,第三方应用自定义简单数据
    'extInfo': 'from=weixin_webview' // Android使用此参数,第三方应用自定义简单数据
},function(res){
    //alert(res.err_msg);
});

launch3rdApp 启动第三方app(二)

条件:Ver5.0.4+,白名单,Android

WeixinJSBridge.invoke('launch3rdApp',{
    'appID': 'wx1234567890', // 公众号appID
    'packageName': 'com.tencent.news', // 软件的包名
    'signature': '1234567890', // apk的签名
    'param':'webview', // 传递给第三方的参数,key是"launchParam",value就是param的值
    'type': 1 // 类型,目前只有1
},function(res){
    //alert(res.err_msg);
});

openUrlByExtBrowser 用safari打开指定链接

条件:Ver5.0.4+,白名单,IOS

WeixinJSBridge.invoke('openUrlByExtBrowser',{
    'appID': 'wx1234567890', // 公众号appID
    'url': 'http://qq.com' // 需要打开的页面链接
},function(res){
    //alert(res.err_msg);
});

geoLocation 获取地理位置

条件:Ver5.2+,白名单

WeixinJSBridge.invoke('geoLocation', {
    'appId':'wx1234567890', // 公众号appID
    'scope':'jsapi_location', // 调用该jsapi所需权限scope(值为jsapi_location)
    'signType':'sha1', // 签名方式(目前仅支持SHA1)
    'addrSign': 'xxx', // 签名
    'timeStamp':'1409821938', // 时间戳
    'nonceStr': +new Date(), // 随机字符串
    'type': 'wgs84'// 非必填,定位坐标类型,android下支持的取值:wgs84、gcj02;ios下没有该参数,全部使用wgs84
}, function(res) {
    if (res.err_msg == 'geo_location:ok') {
        alert('longitude(double) = ' + res.longitude + ', latitude(double) = ' + res.latitude + ', speed(double) = ' +
        res.speed + ', accuracy(double) = ' + res.accuracy); }
    else {
        alert('fail!');
    }
});

注意事项:

  • url 必须是调用时所在页面的 url ,其域名要与填写OAuth2.0授权域名一致
  • timeStamp的单位是秒
  • accesstoken 需要用 OAuth 获取的 access_token,获取 access_token的 scope 是 snsapi_base
  • 签名用的 timeStamp 和 nonceStr 要与调用 API 时用的 timeStamp 和 nonceStr 一致

openLocation 查看地理位置

条件:Ver5.3+,白名单

WeixinJSBridge.invoke('openLocation',{
    'latitude': 23.1002775692, // 纬度,浮点数,范围为90 ~ -90
    'longitude': 113.3246126464, // 经度,浮点数,范围为180 ~ -180
    'name': 'TIT创意园', // 非必填,POI名称
    'address': '广州市珠海区新港中路397号', // 非必填,地址
    'scale': 14, // 非必填,地图缩放级别,整形值,范围从1~28
    'infoUrl': 'http://weixin.qq.com/' // 非必填,在查看位置界面底部显示的超链接,点击可跳转
},function(res){
    //alert(res.err_msg);
});

返回值:

err_msg 说明
open_location:invalid_coordinate 非法的经纬度

WeixinJSBridge.on API

监听分享按钮的"发送给朋友"按钮的点击事件

WeixinJSBridge.on("menu:share:appmessage", callback); // callback回调方法,如可以调用上面sendAppMessage

监听分享按钮的"分享到朋友圈"按钮的点击事件

WeixinJSBridge.on("menu:share:timeline", callback); // callback回调方法,如可以调用上面shareTimeline

使用过程中如果遇到问题,欢迎在issue中提问。

附录:微信JS-SDK说明文档

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.