1241 lines
34 KiB
Markdown
1241 lines
34 KiB
Markdown
# android-ble
|
||
|
||
`android-ble` 是一个面向 `uni-app` / `uni-app x` 的 BLE 低功耗蓝牙插件，支持 Android、iOS、鸿蒙、微信小程序。
|
||
|
||
插件市场相关资源：
|
||
|
||
- BLE 插件：`android-ble` 支付多端 安卓 ios 鸿蒙 微信小程序
|
||
- 经典蓝牙 SPP 插件：[安卓Spp经典蓝牙插件](https://ext.dcloud.net.cn/plugin?id=26830)
|
||
- Ble服务端插件[Android ble低功耗蓝牙周边服务蓝牙服务端](https://ext.dcloud.net.cn/plugin?id=22510)
|
||
- `uni-app` 示例工程压缩包：`bt_uniapp.zip`
|
||
- `uni-app x` 示例页面：`App.uvue`、`pages/Multi/Multi.uvue`
|
||
|
||
## 功能概览
|
||
|
||
- 支持 BLE 扫描、停止扫描、扫描结果过滤
|
||
- 支持连接、断开、自动重连、连接超时设置
|
||
- 支持扫描服务与特征值、自动识别可写/可通知 UUID
|
||
- 支持通知订阅、indicate 订阅、主动读取、RSSI 读取、MTU 设置
|
||
- 支持十六进制字符串、数字数组、`ArrayBuffer` 写入
|
||
- 支持分包发送
|
||
- 支持多蓝牙连接场景
|
||
- iOS 支持按服务 UUID 获取系统已连接设备，并接管到当前 `BleLib` 实例
|
||
- 支持监听系统蓝牙开关状态
|
||
|
||
## 平台支持
|
||
|
||
| 平台 | 支持情况 |
|
||
| --- | --- |
|
||
| uni-app Android | 支持 |
|
||
| uni-app iOS | 支持 |
|
||
| uni-app 鸿蒙 | 支持 |
|
||
| uni-app 微信小程序 | 支持 |
|
||
| uni-app x Android | 支持 |
|
||
| uni-app x iOS | 支持 |
|
||
| uni-app x 鸿蒙 | 支持 |
|
||
| uni-app x 微信小程序 | 支持 |
|
||
| Web | 不支持 |
|
||
|
||
补充说明：
|
||
|
||
- iOS 需 `iOS 13` 及以上版本。
|
||
- Android / iOS / 鸿蒙运行原生能力时，建议使用自定义基座验证。
|
||
- 微信小程序端按 `BleLib` 实例维护连接状态，适合一个对象对应一个蓝牙连接。
|
||
- `getConnectedDevicesWithServices` 与 `redictToConnect` 是 iOS 专属方法，只有 iOS 可以调用，Android、鸿蒙、微信小程序、Web 都不支持调用。
|
||
|
||
## 安装与运行
|
||
|
||
### 插件试用与下载
|
||
|
||
1. 在插件市场选择试用，并绑定目标项目 `appid`。
|
||
2. 下载插件到本地项目。
|
||
3. 在页面中从 `@/uni_modules/android-ble` 引入 `BleLib` 与相关类型。
|
||
|
||
## 快速上手
|
||
|
||
本节用于帮助开发者快速跑通 BLE 标准流程，下面给出 `uni-app x` 与 `uni-app` 双端示例。
|
||
|
||
### 最短接入步骤
|
||
|
||
1. 引入 `BleLib`，创建蓝牙对象实例。
|
||
2. 调用 `openBtBluetooth` 初始化蓝牙适配器。
|
||
3. 调用 `onStartScanBle` 开始扫描设备。
|
||
4. 拿到目标设备地址后调用 `connect`。
|
||
5. 连接成功后调用 `scanServices`。
|
||
6. 调用 `getUUIDs` 查看自动识别出的可用 UUID 组合。
|
||
7. 必要时调用 `setSelectUUID` 切换到目标 `service/notify/write` 组合。
|
||
8. 调用 `onNotityBleData` 开启通知，或调用 `onIndicate` 开启 indicate 订阅。
|
||
9. 调用 `sendData` 发送数据。
|
||
10. 结束时调用 `close` 断开连接。
|
||
|
||
### `uni-app x` 快速上手
|
||
|
||
```ts
|
||
import { BleLib, MyApiResult, BleScanResult, WNuuid, WriteData, NotityData, ScanPara } from "@/uni_modules/android-ble"
|
||
|
||
let lib = new BleLib()
|
||
let firstMac = ""
|
||
|
||
lib.openBtBluetooth(function(res:MyApiResult){
|
||
console.log("openBtBluetooth", res)
|
||
})
|
||
|
||
lib.onBtOpenStateListener(function(res:MyApiResult){
|
||
console.log("bt state", res)
|
||
})
|
||
|
||
let scanPara:ScanPara = {
|
||
scantime:10 * 1000,
|
||
showEmptyName:0,
|
||
btNameFilter:"",
|
||
onScanResult:function(res:MyApiResult){
|
||
// type 为0 扫描成功 10001 表示无蓝牙权限 10002 表示蓝牙未开启
|
||
if(res.type == 0){
|
||
let scan = res.data as BleScanResult
|
||
console.log("scan", scan)
|
||
if(firstMac == ""){
|
||
firstMac = scan.device.address
|
||
}
|
||
}
|
||
},
|
||
scanComplate:function(){
|
||
console.log("scan complete")
|
||
if(firstMac != ""){
|
||
lib.connect(firstMac,false,function(res:MyApiResult){
|
||
console.log("connect", res)
|
||
// type 0 成功 10000 蓝牙连接失败 10001 蓝牙异常断开 10002 表示蓝牙未开启 10003表示无蓝牙权限 10004 表示蓝牙已经连接 10005 鸿蒙虚拟蓝牙地址无效
|
||
if(res.type == 0){
|
||
lib.scanServices(function(serviceRes:MyApiResult){
|
||
console.log("services", serviceRes)
|
||
if(serviceRes.type == 0){
|
||
let uuidList = lib.getUUIDs() as WNuuid[]
|
||
console.log("uuidList", uuidList)
|
||
let uuids = lib.getUUIDs()
|
||
console.log("uuids", uuids)
|
||
if(uuids.length > 0){
|
||
lib.setSelectUUID(0)
|
||
lib.onNotityBleData(
|
||
lib.getServiceUUID(),
|
||
lib.getNotityUUID(),
|
||
true,
|
||
function(notifyRes:MyApiResult){
|
||
// type 为0 表示通知数据 1000 表示订阅成功 1001 表示订阅失败
|
||
if(notifyRes.type == 0){
|
||
let data = notifyRes.data as NotityData
|
||
console.log("notify", data)
|
||
}
|
||
}
|
||
)
|
||
let writeData:WriteData = {
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
hexStrData:"FF001122"
|
||
}
|
||
lib.sendData(writeData,function(sendRes:MyApiResult){
|
||
console.log("send", sendRes)
|
||
})
|
||
let readData:WriteData = {
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
data:[0xff,0x00,0x11,0x22] as number[]
|
||
}
|
||
lib.sendData(readData,function(sendRes:MyApiResult){
|
||
console.log("send", sendRes)
|
||
})
|
||
}
|
||
}
|
||
})
|
||
}
|
||
})
|
||
}
|
||
}
|
||
}
|
||
|
||
lib.onStartScanBle(scanPara)
|
||
```
|
||
|
||
### `uni-app` 快速上手
|
||
|
||
```js
|
||
import { BleLib } from "@/uni_modules/android-ble"
|
||
|
||
var lib = new BleLib()
|
||
var firstMac = ""
|
||
|
||
lib.openBtBluetooth(function(res){
|
||
console.log("openBtBluetooth", res)
|
||
})
|
||
|
||
lib.onBtOpenStateListener(function(res){
|
||
console.log("bt state", res)
|
||
})
|
||
|
||
lib.onStartScanBle({
|
||
scantime:10 * 1000,
|
||
showEmptyName:0,
|
||
btNameFilter:"",
|
||
onScanResult:function(res){
|
||
// type 为0 扫描成功 10001 表示无蓝牙权限 10002 表示蓝牙未开启
|
||
if(res.type == 0){
|
||
var scan = res.data
|
||
console.log("scan", scan)
|
||
if(firstMac == ""){
|
||
firstMac = scan.device.address
|
||
}
|
||
}
|
||
},
|
||
scanComplate:function(){
|
||
console.log("scan complete")
|
||
if(firstMac != ""){
|
||
lib.connect(firstMac,false,function(res){
|
||
console.log("connect", res)
|
||
// type 0 成功 10000 蓝牙连接失败 10001 蓝牙异常断开 10002 表示蓝牙未开启 10003表示无蓝牙权限 10004 表示蓝牙已经连接 10005 鸿蒙虚拟蓝牙地址无效
|
||
if(res.type == 0){
|
||
lib.scanServices(function(serviceRes){
|
||
console.log("services", serviceRes)
|
||
var uuids = lib.getUUIDs()
|
||
console.log("uuids", uuids)
|
||
if(uuids.length > 0){
|
||
lib.setSelectUUID(0)
|
||
lib.onNotityBleData(
|
||
lib.getServiceUUID(),
|
||
lib.getNotityUUID(),
|
||
true,
|
||
function(notifyRes){
|
||
// type 为0 表示通知数据 1000 表示订阅成功 1001 表示订阅失败
|
||
console.log("notify", notifyRes)
|
||
}
|
||
)
|
||
lib.sendData({
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
hexStrData:"FF001122"
|
||
},function(sendRes){
|
||
console.log("send", sendRes)
|
||
})
|
||
}
|
||
})
|
||
}
|
||
})
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
### 自定义基座
|
||
|
||
1. 在 HBuilderX 中执行云打包并制作自定义基座。
|
||
2. 基座制作完成后，运行到手机或模拟器。
|
||
3. 选择运行到 Android App 基座，并选择自定义基座。
|
||
4. 如果之前安装过旧基座，请先卸载旧版本后再安装。
|
||
|
||
### iOS 蓝牙权限配置
|
||
|
||
iOS 端除了引入插件，还需要在项目 `manifest.json` 的 `app-ios.distribute.privacyDescription` 中配置蓝牙用途说明，否则首次访问蓝牙时可能不弹权限框，系统设置里也不会出现应用的蓝牙权限开关。
|
||
|
||
参考配置：
|
||
|
||
```json
|
||
{
|
||
"app-ios": {
|
||
"distribute": {
|
||
"privacyDescription": {
|
||
"NSBluetoothAlwaysUsageDescription": "应用需要使用蓝牙扫描、连接和通信外设设备",
|
||
"NSBluetoothPeripheralUsageDescription": "应用需要使用蓝牙扫描、连接和通信外设设备"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 修改后需要重新云打包或重新生成 iOS 安装包才会生效。
|
||
- 建议卸载旧包后再安装新包。
|
||
- iOS 一般在首次扫描、连接等真正访问蓝牙时弹权限框，不一定在应用启动瞬间弹出。
|
||
|
||
## 推荐调用流程
|
||
|
||
建议按下面顺序接入：
|
||
|
||
1. 创建 `BleLib` 实例。
|
||
2. 调用 `openBtBluetooth` 初始化蓝牙适配器。
|
||
3. 可选：调用 `onBtOpenStateListener` 监听系统蓝牙开关状态。
|
||
4. 调用 `onStartScanBle` 或 `startScanBleDevice` 扫描设备。
|
||
5. 拿到设备地址后调用 `connect` 连接。
|
||
6. 连接成功后调用 `scanServices` 扫描服务。
|
||
7. 通过 `getUUIDs` 获取自动识别出的可用服务组合，必要时调用 `setSelectUUID` 切换。
|
||
8. 调用 `onNotityBleData` 开启通知。
|
||
9. 调用 `sendData` 发送数据，或调用 `onReadData` 主动读取。
|
||
10. 完成后调用 `close` 断开连接。
|
||
|
||
iOS 已连接设备恢复场景：
|
||
|
||
- 先调用 `getConnectedDevicesWithServices` 按服务 UUID 获取系统当前已连接设备。
|
||
- 再把返回结果中的 `device.address` 传给 `redictToConnect`，让当前 `BleLib` 实例接管连接。
|
||
|
||
多设备场景建议：
|
||
|
||
- 每个蓝牙连接使用一个独立的 `BleLib` 实例。
|
||
- 可参考 `pages/Multi/Multi.uvue` 的多连接演示页面。
|
||
|
||
## 主要类型
|
||
|
||
### `ScanPara`
|
||
|
||
扫描参数，常用字段如下：
|
||
|
||
- `btNameFilter`：按名称关键字过滤
|
||
- `fliterNames`：按多个名称前缀过滤
|
||
- `scantime`：扫描时长，单位毫秒
|
||
- `showEmptyName`：是否返回空名称设备，`0` 表示不返回，`1` 表示返回
|
||
- `iosFilterUUIDs`：按 service UUID 数组过滤扫描，当前支持 iOS、Android、鸿蒙、微信小程序
|
||
- `onScanResult`：扫描结果回调
|
||
- `scanComplate`：扫描结束回调
|
||
|
||
### `WNuuid`
|
||
|
||
自动识别出的可用服务组合：
|
||
|
||
- `serviceId`
|
||
- `wuuid`
|
||
- `nuuid`
|
||
|
||
### `WriteData`
|
||
|
||
写入参数：
|
||
|
||
- `serviceId`：服务 UUID
|
||
- `characteristicId`：写入特征 UUID
|
||
- `writeType`：写入类型，`0` 为 `WRITE`，`1` 为 `WRITE_NO_RESPONSE`
|
||
- `buffer`：原始二进制数据，优先级最高
|
||
- `data`：数字数组
|
||
- `hexStrData`：十六进制字符串
|
||
- `fenbao`：是否自动分包发送
|
||
|
||
写入优先级：`buffer` > `data` > `hexStrData`
|
||
|
||
### `MyApiResult`
|
||
|
||
统一回调结构：
|
||
|
||
- `type`：状态码
|
||
- `message`：状态说明
|
||
- `data`：返回数据
|
||
|
||
### `NotityData`
|
||
|
||
通知 / indicate / 读取回调数据结构：
|
||
|
||
- `data`：字节数组
|
||
- `mac`：设备地址，部分平台返回
|
||
- `serviceId`：服务 UUID
|
||
- `characteristicsId`：特征 UUID
|
||
|
||
## API 清单
|
||
|
||
### 适配器与状态
|
||
|
||
- `isEnabled`：检测蓝牙是否开启
|
||
- `openBtBluetooth`：初始化蓝牙适配器
|
||
- `openBluetooth`：打开或关闭蓝牙
|
||
- `openBluetoothSettings`：打开蓝牙设置页
|
||
- `onBtOpenStateListener`：监听系统蓝牙开关状态
|
||
|
||
### 扫描相关
|
||
|
||
- `onStartScanBle`：新版扫描接口，推荐使用
|
||
- `startScanBleDevice`：旧版扫描接口，兼容保留
|
||
- `onScanDataListener`：监听广播信号变化
|
||
- `stopScanBle`：停止扫描
|
||
|
||
### 连接相关
|
||
|
||
- `connect`：连接蓝牙
|
||
- `close`：断开蓝牙
|
||
- `isConnected`：是否已连接
|
||
- `getConnectMac`：获取当前已连接设备地址
|
||
- `setBtConnectTimeout`：设置连接超时时间
|
||
- `setBtAutoConnectTime`：设置自动连接间隔
|
||
- `cancelAutoConnectBt`：取消自动重连
|
||
|
||
### iOS 专属连接恢复
|
||
|
||
- 本小节两个方法只有 iOS 可以调用，其他平台都不支持。
|
||
|
||
- `getConnectedDevicesWithServices`：按服务 UUID 获取系统当前已连接设备
|
||
- `redictToConnect`：接管 `getConnectedDevicesWithServices` 返回的已连接设备
|
||
|
||
### 服务与特征值
|
||
|
||
- `scanServices`：扫描当前连接设备的服务与特征值
|
||
- `getUUIDs`：获取自动识别出的可用 `service + notify + write` 组合
|
||
- `setSelectUUID`：切换当前使用的 UUID 组合
|
||
- `getSericUUID`：获取当前服务 UUID，旧命名，兼容保留
|
||
- `getServiceUUID`：获取当前服务 UUID
|
||
- `getNotityUUID`：获取当前通知 UUID
|
||
- `getWriteUUID`：获取当前写入 UUID
|
||
- `getwriteUUID`：获取当前写入 UUID，旧命名，兼容保留
|
||
|
||
### 数据通信
|
||
|
||
- `onNotityBleData`：开启或关闭通知订阅
|
||
- `onIndicate`：开启 indicate 订阅并监听设备主动上报数据
|
||
- `onReadData`：主动读取蓝牙数据
|
||
- `sendData`：写入数据，支持字符串、数组、`ArrayBuffer`
|
||
- `readRssi`：读取 RSSI
|
||
- `setMtu`：设置 MTU，仅 Android 有效
|
||
- `setPhy2MMode`：设置 Android PHY 2M 模式，仅 Android 有效
|
||
|
||
### 调试与线程
|
||
|
||
- `setDebugMode`：打开调试日志
|
||
- `setThreadTypeName`：设置回调线程名
|
||
|
||
## 方法说明与调用示例
|
||
|
||
本节按方法逐个列出用途、参数、返回值与调用示例，并同时给出 `uni-app x` 与 `uni-app` 参考写法。
|
||
|
||
### `isEnabled`
|
||
|
||
- 用途：检测当前系统蓝牙是否处于开启状态。
|
||
- 参数：无。
|
||
- 返回：`boolean`。
|
||
- 常见场景：进入页面后先判断是否需要提示用户开蓝牙。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
var open = lib.isEnabled()
|
||
console.log(open)
|
||
```
|
||
|
||
### `openBtBluetooth`
|
||
|
||
- 用途：初始化蓝牙适配器，并触发回调告知初始化结果。
|
||
- 参数：`callback`。
|
||
- 返回：无，结果通过回调返回。
|
||
- iOS 说明：iOS 端该方法主要用于初始化和检查蓝牙状态，不会像 Android 一样主动打开系统蓝牙。
|
||
- iOS 回调说明：`type=0` 表示蓝牙已开启，`type=10002` 表示系统蓝牙未开启，`type=10003` 表示蓝牙权限被拒绝、受限或待确认。
|
||
- 常见场景：扫描和连接前先调用一次。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.openBtBluetooth(function(res:MyApiResult){
|
||
// type 为0 表示初始化成功 其它值可结合 message 查看失败原因
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.openBtBluetooth(function(res){
|
||
// type 为0 表示初始化成功 其它值可结合 message 查看失败原因
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `openBluetooth`
|
||
|
||
- 用途：按布尔值控制打开或关闭蓝牙。
|
||
- 参数：`on:boolean`。
|
||
- 返回：无。
|
||
- 常见场景：Android 或小程序场景下快捷控制蓝牙状态。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.openBluetooth(true)
|
||
lib.openBluetooth(false)
|
||
```
|
||
|
||
### `openBluetoothSettings`
|
||
|
||
- 用途：跳转到系统蓝牙相关设置页。
|
||
- 参数：无。
|
||
- 返回：无。
|
||
- iOS 说明：iOS 端会跳转到当前应用的系统设置页，适合在用户拒绝蓝牙权限后引导其手动开启。
|
||
- 常见场景：蓝牙关闭且需要引导用户手动开启时使用。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.openBluetoothSettings()
|
||
```
|
||
|
||
- 推荐搭配 `openBtBluetooth` 使用
|
||
|
||
```js
|
||
lib.openBtBluetooth(function(res){
|
||
if(res.type == 10003){
|
||
// iOS 用户拒绝蓝牙权限后，可引导用户跳转系统设置手动开启
|
||
lib.openBluetoothSettings()
|
||
}
|
||
})
|
||
```
|
||
|
||
### `onBtOpenStateListener`
|
||
|
||
- 用途：监听系统蓝牙开关状态变化。
|
||
- 参数：`callback`。
|
||
- 返回：无，结果通过回调返回。
|
||
- 常见场景：页面常驻监听蓝牙状态变化。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.onBtOpenStateListener(function(res:MyApiResult){
|
||
// data 为 true 表示蓝牙开启 false 表示蓝牙关闭
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.onBtOpenStateListener(function(res){
|
||
// data 为 true 表示蓝牙开启 false 表示蓝牙关闭
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `onStartScanBle`
|
||
|
||
- 用途：新版 BLE 扫描接口，支持过滤条件与扫描完成回调。
|
||
- 参数：`ScanPara`。
|
||
- 返回：无，扫描结果通过 `onScanResult` 返回。
|
||
- 常见场景：绝大多数新项目建议优先使用该接口。
|
||
- 补充说明：如需按服务 UUID 过滤扫描结果，可通过 `iosFilterUUIDs` 传入 UUID 数组，当前支持 iOS、Android、鸿蒙、微信小程序。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
let scanPara:ScanPara = {
|
||
scantime:10 * 1000,
|
||
showEmptyName:0,
|
||
btNameFilter:"",
|
||
onScanResult:function(res:MyApiResult){
|
||
// type 为0 扫描成功 10001 表示无蓝牙权限 10002 表示蓝牙未开启
|
||
if(res.type == 0){
|
||
let scan = res.data as BleScanResult
|
||
console.log(scan)
|
||
}
|
||
},
|
||
scanComplate:function(){
|
||
console.log("scan complete")
|
||
}
|
||
} as ScanPara
|
||
lib.onStartScanBle(scanPara)
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.onStartScanBle({
|
||
scantime:10 * 1000,
|
||
showEmptyName:0,
|
||
btNameFilter:"",
|
||
onScanResult:function(res){
|
||
// type 为0 扫描成功 10001 表示无蓝牙权限 10002 表示蓝牙未开启
|
||
if(res.type == 0){
|
||
var scan = res.data
|
||
console.log(scan)
|
||
}
|
||
},
|
||
scanComplate:function(){
|
||
console.log("scan complete")
|
||
}
|
||
})
|
||
```
|
||
|
||
### `startScanBleDevice`
|
||
|
||
- 用途：旧版扫描接口，保留给旧项目兼容使用。
|
||
- 参数：扫描时长、回调函数。
|
||
- 返回：无，结果通过回调返回。
|
||
- 常见场景：已有老代码迁移成本较高时继续使用。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.startScanBleDevice(15000,function(res:MyApiResult){
|
||
// type 为0 扫描成功 10001 表示无蓝牙权限 10002 表示蓝牙未开启
|
||
if(res.type == 0){
|
||
let scan = res.data as BleScanResult
|
||
console.log(scan)
|
||
}
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.startScanBleDevice(15000,function(res){
|
||
// type 为0 扫描成功 10001 表示无蓝牙权限 10002 表示蓝牙未开启
|
||
if(res.type == 0){
|
||
var scan = res.data
|
||
console.log(scan)
|
||
}
|
||
})
|
||
```
|
||
|
||
### `onScanDataListener`
|
||
|
||
- 用途：实时监听扫描过程中的广播变化与 RSSI 数据。
|
||
- 参数：`callback`。
|
||
- 返回：无，数据通过回调返回。
|
||
- 常见场景：需要显示信号强度变化或原始广播数据。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.onScanDataListener(function(res:MyApiResult){
|
||
let data = res.data as ScanRssiBR
|
||
console.log(data)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.onScanDataListener(function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `stopScanBle`
|
||
|
||
- 用途：停止当前 BLE 扫描。
|
||
- 参数：无。
|
||
- 返回：无。
|
||
- 常见场景：页面离开、用户手动停止扫描、连接前停止扫描。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.stopScanBle()
|
||
```
|
||
|
||
### `connect`
|
||
|
||
- 用途：连接指定蓝牙设备。
|
||
- 参数：设备地址、是否自动连接、回调函数。
|
||
- 返回：无，结果通过回调返回。
|
||
- 回调 `type` 说明：`0` 成功，`10000` 蓝牙连接失败，`10001` 蓝牙异常断开，`10002` 表示蓝牙未开启，`10003` 表示无蓝牙权限，`10004` 表示蓝牙已经连接，`10005` 表示鸿蒙虚拟蓝牙地址无效。
|
||
- 常见场景：用户点击扫描结果后发起连接。
|
||
- iOS 说明：若你希望控制应用退到后台后，连接成功、连接断开、收到通知时系统是否弹出唤回应用提示，请在 `connect` 前先调用 `setIOSConnectNotifyAlertEnabled`。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.connect(device.device.address,false,function(res:MyApiResult){
|
||
console.log(res)
|
||
// type 0 成功 10000 蓝牙连接失败 10001 蓝牙异常断开 10002 表示蓝牙未开启 10003表示无蓝牙权限 10004 表示蓝牙已经连接 10005 鸿蒙虚拟蓝牙地址无效
|
||
if(res.type == 0){
|
||
|
||
}else{
|
||
|
||
}
|
||
})
|
||
```
|
||
|
||
### `getConnectedDevicesWithServices`
|
||
|
||
- 用途：按服务 UUID 查询 iOS 系统当前已经连接的 BLE 外设。
|
||
- 参数：`string[]`，传入目标设备对应的服务 UUID 数组。
|
||
- 返回：`MyApiResult`，`data` 为 `BleScanResult[]`。
|
||
- 平台说明：只有 iOS 可以调用；Android、鸿蒙、微信小程序、Web 都不支持该方法。
|
||
- 返回说明：返回结果中的 `device.address` 为 iOS 外设标识 `identifier.uuidString`，后续需要原样传给 `redictToConnect`。
|
||
- 常见场景：App 重启后恢复已连接设备、需要接管系统层已保持连接的外设。
|
||
- `uni-app x` / `uni-app`（仅 iOS）
|
||
|
||
```js
|
||
var serviceIds = ["FFF0"]
|
||
var res = lib.getConnectedDevicesWithServices(serviceIds)
|
||
console.log(res)
|
||
|
||
if(res.type == 0){
|
||
var list = res.data || []
|
||
if(list.length > 0){
|
||
console.log(list[0].device.address)
|
||
}
|
||
}
|
||
```
|
||
|
||
### `redictToConnect`
|
||
|
||
- 用途：把 `getConnectedDevicesWithServices` 查到的已连接 iOS 外设接管到当前 `BleLib` 实例。
|
||
- 参数：设备地址、回调函数。
|
||
- 返回：无，结果通过回调返回。
|
||
- 平台说明：只有 iOS 可以调用；Android、鸿蒙、微信小程序、Web 都不支持该方法。
|
||
- 调用前提：必须先调用 `getConnectedDevicesWithServices`，并使用其返回结果中的 `device.address` 作为第一个参数。
|
||
- 回调 `type` 说明：`0` 表示接管成功，`10001` 表示设备已断开。
|
||
- 常见场景：业务层拿到系统已连接设备后，继续调用 `scanServices`、`onNotityBleData`、`sendData` 等插件能力。
|
||
- `uni-app x` / `uni-app`（仅 iOS）
|
||
|
||
```js
|
||
var res = lib.getConnectedDevicesWithServices(["FFF0"])
|
||
if(res.type == 0){
|
||
var list = res.data || []
|
||
if(list.length > 0){
|
||
var deviceId = list[0].device.address
|
||
lib.redictToConnect(deviceId,function(connectRes){
|
||
console.log(connectRes)
|
||
if(connectRes.type == 0){
|
||
lib.scanServices(function(serviceRes){
|
||
console.log(serviceRes)
|
||
})
|
||
}
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
### `setIOSConnectNotifyAlertEnabled`
|
||
|
||
- 用途：控制 iOS 端在应用进入后台后，连接成功、连接断开、收到通知时系统是否显示唤回应用提示。
|
||
- 参数：`enabled:boolean`。
|
||
- 返回：无。
|
||
- 默认值：`true`，即默认允许系统显示相关提示。
|
||
- 生效时机：必须在 `connect` 前调用；连接发起后再修改，不影响当前这次连接。
|
||
- 平台说明：仅 iOS 生效，Android、鸿蒙、微信小程序为空实现，用于保持多端调用一致。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setIOSConnectNotifyAlertEnabled(false)
|
||
lib.connect(device.device.address,false,function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.connect(device.device.address,false,function(res){
|
||
console.log(res)
|
||
// type 0 成功 10000 蓝牙连接失败 10001 蓝牙异常断开 10002 表示蓝牙未开启 10003表示无蓝牙权限 10004 表示蓝牙已经连接 10005 鸿蒙虚拟蓝牙地址无效
|
||
if(res.type == 0){
|
||
|
||
}else{
|
||
|
||
}
|
||
})
|
||
```
|
||
|
||
### `close`
|
||
|
||
- 用途：断开当前蓝牙连接并释放连接状态。
|
||
- 参数：无。
|
||
- 返回：无。
|
||
- 常见场景：页面卸载、切换设备、手动断开。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.close()
|
||
```
|
||
|
||
### `isConnected`
|
||
|
||
- 用途：判断当前对象是否已连接蓝牙设备。
|
||
- 参数：无。
|
||
- 返回：`boolean`。
|
||
- 常见场景：发送、读取、订阅前做前置判断。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
var isconnect = lib.isConnected()
|
||
console.log(isconnect)
|
||
```
|
||
|
||
### `getConnectMac`
|
||
|
||
- 用途：获取当前已连接设备地址。
|
||
- 参数：无。
|
||
- 返回：设备地址字符串，未连接时通常为空字符串。
|
||
- 常见场景：业务层记录当前连接目标。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
var deviceId = lib.getConnectMac()
|
||
console.log(deviceId)
|
||
```
|
||
|
||
### `setBtConnectTimeout`
|
||
|
||
- 用途：设置蓝牙连接超时时间。
|
||
- 参数：超时时间，单位毫秒。
|
||
- 返回：无。
|
||
- 常见场景：外设连接较慢，需要调整默认超时值。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setBtConnectTimeout(12000)
|
||
```
|
||
|
||
### `setBtAutoConnectTime`
|
||
|
||
- 用途：设置自动重连的时间间隔。
|
||
- 参数：时间间隔，单位毫秒。
|
||
- 返回：无。
|
||
- 常见场景：需要控制自动连接重试节奏时使用。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setBtAutoConnectTime(12000)
|
||
```
|
||
|
||
### `cancelAutoConnectBt`
|
||
|
||
- 用途：取消自动重连。
|
||
- 参数：无。
|
||
- 返回：无。
|
||
- 常见场景：用户主动退出当前连接流程。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.cancelAutoConnectBt()
|
||
```
|
||
|
||
### `scanServices`
|
||
|
||
- 用途：扫描当前连接设备的服务与特征值。
|
||
- 参数：回调函数。
|
||
- 返回：无，服务列表通过回调返回。
|
||
- 常见场景：连接成功后必须执行一次，供后续通知与写入使用。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.scanServices(function(resSevice:MyApiResult){
|
||
console.log(resSevice)
|
||
if(resSevice.type == 0){
|
||
let d = resSevice.data as BleServices[]
|
||
console.log(d)
|
||
}
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.scanServices(function(resSevice){
|
||
console.log(resSevice)
|
||
})
|
||
```
|
||
|
||
### `getUUIDs`
|
||
|
||
- 用途：获取插件自动识别出的可用 `service + notify + write` 组合列表。
|
||
- 参数：无。
|
||
- 返回：`WNuuid[]`。
|
||
- 常见场景：设备存在多个服务组合时供业务层选择。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
var uuids = lib.getUUIDs()
|
||
console.log(uuids)
|
||
```
|
||
|
||
### `setSelectUUID`
|
||
|
||
- 用途：切换当前使用的 UUID 组合。
|
||
- 参数：组合下标。
|
||
- 返回：无。
|
||
- 常见场景：自动识别到多组候选服务时手动切换。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setSelectUUID(0)
|
||
```
|
||
|
||
### `getSericUUID`
|
||
|
||
- 用途：获取当前选中的服务 UUID，旧命名接口。
|
||
- 参数：无。
|
||
- 返回：`string`。
|
||
- 常见场景：兼容旧项目代码。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
console.log(lib.getSericUUID())
|
||
```
|
||
|
||
### `getServiceUUID`
|
||
|
||
- 用途：获取当前选中的服务 UUID。
|
||
- 参数：无。
|
||
- 返回：`string`。
|
||
- 常见场景：写入、订阅、主动读取前获取服务 UUID。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
console.log(lib.getServiceUUID())
|
||
```
|
||
|
||
### `getNotityUUID`
|
||
|
||
- 用途：获取当前选中的通知特征 UUID。
|
||
- 参数：无。
|
||
- 返回：`string`。
|
||
- 常见场景：开启通知前读取当前通知 UUID。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
console.log(lib.getNotityUUID())
|
||
```
|
||
|
||
### `getWriteUUID`
|
||
|
||
- 用途：获取当前选中的写入特征 UUID。
|
||
- 参数：无。
|
||
- 返回：`string`。
|
||
- 常见场景：发送数据前获取写入 UUID。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
console.log(lib.getWriteUUID())
|
||
```
|
||
|
||
### `getwriteUUID`
|
||
|
||
- 用途：获取当前选中的写入特征 UUID，旧命名接口。
|
||
- 参数：无。
|
||
- 返回：`string`。
|
||
- 常见场景：兼容旧项目代码。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
console.log(lib.getwriteUUID())
|
||
```
|
||
|
||
### `onNotityBleData`
|
||
|
||
- 用途：开启或关闭通知订阅，并监听设备主动上报数据。
|
||
- 参数：服务 UUID、通知 UUID、开关状态、回调函数。
|
||
- 返回：无，订阅状态与通知数据通过回调返回。
|
||
- 常见场景：连接成功并完成服务扫描后开启通知。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.onNotityBleData(
|
||
lib.getSericUUID(),
|
||
lib.getNotityUUID(),
|
||
true,
|
||
function(res:MyApiResult){
|
||
// type 为0 表示通知数据 1000 表示订阅成功 1001 表示订阅失败
|
||
if(res.type == 0){
|
||
let data = res.data as NotityData
|
||
console.log(data)
|
||
}
|
||
}
|
||
)
|
||
```
|
||
|
||
### `onIndicate`
|
||
|
||
- 用途：开启 indicate 订阅，并监听设备主动上报的 indicate 数据。
|
||
- 参数：服务 UUID、indicate 特征 UUID、回调函数。
|
||
- 返回：无，订阅状态与 indicate 数据通过回调返回。
|
||
- 常见场景：设备特征值属性为 `INDICATE`，需要带确认机制的数据上报时使用。
|
||
- 平台说明：Android、iOS、鸿蒙已支持真实 indicate 订阅；微信小程序端当前未实现该接口。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.onIndicate(
|
||
"serviceUUID",
|
||
"indicateUUID",
|
||
function(res:MyApiResult){
|
||
// type 为0 表示 indicate 数据 1000 表示订阅成功 1001 表示订阅失败
|
||
if(res.type == 0){
|
||
let data = res.data as NotityData
|
||
console.log(data)
|
||
}
|
||
}
|
||
)
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.onIndicate(
|
||
"serviceUUID",
|
||
"indicateUUID",
|
||
function(res){
|
||
// type 为0 表示 indicate 数据 1000 表示订阅成功 1001 表示订阅失败
|
||
console.log(res)
|
||
}
|
||
)
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.onNotityBleData(
|
||
lib.getSericUUID(),
|
||
lib.getNotityUUID(),
|
||
true,
|
||
function(res){
|
||
// type 为0 表示通知数据 1000 表示订阅成功 1001 表示订阅失败
|
||
console.log(res)
|
||
}
|
||
)
|
||
```
|
||
|
||
### `onReadData`
|
||
|
||
- 用途：主动读取某个特征值的数据。
|
||
- 参数：服务 UUID、读取 UUID、回调函数。
|
||
- 返回：无，读取结果通过回调返回。
|
||
- 常见场景：设备不主动通知，需要业务端手动拉取数据。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.onReadData("sericeUUID","readUUID",function(res:MyApiResult){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.onReadData("sericeUUID","readUUID",function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `sendData`
|
||
|
||
- 用途：向指定特征值写入数据。
|
||
- 参数：`WriteData`、回调函数。
|
||
- 返回：无，写入结果通过回调返回。
|
||
- 常见场景：发送控制指令、配置参数、透传数据。
|
||
- `uni-app x` 发送 16 进制字符串
|
||
|
||
```ts
|
||
let writeData:WriteData = {
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
hexStrData:"FF001122"
|
||
}
|
||
lib.sendData(writeData,function(res:MyApiResult){
|
||
// 发送结果可结合 type 和 message 判断是否成功
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app` 发送 16 进制字符串
|
||
|
||
```js
|
||
lib.sendData({
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
hexStrData:"FF001122"
|
||
},function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app x` 发送字节数组
|
||
|
||
```ts
|
||
let writeBytes:WriteData = {
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
data:[0xff,0x00,0x11,0x22] as number[]
|
||
}
|
||
lib.sendData(writeBytes,function(res:MyApiResult){
|
||
// 发送结果可结合 type 和 message 判断是否成功
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app` 发送字节数组
|
||
|
||
```js
|
||
lib.sendData({
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
data:[0xff,0x00,0x11,0x22]
|
||
},function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app x` 发送 `ArrayBuffer`
|
||
|
||
```ts
|
||
let buffer = new ArrayBuffer(4)
|
||
let view = new Uint8Array(buffer)
|
||
view[0] = 0xff
|
||
view[1] = 0x00
|
||
view[2] = 0x11
|
||
view[3] = 0x22
|
||
let writeBuffer:WriteData = {
|
||
serviceId:lib.getServiceUUID(),
|
||
characteristicId:lib.getwriteUUID(),
|
||
fenbao:false,
|
||
buffer:buffer
|
||
}
|
||
lib.sendData(writeBuffer,function(res:MyApiResult){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `readRssi`
|
||
|
||
- 用途：读取当前连接设备的 RSSI 信号强度。
|
||
- 参数：回调函数。
|
||
- 返回：无，读取结果通过回调返回。
|
||
- 常见场景：显示连接质量或调试信号强度。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.readRssi(function(res:MyApiResult){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.readRssi(function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `setMtu`
|
||
|
||
- 用途：设置 BLE 连接的 MTU。
|
||
- 参数：MTU 值、回调函数。
|
||
- 返回：无，设置结果通过回调返回。
|
||
- 常见场景：需要发送较大数据包时在 Android 端提高 MTU。
|
||
- `uni-app x`
|
||
|
||
```ts
|
||
lib.setMtu(512,function(res:MyApiResult){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
- `uni-app`
|
||
|
||
```js
|
||
lib.setMtu(512,function(res){
|
||
console.log(res)
|
||
})
|
||
```
|
||
|
||
### `setPhy2MMode`
|
||
|
||
- 用途：切换 Android BLE PHY 2M 模式。
|
||
- 参数：无。
|
||
- 返回：无。
|
||
- 常见场景：Android 设备支持高物理层速率时启用。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setPhy2MMode()
|
||
```
|
||
|
||
### `setDebugMode`
|
||
|
||
- 用途：打开或关闭插件内部调试日志。
|
||
- 参数：`debug:boolean`。
|
||
- 返回：无。
|
||
- 常见场景：联调阶段查看内部扫描、连接、通知过程。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setDebugMode(true)
|
||
lib.setDebugMode(false)
|
||
```
|
||
|
||
### `setThreadTypeName`
|
||
|
||
- 用途：设置插件回调线程名。
|
||
- 参数：线程名字符串。
|
||
- 返回：无。
|
||
- 常见场景：需要和现有线程调度策略保持一致时使用。
|
||
- `uni-app x` / `uni-app`
|
||
|
||
```js
|
||
lib.setThreadTypeName("main")
|
||
```
|
||
|
||
## 常用返回码
|
||
|
||
不同接口返回码略有差异，常见约定如下：
|
||
|
||
| type | 说明 |
|
||
| --- | --- |
|
||
| `0` | 成功 |
|
||
| `1000` | 通知或 indicate 订阅成功 |
|
||
| `1001` | 通知或 indicate 订阅失败，或部分平台表示蓝牙异常断开 |
|
||
| `10000` | 连接失败、读取失败或通用失败 |
|
||
| `10001` | 蓝牙异常断开，或部分场景表示无权限 |
|
||
| `10002` | 蓝牙未开启 |
|
||
| `10003` | 无蓝牙权限 |
|
||
| `10004` | 蓝牙已经连接 |
|
||
| `10005` | 部分平台用于地址无效或未连接 |
|
||
|
||
说明：不同平台和不同接口对错误码的语义可能略有差异，建议结合 `message` 一起判断。
|
||
|
||
## 平台注意事项
|
||
|
||
### Android
|
||
|
||
- 运行原生 BLE 能力建议使用自定义基座。
|
||
- `setMtu` 与 `setPhy2MMode` 为 Android 特有能力。
|
||
- Android 12 及以上系统请注意蓝牙权限授权。
|
||
- Android 端支持通过 `iosFilterUUIDs` 按服务 UUID 过滤扫描。
|
||
- Android 端现已支持真实 `onIndicate` 订阅与数据回调。
|
||
|
||
### iOS
|
||
|
||
- 仅支持 `iOS 13` 及以上。
|
||
- iOS 扫描在部分系统版本下建议配合 `iosFilterUUIDs` 使用。
|
||
- 多连接与多通知场景已做兼容，但仍建议每个连接使用独立实例。
|
||
- 若应用进入后台后不希望系统在连接、断开、通知事件发生时弹出唤回应用提示，可在连接前调用 `setIOSConnectNotifyAlertEnabled(false)`。
|
||
- 该开关底层对应 iOS 连接参数中的 `CBConnectPeripheralOptionNotifyOnConnectionKey`、`CBConnectPeripheralOptionNotifyOnDisconnectionKey`、`CBConnectPeripheralOptionNotifyOnNotificationKey`。
|
||
- iOS 端现已支持真实 `onIndicate` 订阅与数据回调。
|
||
- `getConnectedDevicesWithServices` 与 `redictToConnect` 只有 iOS 可以调用，Android、鸿蒙、微信小程序、Web 都不支持；推荐按“先查已连接设备，再传 `device.address` 接管连接”的顺序调用。
|
||
|
||
### 鸿蒙
|
||
|
||
- 部分虚拟蓝牙地址场景可能返回特定错误码。
|
||
- 建议在真机环境验证扫描、连接、RSSI 与发送流程。
|
||
- 鸿蒙端支持通过 `iosFilterUUIDs` 按服务 UUID 过滤扫描。
|
||
- 鸿蒙端现已支持真实 `onIndicate` 订阅与数据回调。
|
||
|
||
### 微信小程序
|
||
|
||
- 需在微信小程序蓝牙权限与机型能力允许的前提下运行。
|
||
- 建议一个 `BleLib` 实例绑定一个设备连接。
|
||
- 支持多对象多蓝牙连接。
|
||
- 微信小程序端支持通过 `iosFilterUUIDs` 按服务 UUID 过滤扫描。
|
||
|
||
## 示例入口
|
||
|
||
- `App.uvue`：基础单连接示例
|
||
- `pages/Multi/Multi.uvue`：多连接、UUID 选择、通知与发送示例
|
||
|
||
如果你需要查看完整调用方式，优先参考项目内这两个页面的实际示例。
|
||
|
||
## 旧接口说明
|
||
|
||
历史接口与旧版示例已保留在 `old.md` 中，主要用于兼容旧项目：
|
||
|
||
- `onNotityReadBleData`
|
||
- `writeDataToBle`
|
||
- `writeDataToBleWithType`
|
||
- `writeStringDataToBle`
|
||
|
||
新项目建议优先使用：
|
||
|
||
- `onNotityBleData`
|
||
- `sendData`
|
||
- `getServiceUUID`
|
||
- `getWriteUUID`
|
||
|
||
## 更新记录
|
||
|
||
版本变更请查看 `changelog.md`。
|