# 设备

# 电量

# getBatteryInfoSync

getBatteryInfoSync()

ft.getBatteryInfo 的同步版本

返回值

Object res

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

# getBatteryInfo

getBatteryInfo(Object object)

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

object.success 回调函数

参数

Object object

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

# 剪贴板

# setClipboardData

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

setClipboardData(Object object)

设置系统剪贴板的内容。

参数

Object object

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

示例代码

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

# getClipboardData

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

getClipboardData(Object object)

获取系统剪贴板的内容。

参数

Object object

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

object.success 回调函数

参数

Object object

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

示例代码

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

# 网络

# onNetworkStatusChange

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

onNetworkStatusChange(function callback)

监听网络状态变化事件。

参数

function callback

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

参数

Object res

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

res.networkType 的合法值

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

示例代码

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

# offNetworkStatusChange

offNetworkStatusChange(function callback)

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

参数

function callback

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

# getNetworkType

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

getNetworkType(Object object)

获取网络类型。

参数

Object object

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

object.success 回调函数

参数

Object res

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

res.networkType 的合法值

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

示例代码

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

# getRandomValues

获取密码学安全随机数

参数

Object object

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

object.success 回调函数

参数

Object object

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

示例代码

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

# 屏幕

# setVisualEffectOnCapture

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

setVisualEffectOnCapture(Object object)

设置屏幕亮度。

参数

Object object

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

# setScreenBrightness

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

setScreenBrightness(Object object)

设置屏幕亮度。

参数

Object object

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

# setKeepScreenOn

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

setKeepScreenOn(Object object)

设置是否保持常亮状态。

参数

Object object

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

示例代码

ft.setKeepScreenOn({
  keepScreenOn: true
})

# onUserCaptureScreen

onUserCaptureScreen(function callback)

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

参数

function callback

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

示例代码

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

# onScreenRecordingStateChanged

onScreenRecordingStateChanged(function callback)

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

参数

function callback

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

参数

Object res

属性 类型 说明
state string 值为 start 或 stop,start:开始录屏;stop:停止录屏

示例代码

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

# offUserCaptureScreen

offUserCaptureScreen(function callback)

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

参数

function callback

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

# offScreenRecordingStateChanged

offScreenRecordingStateChanged(function callback)

移除用户录屏事件的监听

参数

function callback

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

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

# getScreenRecordingState

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

getScreenRecordingState(Object object)

查询用户是否在录屏

参数

Object object

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

object.success 回调函数

参数

Object res

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

# getScreenBrightness

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

getScreenBrightness(Object object)

获取屏幕亮度。

参数

Object object

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

object.success 回调函数

参数

Object res

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

# 键盘

# onKeyboardHeightChange

onKeyboardHeightChange(function callback)

监听键盘高度变化

参数

function callback

参数

object res

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

示例代码

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

# offKeyboardHeightChange

offKeyboardHeightChange(function callback)

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

参数

function callback

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

# hideKeyboard

hideKeyboard(Object object)

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

参数

Object object

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

示例代码

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

# getSelectedTextRange

