JS-API使用说明

优质

小牛编辑

136浏览

2023-12-01

1 概述
 2 API使用说明
    二维码扫描api
        二维码扫描接口
    地理位置api
        打开地图接口
        获取位置信息接口
    图片api
        选择图片接口
        预览图片接口
        上传图片接口
        下载图片接口
    网络api
        查看网络类型接口
    分享api
        分享到朋友圈接口
        分享给好友接口
        分享到QQ接口
        分享到腾迅微博接口
        分享到QQ空间接口
    音频api
        开始录音接口
        结束录音接口
        录音一分钟结束回调接口
        播放录音接口
        暂停播放接口
        停止播放接口
        播放结束回调接口
        上传录音接口
        下载音频接口
翻译api
录音转成汉字接口
    微信小店api
        打开产品详细页接口
        批量添加卡券接口
        拉取适用卡券列表并获取用户选择信息接口
        查看微信卡包中的卡券接口
    微信界面api
        显示右上角菜单接口
        批量隐藏菜单项接口
        批量显示菜单项接口
        隐藏所有非基本菜单项接口
        显示所有被隐藏的非基本菜单项接口
 3 常见问题

1 概述

x5 3.4 版本提供了一组本地能力api，可以方便地调用本地能力。比如，二维码扫描的api：scanQRCode——在微信中，调用微信jssdk的扫描；而在H5 App里，调用cordova这个“壳”的扫描。

目前这个“壳”可以是微信、cordova，因此可以把js-api使用在微信公众号、wex5 app开发场景下。且一种应用开发好之后，在另一种“壳”下，不需要修改开发好的UI代码，只需修改配置，就能使用；反之亦然。达到一次开发，多“壳”使用的目的。

示例：
引入模块：var scan = require(‘$UI/system/api/native/scan’);
使用api：

    scan.scanQRCode({
        needResult: 1, // 1则直接返回扫描结果，
        success : function(res) {
            alert("OK:"+JSON.stringify(res));
        },
        fail : function(res) {
            alert("fail:"+JSON.stringify(res));
        }
    });

success：扫描成功回调函数。fail：失败回调函数。
更多示例参见UI2/system/api/native/demo。开发者可参考【h5app微信支付起手式】将demo发布成H5App体验，或参考【wex5微信公众号支付开发】将demo部署在微信公众号上体验。js-api大部分的api接口与微信jssdk兼容，其用法也比较接近。

注意: 需要“壳”准备好之后，方能使用本地能力，统一在base.ready触发事件。通常的做法是，给页面按钮设置一个可用性标识。当base.ready时，把可用性标识设为true。如下所示。

<a component="$UI/system/components/justep/button/button" bind-enable="ready"
              class="btn btn-default " xid="scanQRCode1" onClick="scanQRCode1Click">scanQRCode</a>

再设置页面对base.ready的响应。更详细的示例参见studio中UI2/system/api/native/demo。


var base = require('$UI/system/api/native/base');
var Model = function() {
    this.callParent();
    this.ready = justep.Bind.observable(false);
};

Model.prototype.modelLoad = function(event) {
    var self = this;
    base.ready(function() {
     self.ready.set(true);
    });
    };

2 API使用说明

二维码扫描api

需要引入模块，例：var scan = require(‘$UI/system/api/native/scan’);

二维码扫描接口

扫描并返回结果。若想在微信中直接处理扫描结果，needResult设为0。

    scan.scanQRCode({
        needResult: 1, // 1则直接返回扫描结果，
        success : function(res) {
            alert("OK:"+JSON.stringify(res));
        },
        fail : function(res) {
            alert("fail:"+JSON.stringify(res));
        }
    });

地理位置api

需要引入模块，例：var geo = require(‘$UI/system/api/native/geo’);

打开地图接口

微信里打开腾迅地图；app里打开百度地图（已安装）。

 
geo.openLocation({
    latitude : 23.099994,
    longitude : 113.324520,                 //经纬度
    name : 'TIT 创意园',                    //显示名称
    address : '广州市海珠区新港中路 397 号', //地名
    scale : 14,                            //缩放                   
    infoUrl : 'http://weixin.qq.com'       //链接网站
});

获取位置信息接口

说明：cancel是用户取消或拒绝后回调函数，下同。

 
geo.getLocation({
    success : function(res) {
        alert(JSON.stringify(res));
    },
    cancel : function(res) {
        alert('用户拒绝授权获取地理位置');
    },
    fail : function(res) {
         alert("fail:"+JSON.stringify(res));
    }
});

