HarmonyOS 鸿蒙Next蓝牙设备App线下开发——JSAPI 接口描述（下）

搜寻附近的蓝牙外围设备

hilink.startBluetoothDevicesDiscovery (services, allowDuplicatesKey, interval)

开始搜寻附近的蓝牙外围设备。

API版本：1

函数参数说明：

参数	类型	描述
services	array	当前搜索的蓝牙设备的广播数据段中的 ServiceUUIDs 数据段（UUID字符串数组）示例：[‘0000ffe0-0000-1000-8000-00805f9b34fb’, ‘0000ffe1-0000-1000-8000-00805f9b34fb’, ‘0000ffe2-0000-1000-8000-00805f9b34fb’]
allowDuplicatesKey	Boolean	是否允许重复上报同一设备，如果允许重复上报，则hilink.onBluetoothDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同。 iOS：true表示允许，false不允许 Android：true表示不允许，false表示允许
interval	Number	上报设备的间隔，默认为0，意思是找到新设备立即上报，否则根据传入的间隔上报

参数

类型

描述

services

array

当前搜索的蓝牙设备的广播数据段中的 ServiceUUIDs 数据段（UUID字符串数组）

示例：[‘0000ffe0-0000-1000-8000-00805f9b34fb’, ‘0000ffe1-0000-1000-8000-00805f9b34fb’, ‘0000ffe2-0000-1000-8000-00805f9b34fb’]

allowDuplicatesKey

Boolean

是否允许重复上报同一设备，如果允许重复上报，则hilink.onBluetoothDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同。

iOS：true表示允许，false不允许
Android：true表示不允许，false表示允许

interval

Number

上报设备的间隔，默认为0，意思是找到新设备立即上报，否则根据传入的间隔上报

返回值说明：

参数	类型	描述
retCode	Number	错误码：0，90001

说明

启动蓝牙设备发现后，系统以每3秒为周期进行蓝牙扫描，每一轮扫描的结果，会通过 hilink.onBluetoothDeviceFound 回调通知上层。
如果 interval 为0，在 iOS 系统中，每次只上报一个设备；在 Android 系统中，每次上报1个或多个设备。

停止搜寻附近的蓝牙外围设备

hilink.stopBluetoothDevicesDiscovery ()

停止搜寻附近的蓝牙外围设备。

API版本：1

返回值说明：

参数	类型	描述
retCode	Number	错误码：0，90001

监听寻找到新设备的事件

hilink.onBluetoothDeviceFound (CallbackName)

监听寻找到新设备的事件。

API版本：2

回调函数参数说明：

参数	类型	描述
devices	Array	android是Device数组，iOS是单个Device对象；Json字符串格式

Device参数说明：

参数	类型	描述
deviceId	String	用于区分设备的 id，Android 上获取到的 deviceId 为设备 MAC 地址，iOS 上则为设备 UUID。
RSSI	number	当前蓝牙设备的信号强度
advertisData	String	完整的广播数据（转换为16进制字符串输出）（Android 将字符全转大写，iOS 默认不处理）
manufacturerData	String	当前蓝牙设备的广播数据段中的 ManufacturerData 数据段（转换为16进制字符串输出，详情请参见接口定义规则中第四条）
advertisServiceUUIDs	array	当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段（UUID字符串数组）（Android为null）示例：[‘0000ffe0-0000-1000-8000-00805f9b34fb’, ‘0000ffe1-0000-1000-8000-00805f9b34fb’, ‘0000ffe2-0000-1000-8000-00805f9b34fb’]
localName	string	当前蓝牙设备的广播数据段中的 LocalName 数据段
serviceData	string	当前蓝牙设备的广播数据段中的 ServiceData 数据段（转换为16进制字符串输出，详情请参见接口定义规则中第四条）

说明

CallbackName可多次注册不同名称回调函数，已注册的全部回调函数，会在 hilink.stopBluetoothDevicesDiscovery 调用前生效。Hilink.stopBluetoothDevicesDiscovery 后，会清除回调注册。
hilink.onBluetoothDeviceFound 建议在 hilink.startBluetoothDevicesDiscovery 前调用，确保启动发现后每一次搜索到设备都能被准确回调。

