HarmonyKit | 鸿蒙新特性实践：进制转换器 2/8/10/16 四进制通用互转

引言

进制转换是计算机科学的基础运算之一。虽然操作系统自带的计算器都提供了进制转换功能，但在移动端开发调试场景中，需要快速在二进制、八进制、十进制和十六进制之间切换查看同一个数值，专用的进制转换器比通用计算器更加直接高效。HarmonyKit 的进制转换工具基于 JavaScript 原生的 parseInt 和 toString 方法，配合 ArkTS 严格的类型系统，实现了简洁而健壮的四进制互转功能。

parseInt 与 toString：JavaScript 的进制转换原语

在讨论 UI 实现之前，有必要深入理解 JavaScript 为进制转换提供的两个核心 API。parseInt(string, radix) 将指定进制（radix）的字符串解析为十进制整数，其中 radix 的取值范围是 2 到 36。number.toString(radix) 则相反，将数字转换为指定进制的字符串表示。

这两个方法构成了 HarmonyKit 进制转换工具的算法核心，但实际上整个工具只用了两行核心逻辑：

let val = parseInt(this.input.trim(), this.fromRadix);
this.results = [
  val.toString(2),
  val.toString(8),
  val.toString(10),
  val.toString(16).toUpperCase()
];

第一行将用户输入按选定的"源进制"解析为十进制整数，第二行将该整数分别转换为四种进制的字符串表示。注意 toString(16) 后调用 toUpperCase()——JavaScript 的 toString(16) 默认输出小写字母（a-f），而十六进制惯例使用大写字母，因此手动转为大写。二进制和八进制只输出数字，不需要大小写处理。

这种"先统一到十进制，再分发到各进制"的模式是进制转换的通用解法。十进制作为人类最熟悉的中间表示，逻辑清晰且不易出错。如果直接实现二进制到十六进制的转换算法，需要处理 4 位一组的映射关系和补齐逻辑，复杂度和出错概率都远高于这种中间表示法。

接口类型：RadixOption 与 ResultRow

ArkTS 严格模式下要求 ForEach 的循环变量必须有明确的类型标注。进制转换工具定义了两个接口类型来描述数据结构：

interface RadixOption {
  label: string;
  radix: number;
}

interface ResultRow {
  label: string;
  index: number;
}

RadixOption 用于描述四个进制选择按钮。label 是按钮上显示的文本（如 “10(Dec)”），方便用户快速识别；radix 是对应的基数，直接传给 parseInt。将这两个信息封装在接口中而非使用两个独立数组，保证了标签与基数的对应关系不会因为数组索引错位而出错。

ResultRow 用于描述四个结果行。label 是行的中文名称（如 “十六进制 (HEX)”），index 对应 this.results 数组中的索引位置（十六进制在数组中的索引是 3）。之所以不在接口中直接存储结果值，是因为结果值会随用户操作动态变化，而标签和索引是静态的。将可变数据和不可变元数据分离，是响应式 UI 设计的重要原则。

数据初始化与静态配置

页面中定义了两个私有数组作为静态配置数据：

private radixOptions: RadixOption[] = [
  { label: '2(Bin)', radix: 2 },
  { label: '8(Oct)', radix: 8 },
  { label: '10(Dec)', radix: 10 },
  { label: '16(Hex)', radix: 16 }
];

private resultLabels: ResultRow[] = [
  { label: '二进制 (BIN)', index: 0 },
  { label: '八进制 (OCT)', index: 1 },
  { label: '十进制 (DEC)', index: 2 },
  { label: '十六进制 (HEX)', index: 3 }
];

这两个数组使用 private 而非 @State 修饰——它们的内容在组件生命周期内不会改变，不需要触发 UI 重渲染。鸿蒙的 ArkUI 框架中，@State 修饰的变量变化会触发 build() 方法重新执行，而普通类成员变量不会。正确地区分哪些数据需要响应式追踪，哪些不需要，可以避免不必要的 UI 重绘，提升性能。

初始化时，aboutToAppear() 调用 convert() 方法，对默认值 '255'（十进制）执行转换，使得页面加载后立即显示四种进制的转换结果。255 是一个特别好的默认值，因为它在二进制中是全 1（11111111），在十六进制中是 FF，对于开发者来说是熟悉的"边界值"。

源进制选择器的 UI 实现

四个源进制选择按钮使用 ForEach 循环渲染：

Row() {
  Text('源进制').fontSize(12).fontColor('#666');
  Blank();

  ForEach(this.radixOptions, (opt: RadixOption) => {
    Button(opt.label)
      .fontSize(10).height(26)
      .backgroundColor(this.fromRadix === opt.radix ? '#007aff' : '#f0f0f0')
      .fontColor(this.fromRadix === opt.radix ? '#ffffff' : '#666')
      .borderRadius(6).padding({ left: 8, right: 8 })
      .margin({ left: 4 })
      .onClick(() => { this.fromRadix = opt.radix; });
  });
}

