HarmonyOS 6与ArkTS开发待办清单应用实战

1. 项目概述

今天给大家分享一个基于HarmonyOS 6和ArkTS开发的待办清单应用案例。这个案例虽然看起来简单，但包含了HarmonyOS开发中的几个核心知识点：状态管理、条件渲染、样式动态绑定以及组件封装。我自己在实际开发过程中踩过不少坑，这次就把完整的实现过程和经验总结分享给大家。

这个待办清单的主要功能包括：

• 显示待办事项列表
• 点击可以切换完成/未完成状态
• 已完成事项会显示删除线并变灰
• 未完成事项正常显示
• 每个事项前面有对应的状态图标

2. 核心功能实现

2.1 数据结构设计

首先我们需要设计待办事项的数据结构。在ArkTS中，我们使用class来定义数据模型：

typescript复制class ToDoModel {
  index: number;
  content: string;

  constructor(index: number, content: string) {
    this.index = index;
    this.content = content;
  }
}

这里我特意添加了index字段而不是直接用content作为唯一标识，因为在真实应用中，可能会有相同内容的待办事项，用自增ID作为唯一标识更合理。

2.2 主页面组件

主页面组件负责管理整个待办事项列表的数据和状态：

typescript复制@Entry
@Component
struct ToDoListPage {
  @State message: string = '待办列表';
  //待办事项数据集合
  @State dataList: Array<ToDoModel> = [
    new ToDoModel(1, '取快递'),
    new ToDoModel(2, '健身'),
    new ToDoModel(3, '图书馆还书'),
    new ToDoModel(4, '小米4S店提车'),
    new ToDoModel(5, '办理交房手续'),
  ]

  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)

      ForEach(this.dataList, (item: ToDoModel) => {
        ToDoItem({ content: item.content })
      }, (item: ToDoModel) => JSON.stringify(item))
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#ffffff') // 页面背景颜色
  }
}

几个关键点：

1. 使用@State装饰器声明响应式数据，当数据变化时会触发UI更新
2. ForEach用于遍历数据列表并渲染子组件
3. 第三个参数是key生成函数，确保每个列表项有唯一标识

提示：在实际项目中，建议将初始数据放在单独的文件中管理，或者从网络/本地存储加载。

2.3 待办事项子组件

待办事项子组件负责单个事项的展示和交互：

typescript复制@Component
struct ToDoItem {
  private content?: string; //具体的待办项的内容
  @State isComplete: boolean = false; //是否完成

  build() {
    Row() {
      //if条件渲染，替换图标效果
      if (this.isComplete) {
        this.labelIcon($r('app.media.ic_ok'));
      } else {
        this.labelIcon($r('app.media.ic_default'));
      }
      //每一条待办事项，通过opacity属性设置虚化效果，decoration属性设置删除线效果
      Text(this.content)
        .fontSize('20fp')
        .fontWeight(500)
        .opacity(this.isComplete ? 0.4 : 1)
        .decoration({ type: this.isComplete ? TextDecorationType.LineThrough : TextDecorationType.None })
    }
    .borderRadius(24)
    .backgroundColor('#ffffff')
    .width('95%')
    .height('64vp')
    .onClick(() => {
      this.isComplete = !this.isComplete;
    })
  }

  //抽离"是否完成按钮"的子组件，方便复用
  @Builder
  labelIcon(icon: Resource) {
    Image(icon)
      .width('28vp')
      .height('28vp')
      .margin('20vp')
  }
}

这个组件有几个值得注意的技术点：

1. 条件渲染：使用if-else语句根据完成状态显示不同的图标
2. 样式动态绑定：通过三元表达式动态设置文本的透明度和删除线
3. 事件处理：点击事件切换完成状态
4. Builder方法：将图标组件抽离出来复用

3. 功能扩展与优化

3.1 添加新待办事项

基础版本只支持查看和切换状态，实际应用中我们还需要添加新事项的功能。在主页面添加一个输入框和按钮：

typescript复制@Entry
@Component
struct ToDoListPage {
  @State message: string = '待办列表';
  @State dataList: Array<ToDoModel> = [...];
  @State newItemContent: string = ''; // 新增：输入框内容

  build() {
    Column() {
      Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
      
      // 新增：输入框和添加按钮
      Row() {
        TextInput({ placeholder: '输入新待办事项' })
          .width('70%')
          .onChange((value: string) => {
            this.newItemContent = value;
          })
        Button('添加')
          .width('25%')
          .onClick(() => {
            if (this.newItemContent.trim()) {
              this.dataList.push(new ToDoModel(this.dataList.length + 1, this.newItemContent));
              this.newItemContent = '';
            }
          })
      }
      .width('95%')
      .margin({ top: 20 })

      ForEach(this.dataList, (item: ToDoModel) => {
        ToDoItem({ content: item.content })
      }, (item: ToDoModel) => JSON.stringify(item))
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#ffffff')
  }
}

3.2 持久化存储

目前数据只在内存中，应用关闭后会丢失。我们可以使用HarmonyOS的Preferences工具实现本地存储：

1. 首先导入模块：

typescript复制import preferences from '@ohos.data.preferences';

2. 添加存储和加载方法：

typescript复制// 存储数据
async function saveToDoList(context: any, list: Array<ToDoModel>) {
  try {
    const pref = await preferences.getPreferences(context, 'todo_pref');
    await pref.put('todo_list', JSON.stringify(list));
    await pref.flush();
  } catch (e) {
    console.error(`保存失败: ${e}`);
  }
}

// 加载数据
async function loadToDoList(context: any): Promise<Array<ToDoModel>> {
  try {
    const pref = await preferences.getPreferences(context, 'todo_pref');
    const listStr = await pref.get('todo_list', '[]');
    return JSON.parse(listStr);
  } catch (e) {
    console.error(`加载失败: ${e}`);
    return [];
  }
}

3. 在页面组件中使用：

typescript复制@Entry
@Component
struct ToDoListPage {
  // ...
  
