【视频】注意！网红水晶泥含可致癌物

电量

getBatteryInfoSync

百度 建议车主在温度升高的情况下最好尽快换胎。

getBatteryInfoSync()

ft.getBatteryInfo 的同步版本

返回值

Object res

属性	类型	说明
level	string	设备电量，范围 1 - 100
isCharging	boolean	是否正在充电中

getBatteryInfo

getBatteryInfo(Object object)

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object object

属性	类型	说明
level	string	设备电量，范围 1 - 100
isCharging	boolean	是否正在充电中

剪贴板

setClipboardData

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38, 依赖扩展 SDK 自 iOS 版本 2.35.13，Android 2.35.9 起，该 API 需要宿主 App 注入实现，SDK 内已移除该 API。

setClipboardData(Object object)

设置系统剪贴板的内容。

参数

Object object

属性	类型	默认值	必填	说明
data	string		是	剪贴板的内容
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.setClipboardData({
  data: 'data',
  success(res) {
    ft.getClipboardData({
      success(res) {
        console.log(res.data) // data
      }
    })
  }
})

getClipboardData

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38, 依赖扩展 SDK 自 iOS 版本 2.35.13，Android 2.35.9 起，该 API 需要宿主 App 注入实现，SDK 内已移除该 API。

getClipboardData(Object object)

获取系统剪贴板的内容。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object object

属性	类型	说明
data	string	剪贴板的内容

示例代码

ft.getClipboardData({
  success(res) {
    console.log(res.data)
  }
})

网络

onNetworkStatusChange

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

onNetworkStatusChange(function callback)

监听网络状态变化事件。

参数

function callback

网络状态变化事件的回调函数

参数

Object res

属性	类型	说明
isConnected	boolean	当前是否有网络连接
networkType	string	网络类型

res.networkType 的合法值

值	说明
wifi	wifi 网络
2g	2g 网络
3g	3g 网络
4g	4g 网络
unknown	wifi 网络
none	无网络

示例代码

ft.onNetworkStatusChange(function(res) {
  console.log(res.isConnected)
  console.log(res.networkType)
})

offNetworkStatusChange

offNetworkStatusChange(function callback)

取消监听网络状态变化事件，参数为空，则取消所有的事件监听。

参数

function callback

网络状态变化事件的回调函数

getNetworkType

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

getNetworkType(Object object)

获取网络类型。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object res

属性	类型	说明
networkType	string	网络类型

res.networkType 的合法值

值	说明
wifi	wifi 网络
2g	2g 网络
3g	3g 网络
4g	4g 网络
unknown	wifi 网络
none	无网络

示例代码

ft.getNetworkType({
  success(res) {
    const networkType = res.networkType
  }
})

getRandomValues

获取密码学安全随机数

参数

Object object

属性	类型	默认值	必填	说明
length	number		是	整数，生成随机数的字节数，最大 1048576
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object object

属性	类型	说明
randomValues	ArrayBuffer	随机数内容，长度为传入的字节数

示例代码

ft.getRandomValues({
  length: 6 // 生成 6 个字节长度的随机数,
  success: res => {
    console.log(ft.arrayBufferToBase64(res.randomValues)) // 转换为 base64 字符串后打印
  }
})

屏幕

setVisualEffectOnCapture

基础库 2.12.16 开始支持，Android 版本 2.37.1

setVisualEffectOnCapture(Object object)

设置屏幕亮度。

参数

Object object

属性	类型	默认值	必填	说明
visualEffect	string	none	是	截屏/录屏时的表现，仅支持 none / hidden，传入 hidden 则表示在截屏/录屏时隐藏屏幕
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

setScreenBrightness

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

setScreenBrightness(Object object)

设置屏幕亮度。

参数

Object object

属性	类型	默认值	必填	说明
value	number		是	屏幕亮度值，范围 0 ~ 1。0 最暗，1 最亮
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

setKeepScreenOn

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

setKeepScreenOn(Object object)

设置是否保持常亮状态。

参数

Object object

属性	类型	默认值	必填	说明
keepScreenOn	boolean		是	是否保持屏幕常亮
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.setKeepScreenOn({
  keepScreenOn: true
})

onUserCaptureScreen

onUserCaptureScreen(function callback)

监听用户主动截屏事件。用户使用系统截屏按键截屏时触发，只能注册一个监听

参数

function callback

用户主动截屏事件的回调函数

示例代码

ft.onUserCaptureScreen(function(res) {
  console.log('用户截屏了')
})

onScreenRecordingStateChanged

onScreenRecordingStateChanged(function callback)

监听用户录屏事件，用户录屏时触发

参数

function callback

用户主动录屏事件的回调函数

参数

Object res

属性	类型	说明
state	string	值为 start 或 stop，start：开始录屏；stop：停止录屏

示例代码

ft.onScreenRecordingStateChanged(function(res) {
  console.log(res.state)
})

offUserCaptureScreen

offUserCaptureScreen(function callback)

用户主动截屏事件，取消事件监听。

参数

function callback

用户主动截屏事件的回调函数

offScreenRecordingStateChanged

offScreenRecordingStateChanged(function callback)

