ArkUI List × Scroller：平行视界筛选后阅读锚点稳定恢复【鸿蒙心迹】

把文档目录放进大屏的左栏右栏显示正文这种结构本身并不难。真正让人觉得别扭的往往是一个很小的动作读者正在看第十六份文档随手切换到“待处理”筛选再返回目录列表却跳到了第一条。右边文章还在左边却找不到刚才那份材料用户需要重新滑动。对阅读类应用来说这种丢失位置的感觉比布局从两栏变成一栏更明显。这篇用SplitLedger作为演示项目专门处理这个问题。它不模拟系统提供了某种自动保持滚动位置的神奇能力而是把业务层的稳定文档 ID和 ArkUIList的当前索引分开保存。示例含 36 份文档其中 18 份属于“待处理”。读者的锚点为DOC_016筛选前它的索引是 15筛选后是 7最后状态显示RESTORED。这些数字是为了解释算法而固定的示例不是实测性能数据。图 01平行视界目录筛选与阅读锚点恢复的技术封面左右列表只是同一逻辑的示意。## 一、索引不是身份过滤以后尤其不是最容易写的方案是记一个firstIndex离开页面时存起来回来执行scrollToIndex(firstIndex)。这种写法在数据不变时通常能工作换成筛选列表就不可靠了。最极端的情况是筛选前有 36 条筛选后只剩 18 条原先第 27 项甚至可能越界。即便没有越界原先索引 15 的位置也早已不是同一份文档。所以需要保存两个值滚动位置属于视图稳定 ID 属于数据。锚点应该存成DOC_016需要恢复时再到当前筛选结果里计算它的新索引。这样的映射逻辑与屏幕宽度、列数以及列表项样式都无关后续从手机单栏切到折叠屏双栏也不必重写规则。先做一个不依赖 ArkUI 的小模块。它解决的是筛选后从稳定 ID 重新定位而不是在业务层记录一个随时可能过期的数字。arktsinterface DocItem { id: string title: string pending: boolean}function makeDocs(): DocItem[] { const rows: DocItem[] [] for (let i 1; i 36; i) { const id DOC_${String(i).padStart(3, 0)} rows.push({ id, title: i 16 ? 接口联调问题记录 : 文档${i}, pending: i % 2 0 }) } return rows}class AnchorKeeper { private anchorId: string remember(id: string): void { if (id.length 0) { this.anchorId id } } resolve(items: DocItem[]): number { return items.findIndex((item: DocItem) item.id this.anchorId) } currentId(): string { return this.anchorId }}findIndex() 返回的是当前结果数组里的索引不是原始数组的旧索引。返回 -1 也不是异常如果 DOC_016 已经被当前筛选条件排除就没有理由强行把它滚到某个“差不多”的位置。生产环境可以设计降级方案例如定位到与锚点相邻的可见项目、清除筛选或提示“当前条件下不可见”但必须让选择规则显式、可解释。## 二、让 List 的滚动事件只负责观测位置华为 ArkUI 的 List 可以绑定 Scroller通过 onScrollIndex 获得列表可见索引也可以调用 scrollToIndex() 滚动到指定项。这里真正需要警惕的是把观察与恢复写进同一个循环筛选导致列表重排滚动事件更新锚点随后恢复函数反而找到了一个已经被替换的 ID。因此示例先把待恢复的 ID 冻结再替换数组。下面代码重点解决两个动作的分工onScrollIndex 观测当前可见项applyFilter 计算新索引恢复动作由数据更新后的显式按钮触发。为保持文章短而可读makeDocs() 只是业务数据准备函数在真实项目中由本地仓储或分页接口提供不是平台 API。arktsEntryComponentstruct SplitLedgerPage { State docs: DocItem[] makeDocs() // 演示数据36 项 State restoreIndex: number -1 State status: string ‘READY’ private scroller: Scroller new Scroller() private keeper: AnchorKeeper new AnchorKeeper() private savedId: string ‘’ private allDocs: DocItem[] makeDocs() private filtering: boolean false private applyFilter(): void { this.savedId this.keeper.currentId() || ‘DOC_016’ this.filtering true this.docs this.allDocs.filter((doc: DocItem) doc.pending) this.keeper.remember(this.savedId) this.restoreIndex this.keeper.resolve(this.docs) this.status ‘READY’ } private restore(): void { if (this.restoreIndex 0) { this.status ‘NOT_FOUND’ return } this.scroller.scrollToIndex(this.restoreIndex) this.status ‘RESTORED’ this.filtering false } build() { Column({ space: 12 }) { Button(‘筛选待处理’).onClick(() this.applyFilter()) List({ scroller: this.scroller }) { ForEach(this.docs, (item: DocItem) { ListItem() { Text(${item.id} ${item.title}) } }, (item: DocItem) item.id) } .onScrollIndex((first: number) { if (!this.filtering this.docs[first]) { this.keeper.remember(this.docs[first].id) } }) Button(‘恢复阅读位置’).onClick(() this.restore()) Text(this.status) } }}这个 Demo 特意把“筛选”和“恢复”做成两个操作避免在修改数据数组的同一个同步回调里立刻调用滚动指令。实际产品可以在列表完成布局更新后自动恢复但要根据所用 ArkUI 版本选择明确的布局完成时机而不是依赖一个没有保证的零毫秒延迟。示例也没有处理分组列表如果目录引入 ListItemGroup组本身会占据索引应重新设计映射关系。*图 02DevEco Studio 白色主题风格演示图。左侧 SplitLedger 工程树、中间稳定 ID 恢复代码、右侧模拟器和底部 HiLog 的数值均是人工设定的调试示意不是实际运行证据。*## 三、大屏的双栏和手机的单栏数据锚点应该共用平行视界界面很容易把左侧目录选中项与滚动首项混在一起。其实二者并不完全相同右侧正文可能停留在 DOC_016左侧用户又滑动浏览到其它条目。用户再次点击某个文档时需要更新**阅读选中项**用户手动滚动时需要更新**可见锚点**。如果强行用一个状态变量控制两者筛选和回退就会互相牵连。我更倾向于把选中项视为业务状态把阅读锚点视为界面状态。两栏、单栏可以共享 selectedId但每种形态的 scrollAnchorId 可以分别保存。本文为了聚焦问题用 DOC_016 同时展示阅读项和恢复锚点正式应用应该在数据模型中保留两者的区别。尤其要注意用户主动触发筛选之后与系统因窗口形态变化触发的重排不应该无条件使用同一恢复策略。代码还需要解释列表重排时的额外风险有些业务会排序、合并或插入消息。恢复的目标应该是**最稳定的记录标识**不能由 index、标题文案或 UI 节点生成。下面给出纯数据层的最小回归校验解决“筛选之后确实能把 ID 转换为预期索引”的问题。这段 JavaScript 只作逻辑示例无需依赖设备。typescriptconst rows Array.from({ length: 36 }, (_, i) ({ id:DOC_${String(i 1).padStart(3, 0)}, pending: (i 1) % 2 0}));const previousIndex rows.findIndex(row row.id ‘DOC_016’);const filtered rows.filter(row row.pending);const currentIndex filtered.findIndex(row row.id ‘DOC_016’);console.log({ previousIndex, currentIndex, filteredCount: filtered.length });// 预期{ previousIndex: 15, currentIndex: 7, filteredCount: 18 }这个检查的好处是不会掺杂 UI 渲染时序。如果这里先算错了索引后续再调Scroller也不可能得到稳定结果。另一方面纯数据检查通过不等于真机视觉位置完全一致。实际列表项高度不同、资源未加载完成、动态字号变化都可能让锚点落点产生可见偏移必须在目标设备上继续验证。## 四、把异常路径当作正式测试的一部分示例截图展示的最终状态统一是RESTORED筛选“待处理18”后定位DOC_016恢复索引是 7。不能因为截图是绿色成功状态就只覆盖成功路径。至少还需要人为构造三种反例锚点 ID 不在筛选结果中恢复期间第二次触发筛选用户在恢复前先手动滑动。第一种应该得到NOT_FOUND不能盲目复用旧索引第二种需要版本号或取消机制第三种应尊重最新的用户操作避免自动滚动抢走控制权。图 039:16 纯屏演示图以DOC_016、新索引 7 和RESTORED作为一致性检查点。演示并不表示已经完成真机适配测试。## 五、这套办法真正解决的边界这不是一篇完整的平行视界系统能力接入说明而是一个能在手机列表和双栏界面中复用的滚动恢复策略。它把“记住我在看什么”和“把列表滚到哪里”拆开不假设过滤前后的数组下标永远相等。Scroller负责视图定位业务主键负责身份判定二者相互配合但职责不能互换。接入真实项目时还应检查长列表虚拟化、列表项异步高度变化以及系统返回后页面对象是否被重建。对于极长目录可以在数据仓储层维护 ID 到索引的映射避免每次线性查找但只有性能测量证明它有价值时才需要额外缓存。代码中的示例数据和日志均为演示尚未在 DevEco Studio 完成编译与设备实测。资料参考华为开发者联盟《创建列表List》 https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-layout-development-create-list 。