连接低功耗蓝牙设备

hilink.createBLEConnection (deviceId)

连接低功耗蓝牙设备。

若在之前已有搜索过某个蓝牙设备，并成功建立链接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需进行搜索操作。

API版本：1

函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id

返回值说明：

参数	类型	描述
retCode	Number	错误码：0, 90001, 90009

断开与低功耗蓝牙设备的连接

hilink.closeBLEConnection (deviceId)

断开与低功耗蓝牙设备的连接。

API版本：1

函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id

返回值说明：

参数	类型	描述
retCode	Number	错误码：0, 90001, 90010

读取低功耗蓝牙设备的特征值

hilink.readBLECharacteristicValue (deviceId, serviceId, characteristicId, CallbackName)

读取低功耗蓝牙设备的特征值的值，以十六进制字符串返回。

API版本：1

函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id
serviceId	String	蓝牙特征值对应服务的 uuid
characteristicId	String	蓝牙特征值的 uuid

回调函数参数说明：

参数	类型	描述
data	String	返回特征值的值，以16进制字符串返回，详情请参见接口定义规则中第四条。
errCode	Number	错误码：0, 90001

对蓝牙设备写入数据

hilink.writeBLECharacteristicValue (deviceId, serviceId, characteristicId, data, CallbackName)

对蓝牙设备写入data数据。

API版本：1

函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id
serviceId	String	蓝牙特征值对应服务的 uuid（不使用4位的简写，用完整写法的UUID）
characteristicId	String	蓝牙特征值的 uuid（不使用4位的简写，用完整写法的UUID）
data	String	写入的二进制数据，以16进制字符串方式构造，详情请参见接口定义规则中第四条。

回调函数参数说明：

参数	类型	描述
errCode	Number	错误码：0, 90001

说明

Android：
该方法默认延迟100ms
回调数据不是json格式，是一个0
该方法有返回值，0表示写入成功，90001表示写入失败
iOS ：无回调

通知低功耗蓝牙设备特征值的值

hilink.notifyBLECharacteristicValueChange (deviceId, serviceId, characteristicId, state)

通知低功耗蓝牙设备特征值的值，通过 onBLECharacteristicValueChange 返回值。

API版本：1

函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id
serviceId	String	蓝牙特征值对应服务的 uuid
characteristicId	String	蓝牙特征值的 uuid
state	Boolean	true: 启用 notify; false: 停用 notify

返回值说明：

参数	类型	描述
retCode	Number	错误码：0, 90001

监听低功耗蓝牙连接状态的改变事件

hilink.onBLEConnectionStateChange (CallbackName)

监听低功耗蓝牙连接状态的改变事件。

API版本：1

回调函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id
connected	Boolean	连接目前的状态

说明

CallbackName 可多次注册不同名称回调函数，已注册的全部回调函数，会在 hilink.closeBLEConnection 调用前生效。hilink.closeBLEConnection后，会清除回调注册。
hilink.onBLEConnectionStateChange 建议在 hilink.createBLEConnection 前调用，确保每一次连接状态都可以被准确接收。

监听低功耗蓝牙设备的特征值变化

hilink.onBLECharacteristicValueChange (CallbackName)

监听低功耗蓝牙设备的特征值变化。

API版本：1

回调函数参数说明：

参数	类型	描述
deviceId	String	蓝牙设备Id（Android没有返回）
serviceId	String	蓝牙特征值对应服务的 uuid（Android没有返回）
characteristicId	String	蓝牙特征值的 uuid
data	String	特征值最新的值，以16进制字符串方式构造，详情请参见接口定义规则中第四条。

说明

CallbackName可多次注册不同名称回调函数，已注册的全部回调函数，会在 hilink.closeBLEConnection 调用前生效。hilink.closeBLEConnection 后，会清除回调注册。

蓝牙设备建立连接后通知上层

