API列表

扫码体验：

iOS 支付宝客户端 10.0.18 版本开始支持，Android 10.0.18 版本开始支持目前不支持在开发者工具上进行调试，需要使用真机才能正常调用小程序蓝牙接口

my.openBluetoothAdapter

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

初始化小程序蓝牙模块，生效周期为调用 my.openBluetoothAdapter 至调用 my.closeBluetoothAdapter 或小程序被销毁为止。 在小程序蓝牙适配器模块生效期间，开发者可以正常调用下面的小程序API，并会收到蓝牙模块相关的 on 事件回调。

入参

success 返回值

错误码描述

示例代码

my.openBluetoothAdapter({
  success: (res) => {
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 在调用 my.openBluetoothAdapter API之前，调用小程序其它蓝牙模块相关API，API会返回错误，错误码:10000,错误描述:未初始化蓝牙适配器
• bug: 在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下，调用 my.openBluetoothAdapter 会返回错误，错误码见错误码描述；此时小程序蓝牙模块已经初始化完成，可通过 my.onBluetoothAdapterStateChange 监听手机蓝牙状态的改变

my.closeBluetoothAdapter

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

关闭本机蓝牙模块。

入参

示例代码

my.closeBluetoothAdapter({
  success: (res) => {
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 调用该方法将断开所有已建立的蓝牙连接并释放系统资源。
• tip: 建议在结束小程序蓝牙流程时调用，与 my.openBluetoothAdapter 成对调用。
• tip: 调用 my.closeBluetoothAdapter 释放资源为异步操作，不建议使用 my.closeBluetoothAdapter 和 my.openBluetoothAdapter 作为异常处理流程（相当于先关闭再开启，重新初始化，效率低，易发生线程同步问题）

my.getBluetoothAdapterState

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

获取本机蓝牙模块状态。

入参

success 返回值

示例代码

my.getBluetoothAdapterState({
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.startBluetoothDevicesDiscovery

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理allowDuplicatesKey 和 interval 参数，从支付宝钱包10.0.20开始支持

开始搜寻附近的蓝牙外围设备。搜索结果将在 my.onBluetoothDeviceFound 事件中返回。

入参

示例代码

my.startBluetoothDevicesDiscovery({
  services: ['fff0'],
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 该操作比较耗费系统资源，请在搜索并连接到设备后调用 stop 方法停止搜索。

my.stopBluetoothDevicesDiscovery

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

停止搜寻附近的蓝牙外围设备。

入参

示例代码

my.stopBluetoothDevicesDiscovery({
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

my.getBluetoothDevices

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

获取所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备。

入参

success 返回值

device对象

示例代码

my.getBluetoothDevices({
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 模拟器可能无法获取 advertisData 及 RSSI，请使用真机调试
• tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid; 因此 deviceId 不能硬编码到代码中，需要分平台处理，iOS可根据设备属性（ localName/advertisData/manufacturerData 等属性）进行动态匹配。

my.getConnectedBluetoothDevices

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

获取处于已连接状态的设备。

入参

success 返回值

device对象

示例代码

my.getConnectedBluetoothDevices({
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 如果传递的 services 为空，则返回所有的已经连接的设备。
• tip: Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中，需要区分处理。

my.connectBLEDevice

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

连接低功耗蓝牙设备。

入参

示例代码

my.connectBLEDevice({
  // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId: deviceId,
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 若小程序在之前已有搜索过某个蓝牙设备，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需进行搜索操作。
• tip: 若指定的蓝牙设备已经连接，重复连接直接返回成功。

my.disconnectBLEDevice

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

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

入参

示例代码

my.disconnectBLEDevice({
  deviceId: deviceId,
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 蓝牙连接随时可能断开，建议监听 my.onBLEConnectionStateChanged 回调事件，当蓝牙设备断开时按需执行重连操作
• tip: 若对未连接的设备或已断开连接的设备调用数据读写操作的接口，会返回10006错误，详见错误码，建议进行重连操作

my.writeBLECharacteristicValue

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

向低功耗蓝牙设备特征值中写入数据。

入参

示例代码

my.writeBLECharacteristicValue({
  deviceId: deviceId,
  serviceId: serviceId,
  characteristicId: characteristicId,
  value: 'fffe',
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 设备的特征值必须支持 write 才可以成功调用，具体参照 characteristic 的 properties 属性。
• tip: 写入的二进制数据需要进行 hex 编码。

my.readBLECharacteristicValue

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

读取低功耗蓝牙设备特征值中的数据。调用后在 my.onBLECharacteristicValueChange() 事件中接收数据返回。

入参

success 返回值

characteristic对象

蓝牙设备characteristic(特征值)信息

示例代码

my.readBLECharacteristicValue({
  deviceId: deviceId,
  serviceId: serviceId,
  characteristicId: characteristicId,
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 设备的特征值必须支持read才可以成功调用，具体参照 characteristic 的 properties 属性
• tip: 并行多次调用读写接口存在读写失败的可能性。
• tip: 如果读取超时，错误码 10015，my.onBLECharacteristicValueChange 接口之后可能返回数据，需要接入方酌情处理。

my.notifyBLECharacteristicValueChange

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理入参 state ，从支付宝钱包 10.0.20 开始支持

启用低功耗蓝牙设备特征值变化时的 notify 功能。注意：设备的特征值必须支持 notify/indicate 才可以成功调用，具体参照 characteristic 的 properties 属性 另外，必须先启用 notify 才能监听到设备 characteristicValueChange 事件。

入参

示例代码

my.notifyBLECharacteristicValueChange({
  deviceId: deviceId,
  serviceId: serviceId,
  characteristicId: characteristicId,
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 订阅操作成功后需要设备主动更新特征值的 value，才会触发 my.onBLECharacteristicValueChange 。
• tip: 订阅方式效率比较高，推荐使用订阅代替 read 方式。

my.getBLEDeviceServices

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

获取蓝牙设备所有 service（服务）

入参

success 返回值

service对象

蓝牙设备service(服务)信息

示例代码

my.getBLEDeviceServices({
  deviceId: deviceId,
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 建立连接后先执行 my.getBLEDeviceServices 与 my.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。

my.getBLEDeviceCharacteristics

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

获取蓝牙设备所有 characteristic（特征值）

入参

success 返回值

characteristic对象

蓝牙设备 characteristic （特征值）信息

properties 对象

示例代码

my.getBLEDeviceCharacteristics({
  deviceId: deviceId,
  serviceId: serviceId,
  success: (res) => {
      console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

Bug & Tip

• tip: 建立连接后先执行 my.getBLEDeviceServices 与 my.getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互。

my.onBluetoothDeviceFound(callback)

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

搜索到新的蓝牙设备时触发此事件。

入参

callback 返回值

device对象

示例代码

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onBluetoothDeviceFound(this.callback);
  },
  onUnload() {
    my.offBluetoothDeviceFound(this.callback);
  },
  callback(res) {
    console.log(res);
  },
})

Bug & Tip

• tip: 模拟器可能无法获取 advertisData 及 RSSI ，请使用真机调试。
• tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中，需要分平台处理，iOS可根据设备属性（localName/advertisData/manufacturerData等）进行动态匹配。
• tip: 若在 my.onBluetoothDeviceFound 回调中包含了某个蓝牙设备，则此设备会添加到 my.getBluetoothDevices 接口获取到的数组中。

my.offBluetoothDeviceFound

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

移除寻找到新的蓝牙设备事件的监听。

示例代码

my.offBluetoothDeviceFound();

Bug & Tip

• tip: 为防止多次注册事件监听导致一次事件多次回调，建议每次调用on方法监听事件之前，先调用off方法，关闭之前的事件监听。

my.onBLECharacteristicValueChange(callback)

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

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

入参

callback 返回值

示例代码

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onBLECharacteristicValueChange(this.callback);
  },
  onUnload() {
    my.offBLECharacteristicValueChange(this.callback);
  },
  callback(res) {
    console.log(res);
  },
})

my.offBLECharacteristicValueChange

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

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

示例代码

my.offBLECharacteristicValueChange();

my.onBLEConnectionStateChanged(callback)

监听低功耗蓝牙连接的错误事件，包括设备丢失，连接异常断开等。

callback 返回值

Bug & Tip

• tip: 为防止多次注册事件监听导致一次事件多次回调，建议每次调用on方法监听事件之前，先调用off方法，关闭之前的事件监听。

my.offBLEConnectionStateChanged

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

移除低功耗蓝牙连接状态变化事件的监听。

示例代码

my.offBLEConnectionStateChanged();

Bug & Tip

• tip: 为防止多次注册事件监听导致一次事件多次回调，建议每次调用on方法监听事件之前，先调用off方法，关闭之前的事件监听。

my.onBluetoothAdapterStateChange(callback)

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

监听本机蓝牙状态变化的事件。

callback 返回值

my.offBluetoothAdapterStateChange

支付宝客户端 10.0.18 版本开始支持，低版本需做兼容处理

移除本机蓝牙状态变化的事件的监听。

示例代码

my.offBluetoothAdapterStateChange();

Bug & Tip

• tip: 为防止多次注册事件监听导致一次事件多次回调，建议每次调用on方法监听事件之前，先调用off方法，关闭之前的事件监听。

错误码

原文: https://docs.alipay.com/mini/api/bluetooth-api