一个目录页如果只展示十几条项目，用普通的 List 记录当前行号就够了。麻烦出在内容开始分组之后：左栏显示系列目录，右栏显示详情，搜索结果点中“CAT-027”，左栏却滚到了另一个分组，右栏还可能保留上一次打开的详情。表面看是滚动位置不准确，实质是把两种索引当成一种使用。我把这个问题放进一个名为 CatalogSplit 的示例：共 4 个分组、72 条目录数据，搜索结果定位到 CAT-027，它位于第 3 个分组（索引 2） 的第 7 条（组内索引 6）。本文的 CAT-071 是人为构造的演示批次，不是产品线上数据；界面和日志也只展示预期状态，不代表已经完成 DevEco 编译或多设备联调。## 一、先确认错位源头，不急着调动画ArkUI 的 List 把一个 ListItemGroup 作为列表层级的一个子元素计数，而组内 ListItem 拥有自己的位置。检索结果如果只携带一个摊平后的“第 27 条”，再直接传给滚动控制器，就等于把全局业务序号当成了容器子元素索引。分组数目变化、某一组折叠、筛选条件切换以后，这个数字往往不再指向用户想看的项目。平行视界会放大这一点。手机紧凑状态可能先进入目录页，宽屏状态下详情与目录同时出现，用户看到的是“选中一条”的连续交互，而页面实现内部可能在两个区域分别执行数据更新。仅仅让左栏跳过去还不够，右栏必须确认跳转的是同一个业务 ID。否则列表定位成功与详情展示正确只是两个巧合，二者缺少合同。本篇只讨论“已经有分组目录数据之后，怎样准确定位到组内目标项”。不讨论自动配置平行视界，也不假设 scrollToItemInGroup 能替开发者恢复详情导航栈。分栏由应用布局层提供，索引解析由目录层负责，业务选择由详情层确认，三者职责要刻意分开。演示中左栏有“基础展品、材质标本、城市空间、数字模型”四组，筛选后的排序版本记作 epoch=12。搜索命中 CAT-027 时，先在当前快照中重新计算双层坐标，得到 groupIndex=2 / itemIndex=6，再发出滚动请求。这两个数字只是当前列表快照的坐标，不应写进长期书签。## 二、从业务 ID 反解双层坐标我先用一段不依赖 UI 的 ArkTS 把位置解析封装起来。这样搜索模块只提交 ID，不需要知道列表采用 ForEach 还是 LazyForEach，更不需要拼猜所谓“全局索引”。这段代码也是后续判断筛选结果是否过期的基础。tsinterface CatalogItem { id: string; title: string }interface CatalogGroup { id: string; title: string; items: CatalogItem[] }interface GroupPosition { groupIndex: number; itemIndex: number; id: string }function locateItem(groups: CatalogGroup[], itemId: string): GroupPosition | null { for (let g: number = 0; g < groups.length; g++) { const index: number = groups[g].items.findIndex((item: CatalogItem) => item.id === itemId); if (index >= 0) { return { groupIndex: g, itemIndex: index, id: itemId }; } } return null;}这里不缓存 CAT-027 所处的两个索引，因为分组数据随时可能改变。返回 null 也不是异常崩溃，可能只是当前筛选隐藏了这条记录，界面应明确显示“当前条件下未找到”。实际项目还要区分“数据尚未载入”和“数据已载入但不存在”，防止把前者误判成删除。这段遍历在 72 条演示数据内没有性能压力；目录较大时可以把 id → {groupId, itemId} 建成索引，但更新必须与列表的分组快照同步。如果只刷新视图、不刷新映射表，性能优化反而会制造更难复现的误选。业务 ID 是稳定身份，组内数字只是一次布局和筛选下的可操作坐标。## 三、滚动控制器只接受经过复核的位置官方 List 文档明确提供 ListScroller，其 scrollToItemInGroup(index, indexInGroup, smooth?, align?) 用于滚动到指定分组内项目。调用前必须保证控制器已经绑定到对应 List；空列表、无效索引、控制器尚未绑定时不能以“没有异常就算成功”来判断。演示页面将 ListScroller 与单一左栏 List 一对一绑定。以下省略详情栏的 UI 样式，保留关键列表层级和搜索定位动作，便于看清 ListItemGroup 与内部 ListItem 的关系。ts@Entry@Componentstruct CatalogPage { private catalogScroller: ListScroller = new ListScroller(); @State groups: CatalogGroup[] = []; @State selectedId: string = 'CAT-027'; @State jumpStatus: string = 'WAITING_DATA'; private jumpTo(id: string): void { const pos: GroupPosition | null = locateItem(this.groups, id); if (pos === null) { this.jumpStatus = 'NOT_IN_FILTER'; return; } this.catalogScroller.scrollToItemInGroup( pos.groupIndex, pos.itemIndex, false, ScrollAlign.CENTER); this.selectedId = pos.id; this.jumpStatus = 'GROUP_ITEM_READY'; } build() { Column() { Button('定位 CAT-027').onClick(() => this.jumpTo('CAT-027')) List({ scroller: this.catalogScroller }) { ForEach(this.groups, (group: CatalogGroup) => { ListItemGroup() { ForEach(group.items, (item: CatalogItem) => { ListItem() { Text(item.id + ' · ' + item.title) } }, (item: CatalogItem) => item.id) } }, (group: CatalogGroup) => group.id) }.height('78%') Text(this.jumpStatus) } }}这里用 false 表示不做滚动动效，原因不是动画不好看，而是目标可能离当前区域很远；带动画的跨越式定位会使沿途列表项参与加载和布局，长目录下并不划算。ScrollAlign.CENTER 可以让目标靠近可见区域中央，但它只是对齐策略，不保证不同宽度、分组标题高度变化时像素位置相同。为了简化正文，示例没有把“绑定完成”实现为完整的异步组件握手，因此真正项目必须等分组数据提交且 List 完成挂载后再触发 jumpTo。不要在构造器里调用 scrollToItemInGroup，也不要把它当成同步返回目标行布局完成的凭证。右栏详情请求必须以 selectedId 再核对一次，不能从滚动结果推断数据已经加载。## 四、过滤变化时，旧跳转要能自己作废另一个容易忽略的情况是用户连续改筛选条件。例如先点击“全部”，紧接着切到“城市空间”，旧搜索结果稍后才返回。即使旧结果里的 CAT-027 曾经存在，也不意味着它在新过滤快照中仍然可见。这里适合给每次列表快照一个递增代次，而不是试图让所有网络请求按顺序完成。下面的门禁只决定能不能提交定位，不伪装成系统自动提供的折叠事件。epoch 来自应用层筛选更新；目标 ID 是搜索结果里携带的业务键。只有两者都与当前快照一致时，才重新计算双层索引。```tsinterface JumpIntent { epoch: number; itemId: string }class GroupJumpGate { private activeEpoch: number = 12; private dropped: number = 0; setEpoch(next: number): void { this.activeEpoch = next; } resolve(intent: JumpIntent, groups: CatalogGroup[]): GroupPosition | null { if (intent.epoch !== this.activeEpoch) { this.dropped++; return null; } return locateItem(groups, intent.itemId); } staleCount(): number { return this.dropped; }}// 演示：旧代次 11 的请求被拒绝；当前代次 12 才能定位。const gate = new GroupJumpGate();gate.resolve({ epoch: 11, itemId: ‘CAT-027’ }, []); // null````dropped=1是在这组演示输入上可以推导的应用层计数，并非抓取真实设备 HiLog 得来的统计。更重要的是旧任务被拒绝后，不能再顺手更新右栏选中 ID，否则视觉层虽然没有滚动，业务仍然发生了错误选择。最终状态GROUP_ITEM_READY表示当前数据快照已经找到可定位的索引，不表示目标详情网络请求已成功，也不代表系统平行视界能力已经完成配置。## 五、实际调试时只检查三条证据我会先固定分组快照，打印筛选版本、业务 ID 和双层坐标，再检查控制器是否已绑定。对于CAT-071，示例日志应出现 epoch=12、CAT-027、group=2、item=6，以及一个旧请求 STALE_INTENT。重点不是打印大量滚动事件，而是让这些关键信息在同一个诊断点上出现。高频滚动回调不适合每帧打 HiLog，这一点也与 DevEco 的性能规则一致。第二条证据是左栏与右栏的身份一致性。定位动作只改变视口，真正选择动作才更新业务 ID；如果页面设计把它们合并，仍应在提交前检查 selectedId===target.id。第三条是失败后的用户可理解性：搜索筛选后不存在项目，应保留当前详情并提示“当前目录未找到”，而不是偷偷滚到最后一行。![](https://i-blog.csdnimg.cn/direct/e238d170344e456b9c8aedf730d500c1.png)图中的 4组 / 72条、CAT-027、2 / 6、epoch 12和STALE_INTENT 1 均为统一演示字段。竖屏图片是紧凑布局下的效果示意；在真正的平行视界双栏设备上，左栏的索引合同相同，但剩余宽度、分组标题高度和详情布局需要单独测试。## 六、这次方案的边界这套写法解决的是“搜索目标如何准确落到组内项目，以及过期跳转如何被阻止”。它不负责系统决定是否显示双栏、不负责数据接口成功率、不解决跨应用跳转，也不把滚动 API 的返回时刻理解成动画结束。ListItemGroup 的索引规则、ListScroller一对一绑定和scrollToItemInGroup` 参数请以目标 SDK 的官方文档为准。如果目录还带吸顶标题、虚拟加载、组折叠或权限隐藏，项目里要先冻结一次可见数据快照，再从这个快照计算双层索引。数据层和 UI 层使用不同快照，是这类“偶尔点错一条”问题最常见也最费时间的根源。与其给错误索引补几次重试，不如让业务 ID、分组快照、跳转代次在一次事务里被验证。技术资料： 华为 ArkUI List / ListScroller 官方 API；HarmonyOS 多设备适配。本篇未执行真机与 IDE 编译，所有数值及界面均为可复核的示例合同。