移除用户录屏事件的监听

参数

function callback

用户主动截屏事件的回调函数

参数为 onScreenRecordingStateChanged 传入的监听函数，不传参数则移除所有监听函数

getScreenRecordingState

基础库 2.12.16 开始支持，iOS 版本 2.37.1，Android 版本 2.37.1

getScreenRecordingState(Object object)

查询用户是否在录屏

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object res

属性	类型	说明
state	string	录屏状态，值为 on 或 off

getScreenBrightness

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

getScreenBrightness(Object object)

获取屏幕亮度。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object res

属性	类型	说明
value	number	屏幕亮度值，范围 0 ~ 1，0 最暗，1 最亮

键盘

onKeyboardHeightChange

onKeyboardHeightChange(function callback)

监听键盘高度变化

参数

function callback

参数

object res

属性	类型	说明
height	number	键盘高度

示例代码

ft.onKeyboardHeightChange(res => {
  console.log(res.height)
})

offKeyboardHeightChange

offKeyboardHeightChange(function callback)

取消监听键盘高度变化事件

参数

function callback

键盘高度变化事件的回调函数

hideKeyboard

hideKeyboard(Object object)

在 input、textarea 等 focus 拉起键盘之后，手动调用此接口收起键盘

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.hideKeyboard({
  complete: res => {
    console.log('hideKeyboard res', res)
  }
})

getSelectedTextRange

getSelectedTextRange(Object object)

在 input、textarea 等 focus 之后，获取输入框的光标位置。注意：只有在 focus 的时候调用此接口才有效。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object res

属性	类型	说明
start	number	输入框光标起始位置
end	number	输入框光标结束位置

示例代码

ft.getSelectedTextRange({
  complete: res => {
    console.log('getSelectedTextRange res', res.start, res.end)
  }
})
})

电话

makePhoneCall

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

makePhoneCall(Object object)

拨打电话。

参数

Object object

属性	类型	默认值	必填	说明
phoneNumber	string		是	需要拨打的电话号码
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.makePhoneCall({
  phoneNumber: '1340000' // 仅为示例，并非真实的电话号码
})

加速计

stopAccelerometer

stopAccelerometer(Object object)

停止监听加速度数据。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.stopAccelerometer()

startAccelerometer

startAccelerometer(Object object)

开始监听加速度数据。

参数

Object object

属性	类型	默认值	必填	说明
interval	string	normal	否	监听加速度数据回调函数的执行频率
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.interval 的合法值

值	说明
game	适用于更新游戏的回调频率，在 20ms/次 左右
ui	适用于更新 UI 的回调频率，在 60ms/次 左右
normal	普通的回调频率，在 200ms/次 左右

示例代码

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

onAccelerometerChange

onAccelerometerChange(function callback)

监听加速度数据事件。频率根据 ft.startAccelerometer() 的 interval 参数, 接口调用后会自动开始监听。

参数

function callback

加速度数据事件的回调函数

参数

Object res

属性	类型	说明
x	number	X 轴
y	number	Y 轴
z	number	Z 轴

示例代码

ft.onAccelerometerChange(callback)

offAccelerometerChange

offAccelerometerChange(function callback)

取消监听加速度数据事件，参数为空，则取消所有的事件监听。

参数

function callback

加速度数据事件的回调函数

罗盘

stopCompass

stopCompass(Object object)

停止监听罗盘数据

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.stopCompass()

startCompass

startCompass(Object object)

开始监听罗盘数据

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

示例代码

ft.startCompass()

onCompassChange

onCompassChange(function callback)

监听罗盘数据变化事件。频率：5 次/秒，接口调用后会自动开始监听，可使用 ft.stopCompass 停止监听。

参数

function callback

罗盘数据变化事件的回调函数

参数

Object object

属性	类型	说明
direction	number	面对的方向度数
accuracy	number/string	精度

示例代码

ft.onCompassChange(callback)

accuracy 在 iOS/Android 的差异

由于平台差异，accuracy 在 iOS/Android 的值不同。

• iOS：accuracy 是一个 number 类型的值，表示相对于磁北极的偏差。0 表示设备指向磁北，90 表示指向东，180 表示指向南，依此类推。
• Android：accuracy 是一个 string 类型的枚举值。

值	说明
high	高精度
medium	中等精度
low	低精度
no-contact	不可信，传感器失去连接
unreliable	不可信，原因未知
unknow ${value}	未知的精度枚举值，即该 Android 系统此时返回的表示精度的 value 不是一个标准的精度枚举值

offCompassChange

offCompassChange(function callback)

取消监听罗盘数据变化事件，参数为空，则取消所有的事件监听。

参数

function callback

罗盘数据变化事件的回调函数

设备方向

stopDeviceMotionListening

stopDeviceMotionListening(Object object)

停止监听设备方向的变化。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

startDeviceMotionListening

startDeviceMotionListening(Object object)

开始监听设备方向的变化。

参数

Object object

属性	类型	默认值	必填	说明
interval	string	normal	否	监听设备方向的变化回调函数的执行频率
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.interval 的合法值

