洛汐文档库

外观

system.bluetooth 与 BLE 广播

约 508 字大约 2 分钟

2026-07-15

官网已经公开 system.bluetooth.ble 的 Scanner 与 GATT Client；本页补充 system.bluetooth.getAddressAsync()、createAdvertiser() 和 advertiser 实例，用于读取本机蓝牙地址及发送 BLE 广播。

导入

import bluetooth from '@system.bluetooth'
import ble from '@system.bluetooth.ble'

bluetooth.getAddressAsync(callback)

getAddressAsync(callback: (address: string) => void): void

原生入口严格要求一个参数且必须是函数。回调值是本机蓝牙地址；失败时实现可能不给回调，因此业务侧应设置超时。

bluetooth.getAddressAsync(address => {
  console.log('BT address', address)
})

蓝牙 MAC 属于设备标识。预装汽车应用同时声明 hapjs.permission.DEVICE_INFO，普通应用即使能导入 Feature，也可能被权限或系统签名策略拒绝。

ble.createAdvertiser()

createAdvertiser(): Advertiser

返回一个广播器实例。实例确认有 startAdvertising() 和 stopAdvertising()。

advertiser.startAdvertising(options)

interface AdvertiseSetting {
  interval: number
  txPower?: number
  connectable?: boolean
}

interface ServiceData {
  serviceUuid: string
  serviceValue: ArrayBuffer
}

interface AdvData {
  serviceUuids?: string[]
  serviceData: ServiceData[]
}

interface StartAdvertisingOptions {
  setting: AdvertiseSetting
  advData: AdvData
  success?: (data?: object) => void
  fail?: (data: object, code?: number) => void
  complete?: () => void
}

startAdvertising(options: StartAdvertisingOptions): void
字段必需说明
setting.interval是广播间隔，数值单位由蓝牙后端定义；不要直接套用毫秒
setting.txPower否发射功率枚举或档位，由产品蓝牙栈解释
setting.connectable否当前接口只支持不可连接广播；传 true 会被忽略
advData.serviceUuids否广播的 Service UUID 列表
advData.serviceData是至少一个 Service Data 项；空数组会报错
serviceUuid是UUID 字符串，预装应用使用 128 位 UUID
serviceValue是Service Data 二进制内容，使用 ArrayBuffer
const advertiser = ble.createAdvertiser()
const bytes = new Uint8Array([0x01, 0x02, 0x03])

advertiser.startAdvertising({
  setting: {
    interval: 160,
    txPower: 0,
    connectable: false
  },
  advData: {
    serviceUuids: ['0000FE95-0000-1000-8000-00805F9B34FB'],
    serviceData: [{
      serviceUuid: '0000FE95-0000-1000-8000-00805F9B34FB',
      serviceValue: bytes.buffer
    }]
  },
  success() { console.log('advertising') },
  fail(data, code) { console.error(code, data) }
})

advertiser.stopAdvertising()

stopAdvertising(): void

页面隐藏、应用退出或登录二维码失效时必须停止广播。不要依赖垃圾回收释放蓝牙资源。

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
❌△

获取源代码