HarmonyOS 6.1.1 星闪CDSM实战：用createCdsmClient实现多设备集合状态订阅

鸿蒙专家

在万物互联场景中，一对星闪耳机实际上是“左耳”与“右耳”两个独立射频单元组成的合作设备集合。传统蓝牙只能以单点地址配对，应用无法感知副耳的状态，而硬件厂商常用的主副耳方案在弱网环境下易出现失步和断连。HarmonyOS 6.1.1 (API 24) 的 NearLink Kit 引入了 CDSM（Coordinated Devices Set Management）能力，通过 createCdsmClient 构建套件级管理链路，配合 getCdsmInfo 主动查询和 onCdsmInfoChange 订阅变更，让应用能实时掌控集合内每个子单元的连接状态。下面我们结合实战代码解析核心用法。

2. import { cdsm } from '@kit.NearLinkKit';
3. import { BusinessError, Callback } from '@kit.BasicServicesKit';
5. // 创建星闪 CDSM 客户端
6. let cdsmClient: cdsm.CdsmClient | null = null;
7. try {
8.     cdsmClient = cdsm.createCdsmClient('00:11:22:33:AA:FF');
9. } catch (err) {
10.     let error = err as BusinessError;
11.     if (error.code === 201) {  // 权限不足
12.         console.error('缺少 ohos.permission.ACCESS_NEARLINK');
13.     } else if (error.code === 801) {  // 硬件不支持
14.         console.error('当前设备不支持星闪 CDSM');
15.     } else {
16.         console.error(`创建失败: ${error.code} - ${error.message}`);
17.     }
18. }
20. // 主动查询集合信息
21. function queryMembers() {
22.     if (!cdsmClient) return;
23.     try {
24.         const info: cdsm.CdsmInfo = cdsmClient.getCdsmInfo();
25.         info.members.forEach((member, index) => {
26.             console.info(`成员${index}: 地址=${member.address}, 状态=${member.state}`);
27.         });
28.     } catch (err) {
29.         let error = err as BusinessError;
30.         if (error.code === 1009700003) {
31.             console.warn('星闪开关未打开，请在控制中心开启');
32.         }
33.     }
34. }
36. // 订阅状态变化
37. let callback: Callback<cdsm.CdsmInfo> = (data) => {
38.     console.info('集合信息变化', JSON.stringify(data.members));
39.     // 更新UI
40. };
41. try {
42.     cdsmClient?.onCdsmInfoChange(callback);
43. } catch (err) {
44.     console.error('订阅失败', (err as BusinessError).message);
45. }
47. // 页面销毁时务必取消订阅
48. // cdsmClient?.offCdsmInfoChange(callback);  // 精确取消
49. // cdsmClient?.offCdsmInfoChange();          // 取消所有订阅

复制代码

实战中需注意几个关键点：
1. 权限配置：在 module.json5 中声明 ohos.permission.ACCESS_NEARLINK，这是系统级权限，需用户授权。
2. 入参校验：createCdsmClient 的 address 必须是已配对的星闪设备 MAC 地址，格式为 00:11:22:33:AA:FF。建议先用正则校验，示例：/^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/。
3. 异常处理：除了权限(201)和硬件不支持(801)，还要捕获星闪关闭异常(1009700003)，在 UI 中给出明确提示。
4. 生命周期管理：onCdsmInfoChange 订阅的回调函数句柄需保持唯一引用，在页面销毁时调用 offCdsmInfoChange 取消订阅，防止内存泄漏。
5. 类型安全：ArkTS 严格模式下，建议用类包装返回的成员数据，避免 untyped object literals 编译错误，如定义 MemberDisplay 类包含 address、state、name 属性。

通过以上 API 组合，开发者可以彻底摆脱传统单点配对的局限，实现星闪耳机、智能穿戴套件等“多单元单体”设备的统一状态管理。无论是左耳在盒充电、右耳在线使用，还是主副设备无缝切换，应用都能实时感知并做出响应。在 HarmonyOS 6.1.1 的强类型环境下，遵循上述代码模式和异常处理规范，可以快速构建高可靠的星闪 CDSM 功能模块。

热心网友3

感谢楼主分享这么详细的 HarmonyOS 6.1.1 星闪 CDSM 实战教程！代码和异常处理都写得很清楚，特别是对权限、硬件不支持、星闪开关关闭这几个常见错误码的捕获处理，对实际开发非常有帮助。之前一直在用传统的蓝牙主副耳方案，确实会遇到弱网失步的问题，CDSM 这种能实时订阅每个子单元状态的方式很实用。想请教一下，如果集合内的设备中途更换（比如换了另一只耳机），是否需要先销毁旧的 cdsmClient 再重新 create？还是说集合信息变更回调会自动更新成员列表？