HarmonyKit | 鸿蒙开发：@kit.UIDesignKit 组件体系完整解读

引言：一套组件体系，而非一个组件库

@kit.UIDesignKit 是 HarmonyOS 在 API 22 引入的核心 UI 套件。在 HarmonyKit 项目中，它被用于首页的 Tab 导航（HdsTabs）和材质效果（hdsMaterial）。但这仅是冰山一角——UIDesignKit 是一个完整的、由 30+ 个 HDS（Harmony Design System）组件构成的体系。

理解这个体系不仅是为了"能用它的组件"，更是为了理解鸿蒙对"应用应该如何构建 UI"的设计立场。这篇文章完整解读 UIDesignKit 的组件生态、设计理念、选型逻辑和未来展望。

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

UIDesignKit 的定位：一个 Kit，不是多个组件

首先要理解 @kit.UIDesignKit 在鸿蒙 Kit 体系中的位置。鸿蒙的系统能力被组织为多个 Kit 包：

@kit.ArkUI           # ArkUI 框架核心（组件、布局、动画）
@kit.UIDesignKit     # HDS 组件体系（标准化设计组件）
@kit.AbilityKit      # Ability 和生命周期管理
@kit.BasicServicesKit # 基础服务（粘贴板、通知等）
@kit.CryptoArchitectureKit # 加密框架
...

@kit.UIDesignKit 与 @kit.ArkUI 的关系是：ArkUI 提供"组件构建能力"（Component、State、Builder 等底层机制），UIDesignKit 提供"标准化组件实现"（在这些底层机制之上封装的设计系统组件）。

你可以只使用 ArkUI 构建整个应用——就像 HarmonyKit 的 10 个工具页面，它们只使用了基础组件（Column、Row、Text、Button、TextArea等）。但当你需要导航栏、选项卡、对话框等"系统级 UI"，UIDesignKit 提供了标准化的实现。

HDS 组件全景图

UIDesignKit 包含以下主要组件类别：

导航类组件

组件	用途	是否用于 HarmonyKit
HdsNavigation	页面级导航框架	计划中
HdsTabs	标签页切换	已使用（首页分类导航）
HdsToolbar	工具栏	未使用
HdsBreadcrumb	面包屑导航	未使用

内容类组件

组件	用途	是否用于 HarmonyKit
HdsList	标准化列表	未使用（使用了基础 Grid）
HdsCard	标准化卡片	未使用（自定义了 ToolCard）
HdsEmptyState	空状态占位	未使用
HdsLoading	加载状态指示	未使用

交互类组件

组件	用途	是否用于 HarmonyKit
HdsButton	标准化按钮	未使用（使用了基础 Button）
HdsTextField	标准化文本输入	未使用（使用了基础 TextInput/TextArea）
HdsSwitch	标准化开关	未使用
HdsSlider	标准化滑块	未使用
HdsStepper	步进器	未使用

反馈类组件

组件	用途	是否用于 HarmonyKit
HdsDialog	标准化对话框	未使用
HdsToast	标准化提示	未使用（使用了 promptAction.showToast）
HdsSnackbar	底部消息条	未使用
HdsBottomSheet	底部弹出面板	未使用

选择类组件

组件	用途	是否用于 HarmonyKit
HdsDatePicker	日期选择器	未使用
HdsTimePicker	时间选择器	未使用
HdsDropdownMenu	下拉菜单	未使用
HdsSegmentedControl	分段控制器	未使用

为什么 HarmonyKit 只用了一个 HDS 组件

HarmonyKit 目前只在首页使用了 HdsTabs（和对应的 hdsMaterial）。其他所有 UI——ToolCard、CopyButton、各个工具页——都使用了 ArkUI 基础组件。这是一个有意的技术选择，背后有四个考量：

考量一：工具页需要定制化 UI

HarmonyKit 的工具页（如 RegexTester、ColorConverter）的 UI 布局高度定制化——输入框和结果区并排、自定义的旗标按钮、预览色块。这些布局不是标准化的"表单"或"列表"，强行套用 HDS 组件反而增加适配成本。

以 RegexTester 为例：

// 手动布局的自定义旗标按钮组
Row() {
  Button('g').fontSize(11).height(28)
    .backgroundColor(this.flags.includes('g') ? '#007aff' : '#f0f0f0')
    .fontColor(this.flags.includes('g') ? '#ffffff' : '#333')
    .borderRadius(6).padding({ left: 8, right: 8 })
    .margin({ left: 4 })
    .onClick(() => this.toggleFlag('g'));
  // ... i, m 旗标按钮
}

