# 设备

# 日历

# addPhoneRepeatCalendar

addPhoneRepeatCalendar(Object object)

向系统日历添加重复事件

参数

Object object

属性 类型 默认值 必填 说明
title string 日历事件标题
startTime number 开始时间的 unix 时间戳 (1970年1月1日开始所经过的秒数)
allDay boolean 是否全天事件,默认 false
description string 事件说明
location string 事件位置
endTime string 结束时间的 unix 时间戳,默认与开始时间相同
alarm boolean 是否提醒,默认 true
alarmOffset number 提醒提前量,单位秒,默认 0 表示开始时提醒
repeatInterval string 重复周期,默认 month 每月重复
repeatEndTime number 重复周期结束时间的 unix 时间戳,不填表示一直重复
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

# addPhoneCalendar

addPhoneCalendar(Object object)

向系统日历添加事件

参数

Object object

属性 类型 默认值 必填 说明
title string 日历事件标题
startTime number 开始时间的 unix 时间戳 (1970年1月1日开始所经过的秒数)
allDay boolean 是否全天事件,默认 false
description string 事件说明
location string 事件位置
endTime string 结束时间的 unix 时间戳,默认与开始时间相同
alarm boolean 是否提醒,默认 true
alarmOffset number 提醒提前量,单位秒,默认 0 表示开始时提醒
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

# 联系人

# searchContacts

searchContacts(Object object)

查找通讯录,匹配相近的手机号

参数

Object object

属性 类型 默认值 必填 说明
phoneNumber string 需要查找的号码,长度>=8位才匹配
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

object.success 回调函数

参数

Object object

属性 类型 说明
result Array.<Object> 手机号

object.result 的结构

属性 类型 说明
phoneNumber string 手机号
name string 联系人姓名

示例代码

wx.searchContacts({
  phoneNumber: '10000000',
  success (res) {},
  fail: console.error,
})

# chooseContact

