ArkData + HarmonyOS 行囊协同【行囊系列 05】:多出行方案隔离与旧清单迁移【共创稿事节】

一份装备清单维护到第四次迭代,单行勾选、分类筛选、编辑冲突检查、批量装箱和撤销都已各有规则。新的问题反而来自产品本身:周末徒步要带登山杖,家庭露营要带帐篷;切换一次场景,用户却不得不把原有勾选全部改掉。直接把 gears 改成二维数组并不难,难的是保证“当前方案”与“其他方案”不会互相污染,以及老用户升级后不丢失上一版的清单。
这次把“行囊协同”从单清单推进到多出行方案。它仍然是单设备离线工具,不使用未验证的云端协作能力;存储延续此前 GearStore 的 Preferences 文件 packflow_prefs。升级的边界十分具体:旧键 gear_snapshot_v1 可以读,新数据只写 plan_bundle_v2;每个方案持有独立装备集合,切换后撤销栈立即失效,操作失败不以“保存成功”掩盖。示例面向 Stage 模型、ArkTS、API 11 及以上工程配置;实际编译还需要与本地 SDK 对齐。
一、把“当前清单”升级为有所有权的方案
先确定数据所有权。此前 GearItem 的四个字段不变:id、name、category、packed。id 只需在一个方案中唯一,不必让两个不同出行方案的装备竞争同一串主键。新的上层对象承担选择职责,activePlanId 只保存一个稳定字符串,页面绝不以列表下标作为活动方案标识。下标会因删除、排序发生变化,持久化后就容易选错清单。
// entry/src/main/ets/common/model/PackPlan.ets
import { GearItem, seedGears } from './GearItem';
export interface PackPlan {
planId: string;
title: string;
items: GearItem[];
}
export interface PlanBundle {
schema: number;
activePlanId: string;
plans: PackPlan[];
}
export function initialBundle(): PlanBundle {
return {
schema: 2,
activePlanId: 'weekend',
plans: [{ planId: 'weekend', title: '周末轻徒步',
items: seedGears() }]
};
}
export function copyGears(items: GearItem[]): GearItem[] {
return items.map((g: GearItem): GearItem => ({
id: g.id, name: g.name, category: g.category, packed: g.packed
}));
}
这里的 copyGears 不是为追求代码量而加的工具函数。它让新方案从旧方案复制装备时得到独立对象,随后任一方案的 packed 更新都不会污染另一个数组。默认仅有一份“周末轻徒步”,用户主动新增“家庭露营”后才出现第二个方案。当前方案的装备才交给原有分类视图渲染;筛选器负责决定看见哪些行,不负责决定把数据保存到哪里。