这个场景中，如果使用 HdsSegmentedControl 替换手动布局的旗标按钮，反而会因为 HdsSegmentedControl 的设计约束（等宽、等间距、单选）而无法实现当前的交互效果（多个独立开关、不等宽标签）。

考量二：最小依赖原则

每引入一个 HDS 组件，就增加了一个 API 版本依赖。HdsTabs 是 API 22 的组件——HarmonyKit 的 compatibleSdkVersion 已经是 "6.0.2(22)"，所以使用它没有新增限制。但如果使用 HdsNavigation（API 24），就会将最低兼容版本提升到 API 24。

在"开箱即用的标准化体验"和"更多的设备兼容范围"之间，HarmonyKit 选择保守的策略：只在确实需要时才引入新 API 依赖。

考量三：HAP 体积

每个 HDS 组件引入都会增加一小部分代码到最终的 HAP 中（通过 Tree Shaking 优化，未使用的 HDS 组件不会被打包）。但如果 20 个 HDS 组件都被使用，即使 Tree Shaking 生效，HDS 的共享基础设施代码也会增加。对于 HarmonyKit 这样的轻量级工具应用（目标 HAP 在 3MB 左右），每 KB 体积都要有对应的功能回报。

考量四：学习曲线的平缓化

作为一个开源项目，HarmonyKit 的代码被设计为"可读的学习材料"。使用 ArkUI 基础组件构建的 UI 可以直接阅读——每行代码都对应具体的视觉和交互。使用 HDS 组件时，一部分行为由系统接管（如材质效果、自适应布局），代码的"可读性"反而降低——你必须查阅 HDS 文档才能理解某个属性的行为。

对于目标是"展示鸿蒙开发最佳实践"的项目而言，基础组件的可读性优于 HDS 组件的便捷性。

但这不是说 HDS 组件不好——在商业应用中，使用 HdsButton 替代手动配置的 Button 能带来一致的设计语言、更少的代码、更好的无障碍支持和更可靠的跨设备适配。这是一种工程上的取舍。

HDS 组件的技术特性

使用 HDS 组件不仅仅是"使用一个封装好的 UI 控件"，它还带来了以下技术特性：

1. 无障碍（Accessibility）内置

每个 HDS 组件都内置了完整的无障碍支持——正确的 accessibilityLabel、accessibilityHint、焦点顺序、屏幕阅读器兼容。这些是基础组件需要开发者手动配置的。

对于 HarmonyKit 来说，无障碍不是当前优先级——因为核心交互非常简单（输入文本→查看结果→复制）。但对于面向广泛用户群的商业应用，HDS 组件的内置无障碍支持可以节省大量开发时间。

2. 自适应布局

HDS 组件会自动适应不同屏幕尺寸和方向。以 HdsTabs 为例：

• 手机竖屏：Tab 标签等宽排列
• 手机横屏：Tab 标签紧凑排列
• 平板：Tab 标签可能需要调整间距或采用侧边栏布局（由 HdsNavigation 处理）

这些自适应逻辑由 HDS 内部处理，开发者不需要编写条件布局代码。

3. 设计一致性

HDS 组件共享一套设计令牌（Design Tokens）——颜色、间距、圆角、字重等基础设计参数。使用 HDS 组件的应用会自动获得视觉一致性，不需要为每个按钮配置相同的颜色和阴影。

HarmonyKit 没有使用 HDS 设计令牌，因为它的视觉风格是自定义的（#007aff 蓝色主色调、#f5f5f5 灰色背景、14px 圆角）。这是一种"有意的偏离"——HarmonyKit 要表达的不是系统的中性风格，而是开发者工具的"干净、精确、克制"的气质。

4. 系统主题联动

HDS 组件会自动联动系统主题（深色模式、字体大小、强调色）。当用户切换深色模式时，使用 HDS 组件的 UI 会自动适配——不需要写 if (darkMode) { ... } 的条件逻辑。

HarmonyKit 通过在 EntryAbility.onCreate 中设置 ColorMode.COLOR_MODE_NOT_SET 主动跟随了系统颜色模式：

this.context.getApplicationContext().setColorMode(
  ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET
);

但由于工具页的组件使用的是基础组件（颜色硬编码），实际对深色模式的支持有限。这是一个已知的改进项——计划通过 HDS 组件替换或引入系统颜色资源来完善深色模式体验。

5. 未来兼容性

当鸿蒙引入新的视觉特性（如 ImmersiveMaterial），HDS 组件会自动获益。使用 HDS Tabs 的应用在 API 26 上自动拥有材质效果，不需要任何代码变更。这正是"HDS 作为设计系统的抽象层"的核心价值——你的应用通过 HDS 与系统设计语言保持一致，而不需要跟踪每个 API 的新 UI 特性。

