鸿蒙PC 议台 Conclave 实战:用 ArkUI 把技术选型做成可评分、可回溯的 ADR 流水线——兼谈跨平台框架选型对照、派生计算性能与 6 类报错排查
鸿蒙PC 议台 Conclave 实战:用 ArkUI 把技术选型做成可评分、可回溯的 ADR 流水线——兼谈跨平台框架选型对照、派生计算性能与 6 类报错排查
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
前言:技术选型是团队里最容易"失忆"的一件事。三个月前为什么放弃 A 方案改用 B 方案、当时性能差多少、谁拍的板、后来又为什么退回去——这些信息通常只存在于某次语音会议和某个已经沉底的群聊里。等到新人接手或者线上出问题需要复议,大家只能靠记忆重新吵一遍,而且往往吵得更久,因为连"上次的结论"都没人说得清。手机端的应用场景把这个问题掩盖了:会话短、迭代快、一个人能拍板,选错了下次版本改回来就行。鸿蒙PC 的 2in1 桌面形态把代价放大了十倍——一个桌面端工具类应用的生命周期常常以年计,重构一次数据层的成本是手机上完全不同的量级,而团队里同时跑着平台组、数据组、架构组、质量组四条线,每条线都有自己的最优解。这时候"选型"不再是技术判断,而是一个需要有载体、有评分、有留痕、有阶段的治理流程。
本文拿一套真实的鸿蒙PC 工程当样本:应用「议台 Conclave」是一个纯 ArkTS + ArkUI 声明式 UI、只面向 2in1 形态的技术方案选型与 ADR(Architecture Decision Record,架构决策记录)治理实验台,
deviceTypes只保留['2in1'],SDK 26.0.0,零三方依赖,四个手写.ets文件。它把一次选型拆成四个工作面——三态泳道(提案池 / 评审中 / 已采纳)、五维加权评分矩阵(性能 30、成本 15、风险 20、可维护性 20、生态 15)、A/B 双列对照、ADR 决策记录与治理日志——并用"提交评审 → 评审通过采纳 → 退回重议"这条窄状态机,把"拍脑袋"变成"留证据"。文章走三条线:方案选型治理(五维权重怎么定、加权总分为什么算出来是 4 而不是 100、ADR 编号怎么发)、性能优化(
build()里 9 次filter的派生开销、ForEachkey 里为什么要拼阶段、评分条每次重建临时对象)、报错排查(6 类在鸿蒙PC 真机调试中真实会撞上的报错,逐条给根因与一行修复)。需要提前把话说清楚:本工程用的是 ArkUI,不是 ArkUI-X;文中出现的 ArkUI-X、Flutter、Compose Multiplatform 只在"跨平台框架选型对照"一节作为被评估的候选方案出现,工程里没有引入任何跨平台框架运行时。另外界面上的 5 条提案、3 张 ADR、以及"在审 2 · 已采纳 1"这类计数,全部来自Models.ets的本地演示常量,工程不连接任何后端(页脚已标注"演示数据");凡是能静态数出来的数字我都给文件与行号,凡是估算我都会说明估算依据,不把演示数据包装成实测性能。
关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、跨平台框架选型、ArkUI、ArkUI-X 对照、Flutter 对照、Compose Multiplatform 对照、ADR 架构决策记录、技术方案选型、加权评分矩阵、派生状态缓存、ForEach key、报错排查、AtomGit。

