HarmonyKit | 鸿蒙新特性总结：编解码工具的统一模式与代码复用

引言：从"改了这里忘了那里"到统一模式

HarmonyKit 有四个编解码类工具：Base64 编解码、URL 编解码、JSON 格式化、哈希计算。它们在功能上各不相同，但底层的交互模式惊人地一致——都是"用户输入文本 → 选择操作 → 系统处理 → 展示结果 → 复制"的线性流程。

有次我在 Base64 工具的输出区域加了一个复制按钮，但忘记了在 URL 工具里也加。用户反馈"为什么 Base64 能复制，URL 不行？“这个小事让我意识到：即使只有 10 个工具，代码一致性也是需要刻意维护的——不能依赖"开发者的好记心”。

这篇文章提炼了编解码工具的四环节统一模式、两种按钮布局变体、以及 HarmonyKit 实际应用的三条代码复用策略。

项目仓库：https://atomgit.com/VON-/harmony-kit

四环节统一模型

每个编解码工具页面的 UI 结构都可以拆解为四个固定的环节。这四环节模型是 HarmonyKit 10 个工具页面一致性的核心。

环节一：输入区域

所有编解码工具的输入区域都是一个 TextArea 组件，共享四个样式属性：等宽字体(fontFamily('monospace'))、白色背景(backgroundColor('#ffffff'))、8vp 圆角(borderRadius(8))、12vp 内边距(padding(12))。

高度根据工具特征有所不同：JSON 格式化 160vp（字符串通常长）、Base64 和 URL 140-150vp（输入适中）、文本统计 180vp（可能粘贴大段文本）、哈希计算 140vp。

输入区左右 margin 16vp 是因为这个值经过视觉调试后达到了"不浪费屏幕宽度也不被截断"的平衡——12vp 太紧凑（卡片的圆角阴影可能被屏幕边缘截断），20vp 浪费了宝贵的移动端宽度。在 390px 宽的屏幕上，390-32=358px 的内容宽度，13px 等宽字体每行可显示约 50 个字符。对于代码、JSON、Base64 数据来说刚好够用。

所有输入区的 placeholder 都是中文，描述期望的输入格式：“粘贴 JSON 字符串…”“输入要编码/解码的文本…”“输入要匹配的文本…”。用户不需要猜测应该在这里输入什么。

环节二：操作按钮区

操作按钮有三种布局模式，对应三种交互类型：

双按钮模式——Base64：编码|解码，URL：编码|解码。两个互逆操作并排。主操作（编码）用蓝色(#007aff)，辅助操作（解码）用绿色(#34c759)或橙色(#ff9500)。

Row() {
  Button('编码 Encode').backgroundColor('#007aff')
  Button('解码 Decode').backgroundColor('#34c759').margin({ left: 12 })
}
.width('100%').padding({ left: 16, right: 16, top: 12, bottom: 8 });

工具栏模式——JSON：选项(2空格/4空格) + 操作(格式化/压缩)，正则：选项(g/i/m) + 操作(匹配)，哈希：选项(MD5/SHA1/SHA256) + 操作(计算)。左侧是选项组，右侧是操作按钮，中间用 Blank() 撑开。

Row() {
  // 选项组（互斥或 toggle）
  ForEach(options, (opt) => {
    Button(opt.label)
      .backgroundColor(this.selected === opt.key ? '#007aff' : '#f0f0f0')
      .onClick(() => { this.selected = opt.key; });
  });
  Blank();
  // 操作按钮
  Button('执行').backgroundColor('#007aff').onClick(() => this.doWork());
}

双向面板模式——时间戳转换：上半部分"时间戳→日期"，下半部分"日期→时间戳"。两个面板各有一个转换按钮和一个结果行。用 Divider() 分割。

三种模式对应三种用户操作模式：双按钮适合"两个对等操作"的场景，工具栏适合"选项+执行"的场景，双面板适合"我需要同时看到两个方向的结果"的场景。

环节三：输出区域

输出区域有三个固定子元素：

标签行：“结果"标签（灰色 13px）右对齐 + CopyButton。此标签行让用户明确知道"下面是输出”。CopyButton 是标配——"复制结果到剪贴板"是所有工具最高频的后续操作。

Row() {
  Text('输出').fontSize(13).fontColor('#666');
  Blank();
  CopyButton({ text: this.output });
}
.width('100%').padding({ left: 16, right: 16, top: 8, bottom: 4 });

错误展示区域：如果操作异常，在标签行下方、结果区上方展示红色错误文字。

if (this.errorMsg) {
  Text(this.errorMsg).fontSize(12).fontColor('#ff3b30')
    .width('100%').padding({ left: 16, right: 16 });
}

结果展示区：只读 TextArea（用户不能编辑），等宽字体，白色背景。高度 100-200vp 根据预期输出长度调整——哈希值短(32-64字符)、格式化JSON长(可能数百字符)。

环节四：错误处理

每个工具的错误处理遵循三层次：

层次一——空输入静默忽略：用户未输入内容时点按钮，if (!this.input.trim()) return; 静默返回。不展示错误——因为可能是误触。

层次二——格式验证 + 语义化提示：输入了内容但格式不合法。JSON 校验失败时展示 JSON.parse 的原生错误信息（含行号和位置）。Base64 解码失败时展示"请检查输入是否为有效的 Base64 字符串"——用户不需要知道底层"Invalid character at index 5"。

层次三——运行时 try/catch：所有执行方法包裹在 try/catch 中。错误展示在输出区域而非弹窗——成功展示结果、失败展示错误，同一位置。

三条代码复用策略

策略一：CopyButton 全域复用

CopyButton 是 HarmonyKit 中复用率最高的组件——10 个工具的输出区域全部使用。组件内部封装了 pasteboard API 调用和 Toast 反馈。将来复制逻辑从一个 API 迁移到另一个 API 时，只改 CopyButton 一处。

策略二：工具函数静态化

所有编解码工具核心逻辑都是 utils/ 下的 static 方法：Base64Utils.encode()、UrlUtils.encode()、JsonUtils.format()、HashUtils.hash()。方法签名统一：static method(input: string): string（哈希是 Promise<string>）。静态方法保证无实例状态、无副作用、可独立测试。

策略三：页面模板化（非组件化）

10 个工具页虽然遵循同一模板，但没有抽取为通用的 ToolPage 组件。因为每个工具在细节上存在大量差异——JSON 有缩进选择器、Base64 有两个操作按钮、正则测试器有标志位按钮。强行统一会导致大量 if (toolType === 'json') { ... } 分支逻辑。

模板化（复制骨架 → 填充逻辑）比组件化更适合此场景。10 个独立页面的重复代码约 60%，但每个页面自包含、独立可调试。修改 JSON 工具不影响 Base64 工具。

项目仓库：https://atomgit.com/VON-/harmony-kit