端能力 API

由于不同的端自身会提供不同的端能力 API，例如微信小程序中提供了网络请求、本地存储等等端能力的封装，目前在所有端中，微信小程序所提供的端能力 API 最为丰富，所以 Taro 在设计之初端能力的 API 便是采用微信小程序标准，在其他端各自对应实现，同时又对微信小程序的 API 进行了一些优化处理，例如异步的 API 支持 Promise 化，利用队列解决了 wx.request 的请求个数限制问题等等。

因为采用微信小程序标准的缘故，Taro 项目在编译到微信小程序端 API 都是可以正常运行的，如果编译到其他端，则要视当前端的能力支持而定，例如 H5 端就无法调用扫码、蓝牙等端能力，所以这些 API 在 H5 端运行的时候将什么也不做。

网络

发起请求

Taro.request(OBJECT)

发起网络请求，支持 Promise 化使用。

OBJECT 参数说明：

H5 端附加参数说明：

success 返回参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.request({
  url: 'http://localhost:8080/test',
  data: {
    foo: 'foo',
    bar: 10
  },
  header: {
    'content-type': 'application/json'
  }
})
  .then(res => console.log(res.data))

API 支持度

上传、下载

Taro.uploadFile(OBJECT)

使用方式同 wx.uploadFile，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

const uploadTask = Taro.uploadFile(params).then(...)

Taro.downloadFile(OBJECT)

使用方式同 wx.downloadFile，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.downloadFile(params).then(...)

API 支持度

WebSocket

Taro.connectSocket(OBJECT)

创建一个 WebSocket 链接。

支持存在最多两个 WebSocket 链接，每次成功调用 Taro.connectSocket 会返回一个新的 SocketTask。

OBJECT 参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.connectSocket({
  url: 'ws://echo.websocket.org/echo',
  success: function () {
    console.log('connect success')
  }
}).then(task => {
  task.onOpen(function () {
    console.log('onOpen')
    task.send({ data: 'xxx' })
  })
  task.onMessage(function (msg) {
    console.log('onMessage: ', msg)
    task.close()
  })
  task.onError(function () {
    console.log('onError')
  })
  task.onClose(function (e) {
    console.log('onClose: ', e)
  })
})

SocketTask

WebSocket 任务，可通过 wx.connectSocket() 接口创建返回。

属性

socketTask.readyState: websocket 当前的连接状态。

socketTask.CONNECTING: websocket 状态值：连接中。

socketTask.OPEN: websocket 状态值：已连接。

socketTask.CLOSING: websocket 状态值：关闭中。

socketTask.CLOSED: websocket 状态值：已关闭。

socketTask.ws: 浏览器 websocket 实例。（h5 端独有）

方法

SocketTask.send(OBJECT)

通过 WebSocket 连接发送数据。

OBJECT 参数说明：

SocketTask.close(OBJECT)

关闭 WebSocket 连接。

OBJECT 参数说明：

SocketTask.onOpen(CALLBACK)

监听 WebSocket 连接打开事件。

SocketTask.onClose(CALLBACK)

监听 WebSocket 连接关闭事件。

CALLBACK 返回参数

SocketTask.onError(CALLBACK)

监听 WebSocket 错误。

CALLBACK 返回参数

SocketTask.onMessage(CALLBACK)

监听 WebSocket 接受到服务器的消息事件。

CALLBACK 返回参数

Taro.onSocketOpen

@Deprecated 请使用 SocketTask.onOpen

Taro.onSocketError

@Deprecated 请使用 SocketTask.onError

Taro.sendSocketMessage

@Deprecated 请使用 SocketTask.send

Taro.onSocketMessage

@Deprecated 请使用 SocketTask.onMessage

Taro.closeSocket

@Deprecated 请使用 SocketTask.close

Taro.onSocketClose

@Deprecated 请使用 SocketTask.onClose

API 支持度

媒体

图片

Taro.chooseImage(OBJECT)

使用方式同 wx.chooseImage，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.chooseImage(params).then(...)

Taro.previewImage(OBJECT)

使用方式同 wx.previewImage，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.previewImage(params).then(...)

Taro.getImageInfo(OBJECT)

使用方式同 wx.getImageInfo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getImageInfo(params).then(...)

Taro.saveImageToPhotosAlbum(OBJECT)

使用方式同 wx.saveImageToPhotosAlbum，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.saveImageToPhotosAlbum(params).then(...)

API 支持度

录音

Taro.startRecord(OBJECT)

使用方式同 wx.startRecord，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startRecord(params).then(...)

Taro.stopRecord()

​主动调用停止录音。

​示例代码：

import Taro from '@tarojs/taro'

Taro.stopRecord()