按钮的当前选中状态通过 backgroundColor 和 fontColor 的条件表达式体现：当 this.fromRadix === opt.radix 时使用蓝色主题色，否则使用灰色。这里使用了 ArkTS 的三元表达式，简洁但要注意：三元表达式的两个分支返回类型必须一致。由于 '#007aff' 和 '#f0f0f0' 都是字符串类型，编译通过。

onClick 中只修改 this.fromRadix，不自动触发转换。这是刻意为之——用户可能在切换源进制后还需要修改输入值，自动转换会产生中间状态的无效结果。用户需要手动点击"转换"按钮来确认操作，这符合"显式操作"的交互原则，也避免了不必要的计算。

输入框与转换按钮

十进制默认值 255 预填充在输入框中：

TextInput({ text: this.input, placeholder: '输入数值...' })
  .fontSize(16).fontFamily('monospace')
  .backgroundColor('#ffffff').borderRadius(8).padding(12)
  .margin({ left: 16, right: 16, top: 8 })
  .onChange((v: string) => { this.input = v; });

fontFamily('monospace') 用于等宽显示——数字在等宽字体下排列整齐，便于用户检查输入。placeholder 给出了输入提示但不过于具体（不写"输入十进制数值"），因为源进制可以通过按钮切换为 2、8、16。

转换按钮触发 convert() 方法：

convert() {
  let val = parseInt(this.input.trim(), this.fromRadix);
  if (isNaN(val)) {
    this.results = ['无效输入', '无效输入', '无效输入', '无效输入'];
    return;
  }
  this.results = [
    val.toString(2),
    val.toString(8),
    val.toString(10),
    val.toString(16).toUpperCase()
  ];
}

isNaN(val) 判断覆盖了多种无效输入情况：空字符串、非数字字符（如 “xyz”）、在当前进制下不合法的字符（如十六进制模式下的输入 “10” 是合法的，但输入 “1G” 就不合法，因为 G 超出了 0-9/A-F 的范围）、以及值为 NaN 的特殊情况。注意 parseInt 对不合法的输入返回 NaN，而 NaN 有一个著名的 JS 怪癖：typeof NaN === 'number' 但 NaN !== NaN，所以必须用 isNaN() 函数而非 === 来判断。

当输入无效时，所有四个结果行都显示"无效输入"，而非保持上一次的旧结果。这避免了让用户误以为"上一次的转换结果对应的是当前无效输入"的混淆。

结果列表的渲染

结果区域通过 ForEach 循环渲染四个结果行：

ForEach(this.resultLabels, (row: ResultRow) => {
  Row() {
    Text(row.label)
      .fontSize(11).fontColor('#999').width(90);

    Text(this.results[row.index] || '-')
      .fontSize(14).fontFamily('monospace').fontColor('#1a1a1a')
      .layoutWeight(1);

    if (this.results[row.index]) {
      CopyButton({ text: this.results[row.index] });
    }
  }
  .width('100%')
  .padding({ left: 16, right: 16, top: 8, bottom: 8 })
  .backgroundColor('#ffffff')
  .border({ width: { bottom: 0.5 }, color: '#f0f0f0' });
});

每行包含三个部分：左侧的进制名称标签（固定宽度 90vp）、中间的结果值（弹性宽度 layoutWeight(1)）、右侧的复制按钮（条件显示）。底部分隔线使用 border 的 bottom 属性模拟 0.5px 的细线——在 Retina 屏幕上，0.5vp 的边框渲染为 1 个物理像素，比 1vp 的粗线更具现代设计感。

复制按钮的显示条件是 if (this.results[row.index])——只有当结果值非空时（无论是有效结果还是"无效输入"文本）才显示。在初始状态或输入为空时，result 为空字符串（falsy），复制按钮隐藏。这避免了允许用户复制空内容或无意义内容的尴尬。

当 result 为空字符串时，this.results[row.index] || '-' 表达式会显示 - 占位符。|| 运算符在 ArkTS 中的行为与 JavaScript 一致：左侧为 falsy（空字符串、0、null、undefined、NaN）时返回右侧值。所以要特别注意——如果转换结果恰好是 0，|| 会错误地显示 -。但在进制转换的场景中，数字 0 的字符串表示是 "0"（非空字符串，truthy），所以不存在这个问题。

错误输入的覆盖范围

parseInt 的行为有一些反直觉的边缘情况值得注意。例如 parseInt('0x10', 16) 返回 16——即使指定了 radix 为 16，parseInt 仍然会识别前缀 0x 并自动忽略它。而 parseInt('010', 8) 在严格模式下可能不识别前导零。为了保持一致性，RadixConverter 的输入框约定用户输入不含前缀（如不输入 0x 或 0b），源进制由按钮选择的 radix 参数决定。

