当前位置：首页 > news >正文

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

news 2026/7/13 0:07:34

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）。