ArkTS 待办列表状态更新:用不可变数据与稳定键控制刷

举报
yd_236685256 发表于 2026/11/18 00:40:09 2026/11/18
【摘要】 本文以待办列表为例,说明 ArkTS 状态更新中的不可变数组、稳定键与筛选派生,给出 ArkUI 实现、组件状态边界、长列表优化条件和回归验收清单。

问题:为什么点了一个复选框,整页却像“重新来过”?

在 HarmonyOS 的一个小型待办页里,我把任务标题、完成状态和筛选开关放在同一个列表中。最初的实现直接修改数组里的对象:this.items[index].done = checked。代码短,但当列表由多个组件组合、还要支持筛选和排序时,数据更新路径容易变得含糊:有时视图没有按预期刷新,有时行组件暂存的状态又跟着另一条记录走。

这里我采用两个约束:用新的数组表达一次状态变化;用业务 ID 作为列表项的稳定键。状态变化因此可追踪,框架也能更可靠地把旧节点和新数据对应起来。

先把数据变更写成纯转换

下面的例子把“显示哪些行”和“更新哪一项”分开。TodoItem 的 id 在创建任务时生成,之后不随标题或排序变化。

interface TodoItem {
  id: string
  title: string
  done: boolean
}

@Entry
@Component
struct TodoPage {
  @State items: TodoItem[] = [
    { id: 't-101', title: '整理页面状态', done: false },
    { id: 't-102', title: '为列表项补充稳定键', done: true }
  ]
  @State onlyOpen: boolean = false

  private visibleItems(): TodoItem[] {
    return this.items.filter((item: TodoItem) =>
      !this.onlyOpen || !item.done
    )
  }

  private setDone(id: string, done: boolean): void {
    this.items = this.items.map((item: TodoItem) =>
      item.id === id ? { ...item, done: done } : item
    )
  }

  build() {
    Column() {
      Text(this.onlyOpen ? '只看未完成(点此切换)' : '显示全部(点此切换)')
        .onClick(() => { this.onlyOpen = !this.onlyOpen })

      List() {
        ForEach(
          this.visibleItems(),
          (item: TodoItem) => {
            ListItem() {
              Row() {
                Checkbox({ name: 'todo-' + item.id })
                  .select(item.done)
                  .onChange((checked: boolean) => this.setDone(item.id, checked))
                Text(item.title).layoutWeight(1)
              }
              .width('100%')
            }
          },
          (item: TodoItem) => item.id
        )
      }
    }
    .width('100%')
    .padding(16)
  }
}

复选框回调只提交“新状态”,setDone 再按 ID 生成新数组。更新一个项目时,其余项目仍保留原值。筛选只是从源数据派生可见列表,不会把隐藏项从 items 删除,所以切回“显示全部”时数据仍在。示例用 ForEach 说明思路;组件属性和具体 ArkTS 语法应以本地 SDK 文档及编译结果为准。

为什么要用稳定键

列表渲染不只是把一组文本画出来。行组件可能还有焦点、动画、展开状态或输入内容。如果用数组下标作为键,插入或排序后,下标会被复用,节点内部状态就可能落到另一条业务记录上。使用 item.id,身份才跟着数据而不是当前位置。

ID 必须唯一且稳定;不要在构建函数里临时生成,也不要在排序后重算。服务端数据可使用主键;本地草稿则在创建时生成一次并持久化。重复键会让稳定性失效,测试时应覆盖空列表、删除后重排以及相同标题的不同任务。

组件边界与刷新范围

如果把每一行抽成子组件,先明确状态所有权:父组件拥有完整任务列表时,子组件可通过 @Prop 接收展示数据,并通过回调请求父组件修改;确实需要父子双向同步某个简单值时,再考虑 @Link。不要为了少写几个参数,就把整份列表复制到子组件的 @State,否则容易出现两份“看起来都正确”的状态。

给所有字段都加状态装饰器并不会自动带来性能提升。让会变化的状态尽量靠近真正使用它的组件;静态标题、图标说明保持普通数据。更新数组时只改确实变化的记录,避免每次点击顺带重建无关页面数据。

什么时候需要更进一步

几十条记录通常用清楚、可维护的 ForEach 就够了。数据量很大且实测遇到首屏或滚动瓶颈时,再考虑虚拟列表方案,并按所用 SDK 的要求实现数据源与变更通知。虚拟化不只是把 ForEach 换成另一个名字:插入、删除、排序和局部更新都要同步通知数据源,键仍然需要稳定。

我会按这个顺序排查性能:先在真机或模拟器复现并记录列表数量和操作步骤;再确认状态更新是否只发生一次、键是否唯一;最后用性能分析工具观察构建与滚动开销。不要仅凭“用了虚拟列表”就判断问题解决,尤其要检查快速切换筛选、连续勾选和排序后,行内容有没有错位。

验收清单

  1. 连续切换同一项,复选框与数据状态一致。
    1. 打开“只看未完成”后勾选一项,它从筛选结果消失;切回全部后仍能找到且状态正确。
      1. 排序、插入或删除后,标题、复选框和行内状态仍属于同一 ID。
        1. 两条标题相同但 ID 不同的记录可以分别更新。
          1. 数据源为空、只有一项或数量较多时,页面都能正常展示;长列表再依据实际测量决定是否虚拟化。

          2. 对这类页面来说,可靠刷新不是某个装饰器的“魔法”,而是状态归属、不可变更新和稳定身份协同的结果。先把这三点做对,再谈优化策略,排查会简单很多。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。