输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
API参考系统网络Connectivity Kit（短距通信服务）ArkTS API@ohos.bluetooth.connection (蓝牙connection模块)

@ohos.bluetooth.connection (蓝牙connection模块)

更新时间: 2026-06-13 03:51
本文导读
导入模块
ProfileConnectionState
ProfileId
ProfileUuids12+
MajorClass
MajorMinorClass
BluetoothAddress21+
connection.pairDevice
connection.pairDevice
connection.pairDevice21+
connection.getRemoteDeviceName
connection.getRemoteDeviceName16+
connection.getRemoteDeviceClass
connection.getRemoteDeviceTransport20+
connection.getRemoteProfileUuids12+
connection.getRemoteProfileUuids12+
connection.getLocalName
connection.getPairedDevices
connection.getPairState11+
connection.getProfileConnectionState
connection.setDevicePairingConfirmation
connection.setDevicePinCode
connection.setDevicePinCode
connection.setLocalName(deprecated)
connection.setBluetoothScanMode
connection.getBluetoothScanMode
connection.startBluetoothDiscovery
connection.stopBluetoothDiscovery
connection.isBluetoothDiscovering11+
connection.setRemoteDeviceName12+
connection.getRemoteDeviceBatteryInfo12+
connection.on('batteryChange')12+
connection.off('batteryChange')12+
connection.on('bluetoothDeviceFind')
connection.off('bluetoothDeviceFind')
connection.on('bondStateChange')
connection.off('bondStateChange')
connection.on('pinRequired')
connection.off('pinRequired')
connection.on('discoveryResult')18+
connection.off('discoveryResult')18+
connection.onScanModeChange23+
connection.offScanModeChange23+
connection.getLastConnectionTime15+
connection.connectAllowedProfiles16+
connection.connectAllowedProfiles16+
connection.disconnectAllowedProfiles
connection.getVirtualAddressByHash24+
connection.onAclStateChange
connection.offAclStateChange
BondStateParam
PinRequiredParam
DeviceClass
BatteryInfo12+
BluetoothTransport
ScanMode
BondState
UnbondCause12+
DeviceChargeState12+
DiscoveryResult18+
HashAlgorithmType24+
AclStateResult
AclState
展开章节

connection模块提供了蓝牙设备的配对、连接及状态查询等能力。

说明

本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

PhonePC/2in1TabletTVWearable
收起
自动换行
深色代码主题
复制
  1. import { connection } from '@kit.ConnectivityKit';

ProfileConnectionState

PhonePC/2in1TabletTVWearable

type ProfileConnectionState = constant.ProfileConnectionState

蓝牙设备的Profile协议连接状态。Profile协议包括A2DP（Advanced Audio Distribution Profile）、HFP（Hands-Free Profile）和HID（Human Interface Device）等。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
类型 说明
constant.ProfileConnectionState 蓝牙设备的Profile协议连接状态。

ProfileId

PhonePC/2in1TabletTVWearable

type ProfileId = constant.ProfileId

枚举，蓝牙Profile协议。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
类型 说明
constant.ProfileId 蓝牙Profile协议的枚举。

ProfileUuids12+

PhonePC/2in1TabletTVWearable

type ProfileUuids = constant.ProfileUuids

蓝牙Profile协议的UUID。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
类型 说明
constant.ProfileUuids 蓝牙Profile协议的UUID。

MajorClass

PhonePC/2in1TabletTVWearable

type MajorClass = constant.MajorClass

蓝牙设备的主要类型。蓝牙标准协议字段。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
类型 说明
constant.MajorClass 蓝牙设备的主要类型。

MajorMinorClass

PhonePC/2in1TabletTVWearable

type MajorMinorClass = constant.MajorMinorClass

蓝牙设备的子类型，在MajorClass基础上进一步细分的类型。蓝牙标准协议字段。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
类型 说明
constant.MajorMinorClass 蓝牙设备的子类型。

BluetoothAddress21+

PhonePC/2in1TabletTVWearable

type BluetoothAddress = common.BluetoothAddress

描述蓝牙设备地址信息的参数结构，包括地址与地址类型。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
类型 说明
common.BluetoothAddress 蓝牙设备的地址信息。

connection.pairDevice

PhonePC/2in1TabletTVWearable

pairDevice(deviceId: string, callback: AsyncCallback<void>): void