chooseContact(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object object

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

# addPhoneContact

基础库1.3.9开始支持,需要 SDK 通过自定义 API 自行实现

addPhoneContact(Object object)

添加手机通讯录联系人。用户可以选择将该表单以「新增联系人」或「添加到已有联系人」的方式,写入手机系统通讯录。

参数

Object object

属性 类型 默认值 必填 说明
firstName string 名字
photoFilePath string 头像本地文件路径
nickName string 昵称
lastName string 姓氏
middleName string 中间名
remark string 备注
mobilePhoneNumber 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 接口调用结束的回调函数(调用成功、失败都会执行)

# 电量

# getBatteryInfoSync

getBatteryInfoSync()

ft.getBatteryInfo 的同步版本

返回值

Object res

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

# getBatteryInfo

getBatteryInfo(Object object)

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

object.success 回调函数

参数

Object object

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

# 剪贴板

# setClipboardData

基础库1.3.9开始支持,iOS版本2.1.23,Android版本2.1.38, 依赖扩展 SDK

setClipboardData(Object object)

设置系统剪贴板的内容。

参数

Object object

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

示例代码

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

# getClipboardData

基础库1.3.9开始支持,iOS版本2.1.23,Android版本2.1.38, 依赖扩展 SDK

getClipboardData(Object object)

获取系统剪贴板的内容。

参数

Object object

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

object.success 回调函数

参数

Object object

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

示例代码

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

# 网络

# onNetworkStatusChange

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

onNetworkStatusChange(function callback)

监听网络状态变化事件。

参数

function callback

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

参数

Object res

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

res.networkType 的合法值

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

示例代码

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

# offNetworkStatusChange

offNetworkStatusChange(function callback)

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

参数

function callback

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

# getNetworkType

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

getNetworkType(Object object)

获取网络类型。

参数

Object object

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

object.success 回调函数

参数

Object res

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

res.networkType 的合法值

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

示例代码

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

# 屏幕

# setScreenBrightness

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

setScreenBrightness(Object object)

设置屏幕亮度。

参数

Object object

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

# setKeepScreenOn

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

setKeepScreenOn(Object object)

设置是否保持常亮状态。

参数

Object object

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

示例代码

ft.setKeepScreenOn({
  keepScreenOn: true
})

# onUserCaptureScreen

onUserCaptureScreen(function callback)

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

参数

function callback

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

示例代码

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

# offUserCaptureScreen

offUserCaptureScreen(function callback)

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

参数

function callback

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

# getScreenBrightness

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

getScreenBrightness(Object object)

获取屏幕亮度。

参数

Object object

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

object.success 回调函数

参数

Object object

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

# 键盘

# 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

属性 类型 默认值 必填 说明
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被禁止了主动发起运行时权限申请

# 蓝牙-通用

# stopBluetoothDevicesDiscovery(Object object)

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

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

参数

Object object

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

错误

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

# startBluetoothDevicesDiscovery(Object object)

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

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

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

参数

Object object

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

object.powerLevel 的合法值

说明 最低版本
low
medium
high

错误

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

# openBluetoothAdapter(Object object)

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

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

# 参数

Object object

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

object.mode 的合法值

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

# 错误

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

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

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

# 注意

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

注意

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

# onBluetoothDeviceFound(function callback)

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

监听搜索到新设备的事件

# 参数

function callback

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

参数

object res

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

res.devices 的结构

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

# 注意

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

# onBluetoothAdapterStateChange(function callback)

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

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

参数

function callback

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

参数

Object res

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

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

# offBluetoothDeviceFound

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

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

# offBluetoothAdapterStateChange

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

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

# makeBluetoothPair(Object object)

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

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

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

参数

Object object

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

# getConnectedBluetoothDevices(Object object)

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

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

res.devices 的结构

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

错误

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

# getBluetoothDevices(Object object)

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

res.devices 的结构

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

错误

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

# getBluetoothAdapterState(Object object)

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

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

# closeBluetoothAdapter(Object object)

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

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

参数

Object object

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

# 蓝牙-低功耗中心设备

# writeBLECharacteristicValue(Object object)

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

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

参数

Object object

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

错误

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

# setBLEMTU(Object object)

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

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

object.fail 回调函数

参数

Object res

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

# readBLECharacteristicValue(Object object)

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

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

参数

Object object

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

错误

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

注意

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

# onBLEConnectionStateChange(function callback)

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

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

参数

function callback

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

参数

Object res

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

注意

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

# onBLECharacteristicValueChange(function callback)

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

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

参数

function callback

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

参数

Object res

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

注意

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

# offBLEConnectionStateChange

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

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

# offBLECharacteristicValueChange

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

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

# notifyBLECharacteristicValueChange(Object object)

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

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

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

参数

Object res

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

错误

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

注意

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

# getBLEDeviceServices(Object object)

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

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

参数

Object object

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

# getBLEDeviceRSSI(Object object)

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

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

# getBLEDeviceCharacteristics(Object object)

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

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

参数

Object object

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

# createBLEConnection(Object object)

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

连接蓝牙低功耗设备。

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

参数

Object object

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

错误

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

注意

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

# closeBLEConnection(Object object)

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

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

参数

Object object

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

错误

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

# 蓝牙-低功耗外围设备

# onBLEPeripheralConnectionStateChanged(function callback)

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

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

参数

Object object

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

参数

Object res

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

# offBLEPeripheralConnectionStateChanged

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

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

# createBLEPeripheralServer(Object object)

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

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

参数

Object object

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

object.success 回调函数

参数

Object res

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

# BLEPeripheralServer.addService(Object object)

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

添加服务。

参数

Object object

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

object.service 的结构

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

characteristics 的结构

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

properties 的结构

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

permission 的结构

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

descriptors 的结构

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

permission 的结构

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

# BLEPeripheralServer.close(Object object)

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

关闭当前服务端。

参数

Object object

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

# BLEPeripheralServer.offCharacteristicReadRequest()

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

# BLEPeripheralServer.offCharacteristicSubscribed()

取消监听特征订阅事件

# BLEPeripheralServer.offCharacteristicUnsubscribed()

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

# BLEPeripheralServer.offCharacteristicWriteRequest()

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

# BLEPeripheralServer.onCharacteristicReadRequest(function callback)

参数

function callback

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

参数

Object res

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

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

# BLEPeripheralServer.onCharacteristicSubscribed(function callback)

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

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

参数

function callback

特征订阅事件的回调函数

参数

Object res

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

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

# BLEPeripheralServer.onCharacteristicUnsubscribed(function callback)

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

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

参数

function callback

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

参数

Object res

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

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

# BLEPeripheralServer.onCharacteristicWriteRequest(function callback)

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

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

参数

function callback

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

参数

Object res

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

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

# BLEPeripheralServer.removeService(Object object)

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

移除服务。

参数

Object object

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

# BLEPeripheralServer.startAdvertising(Object Object)

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

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

参数

Object object

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

Object.advertiseRequest 的结构

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

manufacturerData 的结构

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

Object.powerLevel 的合法值

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

注意

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

# BLEPeripheralServer.stopAdvertising(Object object)

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

停止广播。

参数

Object object

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

# BLEPeripheralServer.writeCharacteristicValue(Object Object)

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

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

参数

Object object

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

# 蓝牙-信标(Beacon)

# stopBeaconDiscovery(Object object)

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

停止搜索附近的 Beacon 设备

参数

Object object

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

错误

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

# startBeaconDiscovery(Object object)

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

开始搜索附近的 Beacon 设备

参数

Object object

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

错误

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

注意

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

# onBeaconUpdate(function callback)

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

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

参数

function callback

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

参数

Object res

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

# onBeaconServiceChange(function callback)

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

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

参数

function callback

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

参数

Object res

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

# offBeaconUpdate

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

取消监听 Beacon 设备更新事件

# offBeaconServiceChange

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

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

# getBeacons(Object object)

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

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

参数

Object object

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

参数

Object res

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

object.success 回调函数

参数

Object res

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

错误

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

# BeaconInfo

Beacon 设备

属性

string uuid

Beacon 设备广播的 UUID

number major

Beacon 设备的主 ID

number minor

Beacon 设备的次 ID

number proximity

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

proximity 的合法值

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

number accuracy

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

number rssi

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

© 2021 凡泰极客
  • 免费试用
  • 编组
  • 编组 2