Skip to content

微信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.