值	说明
game	适用于更新游戏的回调频率，在 20ms/次 左右
ui	适用于更新 UI 的回调频率，在 60ms/次 左右
normal	普通的回调频率，在 200ms/次 左右

onDeviceMotionChange

onDeviceMotionChange(function callback)

监听设备方向变化事件。频率根据 ft.startDeviceMotionListening() 的 interval 参数。可以使用 ft.stopDeviceMotionListening() 停止监听。

参数

function callback

设备方向变化事件的回调函数

参数

Object res

属性	类型	说明
alpha	number	当 手机坐标 X/Y 和 地球 X/Y 重合时，绕着 Z 轴转动的夹角为 alpha，范围值为 [0, 2*PI)。逆时针转动为正。
beta	number	当手机坐标 Y/Z 和地球 Y/Z 重合时，绕着 X 轴转动的夹角为 beta。范围值为 [-1*PI, PI) 。顶部朝着地球表面转动为正。也有可能朝着用户为正。
gamma	number	当手机 X/Z 和地球 X/Z 重合时，绕着 Y 轴转动的夹角为 gamma。范围值为 [-1*PI/2, PI/2)。右边朝着地球表面转动为正。

offDeviceMotionChange

offDeviceMotionChange(function callback)

取消监听设备方向变化事件，参数为空，则取消所有的事件监听。

参数

function callback

设备方向变化事件的回调函数

陀螺仪

stopGyroscope

stopGyroscope(Object object)

停止监听陀螺仪数据。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

startGyroscope

startGyroscope(Object object)

开始监听陀螺仪数据。

参数

Object object

属性	类型	默认值	必填	说明
interval	string	normal	否	监听陀螺仪数据回调函数的执行频率
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.interval 的合法值

值	说明
game	适用于更新游戏的回调频率，在 20ms/次 左右
ui	适用于更新 UI 的回调频率，在 60ms/次 左右
normal	普通的回调频率，在 200ms/次 左右

onGyroscopeChange

onGyroscopeChange(function callback)

监听陀螺仪数据变化事件。频率根据 ft.startGyroscope() 的 interval 参数。可以使用 ft.stopGyroscope() 停止监听。

参数

function callback

陀螺仪数据变化事件的回调函数

参数

Object res

属性	类型	说明
x	number	x 轴的角速度
y	number	y 轴的角速度
z	number	z 轴的角速度

offGyroscopeChange

offGyroscopeChange(function callback)

取消监听陀螺仪数据变化事件。

参数

function callback

陀螺仪数据变化事件的回调函数

扫码

scanCode

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

scanCode(Object object)

调起客户端扫码界面进行扫码。

参数

Object object

属性	类型	默认值	必填	说明
onlyFromCamera	boolean	false	否	是否只能从相机扫码，不允许从相册选择图片
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数（当授权失败时，返回错误信息：fail unauthorized 用户未授予相机权限）
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

object.success 回调函数

参数

Object res

示例代码

// 允许从相机和相册扫码
ft.scanCode({
  success(res) {
    console.log(res)
  }
})

// 只允许从相机扫码
ft.scanCode({
  onlyFromCamera: true,
  success(res) {
    console.log(res)
  }
})

注意

• 接口授权失败（iOS）:

1. 用户拒绝授权，会返回错误信息： unauthorized,用户未授予相机权限
2. 宿主 App 禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized,SDK 被禁止申请相机权限

• 接口授权失败（Android）：

1. 用户拒绝授权，会返回错误信息：fail unauthorized 用户未授予相机权限
2. 宿主 App 禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized SDK 被禁止了主动发起权限申请

振动

vibrateShort

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

vibrateShort(Object object)

使手机发生较短时间的振动（15 ms）。仅在 iPhone 7 / 7 Plus 以上及 Android 机型生效。

参数

Object object

属性	类型	默认值	必填	说明
type	String		是	震动强度类型，有效值为：heavy、medium、light。 iOS:2.39.11支持；Android:2.25.1支持
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数(当授权失败时，返回错误信息：fail unauthorized 用户未授予震动权限)
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

注意

• 接口授权失败（Android）：

1. 用户拒绝授权，会返回错误信息：unauthorized 用户未授予震动权限
2. 宿主 App 禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized SDK 被禁止了主动发起权限申请

vibrateLong

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

vibrateLong(Object object)

使手机发生较长时间的振动（400 ms)。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数(当授权失败时，返回错误信息：fail unauthorized 用户未授予震动权限)
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行)

注意

• 接口授权失败（Android）：

1. 用户拒绝授权，会返回错误信息：unauthorized 用户未授予震动权限
2. 宿主 App 禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized SDK 被禁止了主动发起权限申请

• iOS：

1. 长振动的效果需要iPhone --> 设置 ---> 响铃模式振动、静音模式振动 开启，否则会无振动效果。

蓝牙-通用

stopBluetoothDevicesDiscovery

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK。 从 2.35.7 开始，蓝牙模块独立，需要单独依赖 BluetoothSDK

stopBluetoothDevicesDiscovery(Object object)

停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

startBluetoothDevicesDiscovery

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

startBluetoothDevicesDiscovery(Object object)

开始搜寻附近的蓝牙外围设备。