开篇图 鸿蒙PC 真机完整桌面:应用窗口停在议台主页。底部是系统 Dock(文件、浏览器、邮件、应用市场、云空间、图库等一整套系统图标),右下角是系统托盘与"下午1:02 / 11月15日"时间,窗口标题栏里最小化、最大化、关闭三个系统按钮齐全,左侧还能看到 DevEco Studio 的工程树。窗口内顶部是"◍ 议台 Conclave / 技术方案选型与 ADR 治理实验台",右上角状态胶囊写着"在审 3 · 已采纳 1"与"演示数据";中间一排三条泳道是提案池(1)/ 评审中(3)/ 已采纳(1);下排三块是评分矩阵(A/B 双列、五维评分条、加权总分)、深色 ADR 决策记录、治理日志
这张图是全文的入口,也是问题的完整呈现。请注意三个细节。
第一,同一屏里同时存在三个不同阶段的方案。评审中那一栏躺着"本地 SQLite + 差量同步"和"沿用分布式对象框架"——这是同一个议题(数据层改造)的两个互斥答案,它们被并排放在一起,而不是被分别写进两份文档。选型工具的第一价值不是"选出赢家",而是让候选方案在同一屏、同一口径、同一时间点被比较。
第二,右下角的 ADR 面板是一条时间轴,不是一篇文章。它按 ADR 编号倒序列出 ADR-011、ADR-010、ADR-008、ADR-007、ADR-003,每条两行:结论 + 依据。决策的"当时理由"和"后续如何被取代"被放在同一个视野里,这才叫可回溯。
第三,“在审 3 · 已采纳 1” 和泳道里的"(1)(3)(1)"是两个口径。前者是状态计数(countIn('review') + countIn('adopted')),后者是每列各自的容量。口径混用是治理工具最常见的失效原因:把"在审 3"当成"待办 3 条",你会排出错误的会;把"已采纳 1"当成"只剩 1 件事",你会漏掉标签页底下那 2 条已采纳的方案。议台的第一条设计原则就是:阶段用于分工,计数用于看板。
一、先把事实边界钉死:截图、工程、建议各是什么
技术文章最容易失信的地方,是把"我截到的界面"当成"我测到的数据"。所以先分三层,后面每一条论断都挂在这三层上。
第一层,问题样本:四张鸿蒙PC 真机完整截图。 四张都是同一台鸿蒙PC 设备的完整桌面,不是手机截图、不是应用内裁剪图、不是设计稿。四张连起来是一条完整的状态推进链:
| 图 | 状态胶囊 | 泳道分布 | ADR 面板 |
|---|---|---|---|
| 图 1(开篇图) | 在审 3 · 已采纳 1 | 1 / 3 / 1 | 最新 ADR-011 |
| 图 2 | 在审 2 · 已采纳 0 | 3 / 2 / 0 | 最新 ADR-010 |
| 图 3 | 在审 2 · 已采纳 1 | 2 / 2 / 1 | 最新 ADR-010,ADR-009 在列 |
| 图 4 | 在审 2 · 已采纳 2 | 1 / 2 / 2 | 最新 ADR-010、ADR-008、ADR-007 |
四张图跨度不到两分钟,但提案总数、阶段分布、ADR 条数、治理日志条数全在变——每一次点击都在同时改写四个工作面,这正是第三章要讨论的性能问题源头:状态不是散落在局部,而是一个中心 @State 集合。
第二层,配套工程:项目源码/Conclave_ohos。 一个纯 ArkTS / ArkUI 声明式 UI、Stage 模型的 2in1 工程,包名 com.conclave.governance,deviceTypes 只有 ['2in1'],compatibleSdkVersion 与 targetSdkVersion 均为 26.0.0,工程级与模块级 dependencies 全为空。它没有接数据库、没有接 HTTP、没有接任何分布式能力——界面上的 5 条提案、3 张 ADR、6 条治理日志种子,全部来自 Models.ets 的静态数据集。
第三层,本文的修复稿。 第三到第五章给出的 .ets 片段,是针对工程里静态可见缺陷的修改建议,全部用 ArkUI 原生能力写、可独立编译,文中逐条标明改哪个文件、改哪几行、改完能看到什么变化。它们不冒充实测性能报告,只承诺一件事:改前改后的差异可以用眼睛复现。
工程基线表(每一项都能在源码里查到,不是估值):
| 项 | 实际值 | 证据 |
|---|---|---|
| 应用 / 包名 | 「议台 Conclave」/ com.conclave.governance | AppScope/app.json5:3 |
| 版本 | versionCode 1000000、versionName 1.0.0 | AppScope/app.json5:5-6 |
| 设备形态 | 仅 ['2in1'],无 phone / tablet | entry/src/main/module.json5:7 |
| SDK | compatibleSdkVersion / targetSdkVersion 均 26.0.0 | build-profile.json5:21-22 |
| 构建模型 | hvigor + ohpm,Stage 模型,strictMode.useNormalizedOHMUrl: true | build-profile.json5:26 |
| 三方依赖 | 工程级、模块级 dependencies 均为 {} | oh-package.json5 |
| 页面入口 | windowStage.loadContent('pages/Index'),单页应用 | EntryAbility.ets:13 |
| 源码规模 | 4 个手写 .ets,约 700 行 | entry/src/main/ets/ |
| 状态中心 | Index.ets 441 行、7 个 @State、4 个 @Builder | pages/Index.ets:13-19 |
| 数据层 | Models.ets 205 行,5 提案 / 3 ADR / 5 维度 | common/Models.ets |
| 主题 | 硬编码色板 22 色 + 字号 6 级 | common/Theme.ets:1-34 |
这张表说明两件事。其一,这是一个零三方依赖的鸿蒙PC 原生 2in1 工程:进程启动后直接加载单页,没有框架运行时抢主线程,所以任何卡顿都更容易归因到业务代码本身;代价是所有聚合、求值、落盘都得自己写。其二,桌面形态适配只做了一半:下排三块用 layoutWeight(1) + 固定宽混排,没有跟随窗口宽度做断点收敛;hover 只做了点击态,没有做指针事件合并。
也必须坦白它的另一面:这个工程目前是方法论原型,不是可用的治理平台。三处证据:Models.ets 的提案评分是写死的常量,没有"谁打的分、什么时候打的";Index.ets 的治理日志只保留 20 条且只在内存里,应用退出即清空;ADR 编号靠 nextAdr 计数器递增,没有按人/按季度分段。换句话说,它验证的是流程形状,不是数据持久化。想把它变成真工具,第一件事是把 createProposals() 换成异步仓库、把 ADR 落盘成 JSON(甚至直接生成 docs/adr/NNNN-*.md),并给评分加"评分人 + 时间戳"两个字段。
二、方案选型治理:把"拍脑袋"拆成四次可验证的动作
2.1 五维权重不是拍出来的,是"返工成本"的函数
大多数团队的选型表长这样:一列候选方案、一列"性能"、一列"成本",打勾或者打星,最后由职级最高的人总结。这种表的失效原因不是维度不够,而是维度没有权重,且权重没有公开。议台把权重直接写成常量,摆在代码里让所有人改得动:
// common/Models.ets:48-54
export const DIM_SPECS: DimSpec[] = [
{ key: 'perf', label: '性能', weight: 30, tone: ConColors.lapis },
{ key: 'cost', label: '成本', weight: 15, tone: ConColors.gold },
{ key: 'risk', label: '风险', weight: 20, tone: ConColors.brick },
{ key: 'maint', label: '可维护性', weight: 20, tone: ConColors.sage },
{ key: 'eco', label: '生态', weight: 15, tone: ConColors.plum }
];
权重合计 100,其中性能独占 30——这个数字值得解释,因为它决定了整套工具的性格。鸿蒙PC 的桌面应用一旦上线,性能欠债的偿还成本是随用户规模线性放大的:手机上"卡一下"用户还能忍,桌面端一个工具类应用要跑到八小时会话,同样的 8ms 延迟会在一次批量操作里被放大几百次;更要命的是桌面端用户会对比,隔壁那个原生应用是 60fps,你这边掉到 40fps,卸载理由是"你比 XX 卡",而不是"你比上个版本卡"。所以性能权重 30 不是技术偏好,是返工成本的量化。
反过来,生态权重只有 15,是因为鸿蒙PC 侧的第三方生态仍在成长期,过度加权"生态丰富度"会系统性偏向"用熟悉的跨平台框架"而不是"用对的形式"。成本权重 15 同样被压低:一次数据层重构的钱,往往小于三年后因为选错的架构而付出的维护税。
2.2 加权总分算出来是 4 不是 100:一个必须承认的实现缺陷
看四张截图,注意评分矩阵底部的"加权总分 4 / 100"。这句话是自相矛盾的——它同时声称了"4"和"100 分制"。原因在实现里:
// common/Models.ets:72-80
export function weightedScore(p: Proposal): number {
let sum = 0;
let total = 0;
for (let i = 0; i < DIM_SPECS.length; i++) {
sum += scoreOf(p.scores, DIM_SPECS[i].key) * DIM_SPECS[i].weight;
total += DIM_SPECS[i].weight;
}
return total === 0 ? 0 : Math.round(sum / total);
}
sum / total 算出的是归一化到 5 分制的加权均分,Math.round 又把它压成整数,于是"本地 SQLite + 差量同步"这条(4/3/3/4/5):
(4×30 + 3×15 + 3×20 + 4×20 + 5×15) / 100 = 380 / 100 = 3.8 → Math.round = 4
函数返回 4,而界面写的是"/ 100"。 这是全工程最典型的一处"报错"——它不抛异常、不闪退,只是悄悄地把信息量从 3.8 砍到 4,让两个本该并列的方案(3.8 和 3.85)显示成同一个数字。这在治理场景里是致命的:评分的唯一作用是区分,一旦四舍五入把区分抹平,评分就退化成装饰。 修法很简单,两行:
// 建议改法一:返回百分制,界面文案不动
return total === 0 ? 0 : Math.round((sum / total) * 20); // 3.8 → 76
// 建议改法二:保留一位小数,界面改回 "/ 5"
return total === 0 ? 0 : Math.round((sum / total) * 10) / 10; // 3.8
我倾向改法一,因为 76 / 100 与"加权总分 4 / 100"相比,既保留了区分度,又符合大多数人对"百分制"的直觉;同时 DIM_SPECS 的权重和恰好是 100,sum / total * 20 在实际数值上等于 sum / 5,可以省掉一次除法。这一条的教训是通用的:凡是"评分/达标率/覆盖率"这类指标,一定要在函数名或返回值类型上钉死量纲,否则量纲会在 UI 层被想当然地解释。
2.3 三态泳道:为什么不能只有"采纳 / 不采纳"
只有两个状态的选型表,最终一定会退化成"结论清单"——因为"还没想清楚"无处安放。议台用三段泳道加一条窄状态机解决这件事:
// common/Models.ets:3
export type Stage = 'pool' | 'review' | 'adopted';
三段对应三种现实:pool 是"有人提了,还没人看";review 是"至少两个人打过分了,正在对比";adopted 是"有 ADR 编号了,可以按这个写了"。关键在于第三段不是终点——advance() 对 adopted 的处理是把方案退回 pool 重议:
// pages/Index.ets:45-92(节选)
advance(p: Proposal): void {
if (p.stage === 'pool') {
this.proposals = this.proposals.map((x: Proposal): Proposal => { ... stage: 'review' ... });
text = '「' + p.title + '」进入评审';
} else if (p.stage === 'review') {
const no = 'ADR-' + this.nextAdr.toString().padStart(3, '0');
this.nextAdr = this.nextAdr + 1;
this.proposals = this.proposals.map(/* ... stage: 'adopted', adrNo: no ... */);
this.adrs = [card].concat(this.adrs);
text = '「' + p.title + '」采纳,生成 ' + no;
} else {
this.proposals = this.proposals.map(/* ... stage: 'pool', adrNo: '' ... */);
text = '「' + p.title + '」退回提案池重议';
}
this.pushLog(text, tone);
}
一个方案被"退回",在大多数团队里意味着这件事结束了;在议台里它意味着回到了能被重新打分的状态。这是 ADR 制度真正区别于"会议纪要"的地方:ADR 有状态(提议 / 采纳 / 被取代 / 废弃),而且状态可以回退。图 4 的 ADR 面板里,ADR-003 的状态是"已废弃",理由一栏写着"被 ADR-008 的原生构建方案取代"——这一条如果只写在群里,半年后没人找得到。