图片api

需要引入模块，例 var image = require(‘$UI/system/api/native/image’);

选择图片接口

 
image.chooseImage({
    success : function(res) {
        alert('已选择 ' + res.localIds.length + ' 张图片');
    },
    fail : function(res) {
         alert("fail:"+JSON.stringify(res));
    }
});

预览图片接口

说明：3.4版本仅微信有效，app只做兼容性处理。

image.previewImage({
            current : "http://192.168.1.93:8080/x5/UI2/system/service/doc/common/simpleFileStore.j?realFileName=modified.jpg&amp;amp;storeFileName=modified.jpg&amp;amp;ownerID=5da957edf147329a&amp;amp;operateType=preview",
            urls : [ 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/367-3hm031s21oc.jpg', 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/370-zilsaglkj5i.jpg',
                    'https://www.xnip.cn/wp-content/uploads/2021/docimg21/381-enlxiwopy4d.jpg' ]
        });

上传图片接口

说明：上传地址在UI2/system/config/config.json配置uploadActionUrl项，x5黓认实现为 “$UI/system/service/doc/common/simpleFileStore.j”
参数localId为本地图片路径，在chooseImage中，success回调以localIds数组返回图片路径。

 image.uploadImage({
    localId : "file:///data/com.wex5.takeout/cache/test.jpg",
    success : function(res) {
        alert('已上传到server：' + res.serverId);
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

下载图片接口

说明：app中下载图片默认复制到相册一份。serverId为服务器地址，通常在upload之后，success有serverId回调回来。

image.downloadImage({
    serverId : "weixin:///AAA123123", //在app中通常是一个串行化的JSON对象，
    success : function(res) {
        alert('已下载,本地文件： ' + res.localId);
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

网络api

需要引入模块，例：var network = require(‘$UI/system/api/native/network’);

查看网络类型接口

network.getNetworkType({
    success : function(res) {
        alert(res.networkType);
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

分享api

需要引入模块，例：var share = require(‘$UI/system/api/native/share’);以下接口在微信中的作用是设置分享的内容，链接等信息；用户点击微信menu中的按钮真正触发分享。

分享到朋友圈接口

说明：trigger: 微信中监听Menu中的按钮点击时触发的方法，该方法仅支持微信Menu中的相关接口。

share.onMenuShareTimeline({
    title : '互联网之子',
    link : 'http://movie.douban.com/subject/25785114/',
    imgUrl : 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/382-qzm5oapou2j.jpg',
    trigger : function(res) {
        alert('用户点击分享到朋友圈');
    },
    success : function(res) {
        alert('已分享');
    },
    cancel : function(res) {
        alert('已取消');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

分享给好友接口

share.onMenuShareAppMessage({
    title : '互联网之子',
    desc : '在长大的过程中，我才慢慢发现，我身边的所有事，别人跟我说的所有事，那些所谓本来如此，注定如此的事，它们其实没有非得如此，事情是可以改变的。更重要的是，有些事既然错了，那就该做出改变。',
    link : 'http://movie.douban.com/subject/25785114/',
    imgUrl : 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/382-qzm5oapou2j.jpg',
    trigger : function(res) {
        // 不要尝试在trigger中使用ajax异步请求修改本次分享的内容，因为客户端分享操作是一个同步操作，这时候使用ajax的回包会还没有返回
        alert('用户点击发送给朋友');
    },
    success : function(res) {
        alert('已分享');
    },
    cancel : function(res) {
        alert('已取消');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

分享到QQ接口

说明：complete函数在成功或失败后都要回调，下同。

share.onMenuShareQQ({
    title : '互联网之子',
    desc : '在长大的过程中，我才慢慢发现，我身边的所有事，别人跟我说的所有事，那些所谓本来如此，注定如此的事，它们其实没有非得如此，事情是可以改变的。更重要的是，有些事既然错了，那就该做出改变。',
    link : 'http://movie.douban.com/subject/25785114/',
    imgUrl : 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/388-vtu2tbyvnqh.jpg',
    trigger : function(res) {
        alert('用户点击分享到QQ');
    },
    complete : function(res) {
        alert(JSON.stringify(res));
    },
    success : function(res) {
        alert('已分享');
    },
    cancel : function(res) {
        alert('已取消');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

分享到腾讯微博接口

说明：此api仅在微信公众号中有效，在x5app只做兼容性处理。

share.onMenuShareWeibo({
    title : '互联网之子',
    desc : '在长大的过程中，我才慢慢发现，我身边的所有事，别人跟我说的所有事，那些所谓本来如此，注定如此的事，它们其实没有非得如此，事情是可以改变的。更重要的是，有些事既然错了，那就该做出改变。',
    link : 'http://movie.douban.com/subject/25785114/',
    imgUrl : 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/388-vtu2tbyvnqh.jpg',
    trigger : function(res) {
        alert('用户点击分享到微博');
    },
    complete : function(res) {
        alert(JSON.stringify(res));
    },
    success : function(res) {
        alert('已分享');
    },
    cancel : function(res) {
        alert('已取消');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

分享到QQ空间接口

share.onMenuShareQZone({
    title : '互联网之子',
    desc : '在长大的过程中，我才慢慢发现，我身边的所有事，别人跟我说的所有事，那些所谓本来如此，注定如此的事，它们其实没有非得如此，事情是可以改变的。更重要的是，有些事既然错了，那就该做出改变。',
    link : 'http://movie.douban.com/subject/25785114/',
    imgUrl : 'https://www.xnip.cn/wp-content/uploads/2021/docimg21/388-vtu2tbyvnqh.jpg',
    trigger : function(res) {
        alert('用户点击分享到QZone');
    },
    complete : function(res) {
        alert(JSON.stringify(res));
    },
    success : function(res) {
        alert('已分享');
    },
    cancel : function(res) {
        alert('已取消');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

音频api

需要引入voice模块，例：var voice = require(‘$UI/system/api/native/voice’);

开始录音接口

voice.startRecord({
    cancel : function() {
        alert('用户拒绝授权录音');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

结束录音接口

录音结束返回localId。

voice.stopRecord({
    success : function(res) {
        alert("OK:" + JSON.stringify(res.localId));
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

录音一分钟结束回调接口

voice.onVoiceRecordEnd({
    complete : function(res) {
        alert('录音时间已超过一分钟'+res.localId);
    }
});

播放录音接口

说明：参数localId是本地录音文件地址。通常需要先录一段音频。

 
voice.playVoice({
	localId : "file://android_asset/com.takeout.some/some.wav"
});

暂停播放接口

voice.pauseVoice({
    localId : "file://android_asset/com.takeout.some/some.wav",
    success : function(res) {
        alert(JSON.stringify(res));
    }
});

停止播放接口

voice.stopVoice({
    localId : "file://android_asset/com.takeout.some/some.wav"
});

播放结束回调接口

voice.onVoicePlayEnd({
    success : function(res) {
        alert(res.localId);
    }
});

上传录音接口

说明：参数localId是本地录音文件地址。通常需要先录一段音频。

voice.uploadVoice({
    localId : "weixin://someVoice",
    success : function(res) {
        alert('上传语音成功，serverId 为' + res.serverId);
    }
});

下载音频接口

说明：参数serverId是服务端ID。通常需要先上传音频返回serverId。

voice.downloadVoice({
    serverId : "someid",
    success : function(res) {
        alert('下载语音成功，localId 为' + res.localId);
    }
});

翻译api

需要引入模块，例：var translate = require(‘$UI/system/api/native/translate’);

录音转成汉字接口

说明：仅在微信公众号中有效。通常先录音。

translate.translateVoice({
	localId : "weixin://someVoice",
	complete : function(res) {
		if (res.translateResult) {
			alert('识别结果：' + res.translateResult);
		} else {
			alert('无法识别');
		}
	}
});

微信支付api

需要引入模块，例：var wxPay = require(‘$UI/system/api/native/wxPay’);

微信支付

支持微信公众号和x5 app。微信公众号支付需要配置Baas端。开发参考【h5app微信支付起手式】，或参考【wex5微信公众号支付开发】。

var tradeNo = justep.UUID.createUUID();                          //订单号
var notifyUrl = location.origin + "/baas/weixin/weixin/notify";  //微信公众号支付结果通知地址
wxPay.pay({
    body : "x5外卖",       // 标题
    mchId : "1305137601",  // 商户ID,微信公众号开发需要
    notifyUrl : notifyUrl, // 支付结果通知回调地址，微信公众号开发需要
    outTradeNo : tradeNo,  // 订单号
    totalFee : "1", // 费用（分）
    success : function(e) {
        alert(JSON.stringify(e))
    },
    cancel : function(e) {
        alert(JSON.stringify(e))
    },
    fail : function(e) {
        alert(JSON.stringify(e))
    }
});

微信小店api

需要引入模块，例：var shop = require(‘$UI/system/api/native/wxShop’);
说明：仅微信公众号有效。

打开产品详细页接口

shop.openProductSpecificView({
    productId : '', // 商品id
    viewType : '' // 0.默认值，普通商品详情页1.扫一扫商品详情页2.小店商品详情页
});

批量添加卡券接口

shop.addCard({
    cardList : [ {
        cardId : '',
        cardExt : ''
    } ], // 需要添加的卡券列表
    success : function(res) {
        var cardList = res.cardList; // 添加的卡券列表信息
    }
});

拉取适用卡券列表并获取用户选择信息接口

shop.chooseCard({
    shopId : '', // 门店Id
    cardType : '', // 卡券类型
    cardId : '', // 卡券Id
    timestamp : 0, // 卡券签名时间戳
    nonceStr : '', // 卡券签名随机串
    signType : '', // 签名方式，默认'SHA1'
    cardSign : '', // 卡券签名
    success : function(res) {
        var cardList = res.cardList; // 用户选中的卡券列表信息
    }
});

查看微信卡包中的卡券接口

shop.openCard({
	cardList : [ {
		cardId : 'pDF3iY9tv9zCGCj4jTXFOo1DxHdo',
		code : "aaabbbcccddd"
	} ]
});

微信界面api

需要引入模块，例：var menu = require(‘$UI/system/api/native/wxMenu’);
说明：仅微信公众号有效。

显示右上角菜单接口

menu.showOptionMenu();

批量隐藏菜单项接口

menu.hideMenuItems({
    menuList : [ 'menuItem:readMode', // 阅读模式
    'menuItem:share:timeline', // 分享到朋友圈
    'menuItem:copyUrl' // 复制链接
    ],
    success : function(res) {
        alert('已隐藏“阅读模式”，“分享到朋友圈”，“复制链接”等按钮');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

批量显示菜单项接口

menu.showMenuItems({
    menuList : [ 'menuItem:readMode', // 阅读模式
    'menuItem:share:timeline', // 分享到朋友圈
    'menuItem:copyUrl' // 复制链接
    ],
    success : function(res) {
        alert('已显示“阅读模式”，“分享到朋友圈”，“复制链接”等按钮');
    },
    fail : function(res) {
        alert(JSON.stringify(res));
    }
});

隐藏所有非基本菜单项接口

menu.hideAllNonBaseMenuItem({
    success : function() {
        alert('已隐藏所有非基本菜单项');
    }
});

显示所有被隐藏的非基本菜单项接口

menu.showAllNonBaseMenuItem({
    success : function() {
        alert('已显示所有非基本菜单项');
    }
});

3 常见问题

1 运行配置问题

打开x5开发工具，配置文件位于UI2/system/config/config.json，修改成你自己的配置。
app需要的参数与微信公众号的参数不同，详见下面的“参数说明”。另外，如果是微信公众号开发，需要配置Baas,参考【wex5微信公众号支付开发】部署微信公众号。如果是x5app,参考【h5app微信支付起手式】发布成App。
参数说明：
“debug” : 调试模式。true打开调试模式会在控制台上看到更多信息。
“wxAppId” : 微信开发中，微信公众号。
“wxJSApiUrl” : 微信开发中，后台服务配合路径，用于getTicket，chooseWXPay。
“wxUserInfoUrl” : 微信开发中，取得用户信息的后台服务。
“uploadActionUrl” : app开发中，上传图片或音频的后台服务。
示例：

{
	"debug" : true,
	"wxAppId" : "wxb3efde94a26e25fe",
	"wxJSApiUrl" : "/baas/weixin/weixin/jsapi",
	"wxUserInfoUrl" : "/baas/weixin/weixin/userinfo",
	"uploadActionUrl" : "$UI/system/service/doc/common/simpleFileStore.j"
}

2 通过ready处理加载完毕回调事件

通常，为了防止用户在js没有加载完的情况下使用功能按键，可先将按钮设与一个observable绑定。当加载完成，把按键设置成可用。参见UI2/system/api/native/demo。
分享

var base = require('$UI/system/api/native/base');
var Model = function() {
    this.callParent();
    this.ready = justep.Bind.observable(false);
};

Model.prototype.modelLoad = function(event) {
    var self = this;
    base.ready(function() {
        self.ready.set(true);
    });
};