此操作比较耗费系统资源，请在搜索到需要的设备后及时调用 ft.stopBluetoothDevicesDiscovery 停止搜索。

参数

Object object

属性	类型	默认值	必填	说明
services	Array.string		否	要搜索的蓝牙设备主服务的 UUID 列表（支持 16/32/128 位 UUID）。某些蓝牙设备会广播自己的主 service 的 UUID。如果设置此参数，则只搜索广播包有对应 UUID 的主服务的蓝牙设备。建议通过该参数过滤掉周边不需要处理的其他蓝牙设备。
allowDuplicatesKey	boolean	false	否	是否允许重复上报同一设备。如果允许重复上报，则 ?onBlueToothDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同。
interval	number	0	否	上报设备的间隔，单位 ms。0 表示找到新设备立即上报，其他数值根据传入的间隔上报。
powerLevel	string	medium	否	扫描模式，越高扫描越快，也越耗电
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.powerLevel 的合法值

值	说明	最低版本
low	低
medium	中
high	高

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

openBluetoothAdapter

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

openBluetoothAdapter(Object object)

初始化蓝牙模块。iOS 上开启主机/从机（外围设备）模式时需分别调用一次，并指定对应的 mode。

参数

---

Object object

属性	类型	默认值	必填	说明	最低版本
mode	string	central	否	蓝牙模式，可作为主/从设备，仅 iOS 需要。
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.mode 的合法值

值	说明	最低版本
central	主机模式
peripheral	从机（外围设备）模式

错误

---

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

object.fail 回调函数返回的 state 参数（仅 iOS）

---

状态码	说明
0	未知
1	重置中
2	不支持
3	未授权
4	未开启

注意

---

• 其他蓝牙相关 API 必须在 ?openBluetoothAdapter? 调用之后使用。否则 API 会返回错误（errCode=10000）。
• 在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下，调用 ?openBluetoothAdapter? 会返回错误（errCode=10001），表示手机蓝牙功能不可用。此时小程序蓝牙模块已经初始化完成，可通过 ?onBluetoothAdapterStateChange? 监听手机蓝牙状态的改变，也可以调用蓝牙模块的所有 API。

---

注意

• 接口授权失败（iOS）:

1. 宿主 App 禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized，SDK 被禁止申请蓝牙权限

onBluetoothDeviceFound

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK onBluetoothDeviceFound(function callback) 监听搜索到新设备的事件

参数

---

function callback

搜索到新设备的事件的回调函数

参数

object res

属性	类型	说明
devices	Array.Object	新搜索到的设备列表

res.devices 的结构

属性	类型	说明
name	string	蓝牙设备名称，某些设备可能没有
deviceId	string	蓝牙设备 id
RSSI	number	当前蓝牙设备的信号强度，单位 dBm
advertisData	ArrayBuffer	当前蓝牙设备的广播数据段中的 ManufacturerData 数据段。
advertisServiceUUIDs	Array.string	当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName	string	当前蓝牙设备的广播数据段中的 LocalName 数据段
serviceData	Object	当前蓝牙设备的广播数据段中的 ServiceData 数据段

注意

---

• 若在 ?onBluetoothDeviceFound? 回调了某个设备，则此设备会添加到 ?getBluetoothDevices? 接口获取到的数组中。
• 安卓下部分机型需要有位置权限才能搜索到设备，需留意是否开启了位置权限
• 重复调用会覆盖之前的回调

onBluetoothAdapterStateChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK onBluetoothAdapterStateChange(function callback)

监听蓝牙适配器状态变化事件

参数

function callback

蓝牙适配器状态变化事件的回调函数

参数

Object res

属性	类型	说明
available	boolean	蓝牙适配器是否可用
discovering	boolean	蓝牙适配器是否处于搜索状态

注意 重复调用会覆盖之前的回调

offBluetoothDeviceFound

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

取消监听寻找到新设备的事件。

offBluetoothAdapterStateChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

取消监听蓝牙适配器状态变化事件。

makeBluetoothPair

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

makeBluetoothPair(Object object)

蓝牙配对接口，仅安卓支持。

通常情况下（需要指定 pin 码或者密码时）系统会接管配对流程，直接调用 createBLEConnection 即可。该接口只应当在开发者不想让用户手动输入 pin 码且真机验证确认可以正常生效情况下用

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
pin	string		是	pin 码，Base64 格式。
timeout	number	20000	否	超时时间，单位 ms
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

getConnectedBluetoothDevices

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

getConnectedBluetoothDevices(Object object)

根据主服务 UUID 获取已连接的蓝牙设备。

参数

Object object

属性	类型	默认值	必填	说明
services	Array.string		是	蓝牙设备主服务的 UUID 列表（支持 16/32/128 位 UUID）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行

object.success 回调函数

参数

Object res

属性	类型	说明
devices	Array.Object	搜索到的设备列表

res.devices 的结构

属性	类型	说明
name	string	蓝牙设备名称，某些设备可能没有
deviceId	string	用于区分设备的 id

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

getBluetoothDevices

getBluetoothDevices(Object object)