hilink.onBLEServicesDiscovered(CallbackName)

蓝牙设备建立连接后，开始发现设备支持的服务，当服务发现完成，调用本接口通知上层。

API版本：1

回调函数参数说明：

参数	类型	描述
errCode	Number	0，表示发现了BLE服务。

说明

iOS：回调数据不是json格式，是一个0
CallbackName 可多次注册不同名称回调函数，已注册的全部回调函数，会在 hilink.closeBLEConnection 调用前生效。hilink.closeBLEConnection后，会清除回调注册。

对蓝牙设备发送数据

hilink.writeBLECharacteristicValueIsDelayTime(delayTime,deviceId,serviceId, characteristicId, data, CallbackName)（Android独有）

对蓝牙设备发送data数据。

API版本：1

函数参数说明：

参数	类型	描述
delayTime	Int	延迟delayTime毫秒写入数据(取值范围0-200，单位毫秒)
deviceId	String	蓝牙设备Id（Android：deviceId可为任意值）
serviceId	String	蓝牙特征值对应服务的 uuid
characteristicId	String	蓝牙特征值的 uuid
data	String	写入的二进制数据，以16进制字符串方式构造，详情请参见接口定义规则中第四条。

回调函数参数说明：

参数	类型	描述
errCode	Number	错误码：0, 90001

说明

该方法为 Android 独有的方法，iOS 没有此方法。
回调数据不是 json 格式，是一个0。
该方法有返回值，0表示写入成功，90001表示写入失败。

设置手机与已连接设备间的传输速率

hilink. requestConnectionPriority (int connectionPriority)（Android独有）

参数	类型	描述
connectionPriority	int	只能传0,1,2； 0 表示 Bluetooth 传输的默认值； 1 表示请求高优先级，低延迟连接，以便快速传输LE上的大量数据，传输完成请再次设置为0，降低功耗 2 表示请求低功耗，降低数据传输速率
返回值	类型	描述
retCode	int	0 成功 90001 失败

参数

类型

描述

connectionPriority

int

只能传0,1,2；

0 表示 Bluetooth 传输的默认值；

1 表示请求高优先级，低延迟连接，以便快速传输LE上的大量数据，传输完成请再次设置为0，降低功耗

2 表示请求低功耗，降低数据传输速率

返回值

类型

描述

retCode

int

0 成功

90001 失败

获取手机当前网络类型

hilink. getNetworkState(String CallbackName)

参数	类型	描述
CallbackName	String	回调函数的方法名

回调函数参数说明：

参数	类型	描述
state	Int	手机当前网络类型 0:未连网; 1：wifi; 2: 3G/4G;

设置Mtu成功后收到的监听

hilink.registerRequestMtu(String CallbackName) （Android独有）

设置蓝牙设备Mtu值，当设置成功时，调用本接口通知上层。

回调函数参数说明：

参数	类型	描述
status	Number	0,成功；非0，失败
mtu	Number	默认为设置值，超过手机与设备传输的最大值则返回最大值

说明

CallbackName 可多次注册不同名称回调函数，已注册的全部回调函数，会在 hilink.closeBLEConnection 调用前生效。hilink.closeBLEConnection 调用后，会清除回调注册。

设置蓝牙设备Mtu值

hilink. requestMtu(int mtu)（Android独有）

参数	类型	描述
mtu	Number	设置手机与设备传输的mtu值

设置启用指示还是启用通知

hilink. setEnableIndication (boolean isEnableIndication)（Android独有）

设置启用指示还是启用通知。

该方法需要和 notifyBLECharacteristicValueChange 配合使用，在 notifyBLECharacteristicValueChange 前调用；不设置默认是 false。

函数参数说明：

参数	类型	描述
isEnableIndication	boolean	true：启用指示 false：不启用指示，启用通知；不设置默认是 false

参数

类型

描述

isEnableIndication

boolean

true：启用指示

false：不启用指示，启用通知；不设置默认是 false

回调函数参数说明：无

说明