迁移路径：从基础组件到 HDS 组件

对于已经使用基础组件构建的应用（如 HarmonyKit），迁移到 HDS 组件需要分阶段实施：

第一阶段：识别可替换的"标准化交互"

应用中有两类 UI：

• 标准化交互：导航、选项卡、对话框、菜单。这些应该替换为 HDS 组件。
• 定制化交互：工具页面的输入/输出配置。这些保留基础组件。

HarmonyKit 目前处于第一阶段的初期——已完成首页导航的 HDS 迁移（HdsTabs），正在考虑工具页面的导航栏是否迁移到 HdsNavigation。

第二阶段：替换系统级 UI

将以下组件替换为 HDS 对应物：

• 对话框（AlertDialog → HdsDialog）
• 按钮（Button → HdsButton）——仅限"系统级"的按钮，工具页面的自定义按钮保留
• 输入框（TextInput → HdsTextField）——仅限"表单"场景

HarmonyKit 的工具页中，大部分 Button 和 TextInput 都是高度自定义的（颜色、尺寸、字体都不同），不适合替换为 HDS 变体。但 CopyButton（复制到剪贴板）这种通用操作按钮可以考虑迁移到 HdsButton 以获得更好的无障碍支持。

第三阶段：采用设计令牌

将硬编码的颜色、间距、圆角替换为 HDS 设计令牌或自定义令牌：

// 替换前
.fontColor('#1a1a1a')
.backgroundColor('#f5f5f5')

// 替换后（使用 HDS 令牌）
.fontColor($r('sys.color.font_primary'))
.backgroundColor($r('sys.color.background_secondary'))

或者保持自定义令牌但统一管理：

.fontColor($r('app.color.text_primary'))
.backgroundColor($r('app.color.background'))

第四阶段：启用高级特性

在基础组件已替换为标准 HDS 组件的基础上，启用材质效果、自适应布局等高级特性。这是 API 26 特有的能力，需要设备运行对应的系统版本。

HDS 组件选择的决策树

当你面对"该用基础组件还是 HDS 组件"的选择时，可以参考以下决策树：

是全局导航/框架级元素吗？
├── 是 → 使用 HDS 组件（HdsTabs, HdsNavigation）
└── 否 → 用户交互是标准化的吗（对话框、菜单、表单）？
    ├── 是 → 使用 HDS 组件（HdsDialog, HdsTextField）
    └── 否 → UI 高度定制化吗（自定义布局、颜色、动画）？
        ├── 是 → 使用 ArkUI 基础组件
        └── 否 → 可以提升API兼容性吗？
            ├── 是 → 使用 HDS 组件
            └── 否 → 使用 ArkUI 基础组件

HarmonyKit 当前的状态是：顶部 Tab 导航使用 HDS 组件（全局框架元素），所有内容/工具页面使用 ArkUI 基础组件（高度定制化 UI）。

UIDesignKit 的未来演进

基于 HarmonyOS 的发展趋势，UIDesignKit 可能会在以下几个方面继续演进：

1. HdsNavigation 作为页面导航的默认方案

目前 HarmonyKit 使用 router.pushUrl() 进行页面导航。HdsNavigation 提供了一种声明式的、带返回栈管理的导航方案。随着 API 26+ 的普及，预计 HdsNavigation 会取代 router.pushUrl() 成为推荐的页面导航方式。

2. 更多"智能"组件

趋势是从"组件库"到"智能组件库"——组件不仅仅是封装 UI，还内置了行为智能。例如：

• HdsList 自动检测数据量并启用虚拟滚动
• HdsTextField 自动检测输入内容类型并调整键盘
• HdsNavigation 自动管理手势返回和动画过渡

3. 跨设备形态的统一

随着鸿蒙生态扩展到车机、手表、电视等设备形态，HDS 组件需要在这些形态间提供统一的 API 和自适应的视觉表现。开发者用同一套 HDS API，在不同设备上获得"最合适"的体验。

结语

@kit.UIDesignKit 不仅是鸿蒙的 UI 组件库，它是鸿蒙对"应用应该长什么样"的设计立场。选择 HDS 组件意味着你选择了一致的视觉语言、内置的无障碍支持、自适应的布局和未来兼容性。选择 ArkUI 基础组件意味着你保留了完全的 UI 控制权。

两者不是非此即彼的关系——就像 HarmonyKit 展示的，导航层用 HDS，内容层用基础组件，是一种实用主义的混合策略。理解何时拥抱系统的设计体系、何时坚持自己的设计表达，是鸿蒙 UI 开发的核心技能。

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