getSelectedTextRange(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

示例代码

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

# 电话

# makePhoneCall

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

makePhoneCall(Object object)

拨打电话。

参数

Object object

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

示例代码

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

# 加速计

# stopAccelerometer

stopAccelerometer(Object object)

停止监听加速度数据。

参数

Object object

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

示例代码

ft.stopAccelerometer()

# startAccelerometer

startAccelerometer(Object object)

开始监听加速度数据。

参数

Object object

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

object.interval 的合法值

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

示例代码

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

# onAccelerometerChange

onAccelerometerChange(function callback)

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

参数

function callback

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

参数

Object res

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

示例代码

ft.onAccelerometerChange(callback)

# offAccelerometerChange

offAccelerometerChange(function callback)

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

参数

function callback

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

# 罗盘

# stopCompass

stopCompass(Object object)

停止监听罗盘数据

参数

Object object

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

示例代码

ft.stopCompass()

# startCompass

startCompass(Object object)

开始监听罗盘数据

参数

Object object

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

示例代码

ft.startCompass()

# onCompassChange

onCompassChange(function callback)

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

参数

function callback

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

参数

Object object

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

示例代码

ft.onCompassChange(callback)

accuracy 在 iOS/Android 的差异

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

  • iOS:accuracy 是一个 number 类型的值,表示相对于磁北极的偏差。0 表示设备指向磁北,90 表示指向东,180 表示指向南,依此类推。
  • Android:accuracy 是一个 string 类型的枚举值。
说明
high 高精度
medium 中等精度
low 低精度
no-contact 不可信,传感器失去连接
unreliable 不可信,原因未知
unknow ${value} 未知的精度枚举值,即该 Android 系统此时返回的表示精度的 value 不是一个标准的精度枚举值

# offCompassChange

offCompassChange(function callback)

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

参数

function callback

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

# 设备方向

# stopDeviceMotionListening

stopDeviceMotionListening(Object object)

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

参数

Object object

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

# startDeviceMotionListening

startDeviceMotionListening(Object object)

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

参数

Object object

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

object.interval 的合法值

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

# onDeviceMotionChange

onDeviceMotionChange(function callback)

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

参数

function callback

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

参数

Object res

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

# offDeviceMotionChange

offDeviceMotionChange(function callback)

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

参数

function callback

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

# 陀螺仪

# stopGyroscope

stopGyroscope(Object object)

停止监听陀螺仪数据。

参数

Object object

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

# startGyroscope

startGyroscope(Object object)

开始监听陀螺仪数据。

参数

Object object

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

object.interval 的合法值

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

# onGyroscopeChange

onGyroscopeChange(function callback)

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

参数

function callback

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

参数

Object res

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

# offGyroscopeChange

offGyroscopeChange(function callback)

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

参数

function callback

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

# 扫码

# scanCode

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

scanCode(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

示例代码

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

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

注意

  • 接口授权失败(iOS):
  1. 用户拒绝授权,会返回错误信息: unauthorized,用户未授予相机权限
  2. 宿主 App 禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK 被禁止申请相机权限
  • 接口授权失败(Android):
  1. 用户拒绝授权,会返回错误信息:fail unauthorized 用户未授予相机权限
  2. 宿主 App 禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized SDK 被禁止了主动发起权限申请

# 振动

# vibrateShort

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

vibrateShort(Object object)

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

参数

Object object

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

注意

  • 接口授权失败(Android):
  1. 用户拒绝授权,会返回错误信息:unauthorized 用户未授予震动权限
  2. 宿主 App 禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized SDK 被禁止了主动发起权限申请

# vibrateLong

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

vibrateLong(Object object)

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

参数

Object object

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

注意

  • 接口授权失败(Android):
  1. 用户拒绝授权,会返回错误信息:unauthorized 用户未授予震动权限
  2. 宿主 App 禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized SDK 被禁止了主动发起权限申请
  • iOS:
  1. 长振动的效果需要iPhone --> 设置 ---> 响铃模式振动、静音模式振动 开启,否则会无振动效果。

# 蓝牙-通用

# stopBluetoothDevicesDiscovery

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

stopBluetoothDevicesDiscovery(Object object)

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

参数

Object object

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

错误

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

# startBluetoothDevicesDiscovery

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

startBluetoothDevicesDiscovery(Object object)

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

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

参数

Object object

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

object.powerLevel 的合法值

说明 最低版本
low
medium
high

错误

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

# openBluetoothAdapter

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

openBluetoothAdapter(Object object)

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

参数


Object object

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

object.mode 的合法值

说明 最低版本
central 主机模式
peripheral 从机(外围设备)模式

错误


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

object.fail 回调函数返回的 state 参数(仅 iOS)


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

注意


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

注意

  • 接口授权失败(iOS):
  1. 宿主 App 禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK 被禁止申请蓝牙权限

# onBluetoothDeviceFound

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

参数


function callback

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

参数

object res

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

res.devices 的结构

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

注意


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

# onBluetoothAdapterStateChange

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

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

参数

function callback

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

参数

Object res

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

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

# offBluetoothDeviceFound

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

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

# offBluetoothAdapterStateChange

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

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

# makeBluetoothPair

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

makeBluetoothPair(Object object)

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

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

参数

Object object

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

# getConnectedBluetoothDevices

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

getConnectedBluetoothDevices(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

res.devices 的结构

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

错误

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

# getBluetoothDevices

getBluetoothDevices(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

res.devices 的结构

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

错误

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

# getBluetoothAdapterState

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

getBluetoothAdapterState(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

错误

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

# closeBluetoothAdapter

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

closeBluetoothAdapter(Object object)

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

参数

Object object

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

错误

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

# 蓝牙-低功耗中心设备

# writeBLECharacteristicValue

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

writeBLECharacteristicValue(Object object)

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

参数

Object object

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

writeType

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

错误

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

# setBLEMTU

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

setBLEMTU(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

object.fail 回调函数

参数

Object res

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

# readBLECharacteristicValue

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

readBLECharacteristicValue(Object object)

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

参数

Object object

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

错误

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

注意

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

# onBLEConnectionStateChange

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

onBLEConnectionStateChange(function callback)

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

参数

function callback

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

参数

Object res

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

注意

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

# onBLECharacteristicValueChange

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

onBLECharacteristicValueChange(function callback)

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

参数

function callback

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

参数

Object res

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

注意

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

# offBLEConnectionStateChange

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

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

# offBLECharacteristicValueChange

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

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

# notifyBLECharacteristicValueChange

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

notifyBLECharacteristicValueChange(Object object)

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

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

参数

Object res

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

错误

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

注意

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

# getBLEDeviceServices

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

getBLEDeviceServices(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

错误

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

# getBLEDeviceRSSI

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

getBLEDeviceRSSI(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

# getBLEDeviceCharacteristics

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

getBLEDeviceCharacteristics(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

characteristics

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

properties

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

错误

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

# createBLEConnection

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

createBLEConnection(Object object)

连接蓝牙低功耗设备。

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

参数

Object object

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

错误

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

注意

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

# closeBLEConnection

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

closeBLEConnection(Object object)

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

参数

Object object

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

错误

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

# 蓝牙-低功耗外围设备

# onBLEPeripheralConnectionStateChanged

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

onBLEPeripheralConnectionStateChanged(function callback)

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

参数

Object object

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

参数

Object res

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

# offBLEPeripheralConnectionStateChanged

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

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

# createBLEPeripheralServer

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

createBLEPeripheralServer(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

# BLEPeripheralServer.addService

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

BLEPeripheralServer.addService(Object object)

添加服务。

参数

Object object

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

object.service 的结构

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

characteristics 的结构

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

properties 的结构

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

permission 的结构

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

descriptors 的结构

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

permission 的结构

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

# BLEPeripheralServer.close

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

BLEPeripheralServer.close(Object object)

关闭当前服务端。

参数

Object object

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

# BLEPeripheralServer.offCharacteristicReadRequest

BLEPeripheralServer.offCharacteristicReadRequest()

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

# BLEPeripheralServer.offCharacteristicSubscribed

BLEPeripheralServer.offCharacteristicSubscribed()

取消监听特征订阅事件

# BLEPeripheralServer.offCharacteristicUnsubscribed

BLEPeripheralServer.offCharacteristicUnsubscribed()

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

# BLEPeripheralServer.offCharacteristicWriteRequest

BLEPeripheralServer.offCharacteristicWriteRequest()

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

# BLEPeripheralServer.onCharacteristicReadRequest

BLEPeripheralServer.onCharacteristicReadRequest(function callback)

参数

function callback

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

参数

Object res

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

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

# BLEPeripheralServer.onCharacteristicSubscribed

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

BLEPeripheralServer.onCharacteristicSubscribed(function callback)

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

参数

function callback

特征订阅事件的回调函数

参数

Object res

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

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

# BLEPeripheralServer.onCharacteristicUnsubscribed

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

BLEPeripheralServer.onCharacteristicUnsubscribed(function callback)

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

参数

function callback

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

参数

Object res

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

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

# BLEPeripheralServer.onCharacteristicWriteRequest

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

BLEPeripheralServer.onCharacteristicWriteRequest(function callback)

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

参数

function callback

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

参数

Object res

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

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

# BLEPeripheralServer.removeService

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

BLEPeripheralServer.removeService(Object object)

移除服务。

参数

Object object

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

# BLEPeripheralServer.startAdvertising

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

BLEPeripheralServer.startAdvertising(Object Object)

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

参数

Object object

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

Object.advertiseRequest 的结构

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

manufacturerData 的结构

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

Object.powerLevel 的合法值

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

注意

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

# BLEPeripheralServer.stopAdvertising

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

BLEPeripheralServer.stopAdvertising(Object object)

停止广播。

参数

Object object

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

# BLEPeripheralServer.writeCharacteristicValue

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

BLEPeripheralServer.writeCharacteristicValue(Object Object)

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

参数

Object object

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

# 蓝牙-信标(Beacon)

# stopBeaconDiscovery

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

stopBeaconDiscovery(Object object)

停止搜索附近的 Beacon 设备

参数

Object object

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

错误

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

# startBeaconDiscovery

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

startBeaconDiscovery(Object object)

开始搜索附近的 Beacon 设备

参数

Object object

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

错误

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

注意

  • 接口授权失败(iOS):
  1. 宿主 App 禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK 被禁止申请蓝牙权限

# onBeaconUpdate

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

onBeaconUpdate(function callback)

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

参数

function callback

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

参数

Object res

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

# onBeaconServiceChange

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

onBeaconServiceChange(function callback)

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

参数

function callback

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

参数

Object res

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

# offBeaconUpdate

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

取消监听 Beacon 设备更新事件

# offBeaconServiceChange

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

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

# getBeacons

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

getBeacons(Object object)

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

参数

Object object

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

参数

Object res

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

object.success 回调函数

参数

Object res

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

错误

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

# BeaconInfo

Beacon 设备

属性

string uuid

Beacon 设备广播的 UUID

number major

Beacon 设备的主 ID

number minor

Beacon 设备的次 ID

number proximity

表示设备距离的枚举值(仅 iOS)

proximity 的合法值

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

number accuracy

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

number rssi

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

# 联系人

# addPhoneContact

添加手机通讯录联系人。

参数

Object object

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

# chooseContact

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

参数

Object res

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

object.success 回调函数

参数

Object res

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

# 无障碍

# checkIsOpenAccessibility

基础库 2.12.1 开始支持

checkIsOpenAccessibility(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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