API 支持度

录音管理

Taro.getRecorderManager()

使用方式同 wx.getRecorderManager。

示例代码：

import Taro from '@tarojs/taro'

const recorderManager = Taro.getRecorderManager()

API 支持度

音频播放控制

Taro.playVoice(OBJECT)

使用方式同 wx.playVoice，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.playVoice(params).then(...)

Taro.pauseVoice()

暂停正在播放的语音。再次调用 Taro.playVoice 播放同一个文件时，会从暂停处开始播放。如果想从头开始播放，需要先调用 Taro.stopVoice。

示例代码：

import Taro from '@tarojs/taro'

Taro.startRecord(params)
  .then(res => {
    const filePath = res.tempFilePath
    Taro.playVoice({ filePath })

    setTimeout(Taro.pauseVoice, 5000)
  })

Taro.stopVoice

结束播放语音。

示例代码：

import Taro from '@tarojs/taro'

Taro.startRecord(params)
  .then(res => {
    const filePath = res.tempFilePath
    Taro.playVoice({ filePath })

    setTimeout(Taro.stopVoice, 5000)
  })

API 支持度

音乐播放控制

Taro.getBackgroundAudioPlayerState(OBJECT)

使用方式同 wx.getBackgroundAudioPlayerState，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getBackgroundAudioPlayerState(params).then(...)

Taro.playBackgroundAudio(OBJECT)

使用方式同 wx.playBackgroundAudio，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.playBackgroundAudio(params).then(...)

Taro.pauseBackgroundAudio()

暂停播放音乐。

示例代码：

import Taro from '@tarojs/taro'

Taro.pauseBackgroundAudio()

Taro.seekBackgroundAudio(OBJECT)

使用方式同 wx.seekBackgroundAudio，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.seekBackgroundAudio(params).then(...)

Taro.stopBackgroundAudio()

停止播放音乐。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopBackgroundAudio()

Taro.onBackgroundAudioPlay(CALLBACK)

监听音乐播放。

Taro.onBackgroundAudioPause(CALLBACK)

监听音乐暂停。

Taro.onBackgroundAudioStop(CALLBACK)

监听音乐停止。

API 支持度

背景音频播放管理

Taro.getBackgroundAudioManager()

使用方式同 wx.getBackgroundAudioManager。

示例代码：

import Taro from '@tarojs/taro'

const backgroundAudioManager = Taro.getBackgroundAudioManager()

API 支持度

音频组件控制

Taro.createAudioContext(audioId, this.$scope)

使用方式同 wx.createAudioContext。

示例代码：

import Taro from '@tarojs/taro'

const audioCtx = Taro.createAudioContext('myAudio')

Taro.createInnerAudioContext()

使用方式同 wx.createInnerAudioContext。

示例代码：

import Taro from '@tarojs/taro'

const innerAudioContext = Taro.createInnerAudioContext()

API 支持度

视频

Taro.chooseVideo(OBJECT)

使用方式同 wx.chooseVideo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.chooseVideo(params).then(...)

Taro.saveVideoToPhotosAlbum(OBJECT)

使用方式同 wx.saveVideoToPhotosAlbum，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.saveVideoToPhotosAlbum(params).then(...)

API 支持度

视频组件控制

Taro.createVideoContext(videoId, this.$scope)

使用方式同 wx.createVideoContext。

示例代码：

import Taro from '@tarojs/taro'

const videoContext = Taro.createVideoContext('myVideo')

API 支持度

相机组件控制

Taro.createCameraContext(this.$scope)

使用方式同 wx.createCameraContext。

示例代码：

import Taro from '@tarojs/taro'

const cameraContext = Taro.createCameraContext()

API 支持度

文件

Taro.saveFile(OBJECT)

使用方式同 wx.saveFile，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.saveFile(params).then(...)

Taro.getFileInfo(OBJECT)

使用方式同 wx.getFileInfo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getFileInfo(params).then(...)

Taro.getSavedFileList(OBJECT)

使用方式同 wx.getSavedFileList，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getSavedFileList(params).then(...)

Taro.getSavedFileInfo(OBJECT)

使用方式同 wx.getSavedFileInfo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getSavedFileInfo(params).then(...)

Taro.removeSavedFile(OBJECT)

使用方式同 wx.removeSavedFile，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.removeSavedFile(params).then(...)

Taro.openDocument(OBJECT)

使用方式同 wx.openDocument，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.openDocument(params).then(...)

API 支持度

数据缓存

Taro.setStorage(OBJECT)

将数据存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个异步接口，支持 Promise 化使用。

OBJECT 参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.setStorage({ key: 'key', data: 'value' })
  .then(res => console.log(res))