  aboutToAppear() {
    loadToDoList(getContext(this)).then(list => {
      if (list.length > 0) {
        this.dataList = list;
      }
    });
  }
  
  // 在修改数据的地方调用saveToDoList
  // 例如添加新事项后：
  // this.dataList.push(...);
  // saveToDoList(getContext(this), this.dataList);
}

3.3 性能优化

当列表项很多时，需要注意渲染性能：

1. 为ForEach提供稳定的key：

typescript复制ForEach(this.dataList, (item: ToDoModel) => {
  ToDoItem({ content: item.content })
}, (item: ToDoModel) => item.index.toString()) // 使用index作为key

2. 避免不必要的重新渲染：

typescript复制// 在ToDoItem组件中添加以下装饰器
@Reusable
@Component
struct ToDoItem {
  // ...
}

3. 使用LazyForEach处理超长列表：

typescript复制// 需要实现数据源接口
class ToDoDataSource implements IDataSource {
  // 实现必要的方法
}

// 使用LazyForEach
LazyForEach(new ToDoDataSource(), (item: ToDoModel) => {
  ToDoItem({ content: item.content })
}, (item: ToDoModel) => item.index.toString())

4. 常见问题与解决方案

4.1 图标不显示问题

如果遇到图标不显示的情况，检查以下几点：

1. 确保图片资源放在resources/base/media/目录下
2. 检查图片文件名是否正确，包括大小写
3. 确认$r('app.media.ic_ok')中的路径是否正确

4.2 状态更新不生效

如果点击后状态没有变化，检查：

1. 是否使用了@State装饰器声明状态变量
2. 是否在事件处理函数中正确修改了状态
3. 确保没有在子组件中直接修改父组件传递的props

4.3 列表滚动问题

默认情况下Column不会滚动，如果需要滚动列表：

typescript复制Column() {
  // ...列表内容
}
.scrollable(ScrollDirection.Vertical)
.scrollBar(BarState.On)

4.4 样式适配问题

鸿蒙应用需要适配不同设备，建议：

1. 使用vp作为尺寸单位而不是固定像素
2. 对于字体大小，使用fp单位
3. 使用百分比或弹性布局而不是固定宽度

5. 项目结构与代码组织建议

随着项目复杂度增加，良好的代码组织非常重要：

code复制src/main/ets/
├── components/       // 公共组件
│   └── ToDoItem.ets  // 待办事项组件
├── model/            // 数据模型
│   └── ToDoModel.ets 
├── utils/            // 工具函数
│   └── storage.ets   // 存储相关工具
└── pages/            // 页面
    └── ToDoList.ets  // 主页面

在ToDoModel.ets中定义数据模型：

typescript复制export class ToDoModel {
  index: number;
  content: string;
  completed: boolean; // 可以添加更多字段

  constructor(index: number, content: string, completed: boolean = false) {
    this.index = index;
    this.content = content;
    this.completed = completed;
  }
}

在storage.ets中封装存储逻辑：

typescript复制import preferences from '@ohos.data.preferences';

export async function saveToDoList(context: any, list: Array<ToDoModel>): Promise<void> {
  // ...实现存储逻辑
}

export async function loadToDoList(context: any): Promise<Array<ToDoModel>> {
  // ...实现加载逻辑
}

6. 测试与调试技巧

6.1 单元测试

为关键功能添加单元测试：

typescript复制// 测试ToDoModel
describe('ToDoModel', () => {
  it('should create instance correctly', () => {
    const item = new ToDoModel(1, '测试事项');
    expect(item.index).assertEqual(1);
    expect(item.content).assertEqual('测试事项');
  });
});

6.2 预览器调试

使用DevEco Studio的预览器快速验证UI变化：

1. 支持热重载，修改代码后立即看到效果
2. 可以模拟不同设备尺寸
3. 支持调试日志输出

6.3 真机调试

在真机上测试时注意：

1. 检查权限是否配置正确
2. 测试不同分辨率的显示效果
3. 验证存储功能是否正常工作

7. 进一步学习建议

如果想深入学习HarmonyOS开发，建议：

1. 掌握ArkTS语言特性，特别是装饰器和响应式编程
2. 学习HarmonyOS的UI组件和布局方式
3. 了解Ability和页面生命周期
4. 熟悉常用的API，如网络请求、存储、传感器等
5. 参考官方文档和示例代码

这个待办清单虽然简单，但涵盖了HarmonyOS开发的许多核心概念。我在实际开发中发现，良好的状态管理和组件设计是构建复杂应用的基础。建议从这个小项目开始，逐步扩展功能，比如添加分类、提醒、同步等功能，这样可以循序渐进地掌握HarmonyOS开发的各个方面。