获取在蓝牙模块生效期间所有搜索到的蓝牙设备。包括已经和本机处于连接状态的设备。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
devices	Array.Object	UUID 对应的已连接设备列表

res.devices 的结构

属性	类型	说明
name	string	蓝牙设备名称，某些设备可能没有
deviceId	string	蓝牙设备 id
RSSI	number	当前蓝牙设备的信号强度，单位 dBm
advertisData	ArrayBuffer	当前蓝牙设备的广播数据段中的 ManufacturerData 数据段。
advertisServiceUUIDs	Array.string	当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName	string	当前蓝牙设备的广播数据段中的 LocalName 数据段
serviceData	Object	当前蓝牙设备的广播数据段中的 ServiceData 数据段

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

getBluetoothAdapterState

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

getBluetoothAdapterState(Object object)

获取本机蓝牙适配器状态。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
discovering	boolean	是否正在搜索设备
available	boolean	蓝牙适配器是否可用

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

closeBluetoothAdapter

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

closeBluetoothAdapter(Object object)

关闭蓝牙模块。调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后，与 openBluetoothAdapter 成对调用。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

蓝牙-低功耗中心设备

writeBLECharacteristicValue

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

writeBLECharacteristicValue(Object object)

向蓝牙低功耗设备特征值中写入二进制数据。注意：必须设备的特征支持 write 才可以成功调用。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
serviceId	string		是	蓝牙特征对应服务的 UUID
characteristicId	string		是	蓝牙特征的 UUID
value	ArrayBuffer		是	蓝牙设备特征对应的二进制值
writeType	string		是	蓝牙特征值的写模式设置，有两种模式，iOS 优先 write，安卓优先 writeNoResponse
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

writeType

合法值	类型
write	强制回复写，不支持时报错
writeNoResponse	强制无回复写，不支持时报错

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

setBLEMTU

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

setBLEMTU(Object object)

协商设置蓝牙低功耗的最大传输单元 (Maximum Transmission Unit, MTU)。需在 createBLEConnection 调用成功后调用。仅安卓系统 5.1 以上版本有效，iOS 因系统限制不支持。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
mtu	number		是	最大传输单元。设置范围为 (22,512) 区间内，单位 bytes
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
mtu	number	最终协商的 MTU 值，与传入参数一致。安卓客户端 8.0.9 开始支持

object.fail 回调函数

参数

Object res

属性	类型	说明
mtu	number	最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。

readBLECharacteristicValue

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

readBLECharacteristicValue(Object object)

读取蓝牙低功耗设备特征值的二进制数据。注意：必须设备的特征支持 read 才可以成功调用。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
serviceId	string		是	蓝牙特征对应服务的 UUID
characteristicId	string		是	蓝牙特征的 UUID
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

注意

• 并行调用多次会存在读失败的可能性。
• 接口读取到的信息需要在 ?onBLECharacteristicValueChange? 方法注册的回调中获取

onBLEConnectionStateChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

onBLEConnectionStateChange(function callback)

监听蓝牙低功耗连接状态的改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等

参数

function callback

蓝牙低功耗连接状态的改变事件的回调函数

参数

Object res

属性	类型	说明
deviceId	string	蓝牙设备 id
connected	boolean	是否处于已连接状态

注意

重复调用会覆盖原来的回调

onBLECharacteristicValueChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

onBLECharacteristicValueChange(function callback)

监听蓝牙低功耗设备的特征值变化事件。必须先调用 notifyBLECharacteristicValueChange 接口才能接收到设备推送的 notification。

参数

function callback

蓝牙低功耗设备的特征值变化事件的回调函数

参数

Object res

属性	类型	说明
deviceId	string	蓝牙设备 id
serviceId	string	蓝牙特征对应服务的 UUID
characteristicId	string	蓝牙特征的 UUID
value	ArrayBuffer	特征最新的值

注意

重复调用会覆盖原来的回调

offBLEConnectionStateChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

取消监听蓝牙低功耗连接状态的改变事件

offBLECharacteristicValueChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

取消监听蓝牙低功耗设备的特征值变化事件。

notifyBLECharacteristicValueChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

notifyBLECharacteristicValueChange(Object object)

启用蓝牙低功耗设备特征值变化时的 notify 功能，订阅特征。注意：必须设备的特征支持 notify 或者 indicate 才可以成功调用。

另外，必须先启用 notifyBLECharacteristicValueChange 才能监听到设备 characteristicValueChange 事件

参数

Object res

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
serviceId	string		是	蓝牙特征对应服务的 UUID
characteristicId	string		是	蓝牙特征的 UUID
state	boolean		是	是否启用 notify
type	string	indication	否	设置特征订阅类型，有效值有 ?notification? 和 ?indication
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

注意

订阅操作成功后需要设备主动更新特征的 value，才会触发 onBLECharacteristicValueChange 回调。 安卓平台上，在本接口调用成功后立即调用 writeBLECharacteristicValue 接口，在部分机型上会发生 10008 系统错误

getBLEDeviceServices

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

getBLEDeviceServices(Object object)

获取蓝牙低功耗设备所有服务 (service)。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id。需要已经通过 ?createBLEConnection? 建立连接
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
services	Array.Object	设备服务列表