主动发起与对端蓝牙设备的配对流程。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 需要配对的对端蓝牙设备地址，例如："XX:XX:XX:XX:XX:XX"。
callback AsyncCallback<void> 是 回调函数。当配对成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // callback
  3. try {
  4.     connection.pairDevice('11:22:33:44:55:66', (err: BusinessError) => {
  5.         console.info('pairDevice, device name err:' + JSON.stringify(err));
  6.     });
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.pairDevice

PhonePC/2in1TabletTVWearable

pairDevice(deviceId: string): Promise<void>

主动发起与对端蓝牙设备的配对流程。使用Promise异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 需要配对的对端蓝牙设备地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // promise
  3. try {
  4.     connection.pairDevice('11:22:33:44:55:66').then(() => {
  5.         console.info('pairDevice');
  6.     }, (error: BusinessError) => {
  7.         console.error('pairDevice: errCode:' + error.code + ',errMessage' + error.message);
  8.     })
  9. 

  10. } catch (err) {
  11.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  12. }

connection.pairDevice21+

PhonePC/2in1TabletTVWearable

pairDevice(deviceId: BluetoothAddress): Promise<void>

主动发起与对端蓝牙设备的配对流程。使用Promise异步回调。

  • 若开发者已知目标设备的MAC地址及地址类型，建议调用此接口发起配对。
  • 蓝牙配对状态通过on('bondStateChange')的回调结果获取。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId BluetoothAddress 是 需要配对的对端蓝牙设备地址信息，包括地址与地址类型。

返回值：

展开
类型 说明
Promise<void> Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { common } from '@kit.ConnectivityKit';
  3. // promise
  4. try {
  5.     let btAddr: common.BluetoothAddress = {
  6.         "address": '11:22:33:44:55:66', // 目标设备的实际MAC地址或虚拟MAC地址
  7.         "addressType": common.BluetoothAddressType.REAL, // 相应的地址类型
  8.     }
  9.     connection.pairDevice(btAddr).then(() => {
  10.         console.info('pairDevice');
  11.     }, (error: BusinessError) => {
  12.         console.error('errCode: ' + error.code + ', errMessage' + error.message);
  13.     });
  14. } catch (err) {
  15.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  16. }

connection.getRemoteDeviceName

PhonePC/2in1TabletTVWearable

getRemoteDeviceName(deviceId: string): string

获取对端蓝牙设备的名称。

  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取设备名称。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
string 以字符串格式返回设备名称。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX');
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.getRemoteDeviceName16+

PhonePC/2in1TabletTVWearable

getRemoteDeviceName(deviceId: string, alias?: boolean): string

获取对端蓝牙设备的名称，其中alias为可选参数。

  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取设备名称。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 16开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。
alias boolean 否

表示是否获取对端蓝牙设备别名。

- 如果携带alias，则根据alias判断是否获取对端蓝牙设备别名：true表示获取对端蓝牙设备别名，false表示获取对端蓝牙设备原始名称。

- 如果未携带alias，则默认值为true，返回对端蓝牙设备别名。

返回值：

展开
类型 说明
string 以字符串格式返回设备名称。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Failed to obtain the name or alias of the peer Bluetooth device.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX', true);
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.getRemoteDeviceClass

PhonePC/2in1TabletTVWearable

getRemoteDeviceClass(deviceId: string): DeviceClass

获取对端蓝牙设备的类别。

  • 从API version 18开始，此接口不再校验ohos.permission.ACCESS_BLUETOOTH权限。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取设备类别信息。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
DeviceClass 对端设备的类别。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX');
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.getRemoteDeviceTransport20+

PhonePC/2in1TabletTVWearable

getRemoteDeviceTransport(deviceId: string): BluetoothTransport

获取对端蓝牙设备的传输类型。

  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取设备的传输类型。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
BluetoothTransport 对端设备的传输类型。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Get transport failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let transport: connection.BluetoothTransport = connection.getRemoteDeviceTransport('XX:XX:XX:XX:XX:XX');
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.getRemoteProfileUuids12+

PhonePC/2in1TabletTVWearable

getRemoteProfileUuids(deviceId: string, callback: AsyncCallback<Array<ProfileUuids>>): void

获取对端蓝牙设备的Profile协议能力，通过UUID区分。使用Callback异步回调。

  • 建议仅对已配对的设备调用该方法。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取Profile协议能力。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
callback AsyncCallback<Array<ProfileUuids>> 是 回调函数。当获取UUID成功，err为undefined，获取到的是Profile协议能力集合；否则为错误对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err: BusinessError, data: Array<connection.ProfileUuids>) => {
  4.         console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data));
  5.     });
  6. } catch (err) {
  7.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  8. }

connection.getRemoteProfileUuids12+

PhonePC/2in1TabletTVWearable

getRemoteProfileUuids(deviceId: string): Promise<Array<ProfileUuids>>

获取对端蓝牙设备的Profile协议能力，通过UUID区分。使用Promise异步回调。

  • 建议仅对已配对的设备调用该方法。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取Profile协议能力。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
Promise<Array<ProfileUuids>> Promise对象，返回支持的Profile协议能力集合。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => {
  4.         console.info('getRemoteProfileUuids');
  5.     }, (err: BusinessError) => {
  6.         console.error('getRemoteProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  7.     });
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.getLocalName

PhonePC/2in1TabletTVWearable

getLocalName(): string

获取本机蓝牙设备的名称。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

返回值：

展开
类型 说明
string 本机蓝牙设备名称。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let localName: string = connection.getLocalName();
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.getPairedDevices

PhonePC/2in1TabletTVWearable

getPairedDevices(): Array<string>

获取已配对蓝牙设备的地址集合。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

返回值：

展开
类型 说明
Array<string>

已配对蓝牙设备的地址集合。

基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。

- 已配对的地址不会变更。

- 若该设备重启蓝牙开关，重新获取到的虚拟地址会立即变更。

- 若取消配对，蓝牙子系统会根据该地址的实际使用情况，决策后续变更时机；若其他应用正在使用该地址，则不会立刻变更。

- 若要持久化保存该地址，可使用access.addPersistentDeviceId方法。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let devices: Array<string> = connection.getPairedDevices();
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.getPairState11+

PhonePC/2in1TabletTVWearable

getPairState(deviceId: string): BondState

获取对端蓝牙设备的配对状态信息。

  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取配对状态信息。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
BondState 表示设备的蓝牙配对状态。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX");
  4.     console.info('getPairState: ' + res);
  5. } catch (err) {
  6.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  7. }

connection.getProfileConnectionState

PhonePC/2in1TabletTVWearable

getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState

获取蓝牙Profile协议的连接状态，其中ProfileId为可选参数。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
profileId ProfileId 否

表示Profile协议的枚举值。如果携带ProfileId，则返回指定Profile协议的连接状态。如果未携带ProfileId，则检查所有支持的Profile连接状态，按如下优先级顺序检查并返回：

- 存在已连接的Profile协议，则返回STATE_CONNECTED。

- 存在正在连接的Profile协议，则返回STATE_CONNECTING。

- 存在正在断连的Profile协议，则返回STATE_DISCONNECTING。

- 以上条件均不满足，则返回STATE_DISCONNECTED。

返回值：

展开
类型 说明
ProfileConnectionState Profile协议的连接状态。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Incorrect parameter types.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900004 Profile not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. import { constant } from '@kit.ConnectivityKit';
  3. try {
  4.     let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE);
  5. } catch (err) {
  6.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  7. }

