mpapi
v0.2.2
Published
小程序API兼容插件,一次编写,多端运行。支持:微信小程序、支付宝小程序、百度智能小程序、字节跳动小程序
Downloads
16
Maintainers
Readme
mpapi
mpapi(miniProgram API),小程序 API 兼容插件,一次编写,多端运行。
:alarm_clock: 更新日期: 2019-05-31
此项目解决的问题:寻找不同小程序 API 之间的差异,尽可能地通过一套 API 兼容多个小程序使用。
特点
- 一次编写,多端运行,支持: 微信小程序、支付宝小程序、百度智能小程序、字节跳动小程序
- 支持 Promise(包含 success 回调的才有)
- 针对某些 API 使用做了优化,如:
api.showToast
可以直接传string
、api.setStorageSync
无需调用try catch 等
- 支持特殊 API 的事件处理,例如:
request
、downloadFile
,详情 - 支持不同端的判断,
api.isWechat
、api.isAlipay
、api.isSwan
、api.isTt
安装
npm install mpapi --save
非npm安装方式,直接引入 lib
目录下的 mpapi.js
到项目即可
使用
const api = require('mpapi')
api.alert({...}).then((res) => {})
api.confirm({...}).then((res) => {})
api.getLocation().then((res) => {})
...
快速查看
- 兼容 API 列表
- 其它包装成 Promise 的 API
- API 差异
- 使用说明
- 特殊 API 的事件处理,
request
、downloadFile
、uploadFile
等 - 官方 API 文档:微信小程序、支付宝小程序、百度智能小程序、字节跳动小程序
兼容API列表
所有小程序都可以使用的 API
交互
- [x]
alert
- [x]
confirm
- [x]
showToast
- [x]
showLoading
- [x]
showActionSheet
- [x]
导航栏
- [x]
setNavigationBarTitle
- [x]
setNavigationBarColor
- [x]
文件
- [x]
saveFile
- [x]
getFileInfo
- [x]
getSavedFileInfo
- [x]
getSavedFileList
- [x]
removeSavedFile
- [x]
图片
- [x]
chooseImage
- [x]
previewImage
- [x]
compressImage
- [x]
saveImageToPhotosAlbum
- [x]
请求
- [x]
request
- [x]
uploadFile
- [x]
downloadFile
- [x]
数据缓存
- [x]
setStorageSync
- [x]
getStorageSync
- [x]
clearStorageSync
- [x]
getStorageInfoSync
- [x]
removeStorageSync
- [x]
系统设备
- [x]
getSystemInfoSync
- [x]
setScreenBrightness
- [x]
getScreenBrightness
- [x]
makePhoneCall
- [x]
scanCode
- [x]
setClipboardData
- [x]
getClipboardData
- [x]
其它包装成Promise的API
只在特定小程序下才会支持。
微信小程序、支付宝小程序、百度智能小程序、字节跳动小程序,有图标表示只支持对应小程序,没有图标表示都支持。
交互
- [x]
hideToast
- [x]
hideLoading
- [x]
showModal
- [x]
prompt
- [x]
缓存
- [x]
getStorage
- [x]
setStorage
- [x]
removeStorage
- [x]
getStorageInfo
- [x]
路由
- [x]
reLaunch
- [x]
switchTab
- [x]
redirectTo
- [x]
navigateTo
- [x]
navigateBack
- [x]
位置
- [x]
getLocation
- [x]
openLocation
- [x]
chooseLocation
- [x]
文件图片
- [x]
saveImage
- [x]
getImageInfo
- [x]
chooseVideo
- [x]
chooseMessageFile
- [x]
saveVideoToPhotosAlbum
- [x]
openDocument
- [x]
音频
- [x]
stopVoice
- [x]
playVoice
- [x]
getAvailableAudioSources
- [x]
stopBackgroundAudio
- [x]
playBackgroundAudio
- [x]
seekBackgroundAudio
- [x]
pauseBackgroundAudio
- [x]
getBackgroundAudioPlayerState
- [x]
setInnerAudioOption
- [x]
startRecord
- [x]
stopRecord
- [x]
stopRecord
- [x]
导航栏
- [x]
getTitleColor
- [x]
setNavigationBar
- [x]
showNavigationBarLoading
- [x]
hideNavigationBarLoading
- [x]
背景
- [x]
setBackgroundTextStyle
- [x]
setBackgroundColor
- [x]
showTabBar
- [x]
hideTabBar
- [x]
setTabBarItem
- [x]
setTabBarStyle
- [x]
showTabBarRedDot
- [x]
hideTabBarRedDot
- [x]
setTabBarBadge
- [x]
removeTabBarBadge
- [x]
下拉刷新
- [x]
startPullDownRefresh
- [x]
stopPullDownRefresh
- [x]
滚动
- [x]
pageScrollTo
- [x]
sendSocketMessage
- [x]
connectSocket
- [x]
closeSocket
- [x]
startLocalServiceDiscovery
- [x]
stopLocalServiceDiscovery
- [x]
置顶
- [x]
setTopBarText
- [x]
画布
- [x]
canvasGetImageData
- [x]
canvasPutImageData
- [x]
canvasToTempFilePath
- [x]
分享转发
- [x]
getShareInfo
- [x]
updateShareMenu
- [x]
showShareMenu
- [x]
hideShareMenu
- [x]
showFavoriteGuide
- [x]
openShare
- [x]
登录、授权、用户信息
- [x]
login
- [x]
checkSession
- [x]
getUserInfo
- [x]
getAuthCode
- [x]
getAuthUserInfo
- [x]
getPhoneNumber
- [x]
authorize
- [x]
支付
- [x]
tradePay
- [x]
requestPayment
- [x]
requestPolymerPayment
- [x]
开放接口
- [x]
getSetting
- [x]
openSetting
- [x]
reportAnalytics
- [x]
chooseInvoiceTitle
- [x]
navigateToMiniProgram
- [x]
navigateBackMiniProgram
- [x]
开放接口 - 微信小程序
- [x]
addCard
- [x]
openCard
- [x]
chooseInvoice
- [x]
startSoterAuthentication
- [x]
checkIsSoterEnrolledInDevice
- [x]
checkIsSupportSoterAuthentication
- [x]
getWeRunData
- [x]
开放接口 - 支付宝小程序
- [x]
startZMVerify
- [x]
textRiskIdentification
- [x]
addCardAuth
- [x]
getRunScene
- [x]
chooseCity
- [x]
datePicker
- [x]
optionsSelect
- [x]
multiLevelSelect
- [x]
rsa
- [x]
开放接口 - 百度智能小程序
- [x]
getSwanId
- [x]
navigateToSmartProgram
- [x]
navigateBackSmartProgram
- [x]
setPageInfo
- [x]
setMetaDescription
- [x]
setMetaKeywords
- [x]
setDocumentTitle
- [x]
loadSubPackage
- [x]
联系人
- [x]
chooseAddress
- [x]
chooseContact
- [x]
choosePhoneContact
- [x]
chooseAlipayContact
- [x]
addPhoneContact
- [x]
字体加载
- [x]
loadFontFace
- [x]
系统信息
- [x]
getSystemInfo
- [x]
getBatteryInfo
- [x]
getNetworkType
- [x]
setKeepScreenOn
- [x]
startAccelerometer
- [x]
stopAccelerometer
- [x]
startCompass
- [x]
stopCompass
- [x]
startDeviceMotionListening
- [x]
stopDeviceMotionListening
- [x]
startGyroscope
- [x]
stopGyroscope
- [x]
vibrate
- [x]
vibrateShort
- [x]
vibrateLong
- [x]
watchShake
- [x]
setEnableDebug
- [x]
getServerTime
- [x]
scan
- [x]
蓝牙无线
- [x]
getBeacons
- [x]
startBeaconDiscovery
- [x]
stopBeaconDiscovery
- [x]
startWifi
- [x]
stopWifi
- [x]
setWifiList
- [x]
getWifiList
- [x]
connectWifi
- [x]
getConnectedWifi
- [x]
getBLEDeviceServices
- [x]
getBLEDeviceCharacteristics
- [x]
createBLEConnection
- [x]
closeBLEConnection
- [x]
writeBLECharacteristicValue
- [x]
readBLECharacteristicValue
- [x]
notifyBLECharacteristicValueChange
- [x]
startBluetoothDevicesDiscovery
- [x]
stopBluetoothDevicesDiscovery
- [x]
openBluetoothAdapter
- [x]
getConnectedBluetoothDevices
- [x]
getBluetoothDevices
- [x]
getBluetoothAdapterState
- [x]
closeBluetoothAdapter
- [x]
stopHCE
- [x]
startHCE
- [x]
getHCEState
- [x]
sendHCEMessage
- [x]
第三方平台
- [x]
getExtConfig
- [x]
深层级的 API
api.ap
- [x]
api.ap.$faceVerify
- [x]
api.ap.$navigateToAlipayPage
- [x]
...
- [x]
api.ai
- [x]
api.ai.$ocrIdCard
- [x]
api.ai.$ocrBankCard
- [x]
...
- [x]
某些新实例的对象上面的 API
- [x]
createMapContext
- [x]
createVideoContext
- [x]
createAudioContext
- [x]
createCameraContext
- [x]
createInnerAudioContext
- [x]
createLivePusherContext
- [x]
createLivePlayerContext
- [x]
getBackgroundAudioManager
- [x]
getRecorderManager
- [x]
createSelectorQuery
- [x]
getFileSystemManager
- [x]
createARCameraContext
- [x]
例如:注意:方法加了 $
前缀
let ctx = api.createMapContext('maper')
ctx.$getCenterLocation().then((res) => {
console.log('createMapContext:getCenterLocation')
console.log(res)
})
小程序之间的API差异
1、传参不一致
例如:showLoading
方法,加载的显示文案,微信和百度里面是 title
参数,支付宝里面是 content
参数,如下
// 微信
wx.showLoading({
title: '加载中'
})
// 百度
swan.showLoading({
title: '加载中'
})
// 支付宝
my.showLoading({
content: '加载中'
})
// 使用 mpapi 之后,多端兼容
api.showLoading('加载中')
api.showLoading({
title: '提示内容'
})
2、返回参不一致
例如:showActionSheet
方法,执行完之后获取选择的索引,微信和百度里面是 res.tapIndex
,支付宝里面是 res.index
,如下
// 微信
wx.showActionSheet({
itemList: ['台球', '羽毛球', '篮球'],
success: (res) => {
// res.tapIndex
}
})
// 支付宝
my.showActionSheet({
items: ['台球', '羽毛球', '篮球'],
success: (res) => {
// res.index
}
})
// 使用 mpapi,多端兼容
api.showActionSheet({
itemList: ['台球', '羽毛球', '篮球'],
success: (res) => {
// res.tapIndex
}
})
3、不支持,但可兼容
例如:支付宝里面有 my.alert
,而微信和百度里面没有此方法,但是可以通过微信的 wx.showModal
或百度的 swan.showModal
封装一个 alert
方法,如下
api.alert('提示内容')
api.alert({
content: '提示内容'
})
// 请求数据,兼容多端
api.request({...}).then((res) => {})
4、不支持,无法兼容
有的 API 只在特定端里面有效,无法兼容处理,如下
// 只在支付宝里面有效,微信和百度小程序里面会报错
api.startZMVerify({...})
// 建议这样处理
if(api.isAlipay){
api.startZMVerify({...})
}
// 只在微信里面有效,支付宝或百度小程序里面会报错
api.setTopBarText({...})
// 建议这样处理
if(api.isWechat){
api.setTopBarText({...})
}
// 百度智能小程序的特殊 API 一样的道理
if(api.isSwan){
api.getSwanId().then((res) => {})
}
使用说明
1、支持 Promise
风格
所有小程序的 API 只要包含 success
回调,都已经用 Promise
封装过,可以直接使用,两种写法都支持,例如
// 使用回调
api.showActionSheet({
itemList: ['台球', '羽毛球', '篮球'],
success: (res) => {
// res.tapIndex
}
})
// 或者
api.showActionSheet({
itemList: ['台球', '羽毛球', '篮球']
}).then((res) => {
// res.tapIndex
})
// 其它
api.setStorage({...}).then((res) => {})
api.chooseImage({...}).then((res) => {})
...
2、兼容方法里的传参和返回参,以微信小程序调用为准。其它端不兼容的参数不处理(某些参数也无法处理,特定小程序不支持)开发者需要留意,例如
api.chooseImage({
count: 1,
sizeType: ['original', 'compressed'], // 只在微信可用
sourceType: ['album', 'camera'],
}).then((res) => {
// res.tempFilePaths 在微信和支付宝都可用
// res.tempFiles 只在微信可用
})
特殊API的事件处理
某些 API 既要支持 Promise,又要调用它的事件,那么可以采用如下方式:
以前:
const downloadTask = wx.downloadFile({
url: 'https://example.com/audio/123', // 仅为示例,并非真实的资源
success(res){
console.log(res)
}
})
downloadTask.onProgressUpdate((res) => {
console.log(res)
})
downloadTask.abort() // 取消下载任务
使用 mpapi
之后:
const api = require('mpapi')
const downloadTask = api.downloadFile({
url: 'https://example.com/audio/123' // 仅为示例,并非真实的资源
}).then((res) => {
console.log('success')
console.log(res)
})
downloadTask.$event('onProgressUpdate', (res) => {
console.log(res)
})
// downloadTask.$event('abort') // 取消下载任务
其它 API 可以类似处理,例如:request
、uploadFile
、connectSocket
Issues
如果您在使用过程中发现 Bug,或者有好的建议,欢迎报告问题。