Taro.setStorageSync(KEY, DATA)

将 data 存储在本地缓存中指定的 key 中，会覆盖掉原来该 key 对应的内容，这是一个同步接口。

参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.setStorageSync('key', 'value')

Taro.getStorage(OBJECT)

从本地缓存中异步获取指定 key 对应的内容，支持 Promise 化使用。

OBJECT 参数说明：

success 返回参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.getStorage({ key: 'key' })
  .then(res => console.log(res.data))

Taro.getStorageSync(KEY)

从本地缓存中同步获取指定 key 对应的内容。

参数说明：

示例代码：

import Taro from '@tarojs/taro'

const data = Taro.getStorageSync('key')

Taro.getStorageInfo(OBJECT)

异步获取当前 storage 的相关信息，支持 Promise 化使用。

OBJECT 参数说明：

success 返回参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.getStorageInfo()
  .then(res => console.log(res.keys))

Taro.getStorageInfoSync()

同步获取当前 storage 的相关信息。

示例代码：

import Taro from '@tarojs/taro'

const res = Taro.getStorageInfoSync()
console.log(res.keys)

Taro.removeStorage(OBJECT)

从本地缓存中异步移除指定 key，支持 Promise 化使用。

OBJECT 参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.removeStorage({ key: 'key' })
  .then(res => console.log(res))

Taro.removeStorageSync(KEY)

从本地缓存中同步移除指定 key 。

参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.removeStorageSync('key')

Taro.clearStorage()

清理本地数据缓存。

示例代码：

import Taro from '@tarojs/taro'

Taro.clearStorage()

Taro.clearStorageSync()

同步清理本地数据缓存

示例代码：

import Taro from '@tarojs/taro'

Taro.clearStorageSync()

API 支持度

位置

获取位置

Taro.getLocation(OBJECT)

使用方式同 wx.getLocation，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getLocation(params).then(...)

Taro.chooseLocation(OBJECT)

使用方式同 wx.chooseLocation，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.chooseLocation(params).then(...)

API 支持度

查看位置

Taro.openLocation(OBJECT)

使用方式同 wx.openLocation，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.openLocation(params).then(...)

API 支持度

地图组件控制

Taro.createMapContext(mapId, this.$scope)

使用方式同 wx.createMapContext。

示例代码：

import Taro from '@tarojs/taro'

const mapCtx = Taro.createMapContext('myMap')

API 支持度

设备

系统信息

Taro.getSystemInfo(OBJECT)

获取系统信息，支持 Promise 化使用。

OBJECT 参数说明：

success 返回参数说明：

注意：H5 端不支持 version、statusBarHeight、fontSizeSetting、SDKVersion

示例代码：

import Taro from '@tarojs/taro'

Taro.getSystemInfo({
  success: res => console.log(res)
})
  .then(res => console.log(res))

Taro.getSystemInfoSync()

获取系统信息同步接口。

同步返回参数说明：

注意：H5 端不支持 version、statusBarHeight、fontSizeSetting、SDKVersion

示例代码：

import Taro from '@tarojs/taro'

const res = Taro.getSystemInfoSync()
console.log(res.model)
console.log(res.pixelRatio)
console.log(res.windowWidth)
console.log(res.windowHeight)
console.log(res.language)
console.log(res.version)
console.log(res.platform)

Taro.canIUse(String)

使用方式同 wx.canIUse。

示例代码：

import Taro from '@tarojs/taro'

Taro.canIUse('openBluetoothAdapter')
Taro.canIUse('getSystemInfoSync.return.screenWidth')
Taro.canIUse('getSystemInfo.success.screenWidth')
Taro.canIUse('showToast.object.image')
Taro.canIUse('onCompassChange.callback.direction')
Taro.canIUse('request.object.method.GET')
Taro.canIUse('live-player')
Taro.canIUse('text.selectable')
Taro.canIUse('button.open-type.contact')

API 支持度

网络状态

Taro.getNetworkType(OBJECT)

获取网络类型，支持 Promise 化使用。

OBJECT 参数说明：

success 返回参数说明：

networkType 有效值：

注意：

H5 下此 API 兼容性较差，详见 Can I use。并且标准不一，对于三种规范分别支持的 networkType 有效值如下。

• 仅支持不符合规范的 navigator.connetion.type，详情。networkType 有效值为：’wifi’、’3g’、’2g’、’unknown’。
• 支持 navigator.connetion.type。networkType 有效值为：’cellular’、’wifi’、’none’。
• 支持 navigator.connetion.effectiveType。networkType 有效值为：’slow-2g’、’2g’、’3g’、’4g’。

示例代码：

import Taro from '@tarojs/taro'