图 2 鸿蒙PC 真机完整桌面:“在审 2 · 已采纳 0”——已采纳栏是空的,提案池里堆着三条(“本地 SQLite + 差量同步”“启动器换 ArkUI 声明式重写"和池底一条),评审中两条并排;右下治理日志五条,最上面一条是”「本地 SQLite + 差量同步」退回提案池重议"。已采纳 0 但 ADR 面板里 ADR-010 还在,这正是 2.4 节"方案可以回退、决策不能删除"的直接证据
2.4 治理日志:把"动作"和"结论"分开存
GovLog 只存四样东西:id、时间、文案、色值。ADR 存结论,日志存动作。两者分开的好处在图 1 与图 4 的对比里非常明显:ADR 面板条数几乎不变(因为结论稀有),而右下角的治理日志每条状态迁移都追加一行(因为动作频繁)。结论是资产,动作是流水,资产要精、流水要全。 混在一起存,结果一定是"日志太多没人读、结论太散找不到"。
// pages/Index.ets:39-43
pushLog(text: string, tone: string): void {
const e: GovLog = { id: this.nextId, time: clockText(), text: text, tone: tone };
this.nextId = this.nextId + 1;
this.logs = [e].concat(this.logs).slice(0, 20);
}
.slice(0, 20) 是一个值得说的上限:治理日志不是审计日志,不需要全量保留,20 条刚好够覆盖"一次评审会里的所有动作",再多就要靠分页或落盘。但如果真要把它做上生产,这里必须换成"落盘 + 内存只留最近 N 条",否则用户关掉窗口,整场评审的流水就没了——而这个工程目前就是这样(见第一章的诚实边界)。
2.5 跨平台框架选型对照:这条路在鸿蒙PC 上该怎么走
前面四条讲的是"怎么比",这一节讲"比什么"。因为「议台」本身就在评估一条真实的候选方案——Models.ets 里 id=4 的提案写着"启动器换 ArkUI 声明式重写",备注是"老命令式栈已到维护成本拐点"。把这条提案摊开,就是鸿蒙PC 上最常见的跨平台框架选型问题:到底用 ArkUI 原生写,还是引入一个跨平台框架?
先把术语钉准:本项目使用的是 ArkUI(ArkTS 声明式 UI),不是 ArkUI-X。 两者经常被混为一谈,但工程含义完全不同:
| 方案 | 在鸿蒙PC 上的形态 | 优势 | 代价(按议台五维打分) |
|---|---|---|---|
| ArkUI 原生 | ArkTS + 声明式 UI,2in1 能力(窗口、hover、多窗)一等公民 | 性能最好,系统能力零包装;包体最小 | 生态锁定;Web/移动端代码无法复用(成本 2) |
| ArkUI-X | 以 ArkUI 为基座的跨平台框架,可把 ArkTS 页面跑到其他平台 | 一套 ArkTS 代码多端复用 | 目标平台能力需桥接;桌面专属交互(右键菜单、多窗口)要自己补 |
| Flutter | Skia/Impeller 全自绘,需社区 ohos 适配层 | UI 一致性极强,组件生态最成熟 | 画布由框架自己画,系统级控件(输入法、文件选择、窗口装饰)都要走桥接;包体基线比原生高,二进制体积随引擎固定 |
| Compose Multiplatform | Kotlin 声明式 UI + Skiko 渲染 | 与 Android/桌面共享业务代码 | 需 Kotlin/Native 工具链与 cinterop;启动期多一层运行时初始化 |
这张表不是"谁更好"的排名,而是"在什么条件下谁更合适"。议台给出的判断口径是:如果你的应用是"系统能力的编排器"(窗口、拖拽、打印、剪贴板、文件访问占主导),ArkUI 原生的收益最大,因为这些能力在跨平台框架里都要经过一层桥接,而桥接层恰恰是鸿蒙PC 上最容易出兼容问题的地方;如果你的应用是"纯内容消费 + 表单"且已有大量 Web 资产,那么跨平台框架的成本项会显著下降,因为复用省下的工程量可以覆盖包体和桥接代价。
这条判据可以直接写进评分:把一个"跨平台复用比例"作为 cost 维度的评分依据,把"桌面专属交互数量"作为 maint 维度的依据。选型治理的价值不在于选出唯一正确答案,而在于把"为什么这次选它"变成一组可复核的数字。 顺带说一句,这也是本文开头要强调的关键词落点:鸿蒙PC 上的每一个跨平台框架决策,最终都要落到"哪些能力走原生、哪些能力被包装"这张清单上。
三、性能优化:把 build() 当成热路径来读
ArkUI 是声明式 UI:状态变化后框架重新执行 build() 生成新的视图描述,与旧树做差分,只把差异提交给渲染管线。差分的成本取决于"树的规模"与"差异的粒度",而"树的规模"完全由 build() 里的表达式决定。议台的所有状态都压在一个 struct 里:
// pages/Index.ets:13-19
@State proposals: Proposal[] = createProposals();
@State adrs: AdrCard[] = createAdrs();
@State logs: GovLog[] = [];
@State selectedId: number = 1;
@State compareId: number = 2;
@State nextId: number = 600;
@State nextAdr: number = 10;
七个 @State,任何一个变化都会让 Index.build() 完整执行一次。在图 1 到图 4 那条"点一张卡 → 换一个阶段 → 追加一条日志"的链路里,一次点击同时改 proposals、adrs、logs、nextId、nextAdr 五个状态,也就是说一次点击至少触发一轮完整的树重建。下面五处是我按源码静态数出来的浪费,它们的共同点是:每一处都不影响正确性,只影响"点一下要多久才看到变化"。
3.1 派生计算在 build() 里反复扫描全表
先看泳道怎么取数:
// pages/Index.ets:228-234
inStage(stage: Stage): Proposal[] {
return this.proposals.filter((p: Proposal): boolean => p.stage === stage);
}
countIn(stage: Stage): number {
return this.inStage(stage).length;
}
inStage 每调一次就遍历全表一次。而 Swimlane(stage) 这个 @Builder 里,countIn(stage) 被调用两次(标题的"(n)"一次、空态判断一次),ForEach 的数据源 this.inStage(stage) 再调一次。三条泳道合计:
3 泳道 × 3 次 filter × 5 个提案 = 45 次比较 / 每次 build
5 个提案时这是 45 次比较,可以忽略;但一个真实的选型库在一个季度里堆到 50 条提案、20 条 ADR 是常态,那时就是 3×3×50 = 450 次比较,而且每次 build 都重算一遍。更糟的是 proposals.filter 每次返回新数组,ForEach 的 diff 只能靠 key 兜底(见 3.2),数组引用一变,框架必须完整比对一遍。
ArkUI 没有 useMemo,派生状态必须自己维护。最省事的改法是把"按阶段分组"提到一次:
// 建议新增:一次遍历分成三条泳道
groupByStage(list: Proposal[]): Map<Stage, Proposal[]> {
const m: Map<Stage, Proposal[]> = new Map();
m.set('pool', []);
m.set('review', []);
m.set('adopted', []);
for (let i = 0; i < list.length; i++) {
const arr = m.get(list[i].stage);
if (arr !== undefined) {
arr.push(list[i]);
}
}
return m;
}
然后用一个"脏标记 + 缓存字段"的私有方法把它兜住:
// 建议改法:只在 proposals 换引用时重算
private groupedCache: Map<Stage, Proposal[]> = new Map();
private groupedDirty: boolean = true;
private grouped(): Map<Stage, Proposal[]> {
if (this.groupedDirty) {
this.groupedCache = this.groupByStage(this.proposals);
this.groupedDirty = false;
}
return this.groupedCache;
}
advance() 与 pushLog() 里改完 proposals 顺手置 this.groupedDirty = true。注意别在 @Builder 里直接调 groupByStage——@Builder 每次渲染都会重跑,等于没优化;也别把 const/let 声明塞进 build() 里,那是 ArkUI 的语法禁区(build() 只允许 UI 描述)。这是 ArkUI 里最常见的"以为做了缓存其实没有"的坑:缓存必须挂在成员上,不能挂在一次渲染的局部作用域里。
3.2 ForEach 的 key 为什么要拼上阶段
// pages/Index.ets:209-211
ForEach(this.inStage(stage), (p: Proposal) => {
this.ProposalCard(p)
}, (p: Proposal) => p.id.toString() + p.stage)
key 是 id + stage 而不是 id。这不是随手写的——同一条提案在生命周期里会出现在三条不同的泳道里,如果 key 只用 id,那么它在泳道间移动时,框架会认为"这个 key 的组件还在,只是换了位置",于是复用旧的组件实例和旧的位置状态(滚动偏移、按压态、动画中间值),结果就是卡片"滑"进了另一列但里面还是旧的高亮色。拼上 stage 之后,key 在跨泳道时变化,框架按"删旧建新"处理,视觉上是干脆的一次重排。
代价也要说清楚:key 变化 = 重建,不是复用。所以这个设计牺牲了复用率换正确性。如果以后泳道变多、卡片变重(比如每张卡里塞一个趋势图),就要考虑把 key 稳定成 id、把阶段只作为属性传入,让卡片自己订阅阶段——那是另一种取舍。
顺带一个真实存在的隐患:ForEach 的第三参在"对比对象"那一行是
// pages/Index.ets:328
}, (x: Proposal) => x.id.toString() + (this.compareId === x.id).toString())
这个 key 里包含了 compareId,意味着每次切换对比对象,这一整行的所有 chip 都会被重建。它们只有 5 个、都是纯文本,所以代价可以接受;但如果哪天给 chip 加了过渡动画,这个 key 会让动画全部从零开始。key 里放"渲染依赖的可变状态"是一个需要显式记账的决定,写完必须能回答:“这个 key 什么时候变、变了要重建多少个组件?”
3.3 评分条:每次 build 重建 6 个临时对象
// pages/Index.ets:117-126
Row({ space: 8 }) {
Text('加权总分') /* ... */
Text(weightedScore({ id: 0, title: '', topic: '', owner: '', stage: 'pool',
scores: scores, note: '', adrNo: '' }).toString() + ' / 100')
/* ... */
}
为了复用 weightedScore(p: Proposal) 的签名,这里构造了一个用完即弃的 Proposal 字面量。每张评分卡一次,A/B 两列就是两次,加上 5 个维度的 scoreOf 调用各一次(Progress 宽度一次、右侧文字一次,共 10 次),一次 build 里光是"为了取分数"就产生了 2 个临时对象 + 12 次函数调用。
这类浪费在 ArkUI 里有一个通用判据:build() 里的每一个函数调用,都会在"任何状态变化"时重跑。所以原则是——能在状态变更时算一次的就别在 build() 里算,能传值就别传对象。改法是把 weightedScore 拆成 weightedRaw(scores: Scores): number,直接吃 Scores 而不是 Proposal:
// 建议改法:不再需要构造临时 Proposal
export function weightedRaw(s: Scores): number {
let sum = 0;
let total = 0;
for (let i = 0; i < DIM_SPECS.length; i++) {
sum += scoreOf(s, DIM_SPECS[i].key) * DIM_SPECS[i].weight;
total += DIM_SPECS[i].weight;
}
return total === 0 ? 0 : Math.round((sum / total) * 20);
}
原来的 weightedScore(p: Proposal) 保留成一个薄包装(return weightedRaw(p.scores)),既不动 advance() 里的调用,又消掉了 build() 里的对象分配。
3.4 不可变更新:性能与正确性的同一个交点
// pages/Index.ets:49-55
this.proposals = this.proposals.map((x: Proposal): Proposal => {
if (x.id === p.id) {
const moved: Proposal = { id: x.id, title: x.title, topic: x.topic, owner: x.owner,
stage: 'review', scores: x.scores, note: x.note, adrNo: x.adrNo };
return moved;
}
return x;
});
这里用 map 造新数组、用对象字面量造新元素,写法比原地改啰嗦得多,但它是必须的:ArkUI 对 @State 数组的观测以"引用是否变化"为准,直接 x.stage = 'review' 界面不会动。有趣的是,这层"为了正确性"的写法在性能上恰好也是最优路径之一——被改动的只有一个元素,其余 4 个元素是同一个对象引用,走的是浅比较快速路径。
真正的风险在别处:map 里手写 8 个字段的拷贝,加字段时极容易漏。Proposal 目前 8 个字段,拷了 8 个;等哪天加上 createdAt、votes,这三处 map(Index.ets:49、60、81)都得同步改,漏一个就是"提案进了评审就丢了创建时间"。这是典型的"正确性靠人工纪律维持"的代码形状。ArkTS 支持展开运算符时可以直接写 { ...x, stage: 'review' },但工程里没有用——如果目标 SDK 或 lint 规则不允许,至少应该抽一个 withStage(p: Proposal, stage: Stage, adrNo: string): Proposal 工厂,把 8 个字段的拷贝收敛到一处。这就是第五章"报错排查"里第 5 条要展开的那个 bug 类型。
3.5 大屏布局:layoutWeight 与固定宽混排的断点问题
下排三块是 layoutWeight(1) + width(320) + width(270) 的混排:
// pages/Index.ets:363-364 / 386 / 427
.layoutWeight(1) // 评分矩阵,弹性
.width(320) // ADR 卡片,固定
.width(270) // 治理日志,固定
在 2in1 的默认窗口宽度下(截图里约 1100px 内容区),弹性列还能拿到 400px 左右,A/B 双列评分条刚好排得开。但鸿蒙PC 的窗口可以被拉到 600px 宽,此时两个固定列吃掉 590px + 三处 padding,弹性列被压到接近 0,A/B 两列的评分条会挤成一团竖排——图 2 与图 4 里评分矩阵右侧被 ADR 面板压住一部分,正是这种"弹性列被挤压后溢出"的表现。
修法不是简单地把固定宽改成百分比,而是加一个断点:
@State winW: number = 1100;
// onAreaChange 里更新 winW
Row({ space: 14 }) {
/* 评分矩阵 layoutWeight(1) */
if (this.winW >= 980) {
/* ADR 卡片 width(320) */
}
}
窄窗时把 ADR 卡片折叠成一枚"查看决策记录"的按钮(点开用半模态 bindSheet),把宽度还给评分矩阵。2in1 形态的性能问题有一半不在 CPU 上,而在"窗口尺寸是用户手里的变量"这件事上:手机端的宽度是常量,桌面端的宽度是输入。任何"固定宽 + 弹性宽"混排都必须回答一个问题——最窄的那个断点,谁让位?

