tmui-cli 5.3.2 → 5.3.3

package/data/uni-app-x-docs/_sidebar.md

@@ -127,6 +127,7 @@
     * [安卓、鸿蒙厂商推送配置](uni-push/vendor_config.md)
     * [谷歌FCM配置](uni-push/google-fcm.md)
   * [uni统计](https://uniapp.dcloud.net.cn/uni-stat-uniappx)
+  * [App升级中心](https://doc.dcloud.net.cn/uniCloud/upgrade-center.html)
 * 教程
 	* [性能优化](performance.md)
 	* [复杂列表开发指南](tutorial/stickynestlist.md)

package/data/uni-app-x-docs/api/_sidebar.md

@@ -29,6 +29,7 @@
   * [设置tabBar](set-tab-bar.md)
   * [页面下拉刷新](pull-down-refresh.md)
   * [将页面滚动到指定位置](page-scroll-to.md)
+  <!-- * [ScrollViewContext](scrollviewcontext.md) -->
   * [监听中间按钮的点击事件](on-tab-bar-mid-button-tap.md)
   * [窗口](window.md)
   * [宽屏适配](wide-screen-adaptation.md)
@@ -82,6 +83,8 @@
   * [安装 APK](install-apk.md)
   * [监听权限申请](create-request-permission-listener.md)
   * [请求系统权限](request-system-permission.md)
+  * [蓝牙-通用](bluetooth-general.md)
+  * [蓝牙-低功耗中心设备](bluetooth-le-central.md)
 * 媒体
   * [拍照或从相册选择图片](choose-image.md)
   * [图片预览](preview-image.md)

package/data/uni-app-x-docs/api/bluetooth-general.md

@@ -0,0 +1,280 @@
+::: warning 注意事项
+
+使用蓝牙能力前，需先调用 [uni.openBluetoothAdapter](#openbluetoothadapter) 初始化蓝牙适配器，并确认初始化成功。调用 [uni.closeBluetoothAdapter](#closebluetoothadapter) 或应用进程结束后，再次使用时需重新初始化。监听类接口可提前注册。
+
+:::
+
+## 模块介绍
+
+蓝牙规范由蓝牙技术联盟（SIG）制定，主流有两种规格：**经典蓝牙（BR/EDR）** 用于音箱、耳机等较大带宽场景；**蓝牙低功耗（BLE，蓝牙 4.0 起）** 功耗低、适合小数据量传输，常见于智能穿戴、传感器、智能家居等设备。
+
+本文与[蓝牙-低功耗中心设备](./bluetooth-le-central.md)介绍 BLE 中心设备能力，用于发现并连接蓝牙低功耗外设，不用于经典蓝牙设备的数据通信。接口按职责分为两部分：
+
+- **蓝牙-通用**：初始化/关闭适配器、监听适配器状态、扫描与发现设备、获取设备列表；
+- **[蓝牙-低功耗中心设备](./bluetooth-le-central.md)**：连接设备、发现服务与特征值、读写特征值、订阅通知、MTU 等。
+
+当前支持微信小程序（uni-app x 4.41 起）和支付宝小程序（uni-app x 5.31 起），App 端暂不支持。各接口的具体支持范围及最低支持版本以兼容性表为准。
+
+
+## 使用流程
+
+<a href="../static/bluetooth-general-flow.svg" target="_blank" rel="noopener"><img src="../static/bluetooth-general-flow.svg" alt="蓝牙通用接口使用流程：注册监听、初始化、扫描发现设备、停止扫描、连接通信及清理资源" width="400"></a>
+
+1. 注册 [uni.onBluetoothAdapterStateChange](#onbluetoothadapterstatechange) 和 [uni.onBluetoothDeviceFound](#onbluetoothdevicefound)，分别监听适配器状态和设备发现事件。
+2. 调用 [uni.openBluetoothAdapter](#openbluetoothadapter)，初始化成功后调用 [uni.startBluetoothDevicesDiscovery](#startbluetoothdevicesdiscovery) 开始扫描。
+3. 通过设备发现事件获取目标设备的 `deviceId`，也可调用 [uni.getBluetoothDevices](#getbluetoothdevices) 获取已发现的设备列表。
+4. 发现目标设备后，调用 [uni.stopBluetoothDevicesDiscovery](#stopbluetoothdevicesdiscovery) 停止扫描，再连接设备并通信，见[蓝牙-低功耗中心设备](./bluetooth-le-central.md)。
+5. 使用结束后，移除当前页面或组件注册的监听；不再使用蓝牙能力时，调用 [uni.closeBluetoothAdapter](#closebluetoothadapter) 释放适配器。
+
+## 权限@permission
+
+### iOS
+
+- 蓝牙访问需要 `NSBluetoothAlwaysUsageDescription` 隐私说明，并获得用户授权。发行时应确认最终应用包含符合实际用途的权限说明。
+- 系统蓝牙开关与应用蓝牙权限是两个独立条件。系统蓝牙已开启，不代表应用已获授权。
+
+### 微信小程序和支付宝小程序
+
+需分别遵循微信小程序和支付宝小程序的蓝牙授权要求与平台限制。各接口的支持范围以对应的兼容性表为准。
+
+## 注意事项@tips
+
+### 设备发现与连接
+
+- **使用扫描返回的 deviceId**：通过设备发现事件或已发现的设备列表获取目标设备的 `deviceId`，再用于后续连接和通信。
+- **iOS 设备标识**：连接设备前需先扫描发现设备，仅保存设备 ID 不能代替设备发现。iOS 的 `deviceId` 来自系统分配的 UUID，不应假设它跨手机、跨安装或跨会话始终不变。
+- **及时停止扫描**：扫描较耗电，发现目标设备后应尽快停止扫描。
+
+适配器可用不代表设备已连接。监听设备连接状态时，使用 [uni.onBLEConnectionStateChange](./bluetooth-le-central.md#onbleconnectionstatechange)，通过回调中的 `deviceId` 和 `connected` 判断目标设备是否连接。
+
+### 事件监听
+
+- **监听与取消监听成对使用**：页面或组件卸载时，调用对应的 `off*` 移除自身注册的监听，避免重复监听或影响其他页面。
+- **iOS 监听 ID**：可保存 `on*` 返回的监听 ID，并将该 ID 传给对应的 `off*`，仅移除自身注册的监听，避免清空其他页面的监听。
+
+### 适配器状态与权限
+
+- **适配器由应用共享**：关闭适配器会影响其他页面正在进行的蓝牙操作，应统一管理其生命周期。
+- **蓝牙关闭后的恢复**：系统蓝牙关闭后，现有扫描与连接会失效。重新开启后，应根据适配器可用状态重新扫描、连接，并重新发现服务与特征值、订阅通知。
+
+系统蓝牙开关和应用蓝牙权限需分别检查。先注册 [uni.onBluetoothAdapterStateChange](#onbluetoothadapterstatechange) 并调用 [uni.openBluetoothAdapter](#openbluetoothadapter) 初始化。
+
+以下操作路径及事件表现为 **iOS 平台差异**，不作为其他平台的操作说明：
+
+| 操作路径 | 事件表现 | uni API 处理方式 |
+| --- | --- | --- |
+| 设置 → 蓝牙：主开关 | 应用进程存活时，会触发适配器状态变化事件 | 在 `onBluetoothAdapterStateChange` 回调中通过 `available` 判断是否可用。关闭时停止后续蓝牙操作；重新开启且 `available` 为 `true` 后，按需重新扫描和连接。 |
+| 设置 → App → 蓝牙：应用权限 | 系统会终止 App，不能依赖原进程继续接收事件 | 重新启动后，重新注册监听并调用 `openBluetoothAdapter`，根据成功或失败回调处理授权结果。 |
+| 控制中心：蓝牙按钮 | 通常不会触发适配器状态变化事件 | 适配器仍可能可用，不能用此操作代替系统蓝牙主开关测试。设备是否断开应通过 `onBLEConnectionStateChange` 判断。 |
+
+### 后台运行
+
+iOS 应用进行后台蓝牙操作需声明 `bluetooth-central` 后台模式，但后台扫描与连接仍受系统调度限制，不能保证与前台行为一致。
+
+### 初始化失败处理
+
+以下错误码及处理方式适用于 App，微信小程序和支付宝小程序的错误码说明详见其文档。
+
+| errCode | 含义 | 建议处理 |
+| --- | --- | --- |
+| `1509602` | 应用未获得蓝牙权限 | 引导用户在“设置 → App → 蓝牙”中授权。权限变更导致 App 重新启动后，重新注册监听并初始化。 |
+| `1509603` | 系统蓝牙已关闭 | 引导用户在“设置 → 蓝牙”中开启主开关，恢复后重新调用初始化。 |
+| `1500102` | 适配器暂不可用 | 等待适配器恢复可用后再尝试，不要连续反复初始化。 |
+| `1509010` | 初始化时等待适配器状态超时 | 稍后重试初始化，并检查系统蓝牙状态；该错误不同于连接设备时的 `1509005`。 |
+| `1500105` | 系统或平台不支持该蓝牙能力 | 检查接口兼容性及运行环境，重复调用不能消除此限制。 |
+| `1500104` / `1509000` | 系统调用失败或其他错误 | 记录接口名、`errCode`、`errMsg` 及可用的错误详情，结合真机环境进一步排查。 |
+
+<!-- UTSAPIJSON.openBluetoothAdapter.name -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.description -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.compatibility -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.param -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.fileFormats -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.returnValue -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.example -->
+
+<!-- UTSAPIJSON.openBluetoothAdapter.tutorial -->
+
+### 使用说明
+
+- 初始化成功只表示应用可以使用蓝牙适配器，不代表已扫描到设备或建立连接。应在成功回调后开始扫描，再按[中心设备使用流程](./bluetooth-le-central.md#使用流程)连接和通信。
+- 初始化失败时，应根据失败回调处理原因，待相关条件恢复后重新初始化，不要继续扫描或连接。
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.name -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.description -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.compatibility -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.param -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.fileFormats -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.returnValue -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.example -->
+
+<!-- UTSAPIJSON.closeBluetoothAdapter.tutorial -->
+
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.name -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.description -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.compatibility -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.param -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.fileFormats -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.returnValue -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.example -->
+
+<!-- UTSAPIJSON.getBluetoothAdapterState.tutorial -->
+
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.name -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.description -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.compatibility -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.param -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.returnValue -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.example -->
+
+<!-- UTSAPIJSON.onBluetoothAdapterStateChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.name -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.description -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.compatibility -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.param -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.returnValue -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.example -->
+
+<!-- UTSAPIJSON.offBluetoothAdapterStateChange.tutorial -->
+
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.name -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.description -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.compatibility -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.param -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.fileFormats -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.returnValue -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.example -->
+
+<!-- UTSAPIJSON.startBluetoothDevicesDiscovery.tutorial -->
+
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.name -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.description -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.compatibility -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.param -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.fileFormats -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.returnValue -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.example -->
+
+<!-- UTSAPIJSON.stopBluetoothDevicesDiscovery.tutorial -->
+
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.name -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.description -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.compatibility -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.param -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.fileFormats -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.returnValue -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.example -->
+
+<!-- UTSAPIJSON.onBluetoothDeviceFound.tutorial -->
+
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.name -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.description -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.compatibility -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.param -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.fileFormats -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.returnValue -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.example -->
+
+<!-- UTSAPIJSON.offBluetoothDeviceFound.tutorial -->
+
+
+<!-- UTSAPIJSON.getBluetoothDevices.name -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.description -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.compatibility -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.param -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.fileFormats -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.returnValue -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.example -->
+
+<!-- UTSAPIJSON.getBluetoothDevices.tutorial -->
+
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.name -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.description -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.compatibility -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.param -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.fileFormats -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.returnValue -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.example -->
+
+<!-- UTSAPIJSON.getConnectedBluetoothDevices.tutorial -->
+
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->

package/data/uni-app-x-docs/api/bluetooth-le-central.md

@@ -0,0 +1,376 @@
+::: warning 注意事项
+
+使用前，需先按[蓝牙-通用](./bluetooth-general.md)中的流程初始化适配器并发现目标设备。建立连接后，先发现服务和特征值，再进行读写或开启通知；断开连接后需重新连接并重新发现服务与特征值。
+
+:::
+
+## 模块介绍
+
+蓝牙低功耗（BLE）中心设备相关接口，用于与蓝牙设备建立连接、发现其服务与特征值，并对特征值进行读写、订阅通知等操作。
+
+- **服务**：设备对外提供的一组功能，由 UUID 标识，可包含一个或多个特征值；
+- **特征值**：服务下的数据点，由 UUID 标识，其 `properties` 描述支持的操作，如 read、write、notify、indicate 等；
+- **UUID**：用于标识服务和特征值。调用接口时，使用 uni.getBLEDeviceServices 和 uni.getBLEDeviceCharacteristics 返回的 UUID。
+
+本文负责连接与数据通信，[蓝牙-通用](./bluetooth-general.md)负责适配器管理与设备发现。各接口及参数的支持范围以对应的兼容性表为准。
+
+## 使用流程
+
+<a href="../static/bluetooth-le-central-flow.svg" target="_blank" rel="noopener"><img src="../static/bluetooth-le-central-flow.svg" alt="BLE 中心设备流程：连接设备、发现服务和特征值、按属性收发数据并清理连接" width="400"></a>
+
+1. 注册 [uni.onBLEConnectionStateChange](#onbleconnectionstatechange) 和 [uni.onBLECharacteristicValueChange](#onblecharacteristicvaluechange)，分别接收连接状态变化和特征值数据。
+2. 使用扫描返回的 `deviceId`，调用 [uni.createBLEConnection](#createbleconnection) 连接目标设备。
+3. 连接成功后，调用 [uni.getBLEDeviceServices](#getbledeviceservices) 发现服务，再调用 [uni.getBLEDeviceCharacteristics](#getbledevicecharacteristics) 获取目标服务的特征值及其属性。
+4. 按特征值属性调用 [uni.readBLECharacteristicValue](#readblecharacteristicvalue) 或 [uni.writeBLECharacteristicValue](#writeblecharacteristicvalue)。调用 `readBLECharacteristicValue` 前需先注册 `onBLECharacteristicValueChange`，读取结果通过该事件的 `value` 返回；读取不要求先开启通知。
+5. 如需接收外设主动发送的数据，调用 [uni.notifyBLECharacteristicValueChange](#notifyblecharacteristicvaluechange) 开启通知，通过已注册的特征值变化事件监听接收数据。
+6. 按需调用 [uni.getBLEDeviceRSSI](#getbledevicerssi) 获取信号强度；iOS 写入长度与 MTU 的说明见 [uni.getBLEMTU](#getblemtu) 和 [uni.setBLEMTU](#setblemtu)。
+7. 不再需要通知时将其关闭；通信结束后调用 [uni.closeBLEConnection](#closebleconnection)，并移除当前页面或组件注册的事件监听。
+
+## 权限@permission
+
+蓝牙权限与[蓝牙-通用](./bluetooth-general.md#permission)一致，请先按该页完成各端权限配置。
+
+## 注意事项@tips
+
+### 通用
+
+- **以特征值属性为准**：读、写和通知分别要求特征值支持对应的操作；支持读取不代表支持通知或写入。
+- **重新连接后重新发现**：断线重连后，应重新获取服务与特征值，并按需开启通知，不要直接沿用上次连接的结果。
+- **区分通知与事件监听**：关闭外设通知需调用 `notifyBLECharacteristicValueChange` 并传入 `state: false`；`offBLECharacteristicValueChange` 只移除事件监听，不能代替关闭通知。
+- **按监听所属范围清理**：不再使用时移除自身注册的特征值和连接状态监听。当前 iOS 插件可保存 `on*` 返回的监听 ID，并将该 ID 传给对应的 `off*`，避免清空其他页面的监听。
+- **控制写入长度与时序**：单次写入长度由平台和当前连接决定，超长数据需由业务分包；同一连接上的读写与通知配置操作宜按完成回调依次执行。
+
+
+<!-- UTSAPIJSON.createBLEConnection.name -->
+
+<!-- UTSAPIJSON.createBLEConnection.description -->
+
+<!-- UTSAPIJSON.createBLEConnection.compatibility -->
+
+<!-- UTSAPIJSON.createBLEConnection.param -->
+
+<!-- UTSAPIJSON.createBLEConnection.fileFormats -->
+
+<!-- UTSAPIJSON.createBLEConnection.returnValue -->
+
+<!-- UTSAPIJSON.createBLEConnection.example -->
+
+<!-- UTSAPIJSON.createBLEConnection.tutorial -->
+
+### iOS 使用说明
+
+- 先初始化适配器并扫描到目标设备，再传入扫描返回的 `deviceId`。能扫描到设备只表示收到了广播，不保证外设当前接受连接。
+- 先注册 `onBLEConnectionStateChange`，再发起连接。同一设备不要并行调用多次 `createBLEConnection`，避免重复连接导致失败。
+- 在 `success` 回调后调用 `getBLEDeviceServices` 和 `getBLEDeviceCharacteristics`，再开始读写或开启通知。连接成功不代表服务发现、特征值发现或业务认证已完成。
+- `timeout` 的单位是毫秒，应设置为大于 0 的数值，并结合真机耗时确定。当前 iOS 插件不传时不设置连接超时期限，但仍可能因系统报告失败或适配器状态变化而结束。
+- 当前 iOS 插件对已经连接的设备再次调用连接会返回成功。
+
+### iOS 连接失败与超时排查 @ios-connection-troubleshooting
+
+`createBLEConnection` 失败时，先确认适配器已初始化且可用，并使用扫描返回的 `deviceId`。连接成功后的服务发现、读写和通知问题，应按对应接口排查。
+
+连接超时表示未在指定时间内完成连接，不代表设备已关机或停止广播；等待上一次断开完成也可能超时。能扫描到设备，不代表设备当前接受连接。
+
+可按以下方向排查：
+
+| 可能原因 | 检查与处理方式 |
+| --- | --- |
+| 信号弱或干扰 | 靠近外设，在干扰较少的环境中重试。 |
+| 外设被占用或不可连接 | 断开其他手机、App 或调试工具的连接，确认外设处于可连接模式。 |
+| 重复连接或断开未完成 | 同一设备只保留一个连接流程，避免并行连接或立即反复重连。 |
+| 超时时间过短 | 结合正常连接耗时，适当增加 `timeout` 后对比。 |
+| 外设重启或配对信息变化 | 重新扫描；若提示配对异常，按设备说明重新配对。持续失败时检查外设日志。 |
+| 连接过多或系统暂不可用 | 关闭不必要的连接和扫描，通过 `onBluetoothAdapterStateChange` 确认可用后再试。 |
+
+重试应设置间隔和次数上限，持续失败时提示用户检查设备。重连成功后，需重新发现服务和特征值，并按需开启通知。仍无法定位时，可按[调试建议](#调试建议)使用蓝牙工具对照验证。
+
+
+<!-- UTSAPIJSON.closeBLEConnection.name -->
+
+<!-- UTSAPIJSON.closeBLEConnection.description -->
+
+<!-- UTSAPIJSON.closeBLEConnection.compatibility -->
+
+<!-- UTSAPIJSON.closeBLEConnection.param -->
+
+<!-- UTSAPIJSON.closeBLEConnection.fileFormats -->
+
+<!-- UTSAPIJSON.closeBLEConnection.returnValue -->
+
+<!-- UTSAPIJSON.closeBLEConnection.example -->
+
+<!-- UTSAPIJSON.closeBLEConnection.tutorial -->
+
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.name -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.description -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.compatibility -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.param -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.returnValue -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.example -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.name -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.description -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.compatibility -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.param -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.returnValue -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.example -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.name -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.description -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.compatibility -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.param -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.returnValue -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.example -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEMTU.name -->
+
+<!-- UTSAPIJSON.getBLEMTU.description -->
+
+<!-- UTSAPIJSON.getBLEMTU.compatibility -->
+
+<!-- UTSAPIJSON.getBLEMTU.param -->
+
+<!-- UTSAPIJSON.getBLEMTU.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEMTU.returnValue -->
+
+<!-- UTSAPIJSON.getBLEMTU.example -->
+
+<!-- UTSAPIJSON.getBLEMTU.tutorial -->
+
+### iOS 注意事项
+
+- 当前 iOS 插件返回的 `mtu` 是指定 `writeType` 对应的最大可写数据长度，单位为字节，不是 ATT MTU；不传 `writeType` 时按 `write` 查询。
+- 直接以返回值作为该写模式的单次写入长度上限，无需再减 3，也不能通过加 3 推算 ATT MTU。查询时的 `writeType` 应与实际写入时一致。
+- 返回的长度上限不代表外设业务协议支持任意长度的数据，分包还需遵循设备协议。
+
+
+<!-- UTSAPIJSON.setBLEMTU.name -->
+
+<!-- UTSAPIJSON.setBLEMTU.description -->
+
+<!-- UTSAPIJSON.setBLEMTU.compatibility -->
+
+<!-- UTSAPIJSON.setBLEMTU.param -->
+
+<!-- UTSAPIJSON.setBLEMTU.fileFormats -->
+
+<!-- UTSAPIJSON.setBLEMTU.returnValue -->
+
+<!-- UTSAPIJSON.setBLEMTU.example -->
+
+<!-- UTSAPIJSON.setBLEMTU.tutorial -->
+
+### iOS 注意事项
+
+iOS 不支持主动设置 MTU，当前插件调用此接口会执行 `fail` 和 `complete`，返回不支持错误。写入前可通过 `getBLEMTU` 查询对应写模式的最大可写长度。
+
+
+<!-- UTSAPIJSON.onBLEMTUChange.name -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.description -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.compatibility -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.param -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.returnValue -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.example -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBLEMTUChange.name -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.description -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.compatibility -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.param -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.returnValue -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.example -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEDeviceServices.name -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.description -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.compatibility -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.param -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.returnValue -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.example -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.name -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.description -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.compatibility -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.param -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.returnValue -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.example -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.tutorial -->
+
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.name -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.description -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.compatibility -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.param -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.fileFormats -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.returnValue -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.example -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.tutorial -->
+
+### 注意事项
+
+- 先注册 `onBLECharacteristicValueChange`，再发起读取。读取结果通过该事件的 `value` 返回，`readBLECharacteristicValue` 的成功回调不包含特征值数据。
+- 主动读取要求特征值支持 `read`，无需先调用 `notifyBLECharacteristicValueChange` 开启通知。
+- 多设备或多特征值共用事件监听时，应按事件中的 `deviceId`、`serviceId` 和 `characteristicId` 匹配数据来源。
+
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.name -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.description -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.compatibility -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.param -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.fileFormats -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.returnValue -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.example -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.tutorial -->
+
+### 注意事项
+
+- 应根据特征值属性选择 `writeType`：`write` 为有响应写，`writeNoResponse` 为无响应写。当前 iOS 插件不传时使用 `write`，不会因特征值只支持无响应写而自动切换；此时需显式传入 `writeNoResponse`。
+- 当前 iOS 插件不会自动分包。超过单次写入长度上限时，会调用 `fail` 和 `complete`，需按长度上限与设备协议自行分包，详见 [getBLEMTU 的 iOS 注意事项](#getblemtu)。
+- 无响应写缺少外设对本次写入的协议层确认。若业务需要确认设备已接收或处理数据，应设计应用层应答机制。
+
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.name -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.description -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.compatibility -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.param -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.fileFormats -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.returnValue -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.example -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.tutorial -->
+
+### 注意事项
+
+- 先注册 `onBLECharacteristicValueChange`，再传入 `state: true` 开启通知；特征值需支持 `notify` 或 `indicate`。
+- 开启成功表示通知配置完成，不代表外设会立即发送数据；是否上报、何时上报由设备协议决定。
+- 不再需要通知时传入 `state: false`。断线重连后如需继续接收通知，应重新发现服务和特征值并再次开启通知。
+
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.name -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.description -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.compatibility -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.param -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.returnValue -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.example -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.name -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.description -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.compatibility -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.param -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.returnValue -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.example -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.tutorial -->
+
+
+<!-- UTSAPIJSON.ble.example -->
+
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->