# 设备
# 电量
# 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）:
- 用户拒绝授权，会返回错误信息： 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
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| type | String | 是 | 震动强度类型，有效值为：heavy、medium、light。 iOS:2.39.11支持；Android:2.25.1支持 | |
| 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 被禁止了主动发起权限申请
- iOS：
- 长振动的效果需要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）:
- 宿主 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）:
- 宿主 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 | 否 | 公司电话 | |
| 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 |