图 3 鸿蒙PC 真机完整桌面:状态胶囊"在审 2 · 已采纳 1",泳道分布 2 / 2 / 1,已采纳栏里是"日志采集改用结构化事件总线 ADR-009";右下角治理日志三条,最新一条"「本地 SQLite + 差量同步」退回提案池重议"。注意评分矩阵的对比对象已经切到"沿用分布式对象框架",A/B 两列的加权总分都是 4——这正是 2.2 节那个四舍五入缺陷的现场
四、报错排查:6 类高频错误与一套定位手段
这一章的每一条都是"界面看起来正常、行为不对"的类型——真正抛异常崩溃的错误反而不难查,难查的是不报错但结果错。以下按"症状 → 根因 → 修法"组织,症状描述尽量对齐你在真机上会看到的东西。
4.1 点了没反应:@State 数组被原地修改
症状:点"提交评审",日志追加了、计数变了,但卡片还在原来的泳道里没动;再点一次,日志又追加一条,卡片还是不动。
根因:ArkUI 对 @State 的数组/对象观测基于引用变化。原地改元素字段(p.stage = 'review')时数组引用没变、元素本身也没被 @Observed 装饰,框架就不会认为"状态变了";原地 push 在多数场景能被观测到,但一旦元素内部字段后续被原地改写,问题会以"部分刷新"的形式复现,比完全不刷新更难查。
修法:要么 this.proposals = this.proposals.map(...) 造新数组(本工程的做法),要么用 @Observed + @ObjectLink 让元素级字段可观测。判断标准很简单:问自己"我有没有给这个 @State 重新赋值",没有就是没刷新。
4.2 卡片错位、高亮跟着"跑"到别的列:ForEach key 不稳定
症状:把一张提案从"评审中"推进到"已采纳",卡片飞过去之后,原本属于它的金色选中边框出现在另一张卡上;或者同一张卡出现两次。
根因:key 只用 p.id,跨泳道时框架认为是"同一个组件换了位置",于是复用了旧的组件实例状态;更严重的是 key 在同一次渲染内重复(例如把 proposals 拼进三个泳道的 ForEach 而没有过滤),框架会直接丢项或错序。
修法:key 必须"全局唯一 + 与视觉生命周期一致"。本工程用 p.id.toString() + p.stage(Index.ets:211),跨泳道即换 key,强制重建。排查这类问题最快的办法是把 key 打印出来:在 key 函数里 console.info('[KEY]', p.id + p.stage),看同一帧里有没有重复值。
4.3 评分矩阵整块消失:非空断言与"悬空 id"
症状:某次操作后,下半屏的评分矩阵整块变空白,日志正常;有时是控制台一条 TypeError: Cannot read property 'title' of undefined。
根因:selectedId 是一个独立于 proposals 的外键。只要有任何路径让某个 id 从 proposals 里消失(未来加"删除提案"、或按标签过滤后重建列表),selected() 就返回 undefined,而 build() 里有多处 this.selected()!.title(Index.ets:310、334、339):
// pages/Index.ets:308-310
if (this.selected() !== undefined) {
Row({ space: 10 }) {
Text('评分矩阵 · ' + this.selected()!.title)
外层的 if 只保护了"那一帧",它保护不了同一个表达式里第二次调用返回 undefined 的可能性(更保护不了 ForEach 内部闭包在下一帧执行时的状态)。非空断言 ! 的语义是"我保证它不为空",而这里的非空性依赖一个跨数组的外键约束,那不是编译器能验证的。
修法:不要在 build() 里赌非空,而是让外键永远指向存在的元素——在每次 proposals 变更后收敛一次:
// 建议新增:外键自愈
private syncSelection(): void {
if (this.selected() === undefined) {
this.selectedId = this.proposals.length > 0 ? this.proposals[0].id : -1;
}
}
调用点只有两处:advance() 末尾与任何"列表被替换"之后。同时把 build() 里的 this.selected()! 换成带兜底的取值方法,非空断言就从"承诺"变成了"契约":
// 建议新增:取值带兜底,build() 里不再出现 ! 操作符
private selTitle(): string {
const p: Proposal | undefined = this.selected();
return p === undefined ? '未选择' : p.title;
}
顺带解决了 3.1 的重复遍历问题——selected() 一次 build 里被调用了 5 次(每次 O(n) 遍历),改成 selTitle() 之后仍会遍历,但只要把"当前选中项"缓存进 @State sel: Proposal | undefined,遍历次数就降到 0。注意别把变量声明塞进 build(),那是 ArkUI 的语法禁区;要么用 @State 缓存,要么用返回值的私有方法。
4.4 ArkTS 严格模式下的三类高频编译错误
这三个是 .ets 文件"第一次写就红"的常客,报错文案和修法都值得记住:
| 编译报错(关键字) | 触发写法 | 修法 |
|---|---|---|
arkts-no-untyped-obj-literals | 把对象字面量赋给 Object/ESObject/无标注的变量 | 声明 interface 或 class 并在字面量处标注类型;本工程的 Proposal/GovLog 就是为此存在 |
arkts-no-any-unknown | 用 any 接住 JSON.parse 的返回值 | 定义具体接口后 as 断言;或用 Record<string, string> 收窄 |
Property 'x' has no initializer | class 字段只声明不赋值 | 用构造函数全赋值(Models.ets 的 AdrCard 在 createAdrs() 里全字段给值),或给默认值 |
本工程之所以一个 class 都没写、全用 interface + 工厂函数(createProposals / createAdrs),就是因为 interface 不需要构造器、对象字面量带类型标注即可通过校验,在 ArkTS 严格模式下这是最省事的建模方式。代价是没有方法——所以 withStatus 那种"不可变更新"的便利也没了,得自己在 map 里手写拷贝(回到 3.4 的风险)。
4.5 界面上冒出 undefined:手写拷贝漏字段
症状:给 Proposal 加了一个 createdAt: string 字段,提案池里显示正常,但一点"提交评审",卡片上就出现 undefined 或 NaN。
根因:advance() 里三处 map 各手写了一遍 8 字段的对象字面量(Index.ets:51、62、83)。加字段时编译器不会报错——因为对象字面量对 interface 是"结构兼容"的,缺字段会直接报错(Property 'createdAt' is missing),但如果字段是可选的(createdAt?: string),编译就过了,运行时拿到 undefined。
修法:把"换阶段"收敛成一个工厂:
export function withStage(p: Proposal, stage: Stage, adrNo: string): Proposal {
const next: Proposal = { id: p.id, title: p.title, topic: p.topic, owner: p.owner,
stage: stage, scores: p.scores, note: p.note, adrNo: adrNo };
return next;
}
以后加字段只改一处。这是一条通用规律:同一个字面量在三个地方重复出现,就一定会有一天只改了两处。
4.6 装不上:包名冲突与设备形态不匹配
症状一:hdc install 报 9568263 ... downgrade,或 DevEco 里点运行弹"安装失败"。
根因:鸿蒙PC 上同时存在多个共用调试签名的工程(本项目 bundleName 是 com.conclave.governance,versionCode 1000000),装新包时设备上已有同包名的旧版本且 versionCode 更高。
修法:先 hdc uninstall com.conclave.governance 再装;或者把新工程的 versionCode 调高。这条在"同一台机器上并行做多个演示工程"时几乎必踩。
症状二:应用在市场/真机上"不显示、装不上"。
根因:module.json5:7 只声明了 deviceTypes: ['2in1']。这是有意为之——议台是鸿蒙PC 专属的双栏/三栏大屏工具,装到手机形态设备上即使能装也毫无意义。
修法:不要为了"能装上"而加 phone。正确的做法是承认形态约束,并在 UI 上做宽窄断点(见 3.5);如果确实需要多端,那是"两条产品线",不是"一个 module 加两个 deviceTypes"。
4.7 定位手段:hilog 的最小可用姿势
真机上没有控制台可看时,hilog 是最便宜的探针。本工程的 EntryAbility 已经埋了三条:
// entryability/EntryAbility.ets:5-19
const DOMAIN = 0x0000;
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(DOMAIN, 'Conclave', 'Ability onCreate');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(DOMAIN, 'Conclave', 'Failed to load content: %{public}s', JSON.stringify(err));
return;
}
hilog.info(DOMAIN, 'Conclave', 'Content loaded');
});
}
用法:hdc shell hilog -T Conclave(按 tag 过滤)。两个细节值得抄:第一,loadContent 的失败分支一定要打日志,否则"白屏"时你连是页面路径写错还是渲染抛异常都不知道;第二,%{public}s 这个占位符别省——不标注 public 的字符串在日志里会被打码成 <private>,排查时会看到一串星号。
五、把三条线缝起来:一张提案卡的完整生命周期
前面三章分别讲了选型、性能、报错,但它们在这套代码里其实是同一个动作的三个侧面。用四张截图串一遍最清楚。

