HarmonyOS ArkUI 搜索页返回恢复：筛选快照、路由结果与过期数据隔离

HarmonyOS ArkUI 搜索页返回恢复：筛选快照、路由结果与过期数据隔离

搜索列表打开详情再返回，最常见的体验断层不是“页面没了”，而是筛选条件、当前页、滚动位置和列表内容各自恢复到了不同时间点：筛选栏仍显示“最近一周”，结果却变成默认列表；滚动条回到顶部；或一个较早发出的请求晚到，把用户刚恢复的内容覆盖掉。

解决这类问题，不应把整页 UI 状态粗暴塞进路由参数，也不应在返回时无条件重新请求。更稳妥的做法是区分可重建的查询条件、短期界面快照、详情页返回结果和异步请求新旧关系，再用明确的恢复判定决定“原样恢复、局部合并还是重新查询”。本文给出应用侧纯逻辑模型，不声称它已经过 ArkUI 编译、系统联调或真机验收。

文章引用的 HarmonyOS Navigation 文档说明了 NavPathStack 的页面跳转、返回、替换、删除和参数传递能力；具体应用应根据目标 API 版本核对所用接口。Navigation 跳转文档 对返回结果的组织方式，官方 FAQ 也列出了 NavDestination 返回时结果回调的相关用法。ArkUI 导航 FAQ

1. 先把“页面状态”拆成三种责任

搜索条件是可解释的查询意图，例如关键词、筛选器和排序方式；它应该能被规范化、比较和重新执行。列表快照是短期体验状态，典型字段是当前页、首个可见项标识和滚动偏移。结果集属于数据层，可能已被详情页修改，也可能因后台更新而过期。

这三类信息寿命不同。把它们全放进一个 SearchPageState 对象，再在返回时整体覆盖，会让缓存字段与权威数据混在一起；只保留筛选条件又会丢失用户的阅读位置。先拆分所有权，恢复策略才有地方落地。

interface SearchCriteria {
keyword: string;
categoryIds: string[];
status: 'all' | 'open' | 'closed';
sort: 'relevance' | 'updated_desc';
fromDay: string;
toDay: string;
}

interface SearchSnapshot {
criteriaKey: string;
dataVersion: string;
page: number;
anchorId: string | null;
offsetPx: number;
savedAt: number;
}

字段名刻意不绑定某个 ArkUI 组件：它们是页面控制器或 ViewModel 可以持有的纯数据契约。滚动像素值只有在同一排序和数据版本下才有意义；业务查询条件则应独立于视图重建。

2. 用稳定的条件指纹识别同一次查询

恢复之前先判断当前搜索条件是否仍等于保存时的条件。字符串要去除首尾空白，集合型筛选器要排序去重；否则 ['a','b'] 与 ['b','a'] 会被误判成两组条件，或重复的筛选 ID 产生虚假的新查询。

指纹不是安全哈希，也不应用来授权。这里的目标只是客户端内的稳定比较，因此可以对字段顺序固定的规范化对象做序列化；若字段新增，必须同步更新规范化契约和测试。

export function criteriaKey(criteria: SearchCriteria): string {
const keyword = criteria.keyword.trim();
const categoryIds = […new Set(criteria.categoryIds.map((id) => id.trim()))]
.filter(Boolean)
.sort();
if (criteria.fromDay > criteria.toDay) {
throw new Error('date range is reversed');
}
return JSON.stringify({
keyword,
categoryIds,
status: criteria.status,
sort: criteria.sort,
fromDay: criteria.fromDay,
toDay: criteria.toDay,
});
}

日期范围比较应基于约定格式；示例要求 YYYY-MM-DD 这种可字典序比较的格式。若产品接受本地化日期或时区时间戳，应先统一转换，不要把展示字符串直接拿来比较。

3. 快照只在条件、数据版本和时间都匹配时恢复

返回时不能只看“有没有快照”。三个检查缺一不可：条件指纹相同；生成列表时的数据版本仍可接受；快照未超过产品设定的短期有效窗口。任一条件不满足就退回重新查询，而不是尝试恢复一个语义已经变化的滚动位置。

有效期不是越长越好。详情可能改变排序字段，用户也可能在另一个入口切换筛选。应由产品对“返回后仍保留多久”作出决定；本例的纯函数只接收 TTL，不替产品虚构具体业务时长。

export type RestoreDecision = 'restore' | 'refresh';

