鸿蒙PC 外设编排与系统能力调用实战:用 ArkUI 把「热插拔—能力探测—系统调用」收敛成一条可观测状态机

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper


前言:鸿蒙PC 和手机在「设备能力」这件事上有一处根本差别,不是屏幕尺寸,而是外设密度。一台 2in1 桌面设备上,USB-C 移动固态盘、Wi-Fi 局域网打印机、HID 数位板、蓝牙耳机、外接摄像头、副屏显示器可以同时挂着;用户什么时候拔一个、插一个,应用事先完全不知道。桌面应用如果只写「点击按钮 → 执行一次」的线性逻辑,很快就会在三个地方失守:状态漂移(界面显示在线,实际链路已断)、日志被淹(一次热插拔刷十几行,用户看不到关键那一行)、权限静默失败(调用没抛异常,但什么也没发生)。

本文以配套工程「外枢 · Periphery」为例,讲清楚如何在鸿蒙PC 上用 ArkUI 声明式 UI 把这四类动作——枚举接入、能力探测、能力下发、链路拔出——收敛成一台会话级可观测状态机,并给出一条把上层交互接到真实系统能力的契约层。工程的界面、状态迁移、时序与日志滚动都是真实跑通的;与系统 Kit 之间的边界用一层 CapabilityRouter 显式隔离,界面上如实标注「演示数据」,绝不把演示值包装成真机回执。这篇文章的技术价值在于那台状态机怎么设计,而不在于数字好不好看。

关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、ArkUI 声明式 UI、2in1 桌面形态、外设热插拔、能力探测、系统能力调用、事件总线、状态机、HID、USB、AtomGit。


一、问题定义:鸿蒙PC 桌面应用的「外设密度」困境

先明确四类动作的语义,后面所有代码都围绕它们展开:

动作触发源期望的可观测结果
枚举 / 接入用户插线,或点击槽位状态灯设备上线、能力清单刷新为「待探测」
能力探测用户点击「开始探测」进入探测中,若干毫秒后逐项确认能力
能力下发滑条、开关、按钮记录一次调用名、入参、返回摘要
链路拔出用户拔线,或再次点击状态灯设备下线、能力标记作废

手机应用里这四类动作常被合并成一条直线:点一下、给个 toast、结束。鸿蒙PC 上不行,因为外设是有持续链路的对象,用户会反复拔插同一台设备去验证「应用到底认不认得它」。我在设计这个实验台时定了三条约束,后文实现全为满足它们:

  1. 状态收敛到单一数据源。 一台外设的在线/离线、忙/闲、已探测/待探测,全部塞进同一个不可变对象,界面只从它派生,不允许第二处布尔值。
  2. 每次动作留下两行痕迹。 一行进「调用日志」(技术视角:调了什么、入参、返回什么),一行进底部「事件走带」(用户视角:刚刚发生了什么)。
  3. 能力调用必须走契约。 按钮里直接写系统 API,是这类工程最常见的债——换真机后一处权限变更要改十个地方。

二、事实边界:截图、工程与数据三者的关系

进入代码前先把材料分清。

第一类是截图。 本文 5 张配图全部是鸿蒙PC 真机上的完整桌面截图:底部有系统 Dock,右上角有系统状态栏与「11月15日」时间,背景是 DevEco Code 开发环境(左侧可见 AppScope / entry / hvigor 工程树与 build-profile.json5、oh-package.json5),前台是浅色的「外枢 Periphery」可拖拽窗口。系统桌面与应用窗口同框,读者一眼能确认运行平台,比任何文字描述都直接。

