@tarojs/taro 3.4.1 → 3.4.2

package/types/api/device/{ble.d.ts → bluetooth-ble.d.ts}

@@ -1,6 +1,53 @@
 import Taro from '../../index'
 
 declare module '../../index' {
+  namespace writeBLECharacteristicValue {
+    interface Promised extends TaroGeneral.BluetoothError {
+      /** 成功：ok，错误：详细信息 */
+      errMsg: string
+    }
+    interface Option {
+      /** 蓝牙特征值的 uuid */
+      characteristicId: string
+      /** 蓝牙设备 id */
+      deviceId: string
+      /** 蓝牙特征值对应服务的 uuid */
+      serviceId: string
+      /** 蓝牙设备特征值对应的二进制值 */
+      value: ArrayBuffer
+      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+      complete?: (res: TaroGeneral.BluetoothError) => void
+      /** 接口调用失败的回调函数 */
+      fail?: (res: TaroGeneral.BluetoothError) => void
+      /** 接口调用成功的回调函数 */
+      success?: (res: TaroGeneral.BluetoothError) => void
+    }
+  }
+
+  namespace setBLEMTU {
+    type Promised = FailCallbackResult | SuccessCallbackResult
+    interface Option {
+      /** 蓝牙设备 id */
+      deviceId: string
+      /** 最大传输单元。设置范围为 (22,512) 区间内，单位 bytes */
+      mtu: number
+      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+      complete?: (res: Promised) => void
+      /** 接口调用失败的回调函数 */
+      fail?: (res: FailCallbackResult) => void
+      /** 接口调用成功的回调函数 */
+      success?: (res: SuccessCallbackResult) => void
+    }
+    interface FailCallbackResult extends TaroGeneral.BluetoothError {
+      /** 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 */
+      mtu: string
+    }
+    interface SuccessCallbackResult extends TaroGeneral.BluetoothError {
+      /** 最终协商的 MTU 值，与传入参数一致。安卓客户端 8.0.9 开始支持。 */
+      mtu: string
+    }
+  }
+
   namespace readBLECharacteristicValue {
     interface Option {
       /** 蓝牙特征值的 uuid */
@@ -18,6 +65,19 @@ declare module '../../index' {
     }
   }
 
+  namespace onBLEMTUChange {
+    interface CallbackResult {
+      /** 蓝牙设备ID */
+      deviceId: string
+      /** 最大传输单元 */
+      mtu: string
+    }
+    /** 蓝牙低功耗的最大传输单元变化事件的回调函数 */
+    type Callback = (
+      result: CallbackResult,
+    ) => void
+  }
+
   namespace onBLEConnectionStateChange {
     interface CallbackResult {
       /** 是否处于已连接状态 */
@@ -49,7 +109,7 @@ declare module '../../index' {
   }
 
   namespace notifyBLECharacteristicValueChange {
-    interface Promised extends TaroGeneral.CallbackResult {
+    interface Promised extends TaroGeneral.BluetoothError {
       /** 成功：ok，错误：详细信息 */
       errMsg: string
     }
@@ -71,6 +131,36 @@ declare module '../../index' {
     }
   }
 
+  namespace getBLEMTU {
+    interface Option {
+      /** 蓝牙设备 id */
+      deviceId: string
+      /** 写模式 （iOS 特有参数）
+       * @default "write"
+       */
+      writeType: keyof WriteType
+      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+      complete?: (res: TaroGeneral.BluetoothError) => void
+      /** 接口调用失败的回调函数 */
+      fail?: (res: TaroGeneral.BluetoothError) => void
+      /** 接口调用成功的回调函数 */
+      success?: (
+        result: SuccessCallbackResult,
+      ) => void
+    }
+    interface SuccessCallbackResult extends TaroGeneral.BluetoothError {
+      /** 最大传输单元 */
+      mtu: number
+    }
+    /** 写模式合法值 */
+    interface WriteType {
+      /** 有回复写 */
+      write
+      /** 无回复写 */
+      writeNoResponse
+    }
+  }
+
   namespace getBLEDeviceServices {
     interface Option {
       /** 蓝牙设备 id */
@@ -84,7 +174,7 @@ declare module '../../index' {
         result: SuccessCallbackResult,
       ) => void
     }
-    interface SuccessCallbackResult extends TaroGeneral.CallbackResult {
+    interface SuccessCallbackResult extends TaroGeneral.BluetoothError {
       /** 设备服务列表 */
       services: BLEService[]
       /** 成功：ok，错误：详细信息 */
@@ -99,6 +189,25 @@ declare module '../../index' {
     }
   }
 
+  namespace getBLEDeviceRSSI {
+    interface Option {
+      /** 蓝牙设备 id */
+      deviceId: string
+      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+      complete?: (res: TaroGeneral.BluetoothError) => void
+      /** 接口调用失败的回调函数 */
+      fail?: (res: TaroGeneral.BluetoothError) => void
+      /** 接口调用成功的回调函数 */
+      success?: (
+        result: SuccessCallbackResult,
+      ) => void
+    }
+    interface SuccessCallbackResult extends TaroGeneral.BluetoothError {
+      /** 信号强度，单位 dBm */
+      RSSI: number
+    }
+  }
+
   namespace getBLEDeviceCharacteristics {
     interface Option {
       /** 蓝牙设备 id */
@@ -112,7 +221,7 @@ declare module '../../index' {
       /** 接口调用成功的回调函数 */
       success?: (res: SuccessCallbackResult) => void
     }
-    interface SuccessCallbackResult extends TaroGeneral.CallbackResult {
+    interface SuccessCallbackResult extends TaroGeneral.BluetoothError {
       /** 设备特征值列表 */
       characteristics: BLECharacteristic[]
       /** 成功：ok，错误：详细信息 */
@@ -139,7 +248,7 @@ declare module '../../index' {
   }
 
   namespace createBLEConnection {
-    interface Promised extends TaroGeneral.CallbackResult {
+    interface Promised extends TaroGeneral.BluetoothError {
       /** 成功：ok，错误：详细信息 */
       errMsg: string
     }
@@ -158,7 +267,7 @@ declare module '../../index' {
   }
 
   namespace closeBLEConnection {
-    interface Promised extends TaroGeneral.CallbackResult {
+    interface Promised extends TaroGeneral.BluetoothError {
       /** 成功：ok，错误：详细信息 */
       errMsg: string
     }
@@ -174,30 +283,49 @@ declare module '../../index' {
     }
   }
 
-  namespace writeBLECharacteristicValue {
-    interface Promised extends TaroGeneral.CallbackResult {
-      /** 成功：ok，错误：详细信息 */
-      errMsg: string
-    }
-    interface Option {
-      /** 蓝牙特征值的 uuid */
-      characteristicId: string
-      /** 蓝牙设备 id */
-      deviceId: string
-      /** 蓝牙特征值对应服务的 uuid */
-      serviceId: string
-      /** 蓝牙设备特征值对应的二进制值 */
-      value: ArrayBuffer
-      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
-      complete?: (res: TaroGeneral.BluetoothError) => void
-      /** 接口调用失败的回调函数 */
-      fail?: (res: TaroGeneral.BluetoothError) => void
-      /** 接口调用成功的回调函数 */
-      success?: (res: TaroGeneral.BluetoothError) => void
-    }
-  }
-
   interface TaroStatic {
+    /** 向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持 write 才可以成功调用。
+     *
+     * **注意**
+     * - 并行调用多次会存在写失败的可能性。
+     * - 小程序不会对写入数据包大小做限制，但系统与蓝牙设备会限制蓝牙4.0单次传输的数据大小，超过最大字节数后会发生写入错误，建议每次写入不超过20字节。
+     * - 若单次写入数据过长，iOS 上存在系统不会有任何回调的情况（包括错误回调）。
+     * - 安卓平台上，在调用 `notifyBLECharacteristicValueChange` 成功后立即调用 `writeBLECharacteristicValue` 接口，在部分机型上会发生 10008 系统错误
+     * @supported weapp
+     * @example
+     * ```tsx
+     * // 向蓝牙设备发送一个0x00的16进制数据
+     * let buffer = new ArrayBuffer(1)
+     * let dataView = new DataView(buffer)
+     * dataView.setUint8(0, 0)
+     * Taro.writeBLECharacteristicValue({
+     *   // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
+     *   deviceId,
+     *   // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
+     *   serviceId,
+     *   // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
+     *   characteristicId,
+     *   // 这里的value是ArrayBuffer类型
+     *   value: buffer,
+     *   success: function (res) {
+     *     console.log('writeBLECharacteristicValue success', res.errMsg)
+     *   }
+     * })
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.writeBLECharacteristicValue.html
+     */
+    writeBLECharacteristicValue(
+      option: writeBLECharacteristicValue.Option,
+    ): Promise<writeBLECharacteristicValue.Promised>
+
+    /** 协商设置蓝牙低功耗的最大传输单元 (Maximum Transmission Unit, MTU)
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.setBLEMTU.html
+     */
+    setBLEMTU(
+      option: setBLEMTU.Option,
+    ): Promise<setBLEMTU.Promised>
+
     /** 读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持 read 才可以成功调用。
      *
      * **注意**
@@ -228,6 +356,21 @@ declare module '../../index' {
       option: readBLECharacteristicValue.Option,
     ): Promise<TaroGeneral.BluetoothError>
 
+    /** 监听蓝牙低功耗的最大传输单元变化事件（仅安卓触发）
+     * @supported weapp
+     * @example
+     * ```tsx
+     * Taro.onBLEMTUChange(function (res) {
+     *   console.log('bluetooth mtu is', res.mtu)
+     * })
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.onBLEMTUChange.html
+     */
+    onBLEMTUChange(
+      /** 蓝牙低功耗的最大传输单元变化事件的回调函数 */
+      callback: onBLEMTUChange.Callback,
+    ): void
+
     /** 监听低功耗蓝牙连接状态的改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等
      * @supported weapp
      * @example
@@ -270,6 +413,33 @@ declare module '../../index' {
       callback: onBLECharacteristicValueChange.Callback,
     ): void
 
+    /** 取消监听蓝牙低功耗的最大传输单元变化事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.offBLEMTUChange.html
+     */
+    offBLEMTUChange(
+      /** 蓝牙低功耗的最大传输单元变化事件的回调函数 */
+      callback: onBLEMTUChange.Callback,
+    ): void
+
+    /** 取消监听蓝牙低功耗连接状态的改变事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.offBLEConnectionStateChange.html
+     */
+    offBLEConnectionStateChange(
+      /** 蓝牙低功耗连接状态的改变事件的回调函数 */
+      callback: onBLEMTUChange.Callback,
+    ): void
+
+    /** 取消监听蓝牙低功耗设备的特征值变化事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.offBLECharacteristicValueChange.html
+     */
+    offBLECharacteristicValueChange(
+      /** 低功耗蓝牙设备的特征值变化事件的回调函数 */
+      callback: onBLEMTUChange.Callback,
+    ): void
+
     /** 启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值。注意：必须设备的特征值支持 notify 或者 indicate 才可以成功调用。
      *
      * 另外，必须先启用 `notifyBLECharacteristicValueChange` 才能监听到设备 `characteristicValueChange` 事件
@@ -299,6 +469,28 @@ declare module '../../index' {
       option: notifyBLECharacteristicValueChange.Option,
     ): Promise<notifyBLECharacteristicValueChange.Promised>
 
+    /** 获取蓝牙低功耗的最大传输单元。需在 [Taro.createBLEConnection](/docs/apis/device/bluetooth-ble/createBLEConnection) 调用成功后调用。
+     *
+     * 注意:
+     *  - 小程序中 MTU 为 ATT_MTU，包含 Op-Code 和 Attribute Handle 的长度，实际可以传输的数据长度为 ATT_MTU - 3
+     *  - iOS 系统中 MTU 为固定值；安卓系统中，MTU 会在系统协商成功之后发生改变，建议使用 [Taro.onBLEMTUChange](/docs/apis/device/bluetooth-ble/onBLEMTUChange) 监听。
+     * @supported weapp
+     * @example
+     * ```tsx
+     * Taro.getBLEMTU({
+     *   deviceId: '',
+     *   writeType: 'write',
+     *   success (res) {
+     *     console.log(res)
+     *   }
+     * })
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.getBLEMTU.html
+     */
+     getBLEMTU(
+      option: getBLEMTU.Option,
+    ): Promise<getBLEMTU.SuccessCallbackResult>
+
     /** 获取蓝牙设备所有服务(service)。
      * @supported weapp
      * @example
@@ -317,6 +509,14 @@ declare module '../../index' {
       option: getBLEDeviceServices.Option,
     ): Promise<getBLEDeviceServices.SuccessCallbackResult>
 
+    /** 获取蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.getBLEDeviceRSSI.html
+     */
+    getBLEDeviceRSSI(
+      option: getBLEDeviceRSSI.Option,
+    ): Promise<getBLEDeviceRSSI.SuccessCallbackResult>
+
     /** 获取蓝牙设备某个服务中所有特征值(characteristic)。
      * @supported weapp
      * @example
@@ -374,39 +574,5 @@ declare module '../../index' {
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.closeBLEConnection.html
      */
     closeBLEConnection(option: closeBLEConnection.Option): Promise<closeBLEConnection.Promised>
-
-    /** 向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持 write 才可以成功调用。
-     *
-     * **注意**
-     * - 并行调用多次会存在写失败的可能性。
-     * - 小程序不会对写入数据包大小做限制，但系统与蓝牙设备会限制蓝牙4.0单次传输的数据大小，超过最大字节数后会发生写入错误，建议每次写入不超过20字节。
-     * - 若单次写入数据过长，iOS 上存在系统不会有任何回调的情况（包括错误回调）。
-     * - 安卓平台上，在调用 `notifyBLECharacteristicValueChange` 成功后立即调用 `writeBLECharacteristicValue` 接口，在部分机型上会发生 10008 系统错误
-     * @supported weapp
-     * @example
-     * ```tsx
-     * // 向蓝牙设备发送一个0x00的16进制数据
-     * let buffer = new ArrayBuffer(1)
-     * let dataView = new DataView(buffer)
-     * dataView.setUint8(0, 0)
-     * Taro.writeBLECharacteristicValue({
-     *   // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
-     *   deviceId,
-     *   // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
-     *   serviceId,
-     *   // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
-     *   characteristicId,
-     *   // 这里的value是ArrayBuffer类型
-     *   value: buffer,
-     *   success: function (res) {
-     *     console.log('writeBLECharacteristicValue success', res.errMsg)
-     *   }
-     * })
-     * ```
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.writeBLECharacteristicValue.html
-     */
-    writeBLECharacteristicValue(
-      option: writeBLECharacteristicValue.Option,
-    ): Promise<writeBLECharacteristicValue.Promised>
   }
 }