HarmonyKit | 鸿蒙开发协作：如何为 HarmonyKit 贡献一个新的工具

引言：从使用者到贡献者

HarmonyKit 的架构设计原则之一是"零破坏性扩展"——新增一个工具不应该修改任何现有工具的代码。这意味着贡献一个新工具的门槛极低：看懂 ToolItem 接口、选择一个页面模板、实现核心逻辑。整个过程 10 分钟。

这篇文章是写给想为 HarmonyKit 贡献代码的开发者的完整指南——从 Fork 仓库到提交 Pull Request。

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

四步标准流程

第一步：数据注册

在 model/ToolItem.ets 的 TOOL_LIST 数组中追加一个对象：

{
  id: 'newtool',           // 唯一标识，用于路由匹配
  name: '新工具名称',        // 卡片显示名称（4-7个字）
  description: '一句话描述',  // 卡片描述（8-20个字）
  icon: 'NT',              // 等宽字体短文本（1-3字符）
  color: '#xxxxxx',        // 主题色（不与已有颜色重复）
  category: '计算',         // 格式化/编解码/计算/文本
  routerPath: 'pages/tools/NewTool'
}

id 是整个应用的唯一标识——用于 Tab 筛选和路由匹配。color 参考已有 10 个工具的配色体系，相邻工具在色环上拉开至少 60 度。

第二步：创建页面文件

在 pages/tools/ 下创建 NewTool.ets。从相似的工具页面复制骨架：

• 输入型工具（Base64、URL、哈希）→ 复制 Base64Tool.ets
• 计算型工具（时间戳、进制、颜色）→ 复制 RadixConverter.ets
• 文本型工具（正则、统计）→ 复制 RegexTester.ets

骨架包含：Header（返回+标题）、Scroll包裹、输入区、操作按钮、输出区+CopyButton。替换核心处理逻辑即可。

第三步：实现核心逻辑

简单逻辑（<10行）直接写在页面方法中。复杂逻辑（>10行）在 utils/NewToolUtils.ets 中创建静态工具类——保持 utils 的纯函数约束。

第四步：注册路由

在 main_pages.json 中添加页面路径。

代码规范

• 输出区域必须有 CopyButton
• 错误信息展示在操作区和输出区之间
• 主题色不与已有工具重复
• 所有方法统一使用 this.getUIContext().getRouter() 而非全局 router

PR 流程

Fork → 创建 feat/new-tool 分支 → 提交 → Pull Request。PR 描述包含工具的用途和核心算法概要。

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