# 设备
# 电量
# 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
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
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
}
})
# 屏幕
# 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('用户截屏了')
})
# offUserCaptureScreen
offUserCaptureScreen(function callback)
用户主动截屏事件。取消事件监听。
参数
function callback
用户主动截屏事件的回调函数
# 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 object
| 属性 | 类型 | 说明 |
|---|---|---|
| value | number | 屏幕亮度值，范围 0 ~ 1，0 最暗，1 最亮 |
# 键盘
# showKeyboard
showKeyboard(Object object)
展示键盘
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| defaultValue | string | 是 | 键盘输入框显示的默认值 | |
| maxLength | number | 是 | 键盘中文本的最大长度 | |
| multiple | boolean | 是 | 是否为多行输入 | |
| confirmHold | boolean | 是 | 当点击完成时键盘是否收起 | |
| confirmType | string | 是 | 键盘右下角 confirm 按钮的类型，只影响按钮的文本内容 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
object.confirmType 的合法值
| 值 | 显示名称 |
|---|---|
| done | 完成 |
| next | 下一个 |
| search | 搜索 |
| go | 前往 |
| send | 发送 |
示例代码
ft.showKeyboard({
defaultValue: 'input text',
maxLength: 50,
multiple: false,
confirmHold: false,
confirmType: 'go',
complete: res => {
console.log('showKeyboard res', res)
}
})
# updateKeyboard
updateKeyboard(Object object)
更新输入框内容
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| value | string | 是 | 输入框更新的值 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
示例代码
ft.updateKeyboard({
value: 'some new value',
complete: res => {
console.log('updateKeyboard res', res)
}
})
# hideKeyboard
hideKeyboard(Object object)
使用 showKeyboard 拉起键盘之后，手动调用此接口收起键盘
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行) |
示例代码
ft.hideKeyboard({
complete: res => {
console.log('hideKeyboard res', res)
}
})
# onKeyboardInput
onKeyboardInput(function callback)
监听键盘输入事件
参数
function callback
键盘输入事件的监听函数
参数
object res
| 属性 | 类型 | 说明 |
|---|---|---|
| value | string | 当前键盘输入的值 |
示例代码
ft.onKeyboardInput(res => {
console.log(res.value)
})
# onKeyboardHeightChange
onKeyboardHeightChange(function callback)
监听键盘高度变化
参数
function callback
键盘高度变化事件的监听函数
参数
object res
| 属性 | 类型 | 说明 |
|---|---|---|
| height | number | 键盘高度 |
示例代码
ft.onKeyboardHeightChange(res => {
console.log(res.height)
})
# onKeyboardConfirm
onKeyboardConfirm(function callback)
监听用户点击键盘 Confirm 按钮时的事件
参数
function callback
用户点击键盘 Confirm 按钮时的事件的监听函数
参数
object res
| 属性 | 类型 | 说明 |
|---|---|---|
| value | string | 当前键盘输入的值 |
示例代码
ft.onKeyboardConfirm(res => {
console.log(res.value)
})
# onKeyboardComplete
onKeyboardComplete(function callback)
监听键盘收起的事件
参数
function callback
监听键盘收起事件的监听函数
参数
object res
| 属性 | 类型 | 说明 |
|---|---|---|
| value | string | 当前键盘输入的值 |
示例代码
ft.onKeyboardComplete(res => {
console.log(res.value)
})
# offKeyboardInput
offKeyboardInput(function callback)
取消监听键盘输入事件
参数
function callback
onKeyboardInput 传入的回调函数
# offKeyboardHeightChange
offKeyboardHeightChange(function callback)
取消监听键盘高度变化事件
参数
function callback
onKeyboardHeightChange 传入的回调函数
# offKeyboardConfirm
offKeyboardConfirm(function callback)
取消监听用户点击键盘 Confirm 按钮时的事件
参数
function callback
onKeyboardConfirm 传入的回调函数
# offKeyboardComplete
offKeyboardComplete(function callback)
取消监听键盘收起的事件
参数
function callback
onKeyboardComplete 传入的回调函数
# 加速计
# 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
设备方向变化事件的回调函数
# 转屏
# setDeviceOrientation
setDeviceOrientation(Object object)
切换横竖屏
接口调用成功后会触发 onDeviceOrientationChange 事件
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| value | string | 是 | 表示切换为横屏还是竖屏 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
object.value 的合法值
| 值 | 说明 |
|---|---|
| landscape | 横屏 |
| portrait | 竖屏 |
示例代码
ft.setDeviceOrientation({
value: 'portrait',
complete: res => {
console.log('setDeviceOrientation res', res)
}
})
# onDeviceOrientationChange
onDeviceOrientationChange(function callback)
监听屏幕转向切换事件
参数
function callback
屏幕转向切换事件的监听函数
参数
object res
| 属性 | 类型 | 说明 |
|---|---|---|
| value | string | 切换后的屏幕方向 |
res.value 的值
| 名称 | 说明 |
|---|---|
| landscape | 横屏正方向，以 HOME 键在屏幕右侧为正方向 |
| landscapeReverse | 横屏反方向，以 HOME 键在屏幕左侧为反方向 |
示例代码
ft.onDeviceOrientationChange(res => {
console.log(res.value)
})
# offDeviceOrientationChange
offDeviceOrientationChange(function callback)
取消监听屏幕转向切换事件
参数
function callback
onDeviceOrientationChange 传入的回调函数
# 陀螺仪
# 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）:
- 用户拒绝授权，会返回错误信息： unauthorized,用户未授予相机权限
- 宿主App禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized,SDK被禁止申请相机权限
- 接口授权失败（Android）：
- 用户拒绝授权，会返回错误信息：fail unauthorized 用户未授予相机权限
- 宿主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
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数(当授权失败时，返回错误信息：fail unauthorized 用户未授予震动权限) | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行) |
注意
- 接口授权失败（Android）：
- 用户拒绝授权，会返回错误信息：unauthorized 用户未授予震动权限
- 宿主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）：
- 用户拒绝授权，会返回错误信息：unauthorized 用户未授予震动权限
- 宿主App禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized SDK被禁止了主动发起权限申请
# 蓝牙-通用
# stopBluetoothDevicesDiscovery(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。
参数
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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
开始搜寻附近的蓝牙外围设备。
此操作比较耗费系统资源，请在搜索到需要的设备后及时调用 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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
初始化蓝牙模块。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）:
- 宿主App禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized，SDK被禁止申请蓝牙权限
# onBluetoothDeviceFound(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听搜索到新设备的事件
# 参数
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(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听蓝牙适配器状态变化事件
参数
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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
蓝牙配对接口，仅安卓支持。
通常情况下（需要指定 pin 码或者密码时）系统会接管配对流程，直接调用 createBLEConnection 即可。该接口只应当在开发者不想让用户手动输入 pin 码且真机验证确认可以正常生效情况下用
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| deviceId | string | 是 | 蓝牙设备 id | |
| pin | string | 是 | pin 码，Base64 格式。 | |
| timeout | number | 20000 | 否 | 超时时间，单位 ms |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# getConnectedBluetoothDevices(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
根据主服务 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(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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
获取本机蓝牙适配器状态。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
object.success 回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| discovering | boolean | 是否正在搜索设备 |
| available | boolean | 蓝牙适配器是否可用 |
# closeBluetoothAdapter(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
关闭蓝牙模块。调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后，与 openBluetoothAdapter 成对调用。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# 蓝牙-低功耗中心设备
# writeBLECharacteristicValue(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
向蓝牙低功耗设备特征值中写入二进制数据。注意：必须设备的特征支持 write 才可以成功调用。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| deviceId | string | 是 | 蓝牙设备 id | |
| serviceId | string | 是 | 蓝牙特征对应服务的 UUID | |
| characteristicId | string | 是 | 蓝牙特征的 UUID | |
| value | ArrayBuffer | 是 | 蓝牙设备特征对应的二进制值 | |
| 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 为空或者是格式不正确 |
# setBLEMTU(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
协商设置蓝牙低功耗的最大传输单元 (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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
读取蓝牙低功耗设备特征值的二进制数据。注意：必须设备的特征支持 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(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听蓝牙低功耗连接状态的改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等
参数
function callback
蓝牙低功耗连接状态的改变事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| deviceId | string | 蓝牙设备 id |
| connected | boolean | 是否处于已连接状态 |
注意
重复调用会覆盖原来的回调
# onBLECharacteristicValueChange(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听蓝牙低功耗设备的特征值变化事件。必须先调用 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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
启用蓝牙低功耗设备特征值变化时的 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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
获取蓝牙低功耗设备所有服务 (service)。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| deviceId | string | 是 | 蓝牙设备 id。需要已经通过 createBLEConnection 建立连接 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# getBLEDeviceRSSI(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
获取蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| deviceId | string | 是 | 蓝牙设备 id | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
object.success 回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| RSSI | Number | 信号强度，单位 dBm |
# getBLEDeviceCharacteristics(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
获取蓝牙低功耗设备某个服务中所有特征 (characteristic)。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| deviceId | string | 是 | 蓝牙设备 id。需要已经通过 createBLEConnection 建立连接 | |
| serviceId | string | 是 | 蓝牙服务 UUID。需要先调用 getBLEDeviceServices 获取 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# createBLEConnection(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
连接蓝牙低功耗设备。
若小程序在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
断开与蓝牙低功耗设备的连接。
参数
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(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听当前外围设备被连接或断开连接事件
参数
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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
建立本地作为蓝牙低功耗外围设备的服务端，可创建多个。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
object.success 回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| server | BLEPeripheralServer | 外围设备的服务端。 |
# BLEPeripheralServer.addService(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
添加服务。
参数
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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
关闭当前服务端。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# BLEPeripheralServer.offCharacteristicReadRequest()
取消监听已连接的设备请求读当前外围设备的特征值事件
# BLEPeripheralServer.offCharacteristicSubscribed()
取消监听特征订阅事件
# BLEPeripheralServer.offCharacteristicUnsubscribed()
取消监听取消特征订阅事件
# BLEPeripheralServer.offCharacteristicWriteRequest()
取消监听已连接的设备请求写当前外围设备的特征值事件
# BLEPeripheralServer.onCharacteristicReadRequest(function callback)
参数
function callback
已连接的设备请求读当前外围设备的特征值事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| serviceId | String | 蓝牙特征对应服务的 UUID |
| characteristicId | String | 蓝牙特征的 UUID |
| callbackId | Number | 唯一标识码，调用 writeCharacteristicValue 时使用 |
注意 重复调用会覆盖原先的回调
# BLEPeripheralServer.onCharacteristicSubscribed(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听特征订阅事件，仅 iOS 支持。
参数
function callback
特征订阅事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| serviceId | String | 蓝牙特征对应服务的 UUID |
| characteristicId | String | 蓝牙特征的 UUID |
注意 重复调用会覆盖原先的回调
# BLEPeripheralServer.onCharacteristicUnsubscribed(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听取消特征订阅事件，仅 iOS 支持。
参数
function callback
取消特征订阅事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| serviceId | String | 蓝牙特征对应服务的 UUID |
| characteristicId | String | 蓝牙特征的 UUID |
注意 重复调用会覆盖原先的回调
# BLEPeripheralServer.onCharacteristicWriteRequest(function callback)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
监听已连接的设备请求写当前外围设备的特征值事件。收到该消息后需要立刻调用 writeCharacteristicValue 写回数据，否则主机不会收到响应。
参数
function callback
已连接的设备请求写当前外围设备的特征值事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| serviceId | String | 蓝牙特征对应服务的 UUID |
| characteristicId | String | 蓝牙特征的 UUID |
注意 重复调用会覆盖原先的回调
# BLEPeripheralServer.removeService(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
移除服务。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| serviceId | String | 是 | service 的 UUID | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# BLEPeripheralServer.startAdvertising(Object Object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
开始广播本地创建的外围设备
参数
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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
停止广播。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# BLEPeripheralServer.writeCharacteristicValue(Object Object)
基础库2.11.2开始支持，iOS版本2.34.1，Android版本2.34.1, 依赖扩展 SDK
往指定特征写入二进制数据值，并通知已连接的主机，从机的特征值已发生变化，该接口会处理是走回包还是走订阅。
参数
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| serviceId | String | 是 | 蓝牙特征对应服务的 UUID | |
| characteristicId | String | 是 | 蓝牙特征的 UUID | |
| value | ArrayBuffer | 是 | characteristic 对应的二进制值 | |
| needNotify | Boolean | 是 | 是否需要通知主机 value 已更新 | |
| callbackId | Number | 否 | 可选，处理回包时使用 | |
| success | function | 否 | 接口调用成功的回调函数 | |
| fail | function | 否 | 接口调用失败的回调函数 | |
| complete | function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# 蓝牙-信标(Beacon)
# stopBeaconDiscovery(Object object)
基础库2.11.2开始支持，iOS版本2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口
停止搜索附近的 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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口
开始搜索附近的 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）:
- 宿主App禁止小程序主动申请权限，会返回错误信息：unauthorized disableauthorized，SDK被禁止申请蓝牙权限
# onBeaconUpdate(function callback)
基础库2.11.2开始支持，iOS版本2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口
监听 Beacon 设备更新事件，仅能注册一个监听
参数
function callback
Beacon 设备更新事件的回调函数
参数
Object res
| 属性 | 类型 | 说明 |
|---|---|---|
| beacons | Array.BeaconInfo | 当前搜寻到的所有 Beacon 设备列表 |
# onBeaconServiceChange(function callback)
基础库2.11.2开始支持，iOS版本2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口
监听 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(Object object)
基础库2.11.2开始支持，iOS版本2.34.1, 依赖扩展 SDK, 安卓暂不支持 Beacon 相关接口
获取所有已搜索到的 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