tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
1322
5.1m

x-bluetooth-s 蓝牙 ​

对齐微信小程序蓝牙通用模块的 UTS API。函数与类型均加 x 前缀，避免与官方同名冲突。一次性接口使用 DCloud success / fail / complete。

本插件覆盖适配器初始化、扫描、已发现/已连接设备查询、适配器与设备事件。不包含 BLE 连接、读写特征值等低功耗蓝牙主机接口。

兼容性 ​

HarmonyiOSAndroidWEB微信小程序
支持支持支持不支持支持

微信端走 wx.*。Android 使用 BluetoothLeScanner + 经典发现，iOS 使用 CBCentralManager，HarmonyOS 使用 @kit.ConnectivityKit 的 access / ble / connection。扫描会合并后续广播里的设备名，第一包无名时不会把有名结果丢掉。Web 无系统蓝牙通用扫描能力，返回 fail 10009。

xMakeBluetoothPair、xIsBluetoothDevicePaired 支持 Android、iOS、HarmonyOS、微信。Web 返回 10009。搜到手机不等于能配对：手机一般不会像耳机那样接受另一台手机的经典配对。

调用 ​

ts
import {
  xOpenBluetoothAdapter,
  xStartBluetoothDevicesDiscovery,
  xStopBluetoothDevicesDiscovery,
  xOnBluetoothDeviceFound,
  xOffBluetoothDeviceFound,
  xCloseBluetoothAdapter,
  XBluetoothDevice
} from "@/uni_modules/x-bluetooth-s"

const foundId = xOnBluetoothDeviceFound((res) => {
  const list : XBluetoothDevice[] = res.devices
  console.log(list.length, list[0].deviceId, list[0].RSSI)
})

xOpenBluetoothAdapter({
  success: () => {
    xStartBluetoothDevicesDiscovery({
      allowDuplicatesKey: false,
      success: () => {
        console.log("scanning")
      }
    })
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg, err.state)
  }
})

xStopBluetoothDevicesDiscovery({})
xOffBluetoothDeviceFound(foundId)
xCloseBluetoothAdapter({})

方法 ​

名称说明
xOpenBluetoothAdapter初始化蓝牙适配器。其它 API 必须在此之后调用
xCloseBluetoothAdapter关闭适配器并清空搜索缓存
xGetBluetoothAdapterState获取适配器是否可用、是否正在搜索
xOnBluetoothAdapterStateChange监听适配器状态，返回监听 id
xOffBluetoothAdapterStateChange移除状态监听；不传 id 则移除全部
xStartBluetoothDevicesDiscovery开始搜索附近蓝牙外围设备
xStopBluetoothDevicesDiscovery停止搜索
xGetBluetoothDevices获取适配器生效期间搜索到的全部设备
xGetConnectedBluetoothDevices按主服务 UUID 获取已连接设备
xOnBluetoothDeviceFound监听新设备，返回监听 id
xOffBluetoothDeviceFound移除设备监听；不传 id 则移除全部
xMakeBluetoothPair蓝牙配对。Android / 鸿蒙 / 微信可用 pin（Base64）；iOS 走 BLE 连接触发系统配对框，pin 无效
xIsBluetoothDevicePaired查询是否已配对。iOS 无法读取系统配对列表，只反映本插件成功配对过或当前已连接

错误码 ​

对齐微信蓝牙错误码：

码含义
10000未初始化蓝牙适配器
10001当前蓝牙适配器不可用
10002没有找到指定设备
10008系统错误（含权限被拒绝）
10009当前平台不支持
10012操作超时
10013参数无效

xOpenBluetoothAdapter 失败时 state 对齐微信 iOS 状态：0 未知 / 1 重置中 / 2 不支持 / 3 未授权 / 4 未开启。

蓝牙开关关闭时，xOpenBluetoothAdapter 仍会完成本地模块初始化，并返回 10001。之后可通过 xOnBluetoothAdapterStateChange 等待用户打开蓝牙。

平台差异 ​

Android

  • deviceId 为 MAC 地址。
  • 扫描需 BLUETOOTH_SCAN / BLUETOOTH_CONNECT（API 31+）或定位权限（更低版本）。部分机型仍需定位才能扫到设备。
  • powerLevel：low / medium / high 对应系统扫描模式。

iOS

  • deviceId 为系统生成的 UUID，不能硬编码。
  • mode 仅作兼容参数，本插件按主机模式初始化。
  • 没有经典蓝牙 createBond。配对通过连接 BLE 外设并访问需加密特征，由系统弹出配对码/确认框，应用不能注入 PIN。
  • 对端必须是可连接的 BLE 外设。另一台手机的经典可发现记录在 iOS 上扫不到，也无法互配。
  • xIsBluetoothDevicePaired 不能读系统配对列表，只记录本插件成功触发过的配对或当前已连接。

HarmonyOS

  • 需 ohos.permission.ACCESS_BLUETOOTH。
  • 扫描走 ble.startBLEScan，无服务过滤时同时做经典发现；适配器状态走 access.getState。
  • 配对走 connection.pairDevice，查询走 connection.getPairState。发起配对会先停止搜索，系统会弹确认框。
  • 搜到 iPhone 只说明对方可被发现。iPhone 作为手机一般不接受另一台手机的经典配对，失败时常见对端拒绝或不在线。

微信小程序

  • 直接转发 wx.openBluetoothAdapter 等官方 API。
  • serviceData 转为 { uuid, data }[]，便于 UTS 使用。

更新日志 ​

1.0.4（2026-08-21） ​

  • iOS 补齐 xMakeBluetoothPair / xIsBluetoothDevicePaired：通过连接 BLE 外设触发系统配对框，pin 无效。
  • iOS 没有经典 createBond，配对码由系统弹出；对端必须是可连接且要求加密的 BLE 设备。

1.0.3（2026-08-20） ​

  • 鸿蒙补齐 xMakeBluetoothPair / xIsBluetoothDevicePaired：走 connection.pairDevice、getPairState，配对前会先停扫。
  • 搜到 iPhone 仍可能配不上：那是手机互配限制，不是扫描失败。

1.0.2（2026-08-20） ​

  • 扫描名称：第一包常无名，后续广播带名字时会补上并再上报，不再只认第一包。
  • 安卓去掉 neverForLocation（会滤掉广播名），并同时做经典蓝牙发现，系统设置里能看到的手机名可以进来。
  • iOS 扫描始终允许重复回调，用 peripheral.name 和广播 LocalName 合并。
  • 鸿蒙修正广播 AD 解析与 UTF-8 设备名，并回退 getRemoteDeviceName / 经典发现。

1.0.1（2026-08-20） ​

  • 鸿蒙：带 @default 的 boolean 改为 ?:，保留 iOS 默认值，避免必填字段编成 !: boolean = false。
  • 鸿蒙：默认 Options 改为先 {} as 再赋值，不再漏写 success / fail / complete。

1.0.0（2026-08-16） ​

  • 新增蓝牙通用模块 API，对齐微信 device/bluetooth 全部方法
  • 支持 Android / iOS / HarmonyOS / 微信小程序；Web 返回 10009
  • xMakeBluetoothPair / xIsBluetoothDevicePaired 仅 Android / 微信可用
最近更新