图 4 鸿蒙PC 真机完整桌面:状态胶囊"在审 2 · 已采纳 2",泳道分布 1 / 2 / 2,已采纳栏并排两条(“本地 SQLite + 差量同步 ADR-010” 在上、“日志采集改用结构化事件总线 ADR-009” 在下);ADR 面板已累积到四条(ADR-010 / ADR-008 / ADR-007 / ADR-003),治理日志两条
第一步,提案进池。createProposals() 里 id=3 的"自建 CRDT 合并层"在 pool,评分 5/1/2/2/3。它性能最高(5),成本最低(1)——这条数据本身就说明了为什么需要五维评分:单看性能它是最优解,看加权总分它只有 3 分((5×30+1×15+2×20+2×20+3×15)/100 = 290/100 = 2.9)。如果只讨论"性能",会上会有五个人支持它;把成本 1 分摆出来,讨论自然转向"什么时候值得付这个工程量"。图 3 与图 4 的对比就是它的两种归宿:要么停在池子里等资源,要么被重新打分后推进。
第二步,点击推进。点"提交评审"触发 advance()。这一刻同时发生五件事:proposals 换成新数组(4 个元素引用不变、1 个新建)、stage 从 pool 变 review、nextId 自增、logs 前插一条、selectedId 可能被改成它。性能上,这是一次"五状态同帧变更",也是第三章所有优化的靶子;正确性上,这是 3.4/4.5 讲的"手写拷贝"最容易出错的时刻。
第三步,评审通过,生成 ADR。再点一次"评审通过,采纳",走 review 分支:no = 'ADR-' + nextAdr.toString().padStart(3, '0'),card.reason 里把评分拼进去('(加权评分 ' + weightedScore(p) + ' 分)'),adrs 前插一张卡。注意这里又调了一次 weightedScore——它和评分矩阵用的是同一个函数,好处是口径天然同源,坏处是量纲缺陷也被一起复制进了 ADR:图 2 里那条"(加权评分 4 分)",读者会自然理解成"4 分(满分 5)“还是"4 分(满分 100)”?这就是 2.2 那个 bug 的第二个受害者。改百分制时这里只需跟一句单位(“76 分”),但已经落档的历史 ADR 需要一次迁移,否则同一张表里会同时存在 5 分制和 100 分制的记录——这类"历史数据不同量纲"的问题,在任何指标系统里都比当时代码难改十倍。
第四步,退回重议。已采纳的卡上按钮变成"退回重议",点击后 stage 回到 pool、adrNo 清空,但ADR 卡不会消失(adrs 里那张还在)。这是设计上的有意选择:方案可以回退,决策不能删除。图 4 里 ADR-003 的状态写着"已废弃",理由"被 ADR-008 的原生构建方案取代"——这就是"决策不删除、只标记被取代"的落地方式。真要做成生产工具,这里应该再加一步:退回时自动给旧 ADR 追加一条 supersededBy 指针,形成一条可追溯的链,而不是在协议里靠人记。
六、诚实边界与下一步
写到这里必须把话说完整,否则这篇文章的结论会被误用。
第一,所有数字都是演示数据。 5 条提案、3 张 ADR 全在 Models.ets 里(createProposals() 与 createAdrs()),治理日志初始为空数组,图里那些"02:30:28"式的时间戳是 clockText() 在点击瞬间取的当前时间。界面上"在审 2 · 已采纳 1"这类计数是 countIn() 现场算的,不是从后端拉的。截图里的 ADR-010、ADR-009 是点击生成的,但"引用"它们的业务后果一件都没有——这个工具治理的是"记录",不是"代码"。
第二,"构建 9 分钟压到 2 分 40 秒"这类话我没有说,也不该说。 ADR-008 卡片上写的是"全量构建 9 分钟压到 2 分 40 秒,缓存命中稳定",那是演示文案,用来展示"一条 ADR 该长什么样",不是我在鸿蒙PC 上跑出来的构建数据,本工程也没有构建基准脚本。真要写实测,需要给出机型、SDK 版本、构建命令、冷热缓存区分和多次取值——缺任何一个都不是性能数据,是故事。
第三,性能优化那五条都是"静态可推断"级别的改动,没有做压测对照。 45 次 filter、2 个临时对象这些数字是从源码数出来的调用次数,不是 profiling 结果。它们的正确表述是"减少了多少工作量",而不是"快了多少毫秒"——后者需要 FrameMeter 或 DevEco Profiler 的帧耗时数据。这也是我给这个工程排的下一个里程碑:把 withFrameNanos 那套帧采样接进来,让"点一下到画面更新"有一个可比较的毫秒数。
第四,下一步的三件事按优先级排: 其一,持久化——把 proposals/adrs/logs 落到 filesDir 的 JSON,并在启动时读回,这样"治理日志只在内存"的硬伤才算补上;其二,口径统一——weightedScore 改百分制、界面文案与 ADR 文案同源、selectedId 悬空自愈;其三,宽窄断点——ADR 卡片在窄窗折叠成 bindSheet,让 2in1 的窗口缩放不再是布局炸弹。
七、总结
回到三条线做收束。
方案选型治理的落点不是"选出一个方案",而是让候选方案在同一屏、同一口径、同一时间点被比较,并把结论固化成有编号、有状态、可被取代的记录。五维权重写在常量里、加权总分算在函数里、ADR 编号发在状态机里——三样都进了代码,才叫流程,否则永远停在 PPT 上。而这一节里最值得带走的细节,恰恰是一个 bug:"加权总分 4 / 100"这种量纲分裂,会让评分工具在不知不觉中失去区分能力,而它不会报错,只会让你在评审会上发现两个"都是 4 分"的方案其实差了 0.15。
性能优化的落点是把 build() 当成热路径:派生计算别在 @Builder 里重算、ForEach 的 key 里放什么要能说清代价、build() 里别为了复用签名构造临时对象、@State 必须换引用才刷新但换引用时别手写 8 个字段的拷贝、固定宽与弹性宽混排要先算清最窄断点谁让位。这五条没有一条需要新框架,也没有一条需要 profile 才能发现——读代码就能数出来。
报错排查的落点是分清"崩溃"和"结果错":崩溃有堆栈好查,结果错只能靠"外键是否悬空、key 是否唯一、字面量是否漏字段、包名/形态是否冲突"这四条清单去扫。hilog 的 %{public}s、loadContent 的失败分支、hdc uninstall 的降级坑,都是这三十分钟能省下来的东西。
最后回到鸿蒙PC 这个前提。同一套 ArkUI 代码在手机上和在 2in1 上跑,遇到的问题不是同一个集合:窗口宽度是变量、会话长度是小时级、系统能力(多窗、拖拽、打印、剪贴板)是主力而不是点缀。这决定了鸿蒙PC 上的技术决策必须留档——因为每一次决策的代价都要在用户桌面上摊好几年。至于要不要引入跨平台框架、要不要让 ArkUI-X 或 Flutter 承担一部分页面,答案不在任何一篇对比文章里,而在你自己那张五维评分表上:先把它写下来,再把它算出来。
八、复现步骤
- 用 DevEco Studio 打开
项目源码/Conclave_ohos(Stage 模型,compatibleSdkVersion26.0.0)。 - 在
build-profile.json5里把signingConfigs.default换成你自己的调试签名(原文件里的路径是导出机器的绝对路径,直接编译会报签名失败)。 - 目标设备选 2in1(鸿蒙PC 真机或 PC 形态模拟器),运行后
windowStage.loadContent('pages/Index')会直接进入议台主页。 - 复现图 1 → 图 4 的状态链:任选一张提案卡点"提交评审"→ 再点"评审通过,采纳";对已采纳的卡点"退回重议"。每次点击观察四处同步变化:泳道归属、状态胶囊计数、ADR 面板条数、治理日志首条。
- 复现 2.2 的量纲缺陷:打开任意两条提案的评分矩阵,看"加权总分"是否被压成同一个整数;把
weightedScore改成Math.round((sum / total) * 20)后重跑,同一对方案应该显示 76 与 77。 - 复现 4.1 的刷新问题:把
advance()里的this.proposals = this.proposals.map(...)改成原地p.stage = 'review'; return;,点击后日志会追加、卡片不会动——这就是 ArkUI 引用观测的边界。
工程源码托管在 AtomGit(PC 社区平台:https://atomgit.com/OpenHarmonyPCDeveloper)。本文全部代码使用 ArkUI(ArkTS 声明式 UI)实现,未引入 ArkUI-X、Flutter 或 Compose Multiplatform 运行时;文中提到的这些跨平台框架仅作为选型对照的候选,出现位置均在第二章第 5 节与第七章的对照讨论中。文中"鸿蒙PC"指搭载 HarmonyOS 的 2in1 桌面设备形态,与手机/平板形态在窗口模型上有本质差异。若你要把这套流程搬进自己的团队,最小的可用版本只需要三样东西:一个带权重的评分常量、一条三态状态机、一个只在追加时写、永不删除的决策记录表。
更多推荐




所有评论(0)