Taro.getNetworkType({
  success: res => console.log(res.networkType)
})
  .then(res => console.log(res.networkType))

Taro.onNetworkStatusChange(CALLBACK)

监听网络状态变化。

CALLBACK 返回参数：

注意：H5 端兼容情况较差，只有当 navigator.connection 支持监听 onChange 事件时才会生效。

示例代码：

import Taro from '@tarojs/taro'

Taro.onNetworkStatusChange(res => {
  console.log(res.isConnected)
  console.log(res.networkType)
})

API 支持度

加速度计

Taro.onAccelerometerChange(CALLBACK)

使用方式同 wx.onAccelerometerChange。

示例代码：

import Taro from '@tarojs/taro'

Taro.onAccelerometerChange(res => {
  console.log(res.x)
  console.log(res.y)
  console.log(res.z)
})

Taro.startAccelerometer(OBJECT)

使用方式同 wx.startAccelerometer。

示例代码：

import Taro from '@tarojs/taro'

Taro.startAccelerometer({ interval: 'game' })

Taro.stopAccelerometer(OBJECT)

使用方式同 wx.stopAccelerometer。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopAccelerometer()

API 支持度

罗盘

Taro.onCompassChange(CALLBACK)

使用方式同 wx.onCompassChange。

示例代码：

import Taro from '@tarojs/taro'

Taro.onCompassChange(res => {
  console.log(res.direction)
})

Taro.startCompass(OBJECT)

使用方式同 wx.startCompass。

示例代码：

import Taro from '@tarojs/taro'

Taro.startCompass()

Taro.stopCompass(OBJECT)

使用方式同 wx.stopCompass。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopCompass()

API 支持度

拨打电话

Taro.makePhoneCall(OBJECT)

拨打电话，支持 Promise 化使用。

OBJECT 参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.makePhoneCall({
  phoneNumber: '10086'
})
  .then(...)

API 支持度

扫码

Taro.scanCode(OBJECT)

使用方式同 wx.scanCode，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.scanCode(params).then(...)

API 支持度

剪贴板

Taro.setClipboardData(OBJECT)

使用方式同 wx.setClipboardData，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setClipboardData(params).then(...)

Taro.getClipboardData(OBJECT)

使用方式同 wx.getClipboardData，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getClipboardData(params).then(...)

API 支持度

蓝牙

Taro.openBluetoothAdapter(OBJECT)

使用方式同 wx.openBluetoothAdapter，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.openBluetoothAdapter(params).then(...)

Taro.closeBluetoothAdapter(OBJECT)

使用方式同 wx.closeBluetoothAdapter，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.closeBluetoothAdapter(params).then(...)

Taro.getBluetoothAdapterState(OBJECT)

使用方式同 wx.getBluetoothAdapterState，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getBluetoothAdapterState(params).then(...)

Taro.onBluetoothAdapterStateChange(CALLBACK)

使用方式同 wx.onBluetoothAdapterStateChange。

示例代码：

import Taro from '@tarojs/taro'

Taro.onBluetoothAdapterStateChange(res => {
  console.log(`adapterState changed, now is`, res)
})

Taro.startBluetoothDevicesDiscovery(OBJECT)

使用方式同 wx.startBluetoothDevicesDiscovery，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startBluetoothDevicesDiscovery(params).then(...)

Taro.stopBluetoothDevicesDiscovery(OBJECT)

使用方式同 wx.stopBluetoothDevicesDiscovery，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopBluetoothDevicesDiscovery(params).then(...)

Taro.getBluetoothDevices(OBJECT)

使用方式同 wx.getBluetoothDevices，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getBluetoothDevices(params).then(...)

Taro.getConnectedBluetoothDevices(OBJECT)

使用方式同 wx.getConnectedBluetoothDevices，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getConnectedBluetoothDevices(params).then(...)

Taro.onBluetoothDeviceFound(CALLBACK)

使用方式同 wx.onBluetoothDeviceFound。

示例代码：

import Taro from '@tarojs/taro'

Taro.onBluetoothDeviceFound(devices => {
  console.log(devices)
  console.log(devices[0].advertisData)
})

Taro.createBLEConnection(OBJECT)

使用方式同 wx.createBLEConnection，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.createBLEConnection(params).then(...)

Taro.closeBLEConnection(OBJECT)

使用方式同 wx.closeBLEConnection，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.closeBLEConnection(params).then(...)

Taro.getBLEDeviceServices(OBJECT)

使用方式同 wx.getBLEDeviceServices，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getBLEDeviceServices(params).then(...)

Taro.getBLEDeviceCharacteristics(OBJECT)

使用方式同 wx.getBLEDeviceCharacteristics，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getBLEDeviceCharacteristics(params).then(...)