第二类是工程。 项目源码/Periphery_ohos,纯 ArkTS + ArkUI 声明式语法的 Stage 模型工程,应用名「外枢 · Periphery」,包名 com.periphery.bridge,versionName 1.0.0 / versionCode 1000000,deviceTypes 只有 2in1(桌面形态专用),compatibleSdkVersion 与 targetSdkVersion 均为 26.0.0,runtimeOS 为 HarmonyOS。它已构建出签名 HAP 并安装到鸿蒙PC 真机运行——界面上每一次点击反馈、槽位高亮、探测转圈、日志入栈与走带滚动,都是这个 HAP 真实执行的结果。

第三类是数据。 窗口右上角那枚「演示数据」胶囊不是装饰:设备档案里的带宽、电池百分比、IP 地址、压感级数,以及探测返回的「全部 5 项能力确认」,来自 Models.ets 的能力词库与状态机,不是抓到的 USB 描述符,也不是系统 Kit 的回执。本文不会把这些数值写成实测值。

那么「已完成」的是什么?是这条链路的结构:状态模型、三态迁移、探测时序、双环形日志、宽屏布局,以及一层可替换的能力契约。这些真实跑通、可直接复用;把契约层 handler 换成真实 Kit 调用,就能在不改 UI 的前提下接上真能力——第八章给完整对接清单。

最后交代用词:本文所有界面均为 ArkUI 声明式语法直写(@Entry / @Component / @State / @Builder),不是 ArkUI-X 跨平台分支。这两个名字常被混用:ArkUI 是鸿蒙原生声明式 UI 框架,ArkUI-X 是把它跨到其他平台的分支工程。讨论鸿蒙PC 桌面交互时,这个区分必须说清。

三、数据模型:把一台外设拆成 12 个可观测字段

外设档案最容易做错的地方,是把「在线」和「可用」当成一件事。真实场景里它们正交:设备插着(online = true),但正在被探测或正被别的进程占用(busy = true),此时不应答任何能力下发。common/Models.ets 用 12 个字段把这层语义拍平:

export interface Peripheral {
  id: string;          // 稳定标识,作为 ForEach key 的基座
  kind: DeviceKind;    // 六类设备族:storage/printer/tablet/audio/camera/display
  name: string;        // 中文名,事件走带里直接引用
  glyph: string;       // 单字形图标,免去图片资源
  bus: string;         // 物理链路,例如 'USB-C · 10 Gbps'
  detail: string;      // 档案副标题,例如 '压感 8192 级 · 266 PPS'
  bandwidth: string;   // 标称带宽
  battery: number;     // -1 表示总线供电,>=0 表示内置电池百分比
  online: boolean;     // 链路是否建立
  busy: boolean;       // 是否正在探测/占用
  caps: string[];      // 能力清单,来自能力词库
  probed: boolean;     // 能力是否已确认
}

三个设计决定值得展开。

其一,battery: -1 表示总线供电。 一个很省的建模技巧:省掉 powerType 枚举,又不用在渲染层判断 undefined:

Text(this.selected()!.battery < 0 ? '总线供电' : '内置电池 ' + this.selected()!.battery + '%')

其二,能力清单按设备族集中管理。 六类设备各 5 项能力,共 30 条文案,全部收在 CAP_LIBRARY:

const CAP_LIBRARY: CapPack = {
  storage: ['批量传输', '热插拔', 'TRIM 回收', '加密分区', 'SMART 健康度'],
  printer: ['双向通道', '墨量回读', '双面打印', '校准页', '队列优先级'],
  tablet:  ['压感级别', '倾角报告', '快捷键环', '防误触', '固件升级'],
  audio:   ['高保真解码', '主动降噪', '低延迟模式', '通话麦克风', '佩戴检测'],
  camera:  ['4K 采集', '自动曝光', '色彩档案', '隐私快门', '帧率协商'],
  display: ['HDR 映射', '色域配置', '刷新率协商', '夜览曲线', '画中画输入']
};

好处是「能力」变成数据而不是散落的 if。新增一台设备,只需在 createPeripherals() 里加一个对象,探测逻辑、渲染逻辑、日志文案全都不用动。