该方法为 Android 独有的方法，iOS 没有此方法。
该方法需要和 notifyBLECharacteristicValueChange 配合使用，在 notifyBLECharacteristicValueChange 前调用。

Native 控制

标题栏显示/隐藏

hilink.setTitleVisible (isVisible)

参数说明：

参数	类型	描述
isVisible	boolean	true：整个标题栏可见 false：整个标题栏不可见

参数

类型

描述

isVisible

boolean

true：整个标题栏可见

false：整个标题栏不可见

标题栏中标题显示/隐藏

hilink.setTitleNameVisible (isVisible)

参数说明：

参数	类型	描述
isVisible	boolean	true：标题栏中标题可见 false：标题栏中标题不可见

参数

类型

描述

isVisible

boolean

true：标题栏中标题可见

false：标题栏中标题不可见

退出当前页面

hilink. finishDeviceActivity()

回退到上一个界面

hilink.overrideBackPressed ()

点击网页返回键时回退到上一个界面，无参数

重写安卓物理返回键及原生标题（安卓+iOS）返回键

hilink. overrideBackPressed ()

当重写安卓物理返回键及原生标题（包括 iOS 和 Android）返回键时，WEB 中调用 js 方法如下：

hilink. overrideBackPressed (
     enable,    //boolean, true启用，false不启用
     resultCallback  //string，成功或失败时，将调用传入resultStr返回结果
);

示例：

hilink. overrideBackPressed(
    true,
    “resultCallback”
);

回调函数示例：

//web页面中需实现该函数，用来获取执行结果
function resultCallback  (resultStr) {
      var result = resultStr;    //请求的返回结果
}

返回九宫格页面

hilink. moveToMainActivity()

在特定界面（详情页点击点击放大进入厂家开发的H5界面）调用此方法回到九宫格界面。

添加指定的打印信息

hilink. h5ConsoleLogPrint(String msgTag,String msgInfo)

参数说明：

参数	类型	描述
msgTag	String	打印信息的信息头
msgInfo	String	打印信息的信息内容

调整标题栏状态

hilink.modifyTitleBar(boolean isWhite, String color, String resultCallback)

参数说明：

参数	类型	描述
isWhite	boolean	表示顶部状态栏状态，true表示白色图标、标题字体为白色，false再看color的值
color	String	在isWhite为false时生效，为“0”表示黑色图标、标题字体为黑色，非“0”表示蓝色图标，标题字体为黑色，非0时必须以“#FFFFFF”格式传入，不能为null
resultCallback	String	暂时无用，但不能为null，可以传个“”

获取手机状态栏高度

hilink. getStatusBarHeight(String resultCallback)

参数	类型	描述
resultCallback	String	回调函数的方法名

回调函数参数说明：

参数	类型	描述
statusBarHeight	Int	手机状态栏高度（单位:dp）

跳转到设置界面

hilink. jumpTo (String uri, String resultCallback)（Android独有）

uri 固定传入值为：com.huawei.smarthome.deviceSettingActivity

参数	类型	描述
uri	String	传入对应的字符串
resultCallback	String	回调函数的方法名

判断当前设备是否是共享设备

hilink. isShareDevice(String deviceId) （Android独有）

判断当前设备是否是共享设备，true表示共享设备，false表示非共享设备

参数	类型	描述
deviceId	String	蓝牙设备Id

判断当前设备是否需要提示固件升级

hilink. isNeedUpgrade(String deviceId, String versionNumber) （Android独有）

判断当前设备是否需要提示固件升级, true表示需要 false表示不需要

参数	类型	描述
deviceId	String	蓝牙设备Id
versionNumber	String	传入的固件版本号码

判断当前手机EMUI系统是否是EMUI10

hilink. isEmuiTen () （Android独有）

判断当前手机EMUI系统是否是EMUI10，true表示是，false表示不是。

此接口主要是针对EMUI10设备在蓝牙设备页面关闭蓝牙，再次打开蓝牙，设备无法连接问题。

获取当前模式

hilink. getDarkMode () （Android独有）