另一个细节是：parseInt 对超出数字范围的字符采用"尽可能解析"的策略。例如 parseInt('10abc', 16) 返回 0x10a = 266——它解析了 10a 部分并忽略了 bc 之后的字符。这可能导致用户误以为输入被完整处理。HarmonyKit 的当前实现利用了这种宽容行为：对大多数正常输入（如纯数字加合法字母）解析正确，而对完全无效的输入（如纯字母"xyz"）返回 NaN 并显示错误。

如果要严格验证，可以在 parseInt 之后检查原始字符串与 val.toString(fromRadix) 是否一致（忽略大小写）。但这种严格模式可能拒绝了合理的输入（如十六进制的小写字母），需要根据使用场景权衡。当前工具选择的是"便利优先"策略。

数据流动的全链路追踪

以用户操作"源进制选择 16，输入 FF，点击转换"为例，追踪数据流动：

1. 用户点击 “16(Hex)” 按钮 → this.fromRadix = 16
2. 用户在 TextInput 中输入 “FF” → this.input = 'FF'
3. 用户点击"转换"按钮 → convert() 被调用
4. parseInt('FF', 16) → 返回 255（十进制整数）
5. val.toString(2) → '11111111'
6. val.toString(8) → '377'
7. val.toString(10) → '255'
8. val.toString(16).toUpperCase() → 'FF'
9. this.results = ['11111111', '377', '255', 'FF']
10. @State results 的变化触发 build() 重新执行，ForEach 循环更新四个结果行

这个链路的每一步都是同步操作。整个转换过程在单帧内完成（通常 < 1ms），用户感受不到任何延迟。这也是为什么进制转换工具不需要 loading 状态或异步处理。

关于大数精度

JavaScript 的 number 类型基于 IEEE 754 双精度浮点数，整数安全范围是 ±2^53-1（约 ±9007199254740991）。超出此范围的整数会丢失精度。例如 parseInt('9999999999999999', 10).toString(16) 可能不会返回期望的值。

HarmonyKit 的进制转换工具没有对此做特殊处理——这是 JavaScript 语言本身的限制。对于绝大多数开发调试场景（如颜色值 0-255、端口号 0-65535、内存地址 0-0xFFFFFFFF），双精度浮点数的整数精度完全足够。但如果需要处理 64 位整数的进制转换（如区块链哈希、大文件校验值），则需使用 BigInt 类型（ES2020 新增），通过 BigInt('0x' + hexString) 和 bigint.toString(radix) 来处理。

与计算器类工具的共性

RadixConverter 与 ColorConverter、TimestampConverter 同属"计算"类工具。它们共享以下模式：

1. 静态工具方法：核心计算逻辑封装在 utils 类的静态方法中（虽然 RadixConverter 的 convert 方法直接内联，因为逻辑足够简单）
2. aboutToAppear 初始化：页面加载时立即执行一次计算，展示默认值的结果
3. @State 驱动 UI：计算结果存储在 @State 变量中，变化时自动触发 UI 更新
4. 错误提示模式：输入无效时显示用户友好的文本而非抛出异常

RadixConverter 的特殊之处在于它不需要单独的工具类——parseInt 和 toString 都是 JavaScript 内置方法，不存在需要封装的复杂算法。这引出了一个有趣的设计哲学问题：什么时候该把逻辑抽到 utils 中？答案是：当逻辑需要多页面复用时，或当逻辑足够复杂需要单独测试时。对于两行核心代码的进制转换，内联在页面中反而是最清晰的做法。

UI 布局的设计考量

进制转换工具的整体布局遵循 HarmonyKit 的统一模板：顶部导航栏（返回按钮 + 工具标题）+ 可滚动内容区。但与编解码类工具使用"输入→操作按钮→输出"的纵向管道不同，进制转换使用了"源进制选择→输入→转换按钮→分隔线→结果列表"的横向+纵向混合布局。

源进制选择器使用了 Blank() 组件在标签和按钮组之间创建弹性间隔，使按钮组右对齐。这与 layoutWeight 的弹性布局有微妙区别：Blank 在 Row 中占据剩余空间并将两侧元素推开，相当于 flexbox 中的 justify-content: space-between；而 layoutWeight 是按比例分配空间。在选项固定的场景下（4 个等宽按钮），两者效果类似，但 Blank 的语义更清晰——“标签靠左，按钮靠右”。

小结

进制转换工具是 HarmonyKit 中最"简单"的工具之一——核心逻辑仅两行代码。但正是这种极简功能，最能体现"在交互上不偷懒"的设计态度。四个源进制按钮的选中态切换、结果行的列表式展示、无效输入的统一处理、条件显示的复制按钮——每一个细节都在降低用户的操作成本。

技术层面，该工具是 JavaScript/ArkTS 原生能力在鸿蒙应用中的直接运用。parseInt 和 toString 是每个前端开发者都熟悉的方法，但将它们与 ArkUI 的 @State、ForEach、条件渲染结合，就构建出了一个有实际价值的开发者工具。这启示我们：好的工具不一定需要高深的技术，精确地解决一个小问题本身就足够有价值。

---

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