其三,normalizeCaps() 这个看起来多余的函数。 它只做一件事:把能力名的占位串换成正确文案。

export function normalizeCaps(caps: string[]): string[] {
  return caps.map((c: string): string => c.replace('打_kw', '打印'));
}

这不是凑数。能力名会被当作索引键(ForEach 的 key、日志里的字段都对它敏感),改文案很容易漏一处;把修正收口到一个出口函数,比事后全局搜替换安全。工程里只有打印族的「双面打印」走这条通道,正好说明它的意义:热修一处,不碰词库本身。

设备族到配色的映射同样收口成 kindTone() / kindLabel() 两个纯函数,UI 层永远不写 switch。这是鸿蒙PC 宽屏上「一眼分辨设备类型」的基础:存储走铜色、打印走青绿、输入走琥珀、音频走绿、成像走红、显示走深铜。

四、状态机:三个方法覆盖外设全生命周期

pages/Index.ets 里三个动作方法构成整台实验台的骨架:toggleDevice()、startProbe()、pushCall()/pushEvent()。

4.1 接入 / 拔出:一次不可变替换

toggleDevice(target: Peripheral): void {
  const next = !target.online;
  this.devices = this.devices.map((d: Peripheral): Peripheral => {
    if (d.id === target.id) {
      return {
        id: d.id, kind: d.kind, name: d.name, glyph: d.glyph, bus: d.bus,
        detail: d.detail, bandwidth: d.bandwidth, battery: d.battery,
        online: next, busy: false, caps: d.caps, probed: next ? d.probed : false
      };
    }
    return d;
  });
  this.pushEvent((next ? '接入' : '拔出') + '「' + target.name + '」', next ? PeriColors.green : PeriColors.red);
  this.pushCall('device.' + (next ? 'attach' : 'detach'), target.bus,
    next ? '枚举成功 · 就绪' : '设备已下线', next ? PeriColors.green : PeriColors.red);
}

四个细节都是踩过才写对的:

  1. 整体重排数组,而不是原地改对象。 ArkUI 的 @State 对数组的观测依赖「重新赋值」。原地 d.online = true 不保证触发刷新,map() 返回新数组是确定能触发的写法。
  2. 新建对象时 12 个字段全部写全。 ArkTS 不做接口字段放宽,少写一个直接编译报错——这是好事,它逼你在迁移状态时把每个字段都想一遍。
  3. 拔出时 probed 必须清零。 设备下线后能力清单不能再显示「已确认」,否则插回来会出现「假已探测」绿徽标。probed: next ? d.probed : false 是状态一致性的关键。
  4. 状态位与动作文案分开表达。 第一版我把「在线显示接入、离线显示拔出」写进同一个三元表达式,结果在线设备上的按钮语义反转:用户以为点了会接入,实际是拔出。正确做法是让按钮描述点击后将发生的动作(在线 → 「拔出」),而不是描述当前状态。这条已经修在工程里,读者复刻时别再踩。

4.2 能力探测:两次 map + 一个 900 ms 时序

探测是唯一有「中间态」的动作。它必须先把设备置为 busy,让界面立刻有反馈,再在延时后落终态:

startProbe(target: Peripheral): void {
  if (!target.online) {
    this.pushCall('capability.probe', target.name, '设备离线,无法探测', PeriColors.red);
    return;
  }
  this.pushCall('capability.probe', target.name, '正在逐项探测…', PeriColors.brass);
  this.devices = this.devices.map((d: Peripheral): Peripheral => {
    if (d.id === target.id) {
      return { id: d.id, kind: d.kind, name: d.name, glyph: d.glyph, bus: d.bus,
        detail: d.detail, bandwidth: d.bandwidth, battery: d.battery,
        online: d.online, busy: true, caps: d.caps, probed: d.probed };
    }
    return d;
  });
  setTimeout(() => {
    this.devices = this.devices.map((d: Peripheral): Peripheral => {
      if (d.id === target.id) {
        return { id: d.id, kind: d.kind, name: d.name, glyph: d.glyph, bus: d.bus,
          detail: d.detail, bandwidth: d.bandwidth, battery: d.battery,
          online: d.online, busy: false, caps: d.caps, probed: true };
      }
      return d;
    });
    this.pushEvent('「' + target.name + '」能力探测完成', PeriColors.brass);
    this.pushCall('capability.probe', target.name, '全部 ' + target.caps.length + ' 项能力确认', PeriColors.green);
  }, 900);
}