connection.setDevicePairingConfirmation

PhonePC/2in1TabletTVWearable

setDevicePairingConfirmation(deviceId: string, accept: boolean): void

收到对端蓝牙设备的配对请求事件后，确认请求结果。

需要权限：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH（该权限仅系统应用可申请）

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
accept boolean 是 是否接受对端设备的配对请求。true表示接受，false表示不接受。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // 订阅“pinRequired”配对请求事件，收到对端配对请求后设置配对确认。
  3. function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data为配对请求的入参，配对请求参数。
  4.     console.info('pin required  = '+ JSON.stringify(data));
  5.     connection.setDevicePairingConfirmation(data.deviceId, true);
  6. }
  7. try {
  8.     connection.on('pinRequired', onReceivePinRequiredEvent);
  9. } catch (err) {
  10.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  11. }

connection.setDevicePinCode

PhonePC/2in1TabletTVWearable

setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void

蓝牙配对时，弹框提示用户输入个人身份识别码（Personal identification number，PIN），调用此接口设置PIN码，完成蓝牙配对。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。
code string 是 用户输入的PIN码，该字符串的字符个数范围为(0, 16]，例如："12345"。
callback AsyncCallback<void> 是 回调函数，当设置PinCode成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // callback
  3. try {
  4.     connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => {
  5.         console.info('setDevicePinCode,device name err: ' + JSON.stringify(err));
  6.     });
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.setDevicePinCode

PhonePC/2in1TabletTVWearable

setDevicePinCode(deviceId: string, code: string): Promise<void>

蓝牙配对时，弹框提示用户输入PIN码，调用此接口请求用户输入PIN码，完成蓝牙配对。使用Promise异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。
code string 是 用户输入的PIN码，该字符串的字符个数范围为(0, 16]，例如："12345"。

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // promise
  3. try {
  4.     connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => {
  5.         console.info('setDevicePinCode');
  6.     }, (error: BusinessError) => {
  7.         console.error('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message);
  8.     })
  9. 

  10. } catch (err) {
  11.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  12. }

connection.setLocalName(deprecated)

PhonePC/2in1TabletTVWearable

setLocalName(name: string): void

设置本机蓝牙设备名称，不能设置为空字符串。如果设为空字符串会失败。

说明

从API version 10开始支持，从API version 12开始废弃，不再提供替代接口。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
name string 是 需要设置的蓝牙名称，名称长度范围：(0, 248]，单位：Byte。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     connection.setLocalName('device_name');
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.setBluetoothScanMode

PhonePC/2in1TabletTVWearable

setBluetoothScanMode(mode: ScanMode, duration: number): void

设置蓝牙扫描模式，决定本机设备是否可被连接，或者可被发现。搭配onScanModeChange接口使用，可实时监听蓝牙扫描模式变更事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
mode ScanMode 是 蓝牙扫描模式。当扫描模式为SCAN_MODE_GENERAL_DISCOVERABLE时，超出duration持续时间(不为0)，扫描模式会重新设置为SCAN_MODE_CONNECTABLE。
duration number 是 设备可被发现的持续时间，单位：ms。设置为0则表示持续可发现。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     // 设置为可连接可发现才可被对端设备扫描到，可以连接。
  4.     connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100);
  5. } catch (err) {
  6.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  7. }

connection.getBluetoothScanMode

PhonePC/2in1TabletTVWearable

getBluetoothScanMode(): ScanMode

获取蓝牙扫描模式。搭配onScanModeChange接口使用，可实时监听蓝牙扫描模式变更事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

返回值：

展开
类型 说明
ScanMode 蓝牙扫描模式。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let scanMode: connection.ScanMode = connection.getBluetoothScanMode();
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.startBluetoothDiscovery

PhonePC/2in1TabletTVWearable

startBluetoothDiscovery(): void

开启蓝牙扫描，发现对端蓝牙设备。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: Array<string>) {
  3.     console.info('data length' + data.length);
  4. }
  5. try {
  6.     connection.on('bluetoothDeviceFind', onReceiveEvent);
  7.     connection.startBluetoothDiscovery();
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.stopBluetoothDiscovery

PhonePC/2in1TabletTVWearable

stopBluetoothDiscovery(): void

关闭蓝牙扫描。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     connection.stopBluetoothDiscovery();
  4. } catch (err) {
  5.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6. }

connection.isBluetoothDiscovering11+

PhonePC/2in1TabletTVWearable