Taro.readBLECharacteristicValue(OBJECT)

使用方式同 wx.readBLECharacteristicValue，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.readBLECharacteristicValue(params).then(...)

Taro.writeBLECharacteristicValue(OBJECT)

使用方式同 wx.writeBLECharacteristicValue，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.writeBLECharacteristicValue(params).then(...)

Taro.notifyBLECharacteristicValueChange(OBJECT)

使用方式同 wx.notifyBLECharacteristicValueChange，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.notifyBLECharacteristicValueChange(params).then(...)

Taro.onBLEConnectionStateChange(CALLBACK)

使用方式同 wx.onBLEConnectionStateChange。

示例代码：

import Taro from '@tarojs/taro'

Taro.onBLEConnectionStateChange(res => {
  // 该方法回调中可以用于处理连接意外断开等异常情况
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

Taro.onBLECharacteristicValueChange(CALLBACK)

使用方式同 wx.onBLECharacteristicValueChange。

示例代码：

import Taro from '@tarojs/taro'

Taro.onBLECharacteristicValueChange(res => {
  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
  console.log(res.value)
})

API 支持度

iBeacon

Taro.startBeaconDiscovery(OBJECT)

使用方式同 wx.startBeaconDiscovery，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startBeaconDiscovery(params).then(...)

Taro.stopBeaconDiscovery(OBJECT)

使用方式同 wx.stopBeaconDiscovery，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopBeaconDiscovery(params).then(...)

Taro.getBeacons(OBJECT)

使用方式同 wx.getBeacons，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getBeacons(params).then(...)

Taro.onBeaconUpdate(CALLBACK)

使用方式同 wx.onBeaconUpdate。

Taro.onBeaconServiceChange(CALLBACK)

使用方式同 wx.onBeaconServiceChange。

API 支持度

屏幕亮度

Taro.setScreenBrightness(OBJECT)

使用方式同 wx.setScreenBrightness，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setScreenBrightness(params).then(...)

Taro.getScreenBrightness(OBJECT)

使用方式同 wx.getScreenBrightness，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getScreenBrightness(params).then(...)

Taro.setKeepScreenOn(OBJECT)

使用方式同 wx.setKeepScreenOn，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setKeepScreenOn(params).then(...)

API 支持度

用户截屏事件

Taro.onUserCaptureScreen(CALLBACK)

监听用户主动截屏事件，用户使用系统截屏按键截屏时触发此事件。

示例代码：

import Taro from '@tarojs/taro'

Taro.onUserCaptureScreen(() => {
    console.log('用户截屏了')
})

API 支持度

振动

Taro.vibrateLong(OBJECT)

使用方式同 wx.vibrateLong，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.vibrateLong(params).then(...)

Taro.vibrateShort(OBJECT)

使用方式同 wx.vibrateShort，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.vibrateShort(params).then(...)

API 支持度

手机联系人

Taro.addPhoneContact(OBJECT)

使用方式同 wx.addPhoneContact，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.addPhoneContact(params).then(...)

API 支持度

NFC

Taro.getHCEState(OBJECT)

使用方式同 wx.getHCEState，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getHCEState(params).then(...)

Taro.startHCE(OBJECT)

使用方式同 wx.startHCE，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startHCE(params).then(...)

Taro.stopHCE(OBJECT)

使用方式同 wx.stopHCE，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopHCE(params).then(...)

Taro.onHCEMessage(CALLBACK)

使用方式同 wx.onHCEMessage。

Taro.sendHCEMessage(OBJECT)

使用方式同 wx.sendHCEMessage，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.sendHCEMessage(params).then(...)

API 支持度

Wi-Fi

Taro.startWifi(OBJECT)

使用方式同 wx.startWifi，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startWifi(params).then(...)

Taro.stopWifi(OBJECT)

使用方式同 wx.stopWifi，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopWifi(params).then(...)

Taro.connectWifi(OBJECT)

使用方式同 wx.connectWifi，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.connectWifi(params).then(...)

Taro.getWifiList(OBJECT)

使用方式同 wx.getWifiList，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getWifiList(params).then(...)

Taro.onGetWifiList(CALLBACK)

使用方式同 wx.onGetWifiList。

Taro.setWifiList(OBJECT)

使用方式同 wx.setWifiList，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setWifiList(params).then(...)

Taro.onWifiConnected(CALLBACK)

使用方式同 wx.onWifiConnected。

Taro.getConnectedWifi(OBJECT)

使用方式同 wx.getConnectedWifi，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getConnectedWifi(params).then(...)

API 支持度

界面

交互反馈

Taro.showToast(OBJECT)

显示消息提示框，支持 Promise 化使用。

OBJECT 参数说明：

icon 有效值

示例代码：

import Taro from '@tarojs/taro'

Taro.showToast({
  title: '成功',
  icon: 'success',
  duration: 2000
})
  .then(res => console.log(res))

Taro.showLoading(OBJECT)

显示 loading 提示框, 需主动调用 Taro.hideLoading 才能关闭提示框，支持 Promise 化使用。

OBJECT 参数说明：

示例代码：

import Taro from '@tarojs/taro'

Taro.showLoading({
  title: 'loading'
})
  .then(res => console.log(res))

Taro.hideToast()

隐藏消息提示框

Taro.hideLoading()

隐藏 loading 提示框

Taro.showModal(OBJECT)

​显示模态弹窗，支持 Promise 化使用。

OBJECT 参数说明：

success 返回参数说明：

示例代码：

import Taro from '@tarojs/taro'

// 注意：无论用户点击确定还是取消，Promise 都会 resolve。
Taro.showModal({
  title: 'xxx',
  content: 'hello world',
})
  .then(res => console.log(res.confirm, res.cancel))

Taro.showActionSheet(OBJECT)

显示操作菜单，支持 Promise 化使用。

​OBJECT 参数说明：

success 返回参数说明：

import Taro from '@tarojs/taro'

// 注意：当用户点击选项时 Promise 会 resolve，而当用户点击取消或蒙层时，Promise 会 reject。
Taro.showActionSheet({
  itemList: ['a', 'b', 'c']
})
  .then(res => console.log(res.errMsg, res.tapIndex))
  .catch(err => console.log(res.errMsg))

API 支持度

设置导航条

Taro.setNavigationBarTitle(OBJECT)

使用方式同 wx.setNavigationBarTitle，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setNavigationBarTitle(params).then(...)

Taro.showNavigationBarLoading()

在当前页面显示导航条加载动画。

Taro.hideNavigationBarLoading()

隐藏导航条加载动画。

Taro.setNavigationBarColor(OBJECT)

使用方式同 wx.setNavigationBarColor，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setNavigationBarColor(params).then(...)

API 支持度

设置 tabBar

Taro.setTabBarBadge(OBJECT)

使用方式同 wx.setTabBarBadge，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setTabBarBadge(params).then(...)

Taro.removeTabBarBadge(OBJECT)

使用方式同 wx.removeTabBarBadge，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.removeTabBarBadge(params).then(...)

Taro.showTabBarRedDot(OBJECT)

使用方式同 wx.showTabBarRedDot，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.showTabBarRedDot(params).then(...)

Taro.hideTabBarRedDot(OBJECT)

使用方式同 wx.hideTabBarRedDot，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.hideTabBarRedDot(params).then(...)

Taro.setTabBarStyle(OBJECT)

使用方式同 wx.setTabBarStyle，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setTabBarStyle(params).then(...)

Taro.setTabBarItem(OBJECT)

使用方式同 wx.setTabBarItem，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setTabBarItem(params).then(...)

Taro.showTabBar(OBJECT)

使用方式同 wx.showTabBar，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.showTabBar(params).then(...)

Taro.hideTabBar(OBJECT)

使用方式同 wx.hideTabBar，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.hideTabBar(params).then(...)

API 支持度

设置置顶信息

Taro.setTopBarText(OBJECT)

使用方式同 wx.setTopBarText，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.setTopBarText(params).then(...)

API 支持度

导航

Taro.navigateTo(OBJECT)

使用方式同 wx.navigateTo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.navigateTo(params).then(...)

Taro.redirectTo(OBJECT)

使用方式同 wx.redirectTo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.redirectTo(params).then(...)

Taro.switchTab(OBJECT)

使用方式同 wx.switchTab，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.switchTab(params).then(...)

Taro.navigateBack(OBJECT)

使用方式同 wx.navigateBack。

示例代码：

import Taro from '@tarojs/taro'

Taro.navigateBack({ delta: 2 })

Taro.reLaunch(OBJECT)

使用方式同 wx.reLaunch，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.reLaunch(params).then(...)

Taro.getCurrentPages(OBJECT)

使用方式同 getCurrentPages， 获取当前的页面栈，决定需要返回几层。

示例代码：

import Taro from '@tarojs/taro'

Taro.getCurrentPages().length

API 支持度

动画

Taro.createAnimation(OBJECT)

使用方式同 wx.createAnimation。

示例代码：

import Taro from '@tarojs/taro'

const animation = Taro.createAnimation({
  transformOrigin: "50% 50%",
  duration: 1000,
  timingFunction: "ease",
  delay: 0
})

API 支持度

位置

Taro.pageScrollTo(OBJECT)

使用方式同 wx.pageScrollTo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.pageScrollTo(params).then(...)

API 支持度

绘图

Taro.createCanvasContext(canvasId, this.$scope)

使用方式同 wx.createCanvasContext。

Taro.createContext(不推荐使用)

创建并返回绘图上下文。

Taro.drawCanvas(不推荐使用)

使用方式同 wx.drawCanvas。

API 支持度

下拉刷新

Taro.startPullDownRefresh(OBJECT)

使用方式同 wx.startPullDownRefresh，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startPullDownRefresh(params).then(...)

Taro.stopPullDownRefresh()

停止当前页面下拉刷新。

示例代码：

import Taro from '@tarojs/taro'

Taro.stopPullDownRefresh()

API 支持度

WXML 节点信息

Taro.createSelectorQuery()

返回一个 SelectorQuery 对象实例。可以在这个实例上使用 select 等方法选择节点，并使用 boundingClientRect 等方法选择需要查询的信息。

示例代码：

import Taro from '@tarojs/taro'

const query = Taro.createSelectorQuery()

selectorQuery.in(component)

将选择器的选取范围更改为自定义组件 component 内。（初始时，选择器仅选取页面范围的节点，不会选取任何自定义组件中的节点。）

注意：对 h5 侧不起作用，h5 侧还是从全局查找。

示例代码：

import Taro from '@tarojs/taro'

Component({
  ready () {
    const query = Taro.createSelectorQuery().in(this.$scope)
  }
})

selectorQuery.select(selector)

在当前页面下选择第一个匹配选择器 selector 的节点，返回一个 NodesRef 对象实例，可以用于获取节点信息。

• ID 选择器：#the-id
• class 选择器（可以连续指定多个）：.a-class.another-class
• 子元素选择器：.the-parent > .the-child
• 后代选择器：.the-ancestor .the-descendant
• 跨自定义组件的后代选择器：.the-ancestor >>> .the-descendant
• 多选择器的并集：#a-node, .some-other-nodes

selectorQuery.selectAll(selector)

在当前页面下选择匹配选择器 selector 的节点，返回一个 NodesRef 对象实例。 与 selectorQuery.selectNode(selector) 不同的是，它选择所有匹配选择器的节点。

selectorQuery.selectViewport()

选择显示区域，可用于获取显示区域的尺寸、滚动位置等信息，返回一个 NodesRef 对象实例。

nodesRef.boundingClientRect([callback])

添加节点的布局位置的查询请求，相对于显示区域，以像素为单位。其功能类似于 DOM 的 getBoundingClientRect。返回值是 nodesRef 对应的 selectorQuery。

返回的节点信息中，每个节点的位置用 left、right、top、bottom、width、height 字段描述。如果提供了 callback 回调函数，在执行 selectQuery 的 exec 方法后，节点信息会在 callback 中返回。

示例代码：

import Taro from '@tarojs/taro'

const query = Taro.createSelectorQuery()
query
  .select('#the-id')
  .boundingClientRect(rect => {
    rect.id      // 节点的 ID
    rect.dataset // 节点的 dataset
    rect.left    // 节点的左边界坐标
    rect.right   // 节点的右边界坐标
    rect.top     // 节点的上边界坐标
    rect.bottom  // 节点的下边界坐标
    rect.width   // 节点的宽度
    rect.height  // 节点的高度
  })
  .exec()
})