为什么是 900 ms:低于 500 ms 用户感觉不到「正在探测」,高于 1500 ms 像卡死。900 ms 刚好让槽位右上角状态灯走完一轮「琥珀 → 绿」,日志里落下两条记录(开始、结束),形成一段可读时序。真实 USB 描述符枚举通常比这快得多,但这个中间态的意义不是模拟耗时,而是证明 UI 有能力承载异步结果:真机对接时把 setTimeout 换成 Kit 的 Promise 回调,外面这层状态迁移一个字不用改。

busy 与 probed 的分离在这里体现价值:探测期间设备是 online: true, busy: true, probed: false,界面同时显示「状态:探测中」与「待探测」两个徽标,语义不打架。如果只用一个枚举,你就得为「在线但探测中」再造一个状态值,越加越乱。

4.3 ForEach 的 key 必须包含状态位

这是鸿蒙PC 宽屏界面上最容易「看着没反应」的一处。槽位列表的 key 是:

ForEach(this.devices, (d: Peripheral) => {
  this.SlotCard(d)
}, (d: Peripheral) => d.id + (d.online ? 'on' : 'off') + (d.busy ? 'b' : ''))

如果 key 只写 d.id,设备接入/拔出后组件复用旧节点,卡片上的状态灯颜色、文字、边框高亮全部不更新——数据是对的,界面是死的。把 online 和 busy 拼进 key,等于告诉 ArkUI「这个槽位的内容语义变了,请重建」。这是 ArkUI 里「不可变数据 + 稳定 key」这一对搭档的典型用法:数据不可变保证刷新,key 带状态保证重建。

五、双环形缓冲:调用日志与事件走带

一个桌面实验台如果只有状态没有痕迹,就无法自证。所以每条动作都要落两条记录,走两个不同的观察面:

pushCall(name: string, arg: string, result: string, tone: string): void {
  const call: SysCall = { id: this.nextId, time: clockText(), name: name, arg: arg, result: result, tone: tone };
  this.nextId = this.nextId + 1;
  this.calls = [call].concat(this.calls).slice(0, 30);
}

pushEvent(text: string, tone: string): void {
  const entry: EventEntry = { id: this.nextId, time: clockText(), text: text, tone: tone };
  this.nextId = this.nextId + 1;
  this.events = [entry].concat(this.events).slice(0, 24);
}

几个刻意的选择:

  • [x].concat(arr).slice(0, N) 而不是 unshift + push。 一次表达式同时完成「插到队首」和「裁掉尾部」,不会出现中间态数组;而且 concat 返回新数组,对 @State 观测最稳。
  • 容量不对称:日志 30 条、事件 24 条。 日志是技术流水,需要更多上下文;走带是给用户扫一眼的,「最近几条」比「很多条」有效。底部走带渲染时再 slice(0, 6),容量与可见量解耦。
  • nextId 单一游标贯穿两个列表。 两个 ForEach 的 key 都取 id.toString(),共用游标保证同一动作的两个视图 id 唯一递增,永远不会因为删减导致 key 冲突。
  • pushCall 的 tone 直接存色值。 日志行的圆点、结论文字共用同一个颜色,避免「调用成功但结论是红的」这种自相矛盾。

clockText() 用 ('0' + n).slice(-2) 补零,比 padStart 少一个分支,也避开部分 ArkTS 环境里的兼容性顾虑。