export function decideRestore(
snapshot: SearchSnapshot | null,
currentCriteriaKey: string,
currentDataVersion: string,
now: number,
ttlMs: number,
): RestoreDecision {
if (!snapshot) return 'refresh';
if (snapshot.criteriaKey !== currentCriteriaKey) return 'refresh';
if (snapshot.dataVersion !== currentDataVersion) return 'refresh';
if (!Number.isFinite(now) || !Number.isFinite(snapshot.savedAt)) return 'refresh';
if (now < snapshot.savedAt || now – snapshot.savedAt > ttlMs) return 'refresh';
if (!Number.isSafeInteger(snapshot.page) || snapshot.page < 1) return 'refresh';
if (!Number.isFinite(snapshot.offsetPx) || snapshot.offsetPx < 0) return 'refresh';
return 'restore';
}

“数据版本”可以是本地仓库单调递增的 revision，也可以是数据源提供的版本标识；它不是服务器时间戳的替代品。若无法可靠判断列表是否变化，宁可使用较保守的刷新策略，并清晰保留查询条件。

4. 返回详情时传变化，不传整份页面

导航参数适合表达详情页要打开哪个实体；返回结果适合表达详情页实际发生的变化。不要把整个搜索列表塞进返回 payload，因为那会让两个页面同时持有列表权威副本，之后很难判断哪一份更新。

返回结果应是窄契约：实体 ID、变更类型和必要字段。取消、仅查看或无修改则不需要返回“假更新”。官方导航能力的具体回调签名要以项目 API 版本对应文档为准；以下是架构草图，不是可直接复制的 SDK 调用代码。

type DetailReturn =
| { kind: 'changed'; id: string; updatedAt: number }
| { kind: 'deleted'; id: string }
| { kind: 'unchanged' };

function applyDetailReturn<T extends { id: string }>(
rows: T[],
result: DetailReturn | null,
updatedRecord?: T,
): T[] {
if (!result || result.kind === 'unchanged') return rows;
if (result.kind === 'deleted') {
return rows.filter((row) => row.id !== result.id);
}
if (!updatedRecord || updatedRecord.id !== result.id) return rows;
const index = rows.findIndex((row) => row.id === result.id);
if (index < 0) return rows;
return rows.map((row, i) => i === index ? updatedRecord : row);
}

这个局部合并只适合“不改变当前列表成员关系与排序”的详情修改。若详情字段会影响筛选命中或排序，返回后应触发查询重算；不能为了保住滚动位置，把已经不符合条件的记录留在结果里。

5. 锚点优先于像素，缺项时有确定回退

单独恢复 offsetPx 很脆弱：一张图片加载高度变化、一个已删除条目消失，都会让相同像素对应到另一条内容。优先保存首个可见实体 ID，再保存它相对视口的偏移；如果该实体已不在结果中，则回退到产品定义的附近项或顶部，而不是滚到随机位置。

这里的 anchorId 是逻辑定位信息，实际滚动控制器适配、列表布局时机和可见项测量属于 UI 层工作，需要项目自身完成并验证。纯逻辑层可以先确定回退索引：锚点还在就返回它的位置，否则使用调用方提供的安全回退项。

export function resolveAnchorIndex(
ids: string[],
anchorId: string | null,
fallbackId: string | null,
): number {
if (anchorId) {
const anchor = ids.indexOf(anchorId);
if (anchor >= 0) return anchor;
}
if (fallbackId) {
const fallback = ids.indexOf(fallbackId);
if (fallback >= 0) return fallback;
}
return ids.length === 0 ? –1 : 0;
}

如果滚动位置依赖分页窗口，快照要同时保留页码或游标，并在重新取数后确认锚点确实出现。否则“先跳回锚点、再发现数据没加载”会产生二次跳动。

6. 防止过期异步响应覆盖恢复结果

返回页面时可能同时触发恢复和刷新；用户还可能在请求途中再次改筛选。只靠 loading 布尔值无法区分两个请求的先后。每次请求开始时发放递增代号，并关联查询指纹；响应到达时只有代号仍是最新且条件仍一致，才能提交到当前列表。

export class RequestFence {
private generation = 0;
private activeCriteriaKey = '';

begin(criteria: SearchCriteria): { generation: number; key: string } {
this.activeCriteriaKey = criteriaKey(criteria);
this.generation += 1;
return { generation: this.generation, key: this.activeCriteriaKey };
}

accepts(token: { generation: number; key: string }): boolean {
return token.generation === this.generation
&& token.key === this.activeCriteriaKey;
}
}

这道栅栏只解决“哪个客户端结果可提交”，不等于取消底层网络任务，也不证明数据源具有一致性。若仓库支持取消，应单独传播取消信号；无论底层能否取消，提交前的新旧核验仍然要保留。