isBluetoothDiscovering(): boolean

判断本机蓝牙设备是否处于设备扫描状态。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

返回值：

展开
类型 说明
boolean 是否开启蓝牙发现。true表示正在发起设备扫描，false表示未发起设备扫描。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.     let res: boolean = connection.isBluetoothDiscovering();
  4.     console.info('isBluetoothDiscovering: ' + res);
  5. } catch (err) {
  6.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  7. }

connection.setRemoteDeviceName12+

PhonePC/2in1TabletTVWearable

setRemoteDeviceName(deviceId: string, name: string): Promise<void>

设置对端蓝牙设备的名称，不能设置为空字符串。如果设为空字符串会失败。使用Promise异步回调。

  • 建议仅对已配对的设备调用该方法。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址进行名称设置。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。
name string 是 修改对端设备名称，名称长度范围：(0, 64]，单位：Byte。

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
2900001 Service stopped.
2900003 Bluetooth disabled.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // promise
  3. try {
  4.     connection.setRemoteDeviceName('11:22:33:44:55:66', 'RemoteDeviceName').then(() => {
  5.         console.info('setRemoteDeviceName success');
  6.     }, (error: BusinessError) => {
  7.         console.error('setRemoteDeviceName: errCode: ' + error.code + ',errMessage' + error.message);
  8.     })
  9. } catch (err) {
  10.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  11. }

connection.getRemoteDeviceBatteryInfo12+

PhonePC/2in1TabletTVWearable

getRemoteDeviceBatteryInfo(deviceId: string): Promise<BatteryInfo>

获取对端蓝牙设备的电量信息。使用Promise异步回调。

  • 对端蓝牙设备的电量信息变更通过on('batteryChange')的回调结果获取。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取电量信息。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示对端蓝牙设备的MAC地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