六、布局:鸿蒙PC 宽屏的「三区一栏」

鸿蒙PC 的窗口宽度是这类工程最大的红利,也是最容易浪费的东西。common/Theme.ets 把关键度量抽成常量:

export class PeriMetrics {
  static readonly topRail: number = 62;   // 顶部抬头高度
  static readonly slotW: number = 168;    // 外设槽位宽
  static readonly slotH: number = 128;    // 外设槽位高
  static readonly logW: number = 300;     // 右侧日志栏固定宽
}

界面因此分成四块:顶部 62 px 抬头(应用名 + 在线计数 + 「演示数据」标注)、658 px 机架带(6 个 168×128 槽位横排)、下方主体(左档案卡 layoutWeight(1) + 右 300 px 试金石侧栏)、底部 48 px 深色事件走带。

两个决定值得说:

槽位用固定宽度而非百分比。 外设机架的产品语义是「插槽」,槽宽漂移会带来两个直接后果:一是「少了一台设备」看不出来(用户以为只是挤了一下),二是卡片内文字换行位置随机。固定 168 px + ForEach 横排,缺一台就是一个空洞,一眼可见。这在鸿蒙PC 的宽屏上尤其重要,因为窗口可以被拖到 2560 px 宽,百分比布局会把卡片拉成广告位。

右侧栏固定 300 px 而不是弹性。 调用日志是「流」,宽度一变化,maxLines(1) 的入参和结论就会被截断成两种不同的省略形态,读起来很跳。固定宽度让日志的换行节奏稳定,也让左档案卡的可用宽度随窗口自适应——大屏收益给正文,小屏牺牲给侧栏,这是桌面应用的常规取舍。

能力标签用 Flex({ wrap: FlexWrap.Wrap }) 承载,因为不同设备族的能力条数固定而文案长度不同(「SMART 健康度」明显长于「防误触」),Flex 的自动换行比 Row 溢出更稳。探测前全部用 faint 灰,探测后按设备族配色点亮:

@Builder
CapChip(label: string, lit: boolean, tone: string) {
  Text(label)
    .fontSize(PeriText.caption)
    .fontColor(lit ? tone : PeriColors.faint)
    .backgroundColor(lit ? PeriColors.panel : PeriColors.canvasDeep)
    .borderRadius(8)
    .padding({ left: 10, right: 10, top: 5, bottom: 5 })
    .border({ width: 1, color: lit ? tone : PeriColors.line })
}

「一个 chip 两种状态」比「亮/灰两套组件」省一半代码,也让「已探测/待探测」的视觉差异只取决于 lit 一个布尔值——又是一个单一数据源。

七、能力契约:从 SysCall 到真实系统 Kit 的一层路由器

前面所有动作最终都会落到 pushCall('clipboard.read', ...) 这样的调用名上。如果就此把它当成日志字符串,工程永远接不上真能力。所以这里补一层 CapabilityRouter:UI 只负责发「能力名 + 入参」,路由表负责找实现。它是纯 ArkTS、零 Kit 依赖、可独立编译的,可以直接放进 entry/src/main/ets/common/。

export type CallStatus = 'ok' | 'denied' | 'unsupported';

export interface CapabilityRequest {
  id: number;
  name: string;
  arg: string;
}

export interface HandlerOutcome {
  status: CallStatus;
  detail: string;
}

export interface CapabilityResult {
  id: number;
  status: CallStatus;
  detail: string;
}

export type CapabilityHandler = (arg: string) => HandlerOutcome;

export class CapabilityRouter {
  private table: Map<string, CapabilityHandler> = new Map<string, CapabilityHandler>();

  register(name: string, handler: CapabilityHandler): void {
    this.table.set(name, handler);
  }

  has(name: string): boolean {
    return this.table.has(name);
  }

