HarmonyOS ArkUI 实战：从零打造一个交互式待办事项应用

在移动应用开发中，“待办事项（To-Do List）” 永远是检验 UI 框架能力的“Hello World”。它不仅涉及基础的
UI 渲染，还涵盖了状态管理（State Management）、布局嵌套（Nested
Layout）、列表渲染（List Rendering） 以及用户交互（Event Handling） 等核心知识点。

今天，我们将通过解析一个完整的 ArkUI 待办事项代码，带你深入理解如何构建一个既美观又具有交互性的 HarmonyOS 应用。

核心功能与界面概览

我们最终实现的界面包含以下几个核心模块：

• 标题区域：显示欢迎信息。
• 计数器区域：一个简单的加减计数器，用于演示基本的交互。
• 颜色选择区域：一组圆形颜色选择器，用于动态改变应用的主题色。
• 列表区域：一个可滚动的待办事项列表，每个事项包含标题和删除按钮。
• 添加按钮：用于向列表中添加新项目。

整个界面布局清晰，色彩鲜明，是一个非常典型的卡片式设计。

代码深度解析

我们将代码拆解为三个部分进行讲解：状态定义、UI 结构 和 交互逻辑。

1. 状态管理：@State 装饰器

在 ArkUI 中，数据驱动视图是核心思想。我们使用 @State 装饰器来声明组件内部的状态变量。

@State message: string = '欢迎使用鸿蒙应用';
@State count: number = 0;
@State textList: string[] = ['项目一', '项目二', '项目三'];
@State selectedColor: string = '#007DFF';

• message：用于存储标题文本。
• count：用于存储计数器的当前值。
• textList：一个字符串数组，用于存储待办事项列表的数据。
• selectedColor：用于存储当前选中的主题颜色。

💡 提示：@State 变量的变化会自动触发 UI 重新渲染，这是实现响应式 UI 的关键。

2. UI 布局结构：Column 与 Row 的嵌套

整个页面的最外层是一个 Column，它负责将页面内容垂直分为五个部分：标题、计数器、颜色选择、列表和添加按钮。

外层容器设置：

Column() {
  // ... 子组件 ...
}
.width('100%')
.height('100%')
.padding(20)
.backgroundColor('#FFFFFF')

• width('100%') 和 height('100%')：使容器占满整个屏幕。
• padding(20)：为容器添加内边距，使内容与屏幕边缘保持距离。
• backgroundColor('#FFFFFF')：设置背景颜色为白色。

3. 交互逻辑：事件处理

代码中包含了多个交互逻辑，我们逐一解析。

计数器交互：

Button('-')
  .onClick(() => {
    this.count = Math.max(0, this.count - 1);
  })

Button('+')
  .onClick(() => {
    this.count++;
  })

• 减按钮：点击时将 count 减 1，但通过 Math.max(0, ...) 确保计数器的值不会小于 0。
• 加按钮：点击时将 count 加 1。
  

颜色选择交互：

Circle()
  .fill(color)
  .onClick(() => {
    this.selectedColor = color;
  })

• 点击颜色圆圈：将 selectedColor 设置为当前圆圈的颜色，从而动态改变应用的主题色。

列表交互：

Button('删除')
  .onClick(() => {
    this.textList.splice(index, 1);
  })

Button('添加新项目')
  .onClick(() => {
    this.textList.push(`项目${this.textList.length + 1}`);
  })

• 删除按钮：点击时从 textList 中删除当前项。
• 添加按钮：点击时向 textList 中添加一个新项目。

总结

通过深入解析这个待办事项应用，我们不仅学习了如何使用 @State 进行状态管理，还掌握了 Column、Row、List 等布局组件的使用方法，以及如何通过 onClick 事件处理用户交互。

这个示例虽然简单，但它涵盖了 HarmonyOS ArkUI 开发的核心概念。希望这篇文章能帮助你更好地理解 ArkUI 的开发模式，为构建更复杂的应用打下坚实的基础。