结构属性	类型	说明
uuid	string	蓝牙设备服务的 UUID
isPrimary	boolean	该服务是否为主服务

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

getBLEDeviceRSSI

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

getBLEDeviceRSSI(Object object)

获取蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
RSSI	Number	信号强度，单位 dBm

getBLEDeviceCharacteristics

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

getBLEDeviceCharacteristics(Object object)

获取蓝牙低功耗设备某个服务中所有特征 (characteristic)。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id。需要已经通过 ?createBLEConnection? 建立连接
serviceId	string		是	蓝牙服务 UUID。需要先调用 ?getBLEDeviceServices 获取
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
characteristics	Array.Object	设备特征列表

characteristics

结构属性	类型	说明
uuid	string	蓝牙设备特征的 UUID
properties	Object	该特征支持的操作类型

properties

结构属性	类型	说明
read	boolean	该特征是否支持 read 操作
write	boolean	该特征是否支持 write 操作
notify	boolean	该特征是否支持 notify 操作
indicate	boolean	该特征是否支持 indicate 操作
writeNoResponse	boolean	该特征是否支持无回复写操作
writeDefault	boolean	该特征是否支持有回复写操作

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

createBLEConnection

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

createBLEConnection(Object object)

连接蓝牙低功耗设备。

若小程序在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需再次进行搜索操作。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
timeout	number		否	超时时间，单位 ms，不填表示不会超时
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

注意

请保证尽量成对的调用 createBLEConnection 和 closeBLEConnection 接口。安卓如果重复调用 createBLEConnection 创建连接，有可能导致系统持有同一设备多个连接的实例，导致调用 closeBLEConnection 的时候并不能真正的断开与设备的连接。 蓝牙连接随时可能断开，建议监听 onBLEConnectionStateChange 回调事件，当蓝牙设备断开时按需执行重连操作 若对未连接的设备或已断开连接的设备调用数据读写操作的接口，会返回 10006 错误，建议进行重连操作。

closeBLEConnection

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

closeBLEConnection(Object object)

断开与蓝牙低功耗设备的连接。

参数

Object object

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
-1	already connet	已连接
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征
10006	no connection	当前连接已断开
10007	property not support	当前特征不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

蓝牙-低功耗外围设备

onBLEPeripheralConnectionStateChanged

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

onBLEPeripheralConnectionStateChanged(function callback)

监听当前外围设备被连接或断开连接事件

参数

Object object

当前外围设备被连接或断开连接事件的回调函数

参数

Object res

属性	类型	说明
deviceId	String	连接状态变化的设备 id
serverId	String	server 的 UUID
connected	Boolean	连接目前状态

offBLEPeripheralConnectionStateChanged

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

取消监听当前外围设备被连接或断开连接事件

createBLEPeripheralServer

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

createBLEPeripheralServer(Object object)

建立本地作为蓝牙低功耗外围设备的服务端，可创建多个。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
server	BLEPeripheralServer	外围设备的服务端。

BLEPeripheralServer.addService

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.addService(Object object)

添加服务。

参数

Object object

属性	类型	默认值	必填	说明
service	Object		是	描述 service 的 Object
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.service 的结构

属性	类型	默认值	必填	说明
uuid	String		是	蓝牙服务的 UUID
characteristics	Array.Object		是	characteristics 列表

characteristics 的结构

属性	类型	默认值	必填	说明
uuid	String		是	characteristic 的 UUID
properties	Object		否	特征支持的操作
permission	Object		否	特征权限
value	ArrayBuffer		否	特征对应的二进制值
descriptors	Array.Object		否	描述符数据

properties 的结构

属性	类型	默认值	必填	说明
write	Boolean	false	否	写
writeNoResponse	Boolean	false	否	无回复写
read	Boolean	false	否	读
notify	Boolean	false	否	订阅
indicate	Boolean	false	否	回包

permission 的结构

属性	类型	默认值	必填	说明
readable	Boolean	false	否	可读
writeable	Boolean	false	否	可写
readEncryptionRequired	Boolean	false	否	加密读请求
writeEncryptionRequired	Boolean	false	否	加密写请求

descriptors 的结构

属性	类型	默认值	必填	说明
uuid	String		是	Descriptor 的 UUID
permission	Object		否	描述符的权限
value	ArrayBuffer		否	描述符数据

permission 的结构

属性	类型	默认值	必填	说明
write	Boolean	false	否	写
read	Boolean	false	否	读

BLEPeripheralServer.close

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.close(Object object)

关闭当前服务端。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

BLEPeripheralServer.offCharacteristicReadRequest

BLEPeripheralServer.offCharacteristicReadRequest()

取消监听已连接的设备请求读当前外围设备的特征值事件

BLEPeripheralServer.offCharacteristicSubscribed

BLEPeripheralServer.offCharacteristicSubscribed()

取消监听特征订阅事件

BLEPeripheralServer.offCharacteristicUnsubscribed

BLEPeripheralServer.offCharacteristicUnsubscribed()

取消监听取消特征订阅事件

BLEPeripheralServer.offCharacteristicWriteRequest

BLEPeripheralServer.offCharacteristicWriteRequest()