  names(): string[] {
    const out: string[] = [];
    this.table.forEach((_h: CapabilityHandler, k: string) => {
      out.push(k);
    });
    return out;
  }

  dispatch(req: CapabilityRequest): CapabilityResult {
    const handler = this.table.get(req.name);
    if (handler === undefined) {
      return { id: req.id, status: 'unsupported', detail: '未注册的能力:' + req.name };
    }
    const outcome = handler(req.arg);
    return { id: req.id, status: outcome.status, detail: outcome.detail };
  }
}

注册与使用的完整片段(可直接替换掉工程里的 pushCall 直写):

const router: CapabilityRouter = new CapabilityRouter();

router.register('clipboard.read', (arg: string): HandlerOutcome => {
  // 真实实现:在此调用剪贴板服务,按返回码映射 status
  return { status: 'ok', detail: '读到 1 条文本 · ' + arg };
});

router.register('device.detach', (arg: string): HandlerOutcome => {
  if (arg.length === 0) {
    return { status: 'denied', detail: '缺少设备标识' };
  }
  return { status: 'ok', detail: '设备已下线' };
});

const result: CapabilityResult = router.dispatch({ id: 201, name: 'clipboard.read', arg: 'text/plain' });

路由表的价值有三个:其一,未注册的能力立刻返回 unsupported,而不是静默什么都不做——「沉默失败」是桌面工具类应用最伤用户的一种 bug;其二,denied 与 unsupported 分开,前者要引导授权,后者要提示设备不支持,两种文案完全不同;其三,UI 与实现彻底解耦,将来把某个 handler 换成真实 Kit 调用,界面代码零改动。

下面这张表是把面板动作映射到真实模块的门牌号。注意:这里给的是模块名与职责,具体函数签名以各 Kit 官方文档为准;工程当前用的是契约里的占位实现,接真能力时逐个替换 handler 即可。

面板动作真实模块(Kit)说明
移动固态盘 · 容量/遍历@ohos.file.fs、@ohos.file.storageStatistics卷信息、目录遍历、空间统计
移动固态盘 · 热插拔@ohos.usbManager设备列表与插拔通知
喷墨一体机@ohos.print打印任务、队列、状态
数位板 · 压感/倾角@ohos.multimodalInput.inputDevice输入设备能力查询与事件
降噪耳机@ohos.bluetooth音频设备连接与编解码协商
外接摄像头@ohos.multimedia.camera采集、曝光、隐私开关
副屏显示器@ohos.display屏幕列表、刷新率与 HDR 能力
读取剪贴板@ohos.pasteboard读写纯文本/富文本
截屏@ohos.screenshot全屏或窗口截图
震动反馈@ohos.vibrator短震自检
屏幕亮度 / 输出音量系统设置与音频服务亮度、音量曲线下发

接真能力时有三个硬约束,缺一个就会退回「看起来能用」:

  1. 权限必须在 module.json5 的 requestPermissions 里声明,且在首次调用时做用户可理解的授权引导,不能直接把系统弹窗甩给用户。
  2. 每个 handler 必须写错误码分支。 denied / unsupported / 超时 / 设备已拔出,四种结果要对应四种界面反馈,不能统一「操作失败」。
  3. 界面必须有降级态。 能力不可用时按钮置灰并给出原因,而不是点了没反应——这条在鸿蒙PC 的宽屏上尤其明显,用户有足够空间读一行解释。

八、鸿蒙PC 真机完整界面:五张桌面截图逐张读

下面 5 张图全部是鸿蒙PC 真机上的完整桌面截图,不是应用窗口裁剪图。读者可以同时看到:底部系统 Dock、右上系统状态栏与「11月15日」、背景里的 DevEco Code 工程树与项目结构页、以及前台可拖拽的应用窗口。

鸿蒙PC 真机完整桌面:外设机架与被拔出的降噪耳机档案