nodesRef.scrollOffset([callback])

添加节点的滚动位置查询请求，以像素为单位。节点必须是 scroll-view 或者 viewport。返回值是 nodesRef 对应的 selectorQuery。

返回的节点信息中，每个节点的滚动位置用 scrollLeft、scrollTop 字段描述。如果提供了 callback 回调函数，在执行 selectQuery 的 exec 方法后，节点信息会在 callback 中返回。

示例代码：

import Taro from '@tarojs/taro'

Taro.createSelectorQuery()
  .selectViewport()
  .scrollOffset(rect => {
    rect.id      // 节点的 ID
    rect.dataset // 节点的 dataset
    res.scrollLeft // 节点的水平滚动位置
    res.scrollTop  // 节点的竖直滚动位置
  })
  .exec()
})

nodesRef.fields(fields, [callback])

获取节点的相关信息，需要获取的字段在 fields 中指定。返回值是 nodesRef 对应的 selectorQuery。可指定获取的字段包括：

注意： computedStyle 的优先级高于 size，当同时在 computedStyle 里指定了 width/height 和传入了 size: true，则优先返回 computedStyle 获取到的 width/height。

示例代码：

import Taro from '@tarojs/taro'

Taro.createSelectorQuery()
  .select('#the-id')
  .fields({
    dataset: true,
    size: true,
    scrollOffset: true,
    properties: ['scrollX', 'scrollY'],
    computedStyle: ['margin', 'backgroundColor']
  }, res => {
    res.dataset    // 节点的 dataset
    res.width      // 节点的宽度
    res.height     // 节点的高度
    res.scrollLeft // 节点的水平滚动位置
    res.scrollTop  // 节点的竖直滚动位置
    res.scrollX    // 节点 scroll-x 属性的当前值
    res.scrollY    // 节点 scroll-y 属性的当前值
    // 此处返回指定要返回的样式名
    res.margin
    res.backgroundColor
  })
  .exec()
})