取消监听已连接的设备请求写当前外围设备的特征值事件

BLEPeripheralServer.onCharacteristicReadRequest

BLEPeripheralServer.onCharacteristicReadRequest(function callback)

参数

function callback

已连接的设备请求读当前外围设备的特征值事件的回调函数

参数

Object res

属性	类型	说明
serviceId	String	蓝牙特征对应服务的 UUID
characteristicId	String	蓝牙特征的 UUID
callbackId	Number	唯一标识码，调用 ?writeCharacteristicValue? 时使用

注意 重复调用会覆盖原先的回调

BLEPeripheralServer.onCharacteristicSubscribed

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.onCharacteristicSubscribed(function callback)

监听特征订阅事件，仅 iOS 支持。

参数

function callback

特征订阅事件的回调函数

参数

Object res

属性	类型	说明
serviceId	String	蓝牙特征对应服务的 UUID
characteristicId	String	蓝牙特征的 UUID

注意 重复调用会覆盖原先的回调

BLEPeripheralServer.onCharacteristicUnsubscribed

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.onCharacteristicUnsubscribed(function callback)

监听取消特征订阅事件，仅 iOS 支持。

参数

function callback

取消特征订阅事件的回调函数

参数

Object res

属性	类型	说明
serviceId	String	蓝牙特征对应服务的 UUID
characteristicId	String	蓝牙特征的 UUID

注意 重复调用会覆盖原先的回调

BLEPeripheralServer.onCharacteristicWriteRequest

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.onCharacteristicWriteRequest(function callback)

监听已连接的设备请求写当前外围设备的特征值事件。收到该消息后需要立刻调用 writeCharacteristicValue 写回数据，否则主机不会收到响应。

参数

function callback

已连接的设备请求写当前外围设备的特征值事件的回调函数

参数

Object res

属性	类型	说明
serviceId	String	蓝牙特征对应服务的 UUID
characteristicId	String	蓝牙特征的 UUID

注意 重复调用会覆盖原先的回调

BLEPeripheralServer.removeService

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.removeService(Object object)

移除服务。

参数

Object object

属性	类型	默认值	必填	说明
serviceId	String		是	service 的 UUID
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

BLEPeripheralServer.startAdvertising

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.startAdvertising(Object Object)

开始广播本地创建的外围设备

参数

Object object

属性	类型	默认值	必填	说明
advertiseRequest	Object		是	广播自定义参数
powerLevel	String	medium	否	广播功率
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

Object.advertiseRequest 的结构

属性	类型	默认值	必填	说明
connectable	Boolean	true	否	当前设备是否可连接
deviceName	String		否	广播中 deviceName 字段，默认为空
serviceUuids	Array.String		否	要广播的服务 UUID 列表。使用 16/32 位 UUID 时请参考注意事项。
manufacturerData	Array.Object		否	广播的制造商信息。仅安卓支持，iOS 因系统限制无法定制。

manufacturerData 的结构

属性	类型	默认值	必填	说明
manufacturerId	String		是	制造商 ID，0x 开头的十六进制
manufacturerSpecificData	ArrayBuffer		否	制造商信息

Object.powerLevel 的合法值

值	说明	最低版本
low	功率低
medium	功率适中
high	功率高

注意

• Android 8.0.9 开始，支持直接使用 16/32/128 位 UUID；
• Android 8.0.9 以下版本只支持 128 位 UUID，使用 16/32 位的 UUID 时需要进行补位（系统会自动识别是否属于预分配区间）
• iOS 必须直接使用 16 位的 UUID，不能补位到 128 位，否则系统组包时仍会按照 128 位传输。iOS 暂不支持 32 位 UUID。
• iOS 同时只能发起一个广播，安卓支持同时发起多个广播。

BLEPeripheralServer.stopAdvertising

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.stopAdvertising(Object object)

停止广播。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

BLEPeripheralServer.writeCharacteristicValue

基础库 2.11.2 开始支持，iOS 版本 2.34.1，Android 版本 2.34.1, 依赖扩展 SDK

BLEPeripheralServer.writeCharacteristicValue(Object Object)

往指定特征写入二进制数据值，并通知已连接的主机，从机的特征值已发生变化，该接口会处理是走回包还是走订阅。

参数

Object object

属性	类型	默认值	必填	说明
serviceId	String		是	蓝牙特征对应服务的 UUID
characteristicId	String		是	蓝牙特征的 UUID
value	ArrayBuffer		是	characteristic 对应的二进制值
needNotify	Boolean		是	是否需要通知主机 value 已更新
callbackId	Number		否	可选，处理回包时使用
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

蓝牙-信标(Beacon)

stopBeaconDiscovery

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓版本 2.35.9, 依赖 BluetoothSDK

stopBeaconDiscovery(Object object)

停止搜索附近的 Beacon 设备

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
11000	unsupport	系统或设备不支持
11001	bluetooth service unavailable	蓝牙服务不可用
11002	location service unavailable	位置服务不可用
11003	already start	已经开始搜索
11004	not startBeaconDiscovery	还未开始搜索
11005	system error	系统错误
11006	invalid data	参数不正确