图 1 鸿蒙PC 真机完整桌面:选中「降噪耳机」槽位,档案卡显示总线「蓝牙 5.3 · LE Audio」、详情「LC3 编解码 · 双设备」、状态「已断开」,右侧调用日志最后两条是 capability.probe → 设备离线,无法探测 与 device.detach → 设备已下线

图 1 是整台实验台最有信息量的一帧:它同时呈现了离线设备的三处一致表达——槽位右上角状态灯变红、卡片状态行「状态:离线」变红、档案卡动作按钮切成绿色「接入」。这三处不是三份独立状态,全部从同一个 Peripheral.online 派生。右侧日志则证明「离线设备不能探测」这条前置校验真的生效了:调用被拦下并落了一行红色结论,而不是静默返回。

鸿蒙PC 真机完整桌面:副屏显示器档案与在线外设计数

图 2 鸿蒙PC 真机完整桌面:选中「副屏显示器」,顶部计数变为「在线外设 4 / 6」,档案给出 HDMI 2.1 · DPAlt、27 寸 4K · 60 Hz、HBR3 ×4,能力 chip 全部为「待探测」灰态

图 2 回答「计数从哪来」。顶部那枚「在线外设 4 / 6」是 onlineCount() 遍历数组算出来的,没有任何增量维护——派生状态永远不缓存,这样无论从哪个入口改了在线状态,计数都不会漂。这张图里还能看到「接入 / 拔出」两个事件已经在走带里滚过一轮(USB-A · UVC 整行红字),说明外接摄像头刚被拔出。

鸿蒙PC 真机完整桌面:移动固态盘档案与调用日志空态

图 3 鸿蒙PC 真机完整桌面:选中「移动固态盘」,总线 USB-C · 10 Gbps、卷标 WORKSPACE · 1 TB、通道状态「链路正常」,右侧日志显示空态提示「暂无调用,拖动滑条或点按钮试试」

图 3 值得单独讲的是空态文案。日志区为空时不是一片白,而是一句带引导的话(「拖动滑条或点按钮试试」)。桌面工具类应用的空态要承担教学职责,尤其是在鸿蒙PC 这种一屏能放很多控件的界面上——用户不知道该先动哪个,就用一句话告诉他。

鸿蒙PC 真机完整桌面:喷墨一体机档案与 Wi-Fi 链路

图 4 鸿蒙PC 真机完整桌面:选中「喷墨一体机」,总线 Wi-Fi 6E · 局域网、IP 192.168.3.28 · 就绪、标称带宽 24 MB/min,能力 chip「双向通道 / 墨量回读 / 双面打印 / 校准页 / 队列优先级」

图 4 是「同一套模型能不能容纳无线的外设」的验证。喷墨一体机走 Wi-Fi,bus 字段从 USB-C · 10 Gbps 换成 Wi-Fi 6E · 局域网,battery: -1 表示市电供电,模型一个字没改。这就是把链路信息放进数据的好处:有线无线只是字符串差异,状态机完全复用。

鸿蒙PC 真机完整桌面:数位板档案与内置电池字段

图 5 鸿蒙PC 真机完整桌面:选中「数位板」,USB-C · HID 复合、压感 8192 级 · 266 PPS、「内置电池 82%」,能力 chip 含「压感级别 / 倾角报告 / 快捷键环 / 防误触 / 固件升级」

图 5 落在 battery 字段上:82% 说明这台设备有内置电池,供电一栏因此显示「内置电池 82%」而不是「总线供电」。同一个三元表达式覆盖两种供电语义,界面没有多一个控件。

九、复现清单与七条实测踩坑

复现步骤(工程目录 项目源码/Periphery_ohos):

  1. 用 DevEco Studio 打开工程根目录,等待 hvigor 同步完成;
  2. 确认 entry/src/main/module.json5 中 deviceTypes: ['2in1'],build-profile.json5 中 compatibleSdkVersion 为 26.0.0;
  3. 连接鸿蒙PC 真机(或在 DevEco 里选择 2in1 形态设备),配置调试签名;
  4. 直接运行 entry 模块;应用名「外枢 · Periphery」,包名 com.periphery.bridge;
  5. 进入后先点任一槽位右上角状态灯切换接入/拔出,再点「开始探测」观察三态迁移与日志落栈。

