羽毛球学习 HarmonyOS 设计续篇（25）：搜索列表性能与回到顶部策略

一、从现有搜索页识别可量化的问题

当前搜索页已经具备关键字输入、资讯与装备两个标签、远端与本地数据合并、空结果提示和稳定 id。它能完成基础搜索，但每次统计、空状态判断和列表构建都会再次调用合并与过滤函数；两个列表也没有独立的滚动位置或统一复位规则。数据量小时不明显，数据增长后容易出现计算重复、结果切换跳动和返回页面位置不可预测。

这是一篇性能治理设计，不宣称优化已经运行。方案要解决三个具体问题：同一输入只计算一次快照；关键字、数据版本或标签变化时明确决定保留还是复位位置；“回到顶部”既能被用户触发，也能在结果语义变化时自动执行。

二、先建立查询快照，而不是在 build 中反复计算

快照应包含标准化关键字、当前数据版本、两个结果集合、耗时和生成序号。页面统计、空状态和列表都读取同一份快照，避免三处计算产生不同结果。关键字只在提交或防抖结束时进入快照，不把每个输入法组合字符都当作完整查询。

export interface SearchSnapshot { query: string dataVersion: number articleIds: string[] equipmentIds: string[] generation: number elapsedMs: number } export interface SearchInput { rawQuery: string selectedTab: 'article' | 'equipment' dataVersion: number } export function normalizeQuery(value: string): string { return value.trim().toLocaleLowerCase() }

空关键字也生成合法快照，只是结果为空。这样 UI 不需要用undefined区分“尚未搜索”和“搜索无结果”，而是通过 query 与结果集合表达。

三、合并数据要有版本，过滤结果要有缓存

远端数据或本地内置数据变化时递增dataVersion。合并层先用 id 去重并生成只读索引，搜索层的缓存键由query + dataVersion构成。同一版本下切换标签不用重新扫描两份数据；版本变化后旧快照自然失效。

export interface SearchIndex { version: number articles: ReadonlyArray<ArticleSearchRow> equipments: ReadonlyArray<EquipmentSearchRow> } export class SearchSnapshotCache { private values: Map<string, SearchSnapshot> = new Map() get(query: string, version: number): SearchSnapshot | undefined { return this.values.get(`${version}:${query}`) } put(snapshot: SearchSnapshot): void { this.values.set( `${snapshot.dataVersion}:${snapshot.query}`, snapshot ) } invalidateBefore(version: number): void { for (const [key, value] of this.values) { if (value.dataVersion < version) this.values.delete(key) } } }

四、生成序号防止慢查询覆盖新查询

当数据规模扩大或未来把搜索放到任务池时，旧查询可能比新查询晚返回。执行器给每次请求分配 generation，结果提交前检查它是否仍是最新值。过期结果直接丢弃，但不把它当错误提示给用户。

export class SearchExecutor { private generation: number = 0 async execute(input: SearchInput, index: SearchIndex): Promise<SearchSnapshot> { const current = ++this.generation const startedAt = Date.now() const query = normalizeQuery(input.rawQuery) const result = await this.filterIndex(query, index) if (current !== this.generation) { throw new Error('STALE_SEARCH_RESULT') } return { query, dataVersion: index.version, articleIds: result.articleIds, equipmentIds: result.equipmentIds, generation: current, elapsedMs: Date.now() - startedAt } } cancelPending(): void { this.generation += 1 } }

五、滚动策略由语义变化决定

回到顶部不应在每次 UI 刷新时执行。新关键字改变了结果语义，应复位当前标签到顶部；数据后台刷新但首个可见 id 仍存在时，应尽量保持锚点；用户切换标签时，保存当前标签位置并恢复另一个标签的位置；用户再次点击已选中的标签或点击悬浮按钮时，执行带动画的回顶。

export interface ScrollAnchor { firstVisibleId: string offset: number } export type ScrollDecision = | { kind: 'keep'; anchor?: ScrollAnchor } | { kind: 'top'; animated: boolean } export function decideScroll( reason: 'new_query' | 'data_refresh' | 'tab_restore' | 'user_request', anchorExists: boolean ): ScrollDecision { if (reason === 'new_query') return { kind: 'top', animated: false } if (reason === 'user_request') return { kind: 'top', animated: true } if (reason === 'data_refresh' && !anchorExists) { return { kind: 'top', animated: false } } return { kind: 'keep' } }

资讯和装备各持有一个 Scroller 与锚点，不能共享 offset。锚点优先用业务 id 恢复；id 已被删除时再退到顶部，避免使用旧索引指向错误条目。

六、回顶入口必须满足可发现性和防误触

当首个可见索引超过阈值，例如 8，显示回顶按钮；靠近顶部时隐藏。按钮点击后先停止仍在进行的惯性滚动，再执行一次动画。连续点击通过 300 ms 节流合并，防止重复动画。再次点击当前标签也可作为快捷回顶，但不能替代可见按钮，因为标签语义对新用户不明确。

七、失败与降级不应破坏上一次可用结果

索引刷新失败时保留上一个有效快照，并显示非阻断提示；搜索执行超时可退回同步的小数据过滤；数据格式异常的单条记录应跳过并计数，不能让整个列表消失。恢复锚点失败时退回顶部。任何降级都要记录原因，但不在快速输入时连续弹窗。

需要区分“没有结果”和“计算失败”：前者展示空结果文案，后者保留旧结果并提供重试。generation 过期属于正常取消，不展示失败。

八、实施顺序、性能预算和证据

第一阶段把合并数据提取为带版本索引，并让统计与两个列表共享快照；第二阶段加入 generation 和缓存；第三阶段接入双 Scroller、锚点恢复与显式回顶；第四阶段增加采样和自动化测试。

建议验收预算：1000 条资讯加 1000 件装备时，已建索引后的本地查询 P95 小于 50 ms；同一输入同一版本只计算一次；快速连续提交 20 次时只呈现最后一次结果；新查询必回顶；标签切换恢复各自位置；刷新删除锚点后安全回顶。后续需要用性能分析器、滚动录屏、计算次数日志和不同数据规模报告形成运行证据，再决定是否将文章升级为实战定位。

参考：HarmonyOS ArkUI 状态管理概述。

九、总结

搜索性能的关键不是把一段filter写得更短，而是让数据版本、查询快照和滚动语义形成稳定合同。只要统计、空状态和列表共享同一份结果，旧查询不会覆盖新查询，滚动位置又能按用户意图恢复，结果数量变化就不会再让页面行为失去解释。