蓝牙服务特征值 PRO#

BluetoothCharacteristic 表示蓝牙服务（BluetoothService）中的一个特征值，是 BLE 设备数据交互的核心单元。每个特征值由唯一 UUID 标识，并定义了支持的操作类型、当前值、通知状态等属性。

一、属性字段#

uuid: string#

特征值的 UUID（统一唯一标识符），用于识别特征的类型。

• 示例：

  • "2A37" 表示标准心率测量特征
  • "6E400002-B5A3-F393-E0A9-E50E24DCCA9E" 是一个自定义特征 UUID

serviceUUID: string | null#

当前特征值所属服务的 UUID，如果服务未被发现则可能为 null。

properties: BluetoothCharacteristicProperty[]#

当前特征值支持的操作类型，是以下字符串枚举值组成的数组（可能同时包含多个）：

可用的属性（BluetoothCharacteristicProperty 枚举）：#

示例判断：#

1if (characteristic.properties.includes("read")) {
2  const value = await peripheral.readValue(characteristic)
3}

isNotifying: boolean#

当前是否处于通知（notify）或指示（indicate）订阅状态。

• true: 已启用订阅，设备会推送值变化
• false: 未启用订阅

可通过 peripheral.subscribe() 和 unsubscribe() 控制通知状态。

value: Data | null#

当前特征值的内容，通常在调用 readValue() 或接收到通知时更新。

• Data 为 Scripting 提供的二进制数据类型
• 若尚未读取或写入，此字段可能为 null

二、特征权限#

虽然 BluetoothCharacteristic 接口本身不包含权限字段，但在创建或定义特征值（如 Peripheral 模式）时可用下列权限枚举类型：

BluetoothAttributePermissions 枚举（权限类型）#

三、操作示例#

读取特征值（需支持 "read"）#

1if (characteristic.properties.includes("read")) {
2  const value = await peripheral.readValue(characteristic)
3  console.log("读取到内容:", value?.toRawString())
4}

写入特征值（需支持 "write" 或 "writeWithoutResponse"）#

1const data = Data.fromRawString("COMMAND")
2if (characteristic.properties.includes("writeWithoutResponse")) {
3  await peripheral.writeValue(characteristic, data, "withoutResponse")
4} else if (characteristic.properties.includes("write")) {
5  await peripheral.writeValue(characteristic, data, "withResponse")
6}

订阅通知（需支持 "notify" 或 "indicate"）#

1if (characteristic.properties.includes("notify")) {
2  await peripheral.subscribe(characteristic, (error, value) => {
3    if (!error && value) {
4      console.log("收到通知:", value.toHexString())
5    }
6  })
7}

取消通知订阅#

1await peripheral.unsubscribe(characteristic)

四、使用建议与注意事项#

• 特征值操作前必须调用 discoverCharacteristics(service) 获取特征值列表。
• 不要假设所有特征值都支持读写，请根据 properties 判断支持的操作。
• 通知（Notify）和指示（Indicate）必须先调用 subscribe()，停止时需配套调用 unsubscribe()。
• 使用 "writeWithoutResponse" 时，建议配合 canSendWriteWithoutResponse 状态控制频率。
• 写入前建议调用 maxWriteValueLength() 获取最大支持长度。