7. 保存时机要早于离开，恢复时机要晚于数据确认

进入详情前，先从当前页面真实状态生成快照，再发起导航。返回后先接收结果，再判断本地数据版本；若版本不变且快照有效，可以复用现有结果并恢复锚点。若有变更，则让仓库按当前条件重新计算，再在新结果里定位锚点。

顺序可以表达为：

不要把这些步骤压成“onAppear 就恢复”。页面出现可能来自首次进入、返回、重建或切换；入口不同，快照状态也不同。应由导航/页面协调层明确携带原因，避免生命周期回调猜测用户意图。

8. 让快照可失效、可清理，而不是永久缓存

快照可能带有搜索词、用户筛选以及结果标识，应按最短可用周期保留，并在用户切换账户、退出登录、清空搜索或进入不兼容的数据范围时主动失效。不要将其写成跨会话永久缓存，除非产品明确需要并完成隐私、存储和生命周期设计。

清理策略至少要回答：快照存在哪里；多久过期；页面被系统回收后是否仍有效；数据版本从哪里来；退出账户是否清空；筛选条件是否含个人信息。若快照只服务一次页面往返，内存中的页面会话状态通常比持久化更容易控制；选择仍需结合项目路由和页面生命周期设计。

export function invalidateSnapshot(
snapshot: SearchSnapshot | null,
reason: 'criteria_changed' | 'account_changed' | 'explicit_clear' | 'expired',
): SearchSnapshot | null {
if (!snapshot) return null;
// 纯逻辑层只表达失效结果；实际存储清理由所有者负责。
return reason === 'criteria_changed'
|| reason === 'account_changed'
|| reason === 'explicit_clear'
|| reason === 'expired'
? null
: snapshot;
}

生产实现可把原因写入诊断事件，但应避免记录原始搜索词或敏感筛选值。记录 criteriaKey 是否安全，取决于其中字段和可逆性，不要因为叫“指纹”就默认匿名。

9. 纯逻辑测试要覆盖竞争条件和边界

页面返回测试不该只验证“有快照时恢复”。关键路径包含：筛选变化导致指纹不同、数据版本推进、时间倒退或超时、锚点被删除、详情返回删除记录、结果影响排序、旧请求晚到，以及快速连续改变条件。

纯逻辑测试可以验证决策函数和请求栅栏，但不能替代 ArkUI 页面生命周期、路由回调、滚动容器布局和设备行为测试。后续联调应单独记录设备、API 版本、复现步骤和证据；本文不把模拟断言冒充系统验证。

本地用例应对每个分支至少覆盖正常值、边界值和无效输入。接口适配层再通过应用实际测试验证路由时序；在这一步完成前，应将验收状态标为“待设备/系统验证”。

10. 排查时按症状定位，不要一律强制刷新

不要用无限延长 TTL 掩盖数据新鲜度问题，也不要每次返回都清空页面状态。对用户可见的选择予以尊重，同时以新条件和当前数据版本决定哪些快照仍可安全复用。

11. 落地前的检查清单与验证边界

• 查询条件规范化规则固定，关键字段变化会生成不同指纹。
• 快照包含条件键、数据版本、页码、锚点和保存时间。
• 过期、时间倒退、条件变化、账户变化都能确定失效。
• 详情返回只携带窄化结果，不复制整份搜索页状态。
• 影响命中或排序的字段变化会触发重算。
• 锚点缺失有稳定回退，不依赖裸像素偏移。
• 异步请求响应提交前校验 generation 与查询键。
• 纯逻辑测试、导航适配测试和设备 UI 验证分开记录。

本地验证应说明运行了哪些纯逻辑断言、Markdown 质量检查、图片尺寸/唯一性检查和 HTML 渲染。ArkUI 生命周期、NavPathStack 具体版本接口、真实滚动恢复和多设备体验属于后续项目验证项；没有实际执行就不能标为通过。

12. 结语：恢复的是用户意图，不是过期页面副本

可靠的返回体验，不等于把离开前的画面一帧不差地复刻。应用需要恢复仍有效的搜索意图和阅读锚点，同时接受详情带来的真实变化，并拒绝不再属于当前查询的迟到响应。

把快照、窄路由结果、数据版本和请求栅栏拆开后，策略才可测试、可解释，也更容易定位“返回丢条件”“列表跳位”和“旧数据覆盖”分别来自哪一层。界面时序仍要在目标 HarmonyOS 版本与实际设备上验证；本文提供的是可独立测试的应用侧设计，不是已完成的系统验收报告。