HarmonyOS 7.0 / API 26 LazyForEach key 稳定性实战：分页追加后旧状态为什么会串到新行
先把问题摆出来
LazyForEach 的 key 如果不稳定，问题通常不是立刻报错，而是旧状态串到新行。分页追加、筛选重排、收藏勾选这些场景里，用户会看到明明点的是 A，状态却跑到 B。
这篇只盯一个能力点：LazyForEach key 稳定性。我不把它写成概念说明，而是按排查路径写：问题怎么出现，怎么复现，代码怎么落地，边界怎么验，最后怎么封装成以后能复用的写法。
版本边界和适用场景
| 项目 | 本文口径 |
|---|---|
| 系统范围 | HarmonyOS 7.0 / API 26 及以上能力适配 |
| 适合页面 | 分页列表页、搜索结果页、收藏列表页、图片流页面 |
| 常见风险 | 旧组件被复用到新数据、勾选状态串行、筛选后错位、局部刷新失效 |
| 验收目标 | key 来自业务唯一值、分页追加不复用旧状态、筛选重排后状态隔离、日志能定位 item |
这里要先定边界。很多页面问题不是 ArkUI 写错了，而是版本能力、设备形态、生命周期、异步任务混在一起后，状态没有被分层。只要边界不清楚，代码就会越补越乱。
常见错误：把能力适配写成一个布尔开关
刚开始最容易写成下面这样。能跑，但后面会很难维护。
interface FeatureSwitch { enabled: boolean; deviceType: string; scene: string; } class BadFeatureAdapter { buildState(input: FeatureSwitch): string { if (!input.enabled) { return 'fallback'; } if (input.deviceType === 'phone') { return 'phone-mode'; } if (input.deviceType === 'tablet') { return 'tablet-mode'; } return 'default-mode'; } }问题在于它只关心“开没开”，没有记录为什么进入这个分支。等页面出现抖动、丢状态、审核截图异常或者多设备表现不一致时，只能靠猜。
改法：把输入、策略和结果拆开
我更倾向于把适配拆成三层：输入层只收集事实，策略层做判断，结果层给 UI 或任务调度使用。这样改完以后，日志能看懂，单测也能写。
type DeviceShape = 'phone' | 'foldable' | 'tablet' | 'pc'; type FeatureScene = 'preview' | 'editing' | 'handoff' | 'review'; interface FeatureContext { apiVersion: number; deviceShape: DeviceShape; scene: FeatureScene; widthVp: number; heightVp: number; lowPowerMode: boolean; } interface FeatureDecision { mode: 'full' | 'compact' | 'safe' | 'off'; reason: string; shouldRecordMetric: boolean; } export class FeaturePolicy { decide(ctx: FeatureContext): FeatureDecision { if (ctx.apiVersion < 26) { return { mode: 'off', reason: 'api-version-not-ready', shouldRecordMetric: true }; } if (ctx.lowPowerMode) { return { mode: 'safe', reason: 'low-power-protect-frame', shouldRecordMetric: true }; } if (ctx.deviceShape === 'foldable' && ctx.widthVp >= 720) { return { mode: 'full', reason: 'foldable-wide-layout', shouldRecordMetric: true }; } if (ctx.scene === 'review') { return { mode: 'safe', reason: 'review-screenshot-stable-first', shouldRecordMetric: true }; } return { mode: 'compact', reason: 'default-compact', shouldRecordMetric: false }; } }这个写法的重点不是类名，而是结果里带 reason。以后日志里看到 `review-screenshot-stable-first`，就知道页面为什么选择安全模式，不需要再翻一堆 if。
案例一：页面首屏不能因为新能力变慢
第一类问题是用 index 当 key。分页追加或筛选后 index 变了，组件复用关系也跟着乱。
class StartupProbe { private marks: Record<string, number> = {}; mark(name: string): void { this.marks[name] = Date.now(); } cost(from: string, to: string): number { return (this.marks[to] ?? 0) - (this.marks[from] ?? 0); } } const probe = new StartupProbe(); const policy = new FeaturePolicy(); probe.mark('page-enter'); const decision = policy.decide({ apiVersion: 26, deviceShape: 'foldable', scene: 'preview', widthVp: 840, heightVp: 720, lowPowerMode: false }); probe.mark('policy-ready'); console.info('feature-mode', decision.mode); console.info('feature-reason', decision.reason); console.info('policy-cost', probe.cost('page-enter', 'policy-ready'));验收时我会看三个值：mode 是否符合预期，reason 是否能解释分支，policy-cost 是否足够小。策略判断应该是轻量逻辑，不能把耗时任务塞进去。
案例二：多设备切换时不能丢上下文
第二类问题是 key 稳定但状态放错地方。item 内部状态没有和数据 id 对齐，也会出现串行。
interface ViewSnapshot { route: string; selectedId: string; scrollOffset: number; featureMode: FeatureDecision['mode']; updatedAt: number; } class SnapshotStore { private current: ViewSnapshot | undefined; save(snapshot: ViewSnapshot): void { this.current = { ...snapshot, updatedAt: Date.now() }; } restore(): ViewSnapshot | undefined { if (!this.current) { return undefined; } return { ...this.current }; } } const store = new SnapshotStore(); store.save({ route: 'detail-preview', selectedId: 'card-10086', scrollOffset: 460, featureMode: decision.mode, updatedAt: Date.now() }); const restored = store.restore(); console.info('restore-route', restored?.route); console.info('restore-feature-mode', restored?.featureMode);这里要防的不是“能不能保存一个对象”，而是设备形态变化后，页面上下文有没有跟着回来。比如折叠屏从半屏切到展开，或者平板分屏宽度变化，用户看到的内容不应该突然回到默认态。
两种实现方式对比
| 方案 | 好处 | 坑点 | 我会放在哪里 |
|---|---|---|---|
| 页面里直接 if/else | 写起来最快 | 分支越来越多，日志看不懂 | 只适合临时验证 |
| 独立 Policy 类 | 能单测，能记录 reason | 要先设计输入输出 | 推荐用于正式代码 |
| Store 里直接保存全部状态 | 恢复简单 | 容易保存脏数据 | 只保存必要字段 |
| Snapshot 分层保存 | 边界清楚 | 需要设计字段 | 适合多设备和复杂页面 |
我的选择是 Policy + Snapshot。Policy 负责判断能力怎么开，Snapshot 负责保存页面上下文。二者不要混在一起。
封装成可以复用的入口
export class HarmonyFeatureRuntime { private readonly policy = new FeaturePolicy(); private readonly snapshots = new SnapshotStore(); prepare(ctx: FeatureContext): FeatureDecision { return this.policy.decide(ctx); } saveView(snapshot: ViewSnapshot): void { this.snapshots.save(snapshot); } restoreView(): ViewSnapshot | undefined { return this.snapshots.restore(); } }这样封装之后，页面只需要关心三件事：准备策略、保存现场、恢复现场。以后换成另一个 HarmonyOS 7.0 能力点，也可以沿用这套排查方式。
检查清单
- API 版本边界有没有写清楚，低版本是否有兜底。
- 新能力是否会影响首屏、滑动、弹窗、页面返回。
- 日志里能不能看出选择某个模式的原因。
- 多设备切换后，页面上下文能不能恢复。
- 代码是否能单独跑策略测试，而不是必须打开完整页面才知道结果。
最后总结
LazyForEach key 要用稳定业务值，不要用 index 顶上去。分页、筛选、重排都要验证状态隔离，尤其是勾选、收藏、展开这类容易被复用污染的状态。