Promise<BatteryInfo> Promise对象，返回电量信息对象。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
2900001 Service stopped.
2900003 Bluetooth disabled.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // promise
  3. try {
  4.     connection.getRemoteDeviceBatteryInfo('11:22:33:AA:BB:FF').then((data: connection.BatteryInfo) => {
  5.         console.info('getRemoteDeviceBatteryInfo success, DeviceType:' + JSON.stringify(data));
  6.     });
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.on('batteryChange')12+

PhonePC/2in1TabletTVWearable

on(type: 'batteryChange', callback: Callback<BatteryInfo>): void

订阅对端设备的电量信息变化事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'batteryChange'，表示对端设备的电量信息变化事件。当该设备通知电量变化时，会触发该事件。
callback Callback<BatteryInfo> 是 指定订阅的回调函数，返回电量信息。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => {
  3.     console.info('BatteryInfo = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('batteryChange', onReceiveEvent);
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.off('batteryChange')12+

PhonePC/2in1TabletTVWearable

off(type: 'batteryChange', callback?: Callback<BatteryInfo>): void

取消订阅对端设备的电量信息变化事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'batteryChange'，表示对端设备的电量信息变化事件。
callback Callback<BatteryInfo> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.on('batteryChange')中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => {
  3.     console.info('BatteryInfo = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('batteryChange', onReceiveEvent);
  7.     connection.off('batteryChange', onReceiveEvent);
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.on('bluetoothDeviceFind')

PhonePC/2in1TabletTVWearable

on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void

订阅蓝牙设备扫描结果上报事件。使用Callback异步回调。

  • 可扫描到的设备类型包括传统蓝牙设备和低功耗蓝牙设备。

  • 该上报方式只支持获取设备地址信息。

  • 推荐使用API version 18开始支持的connection.on('discoveryResult')扫描上报方式，可获取到更多设备信息，包括设备地址、设备信号强度、设备名称和设备类型。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'bluetoothDeviceFind'，表示蓝牙设备扫描结果上报事件。当调用connection.startBluetoothDiscovery后，开始设备扫描，若扫描到设备，触发该事件。
callback Callback<Array<string>> 是

指定订阅的回调函数，会携带扫描到的设备地址集合。

基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。

- 已配对的地址不会变更。

- 若该设备重启蓝牙开关，重新获取到的虚拟地址会立即变更。

- 若取消配对，蓝牙子系统会根据该地址的实际使用情况，决策后续变更时机；若其他应用正在使用该地址，则不会立刻变更。

- 若要持久化保存该地址，可使用access.addPersistentDeviceId方法。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: Array<string>) { // data为蓝牙设备地址集合。
  3.     console.info('bluetooth device find = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('bluetoothDeviceFind', onReceiveEvent);
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.off('bluetoothDeviceFind')

PhonePC/2in1TabletTVWearable

off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void

取消订阅蓝牙设备扫描结果上报事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'bluetoothDeviceFind'，表示蓝牙设备扫描结果上报事件。
callback Callback<Array<string>> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.on('bluetoothDeviceFind')中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: Array<string>) {
  3.     console.info('bluetooth device find = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('bluetoothDeviceFind', onReceiveEvent);
  7.     connection.off('bluetoothDeviceFind', onReceiveEvent);
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.on('bondStateChange')

PhonePC/2in1TabletTVWearable

on(type: 'bondStateChange', callback: Callback<BondStateParam>): void

订阅蓝牙配对状态变化事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是

事件回调类型，支持的事件为'bondStateChange'，表示蓝牙配对状态变化事件。

当调用connection.pairDevice发起主动配对，或者本机设备收到其他设备的配对请求时，触发该事件。
callback Callback<BondStateParam> 是 指定订阅的回调函数，会携带配对状态结果。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: connection.BondStateParam) { // data为回调函数入参，表示配对的状态。
  3.     console.info('pair state = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('bondStateChange', onReceiveEvent);
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.off('bondStateChange')

PhonePC/2in1TabletTVWearable

off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void

取消订阅蓝牙配对状态变化事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'bondStateChange'，表示蓝牙配对状态变化事件。
callback Callback<BondStateParam> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.on('bondStateChange')中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: connection.BondStateParam) {
  3.     console.info('bond state = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('bondStateChange', onReceiveEvent);
  7.     connection.off('bondStateChange', onReceiveEvent);
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.on('pinRequired')

PhonePC/2in1TabletTVWearable

on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void

订阅配对请求事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是

事件回调类型，支持的事件为'pinRequired'，表示配对请求事件。

当调用connection.pairDevice发起主动配对，或者本机设备收到其他设备的配对请求时，触发该事件。
callback Callback<PinRequiredParam> 是 指定订阅的回调函数，会携带配对请求。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: connection.PinRequiredParam) { // data为配对请求参数。
  3.     console.info('pin required = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('pinRequired', onReceiveEvent);
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.off('pinRequired')

PhonePC/2in1TabletTVWearable

off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void

取消订阅配对请求事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'pinRequired'，表示配对请求事件。
callback Callback<PinRequiredParam> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.on('pinRequired')中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. function onReceiveEvent(data: connection.PinRequiredParam) {
  3.     console.info('pin required = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('pinRequired', onReceiveEvent);
  7.     connection.off('pinRequired', onReceiveEvent);
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.on('discoveryResult')18+

PhonePC/2in1TabletTVWearable

on(type: 'discoveryResult', callback: Callback<Array<DiscoveryResult>>): void

订阅蓝牙设备扫描结果上报事件。使用Callback异步回调。

  • 可扫描到的设备类型包括传统蓝牙设备和低功耗蓝牙设备。

  • 该上报方式支持获取设备地址、设备信号强度、设备名称和设备类型。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'discoveryResult'，表示蓝牙设备扫描结果上报事件。当调用connection.startBluetoothDiscovery后，开始设备扫描，若扫描到设备，触发该事件。
callback Callback<Array<DiscoveryResult>> 是 指定订阅的回调函数，会携带扫描结果的集合。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data为蓝牙设备扫描结果集合。
  3.     console.info('bluetooth device find = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('discoveryResult', onReceiveEvent);
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.off('discoveryResult')18+

PhonePC/2in1TabletTVWearable

off(type: 'discoveryResult', callback?: Callback<Array<DiscoveryResult>>): void

取消订阅蓝牙设备发现上报事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
type string 是 事件回调类型，支持的事件为'discoveryResult'，表示蓝牙设备扫描结果上报事件。
callback Callback<Array<DiscoveryResult>> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.on('discoveryResult')中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data为蓝牙设备扫描结果集合。
  3.     console.info('bluetooth device find = '+ JSON.stringify(data));
  4. }
  5. try {
  6.     connection.on('discoveryResult', onReceiveEvent);
  7.     connection.off('discoveryResult', onReceiveEvent);
  8. } catch (err) {
  9.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.onScanModeChange23+

PhonePC/2in1TabletTVWearable

onScanModeChange(callback: Callback<ScanMode>): void

订阅蓝牙扫描模式变更事件。使用Callback异步回调。当调用setBluetoothScanMode更改当前蓝牙扫描模式后，如订阅此事件，则会收到携带最新扫描模式的回调函数。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
callback Callback<ScanMode> 是 指定订阅的回调函数，会携带变更后最新的蓝牙扫描模式。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. function ScanModeChangeEvent(scanMode: connection.ScanMode) {
  2.     console.info(`Scan mode has changed, new mode: ${scanMode}`);
  3. }
  4. try {
  5.     connection.onScanModeChange(ScanModeChangeEvent);
  6. } catch (err) {
  7.     console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
  8. }

connection.offScanModeChange23+

PhonePC/2in1TabletTVWearable

offScanModeChange(callback?: Callback<ScanMode>): void

取消订阅蓝牙扫描模式变更事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
callback Callback<ScanMode> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.onScanModeChange中的回调函数一致；若无传参，则取消订阅所有蓝牙扫描模式变更的回调函数通知。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. function ScanModeChangeEvent(scanMode: connection.ScanMode) {
  2.     console.info(`Scan mode has changed, new mode: ${scanMode}`);
  3. }
  4. try {
  5.     connection.offScanModeChange(ScanModeChangeEvent);
  6. } catch (err) {
  7.     console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
  8. }

connection.getLastConnectionTime15+

PhonePC/2in1TabletTVWearable

getLastConnectionTime(deviceId: string): Promise<number>

获取对端蓝牙设备最近一次连接的时间点。使用Promise异步回调。

  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址获取最近一次连接时间。

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示远端设备MAC地址。例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
Promise<number> Promise对象，返回对端蓝牙设备最近一次连接的时间点，格式为秒级的UNIX时间戳。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

展开
错误码ID 错误信息
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // promise
  3. try {
  4.     connection.getLastConnectionTime('11:22:33:44:55:66').then((time: number) => {
  5.         console.info(`connectionTime: ${time}`);
  6.     });
  7. } catch (err) {
  8.     console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  9. }

connection.connectAllowedProfiles16+

PhonePC/2in1TabletTVWearable

connectAllowedProfiles(deviceId: string, callback: AsyncCallback<void>): void

连接对端设备支持的profile（只包括A2DP、HFP和HID）。使用Callback异步回调。

  • API版本26.0.0之前，需先调用connection.pairDevice发起配对，且仅允许在每次发起配对后30秒内调用此接口一次。
  • 从API版本26.0.0开始，针对A2DP和HFP，调用接口无时间限制，可以在调用connection.pairDevice发起配对后任意时间内进行调用。
  • 当配对成功后，建议先调用getRemoteProfileUuids主动查询目标设备支持的profile能力。若存在应用需要的能力，才调用此接口。
  • 需要与接口connection.disconnectAllowedProfiles配合使用。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址进行profile连接。

需要权限： ohos.permission.ACCESS_BLUETOOTH

系统能力：: SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示需要连接的对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。
callback AsyncCallback<void> 是 回调函数。当发起连接成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见 通用错误码说明文档和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.   connection.connectAllowedProfiles('68:13:24:79:4C:8C', (err: BusinessError) => {
  4.     if (err) {
  5.       console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  6.       return;
  7.     }
  8.     console.info('connectAllowedProfiles');
  9.   });
  10. } catch (err) {
  11.   console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  12. }

connection.connectAllowedProfiles16+

PhonePC/2in1TabletTVWearable

connectAllowedProfiles(deviceId: string): Promise<void>

连接对端设备支持的profile（只包括A2DP、HFP和HID）。使用Promise异步回调。

  • API版本26.0.0之前，需先调用connection.pairDevice发起配对，且仅允许在每次发起配对后30秒内调用此接口一次。
  • 从API版本26.0.0开始，针对A2DP和HFP，调用接口无时间限制，可以在调用connection.pairDevice发起配对后任意时间内进行调用。
  • 当配对成功后，建议先调用getRemoteProfileUuids主动查询目标设备支持的profile能力。若存在应用需要的能力，才调用此接口。
  • 需要与接口connection.disconnectAllowedProfiles配合使用。
  • 从API version 21开始，此接口支持使用对端设备的实际MAC地址进行profile连接。

需要权限： ohos.permission.ACCESS_BLUETOOTH

系统能力：: SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示需要连接的对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果。

错误码：

以下错误码的详细介绍请参见 通用错误码说明文档和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. try {
  3.   connection.connectAllowedProfiles('68:13:24:79:4C:8C').then(() => {
  4.       console.info('connectAllowedProfiles');
  5.     }, (err: BusinessError) => {
  6.       console.error('connectAllowedProfiles:errCode' + err.code + ', errMessage: ' + err.message);
  7.   });
  8. } catch (err) {
  9.   console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  10. }

connection.disconnectAllowedProfilesBeta

PhonePC/2in1TabletTVWearable

disconnectAllowedProfiles(deviceId: string): Promise<void>

断开对端设备支持的profile（只包括A2DP和HFP）。

起始版本： 26.0.0

需要权限： ohos.permission.ACCESS_BLUETOOTH

系统能力：: SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
deviceId string 是 表示需要断开连接的对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。

返回值：

展开
类型 说明
Promise<void> Promise对象。无返回结果。

错误码：

以下错误码的详细介绍请参见 通用错误码说明文档和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported. Failed to call the API when the short-range chip is not inserted on 2in1 device.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

示例：

收起
自动换行
深色代码主题
复制
  1. try {
  2.   await connection.disconnectAllowedProfiles('68:13:24:79:4C:8C');
  3. } catch (err) {
  4.   console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
  5. }

connection.getVirtualAddressByHash24+

PhonePC/2in1TabletTVWearable

getVirtualAddressByHash(algorithmType: HashAlgorithmType, hashValue: string): string

根据已配对设备实际MAC地址的哈希值获取对应的虚拟MAC地址。

当HashAlgorithmType为HASH_ALGORITHM_SHA256时，应使用大写实际MAC地址通过SHA256算法生成对应的哈希值（十六进制64位），取后32位作为输入，哈希值字母不区分大小写。

需要权限： ohos.permission.ACCESS_BLUETOOTH

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Communication.Bluetooth.Core

参数：

展开
参数名 类型 必填 说明
algorithmType HashAlgorithmType 是 哈希算法类型。
hashValue string 是 哈希值，例如："c10b57deb2e1aafd255596e0d4fd6789"。

返回值：

展开
类型 说明
string 返回与哈希值相对应的设备虚拟MAC地址，例如："XX:XX:XX:XX:XX:XX"，返回地址为大写。

错误码：

以下错误码的详细介绍请参见 通用错误码说明文档和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801 Capability not supported. Failed to call the API when the short-range chip is not inserted on 2in1 device.
2900003 Bluetooth disabled.
2900015 Parameter format mismatch with specification.
2900016 Device unpaired.
2900099 Internal system error. For example, IPC error. Detailed error messages can be used to assist in locating the problem.

示例：

收起
自动换行
深色代码主题
复制
  1. // 若查询的真实地址为11:22:33:44:55:AA,
  2. // 对应的64位哈希值为 d2204cb9b6d3d3962cc90fa54130efb4c10b57deb2e1aafd255596e0d4fd6789,
  3. // 当HashAlgorithmType为HASH_ALGORITHM_SHA256时取后32位哈希值
  4. let hashValue: string = "c10b57deb2e1aafd255596e0d4fd6789";
  5. try {
  6.   let addr: string = connection.getVirtualAddressByHash(connection.HashAlgorithmType.HASH_ALGORITHM_SHA256, hashValue);
  7. } catch (err) {
  8.   console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
  9. }

connection.onAclStateChangeBeta

PhonePC/2in1TabletTVWearable

onAclStateChange(callback: Callback<AclStateResult>): void

订阅蓝牙ACL链路连接状态变化事件。当触发蓝牙ACL链路连接与断开连接时，如订阅此事件，则会收到携带对应设备的地址与连接状态的回调函数。

起始版本： 26.0.0

需要权限：ohos.permission.ACCESS_BLUETOOTH 或 (ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.GET_BLUETOOTH_PEERS_MAC)

系统能力：SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
callback Callback<AclStateResult> 是 回调函数，返回蓝牙外设连接状态

错误码：

以下错误码的详细介绍请参见 通用错误码说明文档和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801

Capability not supported.

Failed to call the API when the short-range chip is not inserted on 2in1 device.
2900099

Internal system error.

For example, IPC error. Detailed error messages can be used to assist in locating the problem.

示例：

收起
自动换行
深色代码主题
复制
  1. function AclStateChangeEvent(aclStateResult: connection.AclStateResult) {
  2.     console.info('acl state changed:'+ JSON.stringify(aclStateResult));
  3. }
  4. try {
  5.     connection.onAclStateChange(AclStateChangeEvent);
  6. } catch (err) {
  7.     console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
  8. }

connection.offAclStateChangeBeta

PhonePC/2in1TabletTVWearable

offAclStateChange(callback?: Callback<AclStateResult>): void

取消订阅蓝牙ACL链路连接状态变化事件。

起始版本： 26.0.0

需要权限：ohos.permission.ACCESS_BLUETOOTH 或 (ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.GET_BLUETOOTH_PEERS_MAC)

系统能力：SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
callback Callback<AclStateResult> 否

指定取消订阅的回调函数通知。

若传参，则需与connection.onAclStateChange中的回调函数一致；若无传参，则取消订阅所有蓝牙ACL连接状态变更的回调函数通知。

错误码：

以下错误码的详细介绍请参见 通用错误码说明文档和蓝牙服务子系统错误码。

展开
错误码ID 错误信息
201 Permission denied.
801

Capability not supported.

Failed to call the API when the short-range chip is not inserted on 2in1 device.
2900099

Internal system error.

For example, IPC error. Detailed error messages can be used to assist in locating the problem.

示例：

收起
自动换行
深色代码主题
复制
  1. function AclStateChangeEvent(aclStateResult: connection.AclStateResult) {
  2.     console.info('acl state changed:'+ JSON.stringify(aclStateResult));
  3. }
  4. try {
  5.     connection.offAclStateChange(AclStateChangeEvent);
  6. } catch (err) {
  7.     console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
  8. }

BondStateParam

PhonePC/2in1TabletTVWearable

描述配对状态结果的参数结构。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 类型 只读 可选 说明
deviceId string 否 否 配对中的对端设备地址。
state BondState 否 否 配对状态。
cause12+ UnbondCause 否 否 配对失败的原因。

PinRequiredParam

PhonePC/2in1TabletTVWearable

描述配对请求的参数结构。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 类型 只读 可选 说明
deviceId string 否 否 要配对的对端设备地址。
pinCode string 否 否 配对过程中的密钥。

DeviceClass

PhonePC/2in1TabletTVWearable

描述蓝牙设备的类型。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 类型 只读 可选 说明
majorClass MajorClass 否 否 主要类型。是蓝牙标准协议中定义的类型字段。
majorMinorClass MajorMinorClass 否 否 子类型，是在主要类型上基础上进一步细分的类型。是蓝牙标准协议中定义的类型字段。
classOfDevice number 否 否 设备类型。是蓝牙标准协议中定义的类型字段，包含了MajorClass、MajorMinorClass和支持的主要服务这三种设备信息。

BatteryInfo12+

PhonePC/2in1TabletTVWearable

描述设备的电量信息。

只有支持蓝牙标准协议定义的电量信息AT（Attention）命令（包括：+XEVENT和IPHONEACCEV）的设备才支持上报有效的电量信息。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 类型 只读 可选 说明
batteryLevel number 否 否

表示设备的电量值。

如果该值为-1，表示没有电量信息。
leftEarBatteryLevel number 否 否

若是蓝牙耳机设备类型，表示左侧耳机的电量值。

如果该值为-1，表示没有电量信息。
leftEarChargeState DeviceChargeState 否 否 若是蓝牙耳机设备类型，表示左侧耳机的充电状态。
rightEarBatteryLevel number 否 否

若是蓝牙耳机设备类型，表示右侧耳机的电量值。

如果该值为-1，表示没有电量信息。
rightEarChargeState DeviceChargeState 否 否 若是蓝牙耳机设备类型，表示右侧耳机的充电状态。
boxBatteryLevel number 否 否

若是蓝牙耳机设备类型，表示耳机仓的电量值。

如果值该为-1，表示没有电量信息。
boxChargeState DeviceChargeState 否 否 若是蓝牙耳机设备类型，表示耳机仓的充电状态。

BluetoothTransport

PhonePC/2in1TabletTVWearable

枚举，表示设备传输类型。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 值 说明
TRANSPORT_BR_EDR 0 传统蓝牙（Basic Rate/Enhanced Data Rate，BR/EDR）设备传输方式。
TRANSPORT_LE 1 低功耗蓝牙（Bluetooth Low Energy，BLE）设备传输方式。
TRANSPORT_DUAL20+ 2 同时支持传统蓝牙（BR/EDR）和低功耗蓝牙（BLE）的双模设备传输方式。设备可以根据需要选择使用传统蓝牙（BR/EDR）或低功耗蓝牙（BLE）进行通信。
TRANSPORT_UNKNOWN20+ 3 未知的设备传输方式。

ScanMode

PhonePC/2in1TabletTVWearable

枚举，表示扫描模式。该模式决定设备是否可被发现或可被连接。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 值 说明
SCAN_MODE_NONE 0 不可发现、不可连接模式。
SCAN_MODE_CONNECTABLE 1 可连接模式。
SCAN_MODE_GENERAL_DISCOVERABLE 2 通用可发现模式，可被长时间发现。
SCAN_MODE_LIMITED_DISCOVERABLE 3 有限可发现模式，持续一定时间。
SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE 4 可连接及通用可发现模式。
SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE 5 可连接及有限可发现模式。

BondState

PhonePC/2in1TabletTVWearable

枚举，配对状态。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 值 说明
BOND_STATE_INVALID 0 未配对状态。
BOND_STATE_BONDING 1 配对中的状态。
BOND_STATE_BONDED 2 已配对状态。

UnbondCause12+

PhonePC/2in1TabletTVWearable

枚举，配对失败原因。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 值 说明
USER_REMOVED 0 用户主动移除设备。若配对状态BondState是已配对，也表示配对成功。
REMOTE_DEVICE_DOWN 1 对端设备不在线。例如：对端设备蓝牙是关闭的。
AUTH_FAILURE 2 鉴权失败。例如：两端设备密钥不匹配。
AUTH_REJECTED 3 鉴权被拒绝。例如：对端设备拒绝了配对请求。
INTERNAL_ERROR 4 内部错误。例如：设备不支持配对、配对过程超时等异常。

DeviceChargeState12+

PhonePC/2in1TabletTVWearable

枚举，表示设备当前的充电状态。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 值 说明
DEVICE_NORMAL_CHARGE_NOT_CHARGED 0 不支持超级快充能力的设备当前处于未充电状态。
DEVICE_NORMAL_CHARGE_IN_CHARGING 1 不支持超级快充能力的设备当前处于充电状态。
DEVICE_SUPER_CHARGE_NOT_CHARGED 2 支持超级快充能力的设备当前处于未充电状态。
DEVICE_SUPER_CHARGE_IN_CHARGING 3 支持超级快充能力的设备当前处于充电状态。

DiscoveryResult18+

PhonePC/2in1TabletTVWearable

扫描到设备后，上报的扫描结果。

系统能力：SystemCapability.Communication.Bluetooth.Core

展开
名称 类型 只读 可选 说明
deviceId string 否 否

扫描到的设备地址。

基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。

- 已配对的地址不会变更。

- 若该设备重启蓝牙开关，重新获取到的虚拟地址会立即变更。

- 若取消配对，蓝牙子系统会根据该地址的实际使用情况，决策后续变更时机；若其他应用正在使用该地址，则不会立刻变更。

- 若要持久化保存该地址，可使用access.addPersistentDeviceId方法。
rssi number 否 否 扫描到的设备信号强度，单位：dBm。
deviceName string 否 否 扫描到的设备名称。
deviceClass DeviceClass 否 否 扫描到的设备类型。

HashAlgorithmType24+

PhonePC/2in1TabletTVWearable

枚举，表示哈希算法类型。

哈希算法是一种数学函数，通过对输入数据进行复杂计算，生成一个唯一且固定长度的字符串（即哈希值）。常用于数据完整性校验、数字签名等场景。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Communication.Bluetooth.Core

展开
名称 值 说明
HASH_ALGORITHM_SHA256 0 SHA256哈希算法。

AclStateResultBeta

PhonePC/2in1TabletTVWearable

描述ACL连接状态的参数结构。

起始版本： 26.0.0

系统能力：SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

展开
名称 类型 只读 可选 说明
deviceId string 否 否 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。
state AclState 否 否 连接状态。

AclStateBeta

PhonePC/2in1TabletTVWearable

枚举，表示ACL连接状态。

起始版本： 26.0.0

系统能力： SystemCapability.Communication.Bluetooth.Core

模型约束： 此接口仅可在Stage模型下使用。

展开
名称 值 说明
STATE_CONNECTED 0 ACL链路已连接。
STATE_DISCONNECTED 1 ACL链路已断开连接。
@ohos.bluetooth.ble (蓝牙ble模块)
@ohos.bluetooth.constant (蓝牙constant模块)
相关推荐
文档@ohos.bluetooth.baseProfile (蓝牙baseProfile模块)
文档@ohos.bluetooth.constant (蓝牙constant模块)
文档@ohos.bluetooth.hid (蓝牙hid模块)
文档@ohos.bluetooth.common (蓝牙common模块)
文档@ohos.bluetooth.pan (蓝牙pan模块)
文档@ohos.bluetooth.map (蓝牙map模块)
文档@ohos.bluetooth.access (蓝牙access模块)
文档@ohos.bluetooth (蓝牙)
文档@ohos.bluetooth.pbap (蓝牙pbap模块)
文档@ohos.bluetoothManager (蓝牙)
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词