selectorQuery.exec([callback])

执行所有的请求，请求结果按请求次序构成数组，在 callback 的第一个参数中返回。

API 支持度

开放接口

设置

Taro.getSetting(OBJECT)

使用方式同 wx.getSetting，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getSetting(params).then(...)

Taro.openSetting(OBJECT)

使用方式同 wx.openSetting，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.openSetting(params).then(...)

API 支持度

收货地址

Taro.chooseAddress(OBJECT)

使用方式同 wx.chooseAddress，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.chooseAddress(params).then(...)

API 支持度

授权

Taro.authorize(OBJECT)

使用方式同 wx.authorize，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.authorize(params).then(...)

API 支持度

卡券

Taro.addCard(OBJECT)

使用方式同 wx.addCard，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.addCard(params).then(...)

Taro.openCard(OBJECT)

使用方式同 wx.openCard，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.openCard(params).then(...)

API 支持度

发票

Taro.chooseInvoice(OBJECT)

使用方式同 wx.chooseInvoice，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.chooseInvoice(params).then(...)

Taro.chooseInvoiceTitle(OBJECT)

使用方式同 wx.chooseInvoiceTitle，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.chooseInvoiceTitle(params).then(...)

API 支持度

支付

Taro.faceVerifyForPay(OBJECT)

