一、引言待办清单Todo List是前端开发领域的Hello World几乎所有现代前端框架的官方教程都会以它作为入门案例。这并非偶然——Todo List 虽小却涵盖了前端开发中最核心的三大能力列表渲染将数据数组映射为 UI 元素状态管理添加、删除、修改数据后自动更新视图用户交互输入框、按钮、复选框的协同工作本文将通过构建一个完整的待办清单应用深入讲解 ArkTS 中列表渲染与状态管理的原理与实践。二、需求规格2.1 功能清单功能 描述 优先级查看清单 显示所有待办事项列表 P0添加事项 通过输入框和按钮添加新待办 P0标记完成 通过复选框切换待办的完成状态 P0删除事项 一键删除不再需要的待办 P0完成统计 显示总数量和已完成数量 P12.2 数据模型每一条待办事项需要包含以下三个字段interface Todo {id: number; // 唯一标识text: string; // 待办内容done: boolean; // 是否完成}三、ArkTS 中的列表渲染3.1 ForEach 基础用法在 ArkTS 中列表渲染通过 ForEach 组件实现。它的基本语法是ForEach(arr: any[], // 数据源数组itemGenerator: (item, index) void, // 子组件生成函数keyGenerator?: (item, index) string // 唯一键生成函数可选)在我们的待办清单中List() {ForEach(this.todos, (todo: Todo, index: number) {ListItem() {// 每个待办项的 UI}})}3.2 keyGenerator 的重要性keyGenerator 虽然标记为可选参数但在实际开发中强烈建议提供。它的作用是帮助 ArkUI 框架在列表更新时精确追踪每个元素实现高效的 DOM Diff。ForEach(this.todos, (todo: Todo) {ListItem() { … }}, (todo: Todo) todo.id.toString())如果不提供 keyGenerator框架会使用数组索引作为默认键。这在以下场景会导致严重的渲染错误删除列表中间的某个元素时后续元素会因为索引变化而重新创建复选状态可能会错位动画过渡异常3.3 List 组件的特性ArkTS 的 List 组件专为滚动列表设计具备以下特性虚拟列表Virtual List对于长列表只渲染可视区域内的元素大幅提升性能弹性滚动Bounce Effect在列表边界提供回弹效果滑动操作支持滑动删除等高级交互在待办清单中我们使用 List → ListItem → ForEach 的经典三层结构List() {ForEach(this.todos, (todo: Todo, index: number) {ListItem() {// 待办项内容}})}.layoutWeight(1) // 占据剩余空间.width(‘100%’)四、状态管理深入分析4.1 State 的反应式边界在 ArkTS 中State 装饰器为变量建立了反应式边界Reactive Boundary。当 State 变量的值发生变化时框架会自动收集依赖于该变量的 UI 组件并在下一个帧周期进行重新渲染。但在操作对象数组时有一个常见的陷阱错误示范// 直接修改数组元素属性——可能不会触发 UI 更新let todo this.todos[index];todo.done true;正确做法// 通过数组索引直接修改——ArkTS 可以追踪this.todos[index].done true;在 ArkTS 中, State 对数组的监听是浅监听Shallow Watch。直接通过索引修改数组元素内部的属性是支持的框架会追踪数组元素的变更但替换整个数组对象也会触发更新。4.2 添加待办Button(‘添加’).onClick(() {let txt this.inputText.trim();if (txt) {this.todos.push({ id: this.nextId, text: txt, done: false });this.inputText ‘’;}})这里有一个容易被忽略的细节在添加待办之前先对输入文本进行 trim() 操作去除首尾空白。如果用户只输入了空格txt 为空字符串if (txt) 判断会阻止添加空待办。4.3 删除待办Button(‘’).onClick(() {this.todos.splice(index, 1);})使用 Array.splice(index, 1) 删除指定索引的元素。splice 是原地操作In-place Operation会直接修改原数组。ArkTS 的 State 能够监听到 splice 操作并触发 UI 更新。4.4 切换完成状态Toggle({ type: ToggleType.Checkbox, isOn: todo.done }).onChange((v: boolean) {this.todos[index].done v;})Toggle 组件的 onChange 回调返回当前的选中状态 v。我们将这个值直接赋给对应待办的 done 属性。五、UI 实现细节5.1 待办项的视觉状态已完成和未完成的待办项在视觉上应有明显区分Text(todo.text).fontSize(16).decoration({type: todo.done ? TextDecorationType.LineThrough : TextDecorationType.None}).fontColor(todo.done ? ‘#AAAAAA’ : ‘#333333’)通过 decoration 属性为已完成待办添加删除线LineThrough同时将字体颜色变为灰色。这种视觉变化给用户提供了即时的完成反馈。5.2 统计信息Text(‘总计: ’ this.todos.length)Text(’ 已完成: ’ this.todos.filter(t t.done).length)实时更新的统计信息让用户对整个清单的状态一目了然。filter 方法筛选出所有 done 为 true 的待办再取 length 得到已完成数量。六、常见陷阱与解决方案6.1 列表未更新如果修改待办后列表没有刷新请检查是否使用了 State 装饰器是否直接修改了数组而不是替换ForEach 是否提供了 keyGenerator6.2 删除后状态错乱如果在 ForEach 中没有提供 keyGenerator删除元素后可能出现复选框状态错位的问题。这通常表现为删除了第二项但原来第三项的复选框被标记为已完成。解决方案始终为 ForEach 提供稳定的 keyGenerator使用数据的唯一标识如 todo.id作为键。七、扩展思路本地持久化使用 Preferences API 保存待办数据分类分组按完成状态或标签对清单进行分组拖拽排序使用 onDrag 和 onDrop 事件实现拖拽排序日历集成为待办设置截止日期待办清单虽小但它代表了 CRUDCreate, Read, Update, Delete类应用的基础范式。掌握它你就掌握了绝大多数信息管理类应用的核心模式。