还要给“复制方案”设计一个可理解的产品语义。复制装备名称和分类,是为了减少用户再次输入;不复制已装箱状态,则是为了防止周末轻徒步的完成进度被误认为家庭露营也已装箱。这个决定应在界面操作文案中明确写出,例如“新方案继承装备,装箱进度重置”,不能只靠代码注释解释。反过来,如果是用户对同一趟行程建立备份,那么就应采用快照复制并保留勾选,这属于另一个动作,不能共用“新增方案”按钮。清单管理看似简单,实际已经出现了产品术语到数据迁移语义的一一映射。
方案 ID 也不能由用户可修改的标题直接产生。标题可以从“周末轻徒步”改成“清明踏青”,但历史记录、持久化键、页面选中态都必须保持同一个 planId。本例为了说明版本迁移选用预置的 weekend 与 family;工程化的新增入口应使用明确的唯一 ID 生成策略,并先检查重复。不要用数组长度加一生成 ID,删除方案以后长度会缩短,旧 ID 很容易再次出现。这样设计后,产品可以自由排序、重命名方案,而不用进行危险的关联字段批量修改。
二、双版本读取:迁移是一次严格的信任检查
旧版 GearStore 使用一个 JSON 文本快照,正常情况在 Preferences 中有 version: 1 和 items。新版读取首先尝试 plan_bundle_v2,如果存在就严格验证结构;只有新版键确实不存在时,才考虑旧键。新版损坏不能悄悄回退旧版:那会让用户以为自己最近创建的方案全部消失,又把早期数据覆盖回去。对损坏数据应保留现场并显示恢复错误。
// entry/src/main/ets/common/store/PlanStore.ets
import { preferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
import { GearItem } from '../model/GearItem';
import { PlanBundle, initialBundle } from '../model/PackPlan';
interface OldSnapshot { version: number; items: GearItem[]; }
export class PlanStore {
private db: preferences.Preferences;
constructor(context: common.UIAbilityContext) {
this.db = preferences.getPreferencesSync(context,
{ name: 'packflow_prefs' });
}
private validItems(items: GearItem[]): boolean {
if (!Array.isArray(items) || items.length > 500) { return false; }
const ids: Set<number> = new Set<number>();
for (const g of items) {
if (!g || !Number.isSafeInteger(g.id) || g.id <= 0 ||
typeof g.name !== 'string' || g.name.length < 1 || g.name.length > 30 ||
typeof g.category !== 'string' || g.category.length < 1 ||
typeof g.packed !== 'boolean' || ids.has(g.id)) { return false; }
ids.add(g.id);
}
return true;
}
private validBundle(v: PlanBundle): boolean {
if (!v || v.schema !== 2 || !Array.isArray(v.plans) ||
v.plans.length < 1 || v.plans.length > 20) { return false; }
const ids: Set<string> = new Set<string>();
for (const p of v.plans) {
if (!p || typeof p.planId !== 'string' || !p.planId ||
typeof p.title !== 'string' || !p.title || p.title.length > 30 ||
ids.has(p.planId) || !this.validItems(p.items)) { return false; }
ids.add(p.planId);
}
return ids.has(v.activePlanId);
}
read(): PlanBundle {
const latest = this.db.getSync('plan_bundle_v2', '') as string;
if (latest !== '') {
const v = JSON.parse(latest) as PlanBundle;
if (!this.validBundle(v)) { throw new Error('新版方案数据校验失败'); }
return v;
}
const old = this.db.getSync('gear_snapshot_v1', '') as string;
if (old === '') { return initialBundle(); }
const snapshot = JSON.parse(old) as OldSnapshot;
if (!snapshot || snapshot.version !== 1 ||
!this.validItems(snapshot.items)) { throw new Error('旧清单校验失败'); }
return { schema: 2, activePlanId: 'weekend', plans: [
{ planId: 'weekend', title: '周末轻徒步', items: snapshot.items }
] };
}
async write(bundle: PlanBundle): Promise<void> {
if (!this.validBundle(bundle)) { throw new Error('方案内容非法'); }
this.db.putSync('plan_bundle_v2', JSON.stringify(bundle));
await this.db.flush();
}
}
这段读取故意不在 read() 内自动写入新键。迁移完成应在明确的保存时机执行,保证意外崩溃后旧快照仍可用于人工恢复。上线前还需补充 JSON 文本大小上限、标题白名单及超长文本处理;Preferences 适合少量轻量数据,不是可无限增长的文档数据库。getPreferencesSync、getSync、putSync、flush() 的行为以 Preferences 官方参考 为准。
三、切换动作是原子替换,不是先清空再加载
页面层保留早期的 gears 变量给旧组件使用,但从本篇起把它定位为“当前方案的临时视图”。真正的持久化源是 bundle,每次修改装备必须调用 commitActiveItems();不能再把 this.gears = next 和单独 persist() 当作完整事务。切换时先固定当前方案,再把目标方案装备复制到视图,并清除上次批量撤销的栈。这样“上一套清单的撤销”永远不会落到下一套方案上。
// entry/src/main/ets/pages/Index.ets:接在此前 Index 组件内
@State private bundle: PlanBundle = initialBundle();
@State private gears: GearItem[] = seedGears();
@State private saveHint: string = '准备就绪';
@State private dataReady: boolean = false;
private planStore: PlanStore | null = null;
private planSaveChain: Promise<void> = Promise.resolve();
private planRevision: number = 0;
private commitActiveItems(next: GearItem[]): void {
const id: string = this.bundle.activePlanId;
const plans: PackPlan[] = this.bundle.plans.map((p: PackPlan): PackPlan =>
p.planId === id ? { ...p, items: copyGears(next) } : p);
this.bundle = { ...this.bundle, plans: plans };
this.gears = copyGears(next);
this.persistBundle();
}
private choosePlan(id: string): void {
const p: PackPlan | undefined = this.bundle.plans.find(
(x: PackPlan): boolean => x.planId === id);
if (!p || id === this.bundle.activePlanId) { return; }
this.clearUndo();
this.editingId = 0;
this.draftName = '';
this.selectedCategory = '全部';
this.showOpenOnly = false;
this.bundle = { ...this.bundle, activePlanId: id };
this.gears = copyGears(p.items);
this.persistBundle();
}
private createFamilyPlan(): void {
if (this.bundle.plans.length >= 20 ||
this.bundle.plans.some((p: PackPlan) => p.planId === 'family')) { return; }
const base: GearItem[] = this.gears.map((g: GearItem): GearItem =>
({ ...g, packed: false }));
const plan: PackPlan = { planId: 'family', title: '家庭露营', items: base };
this.bundle = { ...this.bundle, plans: [...this.bundle.plans, plan] };
this.choosePlan('family');
}
上述成员用于替换而非叠加此前的 @State gears、saveHint 和保存队列;项目中同名字段只能保留一份。对旧操作的改造是一条明确的替换规则:原先 toggleGear()、addGear()、saveRename()、batchSetPacked()、undoBatch() 里成功计算 next 后,调用 commitActiveItems(next);不要继续调用旧 GearStore.write(gears)。saveRename() 仍保留第三篇的打开时名字校验,undoBatch() 仍保留第四篇 afterKey 校验。这里没有把两个问题重新实现一遍,而是给它们换上新的提交入口。choosePlan() 必须在页面状态交接处清理编辑会话,防止 A 方案的输入框保存到 B 方案。

页面显示也有一个容易误判的细节:ForEach 的 key 应使用当前方案 ID 与装备 ID 共同构成,而不是只使用装备 ID。两个方案的装备可能都有 id=1,若列表 key 仍只是 1,跨方案切换时可能复用上一个列表项的组件实例及其局部编辑态。稳定 key 可以写成 `${this.bundle.activePlanId}_${g.id}`,若列表内还有真正独立的组件状态,切换方案时也应统一重置。官方 ForEach 说明 要求 key 持久、唯一,因此这里唯一性的范围是整个可交互页面,而不是仅看某份静态数组。
对于原有的分类过滤功能,本篇不引入第二份 @State 复制数组。页面继续根据 this.gears 和筛选条件计算可见分组,切换时先恢复“全部”“显示所有装备”的默认筛选,再渲染新方案。否则从“只看未装箱”切到全部已装箱的新方案,页面可能显示空白,用户误以为数据丢失。这个“空白”既不是数据库问题也不是页面刷新问题,而是旧过滤条件合法地作用于新数据;清除过滤器正是跨方案交互的产品规则。
四、写入顺序、失败提示与升级边界
新的写入队列延续第四篇“先快照、后排队”的约束,只是快照对象从单数组扩大到完整 PlanBundle。排队时应克隆一次结构,避免随后 UI 修改被异步链路读取为另一版本。若用户快速执行“勾选 → 切换 → 新增”,最终持久化的内容必须是最后一次的完整方案包。失败只提示,不把未保存状态称为落盘成功;“重试”则提交当前完整包,而不是将某个旧失败任务继续覆盖最新意图。
// Index.ets:替换旧 aboutToAppear,并与上段成员合并
aboutToAppear(): void { this.reloadPlans(); }
private persistBundle(): void {
if (this.planStore === null || !this.dataReady) {
this.saveHint = '本地数据不可写'; return;
}
const snap: PlanBundle = JSON.parse(JSON.stringify(this.bundle)) as PlanBundle;
const revision: number = ++this.planRevision;
this.saveHint = '正在保存多方案';
this.planSaveChain = this.planSaveChain.catch(() => {}).then(async () => {
if (this.planStore !== null) { await this.planStore.write(snap); }
if (revision === this.planRevision) { this.saveHint = '全部方案已保存'; }
}).catch(() => {
if (revision === this.planRevision) { this.saveHint = '保存失败,可重试'; }
});
}
private reloadPlans(): void {
try {
const context = getContext(this) as common.UIAbilityContext;
this.planStore = new PlanStore(context);
const loaded = this.planStore.read();
const active = loaded.plans.find((p: PackPlan) =>
p.planId === loaded.activePlanId);
if (!active) { throw new Error('活动方案不存在'); }
this.bundle = loaded;
this.gears = copyGears(active.items);
this.clearUndo();
this.dataReady = true;
this.saveHint = '已恢复出行方案';
} catch (_) {
this.dataReady = false;
this.saveHint = '本地方案无法读取,请保留原文件';
}
}
一个容易被忽略的边界是:如果 reloadPlans() 失败但页面仍允许编辑,之后的默认方案可能覆盖故障现场。示例已经让 dataReady 在读取异常时变为 false 并阻止 persistBundle();交互层还需将所有编辑按钮绑定到这一状态,禁用数据变更并提供恢复或诊断入口。切记不要在读取失败后直接触发任何写入。此外,方案数量上限是 20、每方案装备上限是 500,它们服务于示例的资源约束,并不意味着 Preferences 永远适合如此大的存储规模,应依据实际序列化大小和读写行为决定是否改用数据库。
对写入故障还要区分“操作界面已接受”和“落盘已完成”。例如用户勾选头灯后立即退出,页面上可能已经显示勾选但保存队列仍在运行;如果没有等待 flush() 返回就显示“全部方案已保存”,用户下次启动看到未勾选状态会误以为软件自动撤销了操作。因此状态文案只能在最新一笔写入确认后更新。对于连续快速操作,旧任务成功也不得覆盖新任务的提示状态;用 planRevision 比较就是为了解决这类不显眼的提示竞态。
如果应用在旧版快照迁移后第一次新键写入失败,不应删除旧键;尤其不能用 deletePreferences 清空整个 Preferences 文件来“重试”。更稳妥的策略是保持旧键只读,直到产品明确验证新格式已被成功写入,并在后续版本提供可恢复路径。删除旧数据是独立的数据生命周期决策,不是本篇改造自动包含的步骤。多方案列表的体积、单次 JSON 序列化成本和应用退出时机,都需要到真实设备上按实际数据量再评估。
五、按方案隔离验收,而不是按按钮次数验收
验收先从旧清单升级开始:预装 gear_snapshot_v1,其中帐篷与水袋已装箱、头灯与保温毯未装箱;首次读取只应得到“周末轻徒步”一份方案,数值仍是 2/4。然后新增“家庭露营”,新方案继承名称与分类但将 packed 重置为 false;把家庭露营的帐篷勾选,不应改变周末轻徒步的帐篷。再重启应用,两个方案和当前选中方案都应按最后一次成功保存的内容还原。
随后执行更苛刻的边界序列:在周末方案做一次批量装箱但不撤销,立刻切换到家庭方案,点击撤销不能改动家庭方案;打开编辑框、切换方案、再保存旧输入,旧的 editingId 必须已归零;删除某一项后再添加,不能生成与本方案已有记录相同的 id。最后注入损坏 JSON 或错误 schema,只允许出现清晰的读取故障提示,不能静默清空数据。实际设备上的应用生命周期、后台切换及崩溃恢复还应单独验证,不能把界面示意图当成已通过测试的证明。

技术结论是一个并不炫目的约束:当数据从单份清单发展到多份方案,先统一写入入口,再讨论新增多少页面。PackPlan 的边界让原有分类、编辑冲突、批量撤销代码继续有意义,PlanBundle 则保证一次保存承载完整状态。下一篇将围绕数据保护、可恢复性和这套本地工具的工程收尾展开,不提前承诺没有接入的云同步。
更多推荐

所有评论(0)