更新记录

1（2025-08-01）

上传插件

平台兼容性

uni-app(4.24)

uni-app x(4.24)

ZhiMiBLE API 文档

概述

ZhiMiBLE 是一个用于简化蓝牙低功耗(BLE)操作的封装库，提供了跨平台(iOS/Android)的统一API。

属性

eventType

包含所有BLE事件类型常量的对象：

• onBLEStatus: BLE状态变化事件
• onDeviceFounded: 发现设备事件
• getConnectDevice: 获取连接设备事件
• onConnectSuccess: 连接成功事件
• onDisconnect: 断开连接事件
• didDiscoverServices: 发现服务事件
• didDiscoverCharacteristicsForService: 发现特征事件
• didWriteValue: 写入值事件
• didUpdateNotificationStateForCharacteristic: 通知状态更新事件
• didUpdateValue: 值更新事件

WRITE_TYPE_WITH_RESPONSE

值为 0，表示写入操作需要响应

WRITE_TYPE_WITHOUT_RESPONSE

值为 1，表示写入操作不需要响应

方法

setListener(callback)

设置BLE事件监听器

• 参数:
  • callback: 事件回调函数

checkPermission(callback)

检查蓝牙权限

• 参数:
  • callback: 回调函数，接收权限检查结果
• 返回值: Promise对象，resolve参数为包含success属性的对象

parseEvent(evt)

解析并标准化BLE事件数据

• 参数:
  • evt: 原始事件对象
• 返回值: 处理后的事件对象

gotoAppSetting()

跳转到应用设置页面

getBleStatusInfo(status)

获取BLE状态信息

• 参数:
  • status: 状态码
• 返回值: 对应的状态信息对象

openBluetoothAdapter()

初始化蓝牙适配器

startBluetoothDevicesDiscovery()

开始扫描蓝牙设备

stopBluetoothDevicesDiscovery()

停止扫描蓝牙设备

connect(deviceIdOrMacAddress)

连接蓝牙设备

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址

disconnect(deviceIdOrMacAddress)

断开蓝牙设备连接

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址

getConnectDevice()

获取当前连接的设备

disconnectAll()

断开所有设备连接

discoverServices(deviceIdOrMacAddress)

发现设备的服务

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址

discoverCharacteristics(serviceId)

发现服务的特征

• 参数:
  • serviceId: 服务ID

setNotifyValueforCharacteristic(deviceIdOrMacAddress, serviceId, characteristicId)

为特征设置通知

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serviceId: 服务ID
  • characteristicId: 特征ID

setMtu(deviceIdOrMacAddress, mtu)

设置MTU值

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • mtu: MTU值

readValue(deviceIdOrMacAddress, serviceId, characteristicId)

读取特征值

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serviceId: 服务ID
  • characteristicId: 特征ID

writeValue(deviceIdOrMacAddress, serverId, characteristicId, value, isHex, writeType)

写入特征值

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serverId: 服务ID
  • characteristicId: 特征ID
  • value: 要写入的值
  • isHex: 是否为十六进制格式，默认为false
  • writeType: 写入类型，默认为0(需要响应)

writeStringValueWithResponse(deviceIdOrMacAddress, serverId, characteristicId, value)

以字符串格式写入特征值(需要响应)

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serverId: 服务ID
  • characteristicId: 特征ID
  • value: 要写入的字符串值

writeStringValueWithoutResponse(deviceIdOrMacAddress, serverId, characteristicId, value)

以字符串格式写入特征值(不需要响应)

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serverId: 服务ID
  • characteristicId: 特征ID
  • value: 要写入的字符串值

writeHexValueWithResponse(deviceIdOrMacAddress, serverId, characteristicId, value)

以十六进制格式写入特征值(需要响应)

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serverId: 服务ID
  • characteristicId: 特征ID
  • value: 要写入的十六进制值

writeHexValueWithoutResponse(deviceIdOrMacAddress, serverId, characteristicId, value)

以十六进制格式写入特征值(不需要响应)

• 参数:
  • deviceIdOrMacAddress: 设备ID或MAC地址
  • serverId: 服务ID
  • characteristicId: 特征ID
  • value: 要写入的十六进制值