踩坑一:@State 数组原地修改不刷新。 最初写 this.devices[i].online = true,界面毫无反应。改成 map() 返回新数组后立刻正常。规则:@State 装饰的数组/对象,改内容一律走「重新赋值」。

踩坑二:ForEach key 不带状态位。 现象比上一条更隐蔽:数据已更新、日志已打印,但卡片灯色不变。原因就是 key 相同导致节点复用。key 里拼 online 与 busy 是正解。

踩坑三:状态位与动作文案混用一个三元。 我在 4.1 节写过,在线设备上按钮显示「接入」,点击却执行拔出,用户会以为按钮坏了。按钮文案描述动作,状态徽标描述状态,两者不要共用同一个表达式。

踩坑四:Grid/Row 里塞自绘卡片导致高度塌陷。 槽位卡一开始不用固定高度,Text 换行时卡片高度抖动,整排机架高低不齐。给 slotW/slotH 固定值后稳定,也符合「插槽」语义。

踩坑五:Slider 的回调值不取整。 onChange 给的 value 带小数,直接拼到 72.000001% 的文案上很难看。Math.round(value) 后再赋值,同时保证 step: 1 与之对齐。

踩坑六:日志用 push 导致滚动方向反了。 先写的是追加到末尾,最新一条在最下面,用户必须手动滚。桌面宽屏日志区高度固定,改成 concat 插队首后,「最新在上」符合阅读习惯,也不需要额外滚动控制。

踩坑七:拔插时忘了清 probed。 表现为设备插回来就直接显示「已探测」,能力 chip 全亮。这是「假状态」,在真机对接时更危险——真实能力可能已经变化。状态迁移要把所有派生标记一并归零,这也是前面强调「12 个字段写全」的原因。

工程的完整源码已托管在 AtomGit(项目源码/Periphery_ohos 目录随文提交),读者可以直接拉取对照;本文所有代码片段与该工程一致,CapabilityRouter 为可独立编译的新增文件,放进 common/ 即可使用。

十、小结:桌面能力工程的三条可复用结论

回到最初的问题:鸿蒙PC 上的外设与系统能力调用,难点从来不是「怎么调一个 API」,而是怎么让用户随时知道现在的状态,以及刚才发生了什么。三条结论可以直接搬到下一个鸿蒙PC 项目:

  • 单一数据源 + 不可变替换 + 带状态的 key,这三件套解决 90% 的「界面不刷新」问题。ArkUI 的声明式语法不会替你做状态管理,它只是忠实地按你给的数据重建。
  • 每个动作留两行痕迹:技术日志给开发者,事件走带给用户。两者容量、可见量、文案风格都不同,不要合并成一个列表。
  • 能力调用收口到契约层。UI 只发「能力名 + 入参」,路由表决定实现与失败语义;unsupported 与 denied 必须分开,沉默失败在桌面工具里是不可接受的体验。

这台「外枢 · Periphery」目前完成的是交互底座:六类外设的档案模型、三态迁移、探测时序、双环形日志、宽屏三区布局,以及一层可替换的能力契约。下一步的路线很清楚——按第七章的模块表逐个把 handler 换成真实 Kit 调用,并为每一步补上权限引导、错误码分支与降级态。等这层接完,界面上那枚「演示数据」就可以摘掉了。技术栈上,这套界面全部由 ArkUI 原生写法完成,@Builder 复用卡片、@State 驱动状态、Flex 承载变长标签,没有引入任何跨平台中间层,这也是它在鸿蒙PC 上能保持原生交互手感的原因。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