HBuilder5.36及以上版本app-android/app-ios平台uni-app x项目内置支持蓝牙功能,HBuilder5.36以下版本需下载插件:uni-bluetooth
蓝牙规范由蓝牙技术联盟(SIG)制定,主流有两种规格:经典蓝牙(BR/EDR) 用于音箱、耳机等较大带宽场景;蓝牙低功耗(BLE,蓝牙 4.0 起) 功耗低、适合小数据量传输,常见于智能穿戴、传感器、智能家居等设备。
本文与蓝牙-低功耗中心设备介绍 BLE 中心设备能力,用于发现并连接蓝牙低功耗外设,不用于经典蓝牙设备的数据通信。接口按职责分为两部分:
当前支持微信小程序(uni-app x 4.41 起)和支付宝小程序(uni-app x 5.31 起),App 端Harmony平台暂不支持。各接口的具体支持范围及最低支持版本以兼容性表为准。
注意事项
使用蓝牙能力前,需先调用 uni.openBluetoothAdapter 初始化蓝牙适配器,并确认初始化成功。调用 uni.closeBluetoothAdapter 或应用进程结束后,再次使用时需重新初始化。监听类接口可提前注册。
deviceId,也可调用 uni.getBluetoothDevices 获取已发现的设备列表。NSBluetoothAlwaysUsageDescription 隐私说明,并获得用户授权。发行时应确认最终应用包含符合实际用途的权限说明。需分别遵循微信小程序和支付宝小程序的蓝牙授权要求与平台限制。各接口的支持范围以对应的兼容性表为准。
deviceId,再用于后续连接和通信。deviceId 来自系统分配的 UUID,不应假设它跨手机、跨安装或跨会话始终不变。适配器可用不代表设备已连接。监听设备连接状态时,使用 uni.onBLEConnectionStateChange,通过回调中的 deviceId 和 connected 判断目标设备是否连接。
off* 移除自身注册的监听,避免重复监听或影响其他页面。on* 返回的监听 ID,并将该 ID 传给对应的 off*,仅移除自身注册的监听,避免清空其他页面的监听。系统蓝牙开关和应用蓝牙权限需分别检查。先注册 uni.onBluetoothAdapterStateChange 并调用 uni.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 及可用的错误详情,结合真机环境进一步排查。 |
初始化蓝牙模块,建议与 uni.closeBluetoothAdapter 成对调用。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | OpenBluetoothAdapterOptions | 是 | * | |||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | |
| errCode | number | 否 | 错误码 | 错误码 | 错误信息 | 说明 | | - | - | - | | 0 | ok | 正常 | | -1 | already connect | 已连接 | | 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 为空或者是格式不正确 | |
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
关闭蓝牙模块并释放相关系统资源,建议与 uni.openBluetoothAdapter 成对调用。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | CloseBluetoothAdapterOptions | 是 | * | |||||||||||||||||||||
| ||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | |
| errCode | number | 否 | 错误码 | 错误码 | 错误信息 | 说明 | | - | - | - | | 0 | ok | 正常 | | -1 | already connect | 已连接 | | 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 为空或者是格式不正确 | |
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
获取本机蓝牙适配器状态。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | GetBluetoothAdapterStateOptions | 是 | * | |||||||||||||||||||||
| ||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | |
| discovering | boolean | 是 | 是否正在搜索设备。 | |
| available | boolean | 是 | 蓝牙适配器是否可用。 |
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
监听蓝牙适配器状态变化事件。
| 名称 | 类型 | 必填 | 兼容性 | 描述 |
|---|---|---|---|---|
| callback | (result: BluetoothAdapterStateChangeResult) => void | 是 | * |
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
|---|---|---|---|---|
| available | boolean | 是 | 蓝牙适配器是否可用。 | |
| discovering | boolean | 是 | 蓝牙适配器是否正在搜索设备。 |
| 类型 |
|---|
| number |
移除蓝牙适配器状态变化监听函数。传入监听 ID 时移除对应监听,否则移除全部监听。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| listener | number | (result: BluetoothAdapterStateChangeResult) => void | 否 | * | ||||||||||||||||
| |||||||||||||||||||
开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源,搜索到需要的设备后应及时调用 uni.stopBluetoothDevicesDiscovery 停止搜索。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | StartBluetoothDevicesDiscoveryOptions | 是 | * | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | |
| errCode | number | 否 | 错误码 | 错误码 | 错误信息 | 说明 | | - | - | - | | 0 | ok | 正常 | | -1 | already connect | 已连接 | | 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 为空或者是格式不正确 | |
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
停止搜寻附近的蓝牙外围设备。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | StopBluetoothDevicesDiscoveryOptions | 是 | * | |||||||||||||||||||||
| ||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | |
| errCode | number | 否 | 错误码 | 错误码 | 错误信息 | 说明 | | - | - | - | | 0 | ok | 正常 | | -1 | already connect | 已连接 | | 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 为空或者是格式不正确 | |
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
监听搜索到新设备的事件。回调上报的设备会加入 uni.getBluetoothDevices 返回的设备列表。
| 名称 | 类型 | 必填 | 兼容性 | 描述 |
|---|---|---|---|---|
| listener | (result: BluetoothDeviceFoundResult) => void | 是 | * |
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| devices | Array<BluetoothDevice> | 是 | 新搜索到的设备列表。 | ||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||
| 类型 |
|---|
| number |
移除搜索到新设备的事件监听。传入监听 ID 时移除对应监听,否则移除全部监听。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| listener | number | (result: BluetoothDeviceFoundResult) => void | 否 | * | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
获取蓝牙模块生效期间所有搜索到的蓝牙设备,包括已经和本机处于连接状态的设备。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | GetBluetoothDevicesOptions | 是 | * | |||||||||||||||||||||
| ||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | ||||||||||||||||||||||||||||||||||||||||||||||
| devices | Array<BluetoothDevice> | 是 | 蓝牙模块生效期间搜索到的设备列表,包括已经和本机处于连接状态的设备。 | ||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
根据主服务 UUID 获取已连接的蓝牙设备。
| 名称 | 类型 | 必填 | 兼容性 | 描述 | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | GetConnectedBluetoothDevicesOptions | 是 | * | ||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errMsg | string | 是 | 调用结果信息。 | ||||||||||||||||
| devices | Array<ConnectedBluetoothDevice> | 是 | 指定主服务 UUID 对应的已连接设备列表。 | ||||||||||||||||
| |||||||||||||||||||
| 名称 | 类型 | 必备 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| errCode | number | 是 | uni 蓝牙适配器和 BLE 中心设备 API 可能返回的统一错误码。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| mtu | number | 否 | 最终协商的 MTU 值。如果协商失败则无此参数。安卓客户端 8.0.9 开始支持。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errSubject | string | 是 | 统一错误主题(模块)名称 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data | any | 否 | 错误信息中包含的数据 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cause | Error | 否 | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errMsg | string | 是 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见
该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验
<template>
<view class="page">
<view class="log-panel">
<view class="panel-heading">
<text class="panel-title">Log</text>
<button class="clear-button" size="mini" @click="clearLogs">清空</button>
</view>
<scroll-view class="log-list" direction="vertical" :show-scrollbar="true">
<text v-if="logs.length == 0" class="log-empty">等待 API 调用</text>
<text v-for="(log, index) in logs" :key="index" class="log-item">{{ log }}</text>
</scroll-view>
</view>
<scroll-view class="api-scroll" direction="vertical" :show-scrollbar="true">
<view class="api-content">
<view class="section">
<text class="section-title">监听 API</text>
<view class="listener-card">
<view class="listener-heading">
<text class="listener-title">适配器状态变化</text>
<text class="listener-status">listenerId: {{ adapterListenerId == 0 ? '-' : adapterListenerId }}</text>
</view>
<view class="listener-api-row">
<text class="listener-api-name">uni.onBluetoothAdapterStateChange</text>
<button id="test-on-bluetooth-adapter-state-change" class="listener-button" size="mini" type="primary"
@click="onAdapterStateChange">监听</button>
</view>
<view class="listener-api-row">
<text class="listener-api-name">uni.offBluetoothAdapterStateChange</text>
<button id="test-off-bluetooth-adapter-state-change" class="listener-button" size="mini"
@click="offAdapterStateChange">取消</button>
</view>
</view>
<view class="listener-card">
<view class="listener-heading">
<text class="listener-title">发现蓝牙设备</text>
<text class="listener-status">listenerId: {{ deviceListenerId == 0 ? '-' : deviceListenerId }}</text>
</view>
<view class="listener-api-row">
<text class="listener-api-name">uni.onBluetoothDeviceFound</text>
<button id="test-on-bluetooth-device-found" class="listener-button" size="mini" type="primary"
@click="onDeviceFound">监听</button>
</view>
<view class="listener-api-row">
<text class="listener-api-name">uni.offBluetoothDeviceFound</text>
<button id="test-off-bluetooth-device-found" class="listener-button" size="mini"
@click="offDeviceFound">取消</button>
</view>
</view>
</view>
<view class="section">
<text class="section-title">普通 API</text>
<view class="api-card">
<view class="api-action-row">
<text class="api-name">uni.openBluetoothAdapter</text>
<button id="test-open-bluetooth-adapter" class="call-button" size="mini" type="primary" @click="openAdapter">调用</button>
</view>
</view>
<view class="api-card">
<view class="api-action-row">
<text class="api-name">uni.getBluetoothAdapterState</text>
<button id="test-get-bluetooth-adapter-state" class="call-button" size="mini" @click="getAdapterState">调用</button>
</view>
</view>
<view class="api-card">
<view class="parameter-row parameter-row-column">
<text class="parameter-name">services</text>
<input v-model="discoveryServices" class="parameter-input" placeholder="多个 UUID 使用英文逗号分隔" />
</view>
<view class="parameter-row">
<text class="parameter-name">allowDuplicatesKey</text>
<switch :checked="allowDuplicates" @change="allowDuplicates = $event.detail.value" />
</view>
<view class="parameter-row">
<text class="parameter-name">interval (ms)</text>
<input v-model="discoveryInterval" class="parameter-input parameter-input-short" type="number" placeholder="0" />
</view>
<!-- #ifdef APP-ANDROID -->
<view class="parameter-row">
<text class="parameter-name">powerLevel</text>
<picker class="parameter-picker" :range="powerLevels" :value="powerLevelIndex" @change="onPowerLevelChange">
<view class="picker-value">{{ powerLevels[powerLevelIndex] }}</view>
</picker>
</view>
<!-- #endif -->
<view class="api-action-row api-action-row-after-parameters">
<text class="api-name">uni.startBluetoothDevicesDiscovery</text>
<button id="test-start-bluetooth-devices-discovery" class="call-button" size="mini" type="primary"
@click="startDiscovery">调用</button>
</view>
</view>
<view class="api-card">
<view class="api-action-row">
<text class="api-name">uni.stopBluetoothDevicesDiscovery</text>
<button id="test-stop-bluetooth-devices-discovery" class="call-button" size="mini" @click="stopDiscovery">调用</button>
</view>
</view>
<view class="api-card">
<view class="api-action-row">
<text class="api-name">uni.getBluetoothDevices</text>
<button id="test-get-bluetooth-devices" class="call-button" size="mini" @click="getDevices">调用</button>
</view>
</view>
<view class="api-card">
<view class="parameter-row parameter-row-column">
<text class="parameter-name">services</text>
<input v-model="connectedServices" class="parameter-input" placeholder="必填,多个 UUID 使用英文逗号分隔" />
</view>
<view class="api-action-row api-action-row-after-parameters">
<text class="api-name">uni.getConnectedBluetoothDevices</text>
<button id="test-get-connected-bluetooth-devices" class="call-button" size="mini"
@click="getConnectedDevices">调用</button>
</view>
</view>
<view class="api-card">
<view class="api-action-row">
<text class="api-name">uni.closeBluetoothAdapter</text>
<button id="test-close-bluetooth-adapter" class="call-button" size="mini" @click="closeAdapter">调用</button>
</view>
</view>
</view>
<button id="bluetooth-general-performance-test" class="performance-button" type="primary"
@click="openPerformanceTest">综合性能测试</button>
</view>
</scroll-view>
</view>
</template>
<script setup lang="ts">
// #ifdef APP-ANDROID
type PowerLevel = 'low' | 'medium' | 'high'
// #endif
type GeneralBluetoothDevice = {
name ?: string | null
localName ?: string | null
deviceId : string
RSSI ?: number | null
}
const logs = ref<string[]>([])
const adapterListenerId = ref(0)
const deviceListenerId = ref(0)
const adapterOpened = ref(false)
const discovering = ref(false)
const discoveryServices = ref('')
const connectedServices = ref('')
const allowDuplicates = ref(false)
const discoveryInterval = ref('0')
// #ifdef APP-ANDROID
const powerLevels = ['low', 'medium', 'high'] as PowerLevel[]
const powerLevelIndex = ref(1)
// #endif
function addLog(apiName : string, message : string) {
logs.value.unshift('[' + new Date().toLocaleTimeString() + '] ' + apiName + ': ' + message)
if (logs.value.length > 100) logs.value.pop()
}
function addCallbackLog(message : string) {
logs.value.unshift('[' + new Date().toLocaleTimeString() + '] ' + message)
if (logs.value.length > 100) logs.value.pop()
}
function addError(errCode ?: number | null) {
const code = errCode == null ? 'null' : errCode!.toString()
addCallbackLog('errCode=' + code)
}
function clearLogs() {
logs.value = []
}
function parseServices(value : string) : string[] {
const result = [] as string[]
value.split(',').forEach((item : string) => {
const service = item.trim()
if (service.length > 0) result.push(service)
})
return result
}
function formatDevices(devices : GeneralBluetoothDevice[]) : string {
if (devices.length == 0) return 'devices=[]'
const details = [] as string[]
devices.forEach((device : GeneralBluetoothDevice) => {
let name = device.name
if ((name == null || name!.length == 0) && device.localName != null) name = device.localName
const RSSI = device.RSSI == null ? 'null' : device.RSSI!.toString()
details.push('{name=' + (name == null ? '' : name!) + ', deviceId=' + device.deviceId + ', RSSI=' + RSSI + '}')
})
return 'devices(' + devices.length.toString() + ')=[' + details.join(', ') + ']'
}
const adapterStateCallback = (result : { available : boolean, discovering : boolean }) => {
addLog('onBluetoothAdapterStateChange callback', 'available=' + result.available.toString() + ', discovering=' + result.discovering.toString())
}
const deviceFoundCallback = (result : { devices : GeneralBluetoothDevice[] }) => {
addLog('onBluetoothDeviceFound callback', formatDevices(result.devices))
}
function openAdapter() {
addLog('openBluetoothAdapter', 'request')
uni.openBluetoothAdapter({
success: (result) => {
adapterOpened.value = true
addCallbackLog(result.errMsg)
},
fail: (error) => addError(error.errCode)
})
}
function closeAdapter() {
addLog('closeBluetoothAdapter', 'request')
uni.closeBluetoothAdapter({
success: (result) => {
adapterOpened.value = false
discovering.value = false
addCallbackLog(result.errMsg)
},
fail: (error) => addError(error.errCode)
})
}
function getAdapterState() {
addLog('getBluetoothAdapterState', 'request')
uni.getBluetoothAdapterState({
success: (result) => {
addCallbackLog(result.errMsg + ', available=' + result.available.toString() + ', discovering=' + result.discovering.toString())
},
fail: (error) => addError(error.errCode)
})
}
function onAdapterStateChange() {
if (adapterListenerId.value != 0) {
addLog('onBluetoothAdapterStateChange', 'listener already registered, listenerId=' + adapterListenerId.value.toString())
return
}
adapterListenerId.value = uni.onBluetoothAdapterStateChange(adapterStateCallback)
addLog('onBluetoothAdapterStateChange', 'registered, listenerId=' + adapterListenerId.value.toString())
}
function offAdapterStateChange() {
const listenerId = adapterListenerId.value
if (listenerId != 0) uni.offBluetoothAdapterStateChange(listenerId)
else uni.offBluetoothAdapterStateChange()
adapterListenerId.value = 0
addLog('offBluetoothAdapterStateChange', listenerId == 0 ? 'removed all listeners' : 'removed listenerId=' + listenerId.toString())
}
// #ifdef APP-ANDROID
function onPowerLevelChange(event : UniPickerChangeEvent) {
powerLevelIndex.value = event.detail.value as number
}
// #endif
function startDiscovery() {
const services = parseServices(discoveryServices.value)
let interval = parseInt(discoveryInterval.value)
if (Number.isNaN(interval) || interval < 0) interval = 0
let parameterLog = 'request, services=[' + services.join(', ') + '], allowDuplicatesKey=' + allowDuplicates.value.toString() + ', interval=' + interval.toString()
// #ifdef APP-ANDROID
const powerLevel = powerLevels[powerLevelIndex.value]
parameterLog += ', powerLevel=' + powerLevel
// #endif
addLog('startBluetoothDevicesDiscovery', parameterLog)
const options : StartBluetoothDevicesDiscoveryOptions = {
allowDuplicatesKey: allowDuplicates.value,
interval,
// #ifdef APP-ANDROID
powerLevel,
// #endif
success: (result) => {
discovering.value = true
addCallbackLog(result.errMsg)
},
fail: (error) => addError(error.errCode)
}
if (services.length > 0) options.services = services
uni.startBluetoothDevicesDiscovery(options)
}
function stopDiscovery() {
addLog('stopBluetoothDevicesDiscovery', 'request')
uni.stopBluetoothDevicesDiscovery({
success: (result) => {
discovering.value = false
addCallbackLog(result.errMsg)
},
fail: (error) => addError(error.errCode)
})
}
function onDeviceFound() {
if (deviceListenerId.value != 0) {
addLog('onBluetoothDeviceFound', 'listener already registered, listenerId=' + deviceListenerId.value.toString())
return
}
deviceListenerId.value = uni.onBluetoothDeviceFound(deviceFoundCallback)
addLog('onBluetoothDeviceFound', 'registered, listenerId=' + deviceListenerId.value.toString())
}
function offDeviceFound() {
const listenerId = deviceListenerId.value
if (listenerId != 0) uni.offBluetoothDeviceFound(listenerId)
else uni.offBluetoothDeviceFound()
deviceListenerId.value = 0
addLog('offBluetoothDeviceFound', listenerId == 0 ? 'removed all listeners' : 'removed listenerId=' + listenerId.toString())
}
function getDevices() {
addLog('getBluetoothDevices', 'request')
uni.getBluetoothDevices({
success: (result) => addCallbackLog(result.errMsg + ', ' + formatDevices(result.devices)),
fail: (error) => addError(error.errCode)
})
}
function getConnectedDevices() {
const services = parseServices(connectedServices.value)
addLog('getConnectedBluetoothDevices', 'request, services=[' + services.join(', ') + ']')
uni.getConnectedBluetoothDevices({
services,
success: (result) => addCallbackLog(result.errMsg + ', ' + formatDevices(result.devices)),
fail: (error) => addError(error.errCode)
})
}
function openPerformanceTest() {
uni.navigateTo({
url: '/pages/API/bluetooth-benchmark/bluetooth-benchmark'
})
}
onLoad(() => {
onAdapterStateChange()
onDeviceFound()
})
onUnload(() => {
if (adapterListenerId.value != 0) uni.offBluetoothAdapterStateChange(adapterListenerId.value)
if (deviceListenerId.value != 0) uni.offBluetoothDeviceFound(deviceListenerId.value)
if (discovering.value) uni.stopBluetoothDevicesDiscovery({})
if (adapterOpened.value) uni.closeBluetoothAdapter({})
})
</script>
<style>
.page {
display: flex;
flex: 1;
flex-direction: column;
background-color: #f5f5f5;
}
.api-scroll {
flex: 1;
}
.api-content {
display: flex;
flex-direction: column;
padding: 0 15px 15px;
}
.log-panel {
display: flex;
flex-direction: column;
flex-shrink: 0;
margin: 15px 15px 10px;
background-color: #1f2329;
border-radius: 6px;
overflow: hidden;
}
.panel-heading {
display: flex;
flex-direction: row;
align-items: center;
justify-content: space-between;
padding: 8px 10px;
border-bottom-width: 1px;
border-bottom-style: solid;
border-bottom-color: #3a3f47;
}
.panel-title {
font-size: 14px;
font-weight: 600;
color: #ffffff;
}
.clear-button {
margin: 0;
}
.log-list {
height: 210px;
padding: 8px 10px;
}
.log-empty,
.log-item {
margin-bottom: 6px;
font-size: 11px;
line-height: 16px;
color: #aeb6c2;
}
.log-item {
color: #d7dde5;
}
.section {
display: flex;
flex-direction: column;
margin-bottom: 20px;
}
.section-title {
margin-bottom: 10px;
font-size: 16px;
font-weight: 600;
color: #222222;
}
.listener-card {
display: flex;
flex-direction: column;
margin-bottom: 12px;
padding: 12px;
background-color: #ffffff;
border-radius: 6px;
}
.listener-heading {
display: flex;
flex-direction: row;
align-items: center;
justify-content: space-between;
padding-bottom: 8px;
}
.listener-title {
font-size: 14px;
font-weight: 600;
color: #222222;
}
.listener-status {
font-size: 11px;
color: #777777;
}
.listener-api-row {
display: flex;
flex-direction: row;
align-items: center;
min-height: 46px;
border-top-width: 1px;
border-top-style: solid;
border-top-color: #eeeeee;
}
.listener-api-name {
flex: 1;
margin-right: 10px;
font-size: 12px;
color: #333333;
}
.listener-button {
width: 64px;
margin: 0;
}
.api-card {
display: flex;
flex-direction: column;
margin-bottom: 12px;
padding: 12px;
background-color: #ffffff;
border-radius: 6px;
}
.api-name {
flex: 1;
margin-right: 10px;
font-size: 14px;
font-weight: 600;
color: #222222;
}
.api-action-row {
display: flex;
flex-direction: row;
align-items: center;
min-height: 32px;
}
.api-action-row-after-parameters {
margin-top: 10px;
}
.parameter-row {
display: flex;
flex-direction: row;
align-items: center;
justify-content: space-between;
min-height: 42px;
padding: 4px 0;
border-top-width: 1px;
border-top-style: solid;
border-top-color: #eeeeee;
}
.parameter-row-column {
flex-direction: column;
align-items: stretch;
}
.parameter-name {
font-size: 12px;
color: #555555;
}
.parameter-input {
height: 36px;
margin-top: 6px;
padding: 0 10px;
background-color: #f5f5f5;
border-radius: 4px;
font-size: 12px;
}
.parameter-input-short {
width: 120px;
margin-top: 0;
}
.parameter-picker {
width: 120px;
}
.picker-value {
height: 36px;
padding: 0 10px;
background-color: #f5f5f5;
border-radius: 4px;
font-size: 12px;
line-height: 36px;
color: #333333;
}
.call-button {
width: 64px;
margin: 0;
}
.performance-button {
width: 100%;
margin-top: 8px;
margin-bottom: 10px;
}
</style>
| 名称 | 类型 | 必备 | 描述 |
|---|---|---|---|
| errMsg | string | 是 | 错误信息 |