使用方式同 wx.faceVerifyForPay，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.faceVerifyForPay(params).then(...)

Taro.requestPayment(OBJECT)

使用方式同 wx.requestPayment，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.requestPayment(params).then(...)

API 支持度

用户信息

Taro.getUserInfo(OBJECT)

使用方式同 wx.getUserInfo，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getUserInfo(params).then(...)

API 支持度

微信运动

Taro.getWeRunData(OBJECT)

使用方式同 wx.getWeRunData，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.getWeRunData(params).then(...)

API 支持度

登录

Taro.login(OBJECT)

使用方式同 wx.login，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.login(params).then(...)

Taro.checkSession(OBJECT)

使用方式同 wx.checkSession，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.checkSession(params).then(...)

API 支持度

生物认证

Taro.checkIsSoterEnrolledInDevice(OBJECT)

使用方式同 wx.checkIsSoterEnrolledInDevice，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.checkIsSoterEnrolledInDevice(params).then(...)

Taro.checkIsSupportSoterAuthentication(OBJECT)

使用方式同 wx.checkIsSupportSoterAuthentication，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.checkIsSupportSoterAuthentication(params).then(...)

Taro.startSoterAuthentication(OBJECT)

使用方式同 wx.startSoterAuthentication，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.startSoterAuthentication(params).then(...)

API 支持度

小程序跳转

Taro.navigateBackMiniProgram(OBJECT)

使用方式同 wx.navigateBackMiniProgram，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.navigateBackMiniProgram(params).then(...)

Taro.navigateToMiniProgram(OBJECT)

使用方式同 wx.navigateToMiniProgram，支持 Promise 化使用。

示例代码：

import Taro from '@tarojs/taro'

Taro.navigateToMiniProgram(params).then(...)

API 支持度

更新

Taro.getUpdateManager()

使用方式同 wx.getUpdateManager。

示例代码：

import Taro from '@tarojs/taro'

Taro.getUpdateManager()

API 支持度

拓展接口

Taro.arrayBufferToBase64(arrayBuffer)

将 ArrayBuffer 数据转成 Base64 字符串。(小程序端基础库 1.1.0 开始支持，低版本需做兼容处理)

示例代码：

import Taro from '@tarojs/taro'

const arrayBuffer = new Uint8Array([11, 22, 33])
const base64 = Taro.arrayBufferToBase64(arrayBuffer)

Taro.base64ToArrayBuffer(base64)

将 Base64 字符串转成 ArrayBuffer 数据。(小程序端基础库 1.1.0 开始支持，低版本需做兼容处理)

示例代码：

import Taro from '@tarojs/taro'

const base64 = 'CxYh'
const arrayBuffer = Taro.base64ToArrayBuffer(base64)

API 支持度