startBeaconDiscovery

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓版本 2.35.9, 依赖 BluetoothSDK

startBeaconDiscovery(Object object)

开始搜索附近的 Beacon 设备

参数

Object object

属性	类型	默认值	必填	说明
uuids	Array.<string>		是	Beacon 设备广播的 UUID 列表
ignoreBluetoothAvailable	boolean	false	否	是否校验蓝牙开关，仅在 iOS 下有效。iOS 11 起，控制面板里关掉蓝牙，还是能继续使用 Beacon 服务。
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

错误

错误码	错误信息	说明
0	ok	正常
11000	unsupport	系统或设备不支持
11001	bluetooth service unavailable	蓝牙服务不可用
11002	location service unavailable	位置服务不可用
11003	already start	已经开始搜索
11004	not startBeaconDiscovery	还未开始搜索
11005	system error	系统错误
11006	invalid data	参数不正确

注意

• 接口授权失败（iOS）:

1. 宿主 App 禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized，SDK 被禁止申请蓝牙权限

onBeaconUpdate

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口

onBeaconUpdate(function callback)

监听 Beacon 设备更新事件，仅能注册一个监听

参数

function callback

Beacon 设备更新事件的回调函数

参数

Object res

属性	类型	说明
beacons	Array.BeaconInfo	当前搜寻到的所有 Beacon 设备列表

onBeaconServiceChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口

onBeaconServiceChange(function callback)

监听 Beacon 服务状态变化事件，仅能注册一个监听

参数

function callback

Beacon 服务状态变化事件的回调函数

参数

Object res

属性	类型	说明
available	boolean	服务目前是否可用
discovering	boolean	目前是否处于搜索状态

offBeaconUpdate

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口

取消监听 Beacon 设备更新事件

offBeaconServiceChange

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口

取消监听 Beacon 服务状态变化事件

getBeacons

基础库 2.11.2 开始支持，iOS 版本 2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口

getBeacons(Object object)

获取所有已搜索到的 Beacon 设备

参数

Object object

Beacon 服务状态变化事件的回调函数

参数

Object res

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
beacons	Array.BeaconInfo	Beacon 设备列表

错误

错误码	错误信息	说明
0	ok	正常
11000	unsupport	系统或设备不支持
11001	bluetooth service unavailable	蓝牙服务不可用
11002	location service unavailable	位置服务不可用
11003	already start	已经开始搜索
11004	not startBeaconDiscovery	还未开始搜索
11005	system error	系统错误
11006	invalid data	参数不正确

BeaconInfo

Beacon 设备

属性

string uuid

Beacon 设备广播的 UUID

number major

Beacon 设备的主 ID

number minor

Beacon 设备的次 ID

number proximity

表示设备距离的枚举值（仅 iOS）

proximity 的合法值

值	说明	最低版本
0	信号太弱不足以计算距离，或非 iOS 设备
1	十分近
2	比较近
3	远

number accuracy

Beacon 设备的距离，单位 m。iOS 上，proximity 为 0 时，accuracy 为 -1。

number rssi

表示设备的信号强度，单位 dBm

联系人

addPhoneContact

添加手机通讯录联系人。

参数

Object object

属性	类型	默认值	必填	说明
firstName	string	是	名字
photoFilePath	string	否	头像本地文件路径
nickName	string	否	昵称
lastName	string	否	姓氏
middleName	string	否	中间名
remark	string	否	备注
mobilePhoneNumber	string	否	手机号
weChatNumber	string	否	微信号
addressCountry	string	否	联系地址国家
addressState	string	否	联系地址省份
addressCity	string	否	联系地址城市
addressStreet	string	否	联系地址街道
addressPostalCode	string	否	联系地址邮政编码
organization	string	否	公司
title	string	否	职位
workFaxNumber	string	否	工作传真
workPhoneNumber	string	否	工作电话
hostNumber	string	否	公司电话
email	string	否	电子邮件
url	string	否	网站
workAddressCountry	string	否	工作地址国家
workAddressState	string	否	工作地址省份
workAddressCity	string	否	工作地址城市
workAddressStreet	string	否	工作地址街道
workAddressPostalCode	string	否	工作地址邮政编码
homeFaxNumber	string	否	住宅传真
homePhoneNumber	string	否	住宅电话
homeAddressCountry	string	否	住宅地址国家
homeAddressState	string	否	住宅地址省份
homeAddressCity	string	否	住宅地址城市
homeAddressStreet	string	否	住宅地址街道
homeAddressPostalCode	string	否	住宅地址邮政编码
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

chooseContact

拉起手机通讯录，选择联系人

参数

Object res

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
phoneNumber	string	手机号
displayName	string	联系人姓名
phoneNumberList	string	选定联系人的所有手机号（部分 Android 系统只能选联系人而不能选特定手机号）

无障碍

checkIsOpenAccessibility

基础库 2.12.1 开始支持

checkIsOpenAccessibility(Object object)

检测是否开启视觉无障碍功能。

参数

Object object

属性	类型	默认值	必填	说明
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
open	Boolean	iOS 上开启辅助功能旁白，安卓开启 talkback 时返回 true