获取当前模式：1：正常模式 2：深色模式

改变设备标题样式

hilink. changeTitleStyle(int styleValue) （Android独有）

改变设备标题样式：

标题居中风格（默认）
EMUI10.0风格，标题居左

只可选择一种样式，不可切换。

跳转到华为商城

hilink. gotoVmall (int suffix) （Android独有）

跳转到华为商城。

参数	类型	描述
suffix	String	跳转到华为商城某个产品页面的后缀。例：“https://www.vmall.com/product/10086769875080.html”为华为手环网址，则要跳转到手环页面，suffix填“/product/10086769875080.html”。

参数

类型

描述

suffix

String

跳转到华为商城某个产品页面的后缀。

例：“https://www.vmall.com/product/10086769875080.html”为华为手环网址，则要跳转到手环页面，suffix填“/product/10086769875080.html”。

错误码定义

错误码	说明	备注
0	ok	正常
90001	internal error, system error	内部错误/系统错误
90002	data too large	DATA数据过大或过小
90003	no space in this account	同帐号下，存储空间已用完
90004	lack of system space	系统存储空间不足
90005	used in error location	函数在错误的场景被调用；或存在前后依赖的接口，在前述接口未调用前，调动该接口。
90006	device register failed	设备在云端注册失败
90007	device id error	输入的hilink设备Id错误
90008	data format error	输入的数据格式错误
90009	connect ble device failed	连接BLE蓝牙设备失败
90010	disconnect ble device failed	断开BLE蓝牙设备失败
90011	download failed	文件下载失败
90012	device duplicate	设备重复了

ionicwang 1楼•12 天前

这个是华为手环的函数吗

eggper 2楼•12 天前

这个是APP线下开发的~~~

yibo5220 3楼•12 天前

这份文档比较详细，感谢提供

yibo5220 4楼•12 天前

我在使用api的时候，很多都会报错，按照错误码去看文档，发现文档里面根本没有这个错误码，只能说文档还不够完善，很多api都没说明条件的限制，这就导致接口报错了也不知道是哪里出了问题。

songsunli 5楼•12 天前

确实

yuanlaile 6楼•12 天前

有要学HarmonyOS AI的同学吗，联系我：https://www.itying.com/goods-1206.html

phonegap100 7楼•12 天前作者

蓝牙设备没有修改设备名称的接口啊？要怎么修改设备名称啊？

songsunli 8楼•12 天前

请问有跳转华为内置的“故障提醒”界面的接口吗

gougou168 9楼•12 天前

作为IT专家，对于HarmonyOS鸿蒙Next蓝牙设备App线下开发的JSAPI接口描述（下），可以提供以下专业解答：

在HarmonyOS鸿蒙Next的蓝牙设备App线下开发中，JSAPI接口提供了丰富的功能，包括搜寻附近的蓝牙外围设备、连接与断开低功耗蓝牙设备、读取与写入蓝牙设备的特征值等。

具体来说，可以使用hilink.startBluetoothDevicesDiscovery函数开始搜寻附近的蓝牙设备，并通过hilink.onBluetoothDeviceFound回调函数监听寻找到的新设备。找到设备后，可以使用hilink.createBLEConnection函数连接低功耗蓝牙设备，使用hilink.closeBLEConnection函数断开连接。

在连接成功后，可以使用hilink.readBLECharacteristicValue函数读取蓝牙设备的特征值，使用hilink.writeBLECharacteristicValue函数向蓝牙设备写入数据。这些操作都涉及到设备的UUID、特征值UUID等参数。

此外，JSAPI接口还提供了设备管理功能，包括注册蓝牙设备、获取已注册和未注册的设备信息等。这些功能通过hilink.registerBleDevice、hilink.getCurrentUnregisteredDevice和hilink.getCurrentRegisteredDevice等函数实现。

在开发过程中，需要注意接口参数的定义和返回值处理，确保数据格式正确，避免错误码的出现。

如果问题依旧没法解决请联系官网客服，官网地址是：https://www.itying.com/category-93-b0.html 。