【转盘决定吧|08】HarmonyOS ArkTS 6.0.2.130 决定历史:Preferences 持久化、AppStorage 刷新与清空边界
随机工具的结果页做完以后,历史记录往往只剩一句需求:“把结果存下来。”真正把它接进 HarmonyOS 应用,问题会迅速变成一条完整链路:应用启动时谁先取得 Preferences,磁盘 JSON 何时装载到内存,新增记录后列表为什么能立即刷新,连续产生两条结果会不会互相覆盖,筛选到“骰子”后点“清空”究竟应该删骰子记录还是全部记录,写盘失败后界面已经出现的记录又该怎样处理。
本文基于“转盘决定吧”1.0.9 的真实源码,沿 EntryAbility.ets、PreferencesStore.ets、HistoryService.ets、History.ets 和 HistoryView.ets 还原决定历史的保存、读取、筛选、删除与清空路径。当前工程选择用 Preferences 保存不超过 500 条的小型 JSON 数组,再通过 AppStorage 镜像给 ArkUI 页面,这个方案非常适合离线、记录量有限、查询条件简单的决定工具。文章也会指出当前实现中值得继续收紧的失败语义、并发写入和筛选清空边界。

本文聚焦五个可复用问题:
- 为什么 Preferences 不能在页面里直接调用,而应由存储封装和历史服务分层负责。
- 如何通过
AppStorage.setOrCreate()与@StorageLink让增删清即时反映到列表。 - 为什么每次修改都创建新数组,而不是原地改写共享引用。
- 如何避免连续写操作丢记录,并处理内存已更新但磁盘提交失败的情况。
- 如何让“清空全部”和“清空当前分类”在界面与服务中保持同一个含义。
可核验环境:工程现存的
report-202606131742406040.json记录了 SDK 6.0.2.130(API 22)、Hvigor 6.22.3、Node.js 25.9.0,以及当次 releaseassembleApp成功。本轮只做源码阅读与文章精修,没有重新构建、安装或运行应用,因此本文不把历史报告等同于本轮验证结果。文中“当前源码”均来自真实工程;带“建议实现”或“改进写法”的片段用于说明演进方案,不表示项目已经采用。
源码事实与建议实现的边界
为了避免把设计建议写成已经上线的能力,本文使用“转盘决定吧历史快照一致性契约”作为唯一核对标记,并按下面的边界解读全文:
| 分类 | 本文确认的内容 | 应如何理解 |
|---|---|---|
| 当前源码事实 | HistoryService 使用 history_records_v1,上限为 500 条;load() 把 Preferences 数据镜像到 AppStorage.historyList;HistoryView 用 @StorageLink 订阅;新增、删除和清空都先替换内存数组,再调用 putJson() | 可在本文列出的真实文件中逐行复核 |
| 当前源码事实 | 页面支持六种筛选入口、侧滑删除、长按分享;筛选状态下的“清空”仍调用无参数 HistoryService.clear() | 这是现有行为,不代表它已经具备分类清空或二次确认 |
| 建议实现 | JSON 逐条校验、串行写队列、写盘失败回滚、clearAll() 与 clearByType() 拆分、清空确认和加载状态 | 这些是针对当前边界提出的演进方案,示例代码未写入项目 |
| 验证边界 | 本轮未执行构建、真机安装、运行时故障注入,也未验证 AppGallery 发布数据 | 不据此宣称编译、运行、上架或性能结果 |
后文凡是描述“当前”时,只指已读取源码能够证明的行为;凡是出现“可以”“建议”“更稳”时,均属于待实现方案。这样才能让技术分析既有工程参考价值,又不虚构项目能力。
一、先看真实数据模型与存储键
历史记录模型没有保存页面组件或视觉状态,只包含业务结果需要的五个字段:
export type HistoryType = 'wheel' | 'pick' | 'coin' | 'dice' | 'fun';
export class HistoryRecord {
id: string = '';
type: HistoryType = 'wheel';
title: string = '';
result: string = '';
timestamp: number = 0;
}
HistoryService 使用两个不同用途的键:
const KEY = 'history_records_v1';
const MAX = 500;
export class HistoryService {
static readonly STORAGE_KEY = 'historyList';
}
history_records_v1 是 Preferences 中的磁盘键,带版本后缀,负责跨进程重启保留数据;historyList 是 AppStorage 中的运行时键,负责让页面订阅同一份内存快照。二者不能混为一谈:前者解决持久性,后者解决响应式界面。
决定历史的可靠性不取决于把数组写进 Preferences,而取决于持久化快照、AppStorage 镜像和筛选清空语义是否始终指向同一份事实。
二、应用启动顺序决定首次页面看到什么
工程在 EntryAbility.onCreate() 中先初始化 Preferences,再装载设置、历史和转盘数据:
AppStorage.setOrCreate('appContext', this.context.getApplicationContext());
await PreferencesStore.init(this.context);
const settings = await SettingsService.load();
await HistoryService.load();
await WheelService.load();
SettingsService.applyTheme(settings.theme);
await SoundService.init();
这个顺序很重要。HistoryService.load() 内部调用的是同步读取接口,如果 Preferences 单例尚未准备好,PreferencesStore.getString() 会返回默认值,历史就会被镜像成空数组。当前启动链路通过 await PreferencesStore.init() 保证了正常情况下先取得存储实例,再读取 JSON。

启动阶段可以按三个状态理解:
| 阶段 | 磁盘存储 | AppStorage | 页面应看到的内容 |
|---|---|---|---|
| 初始化前 | 未取得实例 | 可能没有键 | 不应提前依赖历史 |
| 装载完成 | 已读取 JSON | 写入 historyList | 显示恢复后的列表 |
| 初始化失败 | 不可用 | 当前会落为空数组 | 应记录失败并提供降级说明 |
三、PreferencesStore 只负责存储协议
项目把 Preferences 的获取、字符串读写和 JSON 转换集中到 PreferencesStore:
const STORE_NAME = 'random_picker_store';
export class PreferencesStore {
private static pref: preferences.Preferences | null = null;
static async init(context: common.UIAbilityContext | common.Context): Promise<void> {
if (PreferencesStore.pref) return;
try {
PreferencesStore.pref = await preferences.getPreferences(context, STORE_NAME);
hilog.info(0, TAG, 'preferences ready');
} catch (e) {
hilog.error(0, TAG, 'init failed: %{public}s', JSON.stringify(e));
}
}
}
这个类不知道什么是转盘、骰子或趣味题,它只建立三条规则:所有服务共享同一个存储实例;读取失败时返回调用方给出的默认值;写入后调用 flush() 提交。
把它留在服务层的意义很直接:页面不用持有 Context,不用拼存储名,也不会在不同组件中重复 JSON.stringify()。以后更换键、添加日志或迁移策略时,页面结构不需要调整。
四、JSON 读取要区分语法正确与结构可信
当前 JSON 封装能够处理空值和解析异常:
static getJson<T>(key: string, def: T): T {
const raw = PreferencesStore.getString(key, '');
if (!raw) return def;
try {
return JSON.parse(raw) as T;
} catch (e) {
hilog.warn(0, TAG, 'parse json failed key=%{public}s', key);
return def;
}
}
JSON.parse() 成功只说明字符串语法有效,并不能证明每一项都符合 HistoryRecord。例如 [null]、[{"timestamp":"昨天"}] 都是合法 JSON,强制转换后却不具备页面所需字段。HistoryService.load() 目前只确认顶层是数组:
const raw = PreferencesStore.getJson<HistoryRecord[]>(KEY, []);
const list: HistoryRecord[] = Array.isArray(raw) ? raw : [];
更稳的装载过程应该逐条规范化:
private static normalize(value: object): HistoryRecord | undefined {
const item = value as Record<string, object>;
if (typeof item.id !== 'string' || item.id.length === 0) return undefined;
if (!HistoryService.isType(item.type)) return undefined;
if (typeof item.title !== 'string') return undefined;
if (typeof item.result !== 'string' || item.result.length === 0) return undefined;
if (typeof item.timestamp !== 'number' || item.timestamp <= 0) return undefined;
const record = new HistoryRecord();
record.id = item.id;
record.type = item.type;
record.title = item.title;
record.result = item.result;
record.timestamp = item.timestamp;
return record;
}
装载边界负责把外部数据转换成可信模型,页面便不必在每个 Text 和时间格式化方法前重复判断。
五、load 把磁盘事实镜像到 AppStorage
真实的装载方法很短:
static async load(): Promise<HistoryRecord[]> {
const raw = PreferencesStore.getJson<HistoryRecord[]>(KEY, []);
const list: HistoryRecord[] = Array.isArray(raw) ? raw : [];
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, list);
return list;
}
它完成两个动作:读取持久化数组;把这批记录作为新的内存快照写入 historyList。HistoryView 使用同名 @StorageLink:
@StorageLink('historyList') records: HistoryRecord[] = [];
因此页面不需要主动轮询 Preferences,也不需要在每次返回历史页时重新读磁盘。只要历史服务替换 AppStorage 中的数组,所有绑定到该键的视图都会收到变化。

六、getAll 的默认值保证页面始终拿到数组
如果某条路径在启动装载前调用历史服务,getAll() 会创建空数组:
static getAll(): HistoryRecord[] {
let list = AppStorage.get<HistoryRecord[]>(HistoryService.STORAGE_KEY);
if (!list) {
list = [];
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, list);
}
return list;
}
这个兜底避免了页面处理 undefined,但也意味着“尚未装载”和“确实没有记录”在当前接口中都是空数组。如果应用将来需要展示启动加载态,可以把初始化状态单独存为 historyStatus,不要用数组长度推断装载是否完成。
另一个边界是返回引用。getAll() 当前直接返回 AppStorage 中的数组,调用方如果原地 push() 或 splice(),可能绕过持久化逻辑。服务可以返回副本:
static getAll(): HistoryRecord[] {
const list = AppStorage.get<HistoryRecord[]>(HistoryService.STORAGE_KEY) ?? [];
return list.slice();
}
读者拿到快照,所有修改仍必须经过 add()、remove() 或 clear()。
七、新增记录采用头插和固定上限
当前新增流程先构造完整记录,再生成新数组:
static async add(type: HistoryType, title: string, result: string): Promise<void> {
const r = new HistoryRecord();
r.id = RandomUtil.id('h');
r.type = type;
r.title = title;
r.result = result;
r.timestamp = Date.now();
const cur = HistoryService.getAll();
const next = [r, ...cur].slice(0, MAX);
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, next);
await PreferencesStore.putJson<HistoryRecord[]>(KEY, next);
}
[r, ...cur] 让最新结果位于列表顶部,slice(0, 500) 则阻止单个 JSON 数组无限增长。每次都创建 next 而不是在 cur 上原地修改,还有一个 ArkUI 层面的好处:AppStorage 收到新数组引用,@StorageLink 的变化更明确。
固定 500 条也对应了技术选型边界。最多几百条、只按类型筛选、整表读写的离线历史适合 Preferences;如果需要数万条、时间范围查询、分页、聚合统计或复杂迁移,应把记录交给关系型存储,而不是继续扩大一个 JSON 字符串。
八、删除与清空同样通过新快照提交
单条删除以稳定 id 为条件:
static async remove(id: string): Promise<void> {
const next = HistoryService.getAll().filter(r => r.id !== id);
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, next);
await PreferencesStore.putJson<HistoryRecord[]>(KEY, next);
}
清空则同时把内存和磁盘替换为空数组:
static async clear(): Promise<void> {
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, []);
await PreferencesStore.putJson<HistoryRecord[]>(KEY, []);
}
三种写操作的模式一致:计算下一份快照,更新 AppStorage,再写 Preferences。统一模式容易阅读,但它也带来一个必须明确的决策:这是“界面优先”的乐观提交。用户先看到变化,磁盘写入稍后完成。
九、乐观提交失败后不能假装成功
PreferencesStore.putString() 当前在实例为空时直接返回,真正写入时则等待 put() 与 flush():
static async putString(key: string, value: string): Promise<void> {
if (!PreferencesStore.pref) return;
await PreferencesStore.pref.put(key, value);
await PreferencesStore.pref.flush();
}
如果存储未初始化,调用方会得到一个已经完成的 Promise,但数据没有落盘;如果 put() 或 flush() 抛出异常,AppStorage 已经更新。此时本次运行看起来保存成功,应用重启后记录却可能消失。
可以在存储层对“未初始化”显式失败,并在历史服务中决定回滚还是保留待重试状态:
static async putString(key: string, value: string): Promise<void> {
if (!PreferencesStore.pref) {
throw new Error('PreferencesStore is not initialized');
}
await PreferencesStore.pref.put(key, value);
await PreferencesStore.pref.flush();
}
历史服务若选择回滚,应保存修改前快照:
private static async commit(previous: HistoryRecord[], next: HistoryRecord[]): Promise<void> {
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, next);
try {
await PreferencesStore.putJson<HistoryRecord[]>(KEY, next);
} catch (error) {
AppStorage.setOrCreate<HistoryRecord[]>(HistoryService.STORAGE_KEY, previous);
throw error;
}
}
页面可以根据异常显示简短失败提示。关键不是必须回滚,而是让界面状态和持久化结果之间的差异成为明确业务状态。
十、连续写操作可能丢失更新
假设两个结果几乎同时调用 add():A 和 B 都读取相同的 cur,分别构造 [A, ...cur] 与 [B, ...cur]。最后完成的写操作会覆盖前一次快照,其中一条记录消失。日常手动点击不一定高频触发,但声音回调、动画完成回调、快捷入口或多组件并发都可能扩大窗口。
历史服务适合把写操作串行化:
private static writeTail: Promise<void> = Promise.resolve();
private static enqueue(operation: () => Promise<void>): Promise<void> {
const task = HistoryService.writeTail.then(operation, operation);
HistoryService.writeTail = task.catch(() => undefined);
return task;
}
static add(type: HistoryType, title: string, result: string): Promise<void> {
return HistoryService.enqueue(async () => {
const record = HistoryService.createRecord(type, title, result);
const previous = HistoryService.getAll();
const next = [record, ...previous].slice(0, MAX);
await HistoryService.commit(previous, next);
});
}
队列让下一次操作在前一次提交结束后重新读取最新快照。它不是为了增加线程概念,而是保护“读当前值、计算下一值、写回”这组三步不可被另一条写操作穿插。
十一、筛选只发生在内存,不必重复读盘
历史视图定义六个筛选项:全部、转盘、抽取、硬币、骰子和趣味。filtered() 直接在 records 上过滤:
private filtered(): HistoryRecord[] {
if (this.filter === 'all') return this.records;
return this.records.filter(r => r.type === this.filter);
}
最多 500 条的规模下,这种内存筛选足够简单。切换筛选时只改变 @State filter,不会访问磁盘。服务层也提供 getByType(),适合非组件调用:
static getByType(type: HistoryType | 'all'): HistoryRecord[] {
const all = HistoryService.getAll();
return type === 'all' ? all : all.filter(r => r.type === type);
}
视图中的 filtered() 在一次构建中被多次调用,包括控制清空按钮和生成列表。当前数据量影响很小;若后续增加搜索与分组,可以在状态变化时计算一次可见快照,避免同一轮重复遍历。
十二、筛选状态下的“清空”存在语义错位
真实页面只有当当前筛选结果非空时才显示“清空”,但点击后调用的是无参数 HistoryService.clear():
if (this.filtered().length > 0) {
Text('清空')
.onClick(() => HistoryService.clear());
}
当用户正在看“骰子”筛选时,按钮的视觉上下文很容易被理解为“清空骰子记录”,实际却会删除转盘、抽取、硬币、骰子和趣味的全部记录。这不是存储错误,而是界面文案与服务契约不一致。
有两种清晰方案:
| 产品意图 | 按钮文案 | 服务接口 |
|---|---|---|
| 永远清除全部历史 | 清空全部 | clearAll() |
| 按当前筛选清除 | 清空当前分类 | clearByType(filter) |
分类清空可以这样实现:
static clearByType(type: HistoryType): Promise<void> {
return HistoryService.enqueue(async () => {
const previous = HistoryService.getAll();
const next = previous.filter((record: HistoryRecord) => record.type !== type);
await HistoryService.commit(previous, next);
});
}
若筛选为 all,调用 clearAll();否则调用 clearByType(this.filter)。服务名、按钮文案和实际结果必须表达同一件事。
十三、破坏性清空需要确认与进行中状态
当前清空为单次点击直接执行,且页面没有等待 Promise。历史记录无法撤销时,建议在操作前展示确认对话框,明确写出删除范围和条数。例如“将删除全部 126 条历史记录,此操作不可恢复”,比笼统的“确定吗”更有信息量。
提交期间还应阻止重复触发:
@State clearing: boolean = false;
private async confirmClear(): Promise<void> {
if (this.clearing) return;
this.clearing = true;
try {
if (this.filter === 'all') {
await HistoryService.clearAll();
} else {
await HistoryService.clearByType(this.filter);
}
} finally {
this.clearing = false;
}
}
确认负责防误触,clearing 负责防重复,服务负责真正的数据变化。三个职责各自独立,页面不需要知道 JSON 怎样写入。
十四、滑动删除依赖稳定 id
列表使用记录 id 作为 ForEach 标识,并把同一个 id 交给侧滑删除:
ForEach(this.filtered(), (r: HistoryRecord) => {
ListItem() {
this.RecordRow(r);
}
.swipeAction({ end: this.SwipeDelete(r.id) });
}, (r: HistoryRecord) => r.id)
id 由 RandomUtil.id('h') 生成,避免使用数组下标。删除顶部记录后,其余行的身份保持不变,转场动画也不会把后续记录误认为全新元素。
服务层删除不存在的 id 时会得到与原内容相同的新数组并再次写盘。可以在提交前判断长度是否变化,减少无效写入;更重要的是保证 id 唯一,装载规范化时可去掉重复记录或记录异常日志。
十五、History 页面与 HistoryView 的标题所有权
History.ets 已经放置了带返回按钮的 AppHeader:
Column() {
AppHeader({ title: '历史记录', showBack: true });
HistoryView();
}
而 HistoryView 内部又绘制一行“历史记录”和“清空”。如果该视图既用于独立页面,也用于主导航嵌入区,标题重复往往来自容器和可复用视图同时拥有页面级导航。
更清楚的边界是:History 拥有返回导航和页面标题,HistoryView 只拥有筛选、批量操作和列表;或者给视图一个 showToolbar 参数,由调用方显式选择。不要让子视图根据路由环境猜自己是否应该画标题。
十六、空状态文案要跟随筛选上下文
当前无数据时统一显示:
EmptyState({ title: '还没有记录', subtitle: '快去转一下试试' });
在“转盘”筛选下很贴切,在“硬币”“骰子”或“趣味”筛选下则不够准确。可以根据当前类型生成动作建议:
private emptySubtitle(): string {
if (this.filter === 'coin') return '抛一次硬币,结果会保存在这里';
if (this.filter === 'dice') return '摇一次骰子,结果会保存在这里';
if (this.filter === 'fun') return '完成一次趣味抽取,结果会保存在这里';
if (this.filter === 'pick') return '完成一次随机抽取,结果会保存在这里';
return '完成一次决定,结果会保存在这里';
}
空状态不是装饰,它应该解释“为什么为空”和“下一步去哪里”。筛选后为空并不代表全部历史为空,文案也应避免误导。
十七、时间格式化需要覆盖旧年份与异常值
当前 formatTime() 对当天记录显示时分,其余记录显示月日:
if (sameDay) return pad(d.getHours()) + ':' + pad(d.getMinutes());
return (d.getMonth() + 1) + '/' + d.getDate();
对最多 500 条的近期历史通常够用,但跨年后 1/3 无法区分年份。如果记录可能保留较久,可以按层级显示:当天用 HH:mm,同年用 M/d,跨年用 YYYY/M/d。装载时还应剔除无效时间戳,避免列表出现 NaN/NaN。
时间展示属于视图格式,timestamp 仍应保存毫秒数。不要把“今天 09:30”这样的本地化文本写入 Preferences,否则跨日期、语言或时区后无法重新解释。
十八、长按分享读取的是当前记录快照
记录行通过长按调用分享服务:
.gesture(LongPressGesture().onAction(() => {
const ctx = getContext(this) as common.UIAbilityContext;
ShareService.shareText(`${r.title}:${r.result}`, ctx);
}));
分享使用的是列表回调中的 r,不会重新从 Preferences 查找,也不会重算随机结果。这个边界与历史模型一致:分享的是当时已经提交的结果快照。
若标题可能为空,界面已经使用 labelOf(type) 兜底,分享逻辑也应复用同一显示标题函数,避免列表显示“骰子”而分享文本只有冒号。展示规则最好集中成一个纯函数,列表和分享共同调用。
十九、v1 键名需要真正的迁移入口
history_records_v1 已经表达了数据版本,但当前装载代码没有迁移分支。版本后缀只有在升级时读取旧键、转换模型、写入新键并保留回退策略,才真正发挥作用。
假设未来为记录增加 sourceKey,可以按以下顺序迁移:
- 优先读取
history_records_v2。 - 若不存在,再读取
history_records_v1。 - 对旧记录补齐可推导字段,无法推导的保持空值。
- 逐条规范化、去重、按时间倒序并限制 500 条。
- 写入 v2,确认成功后再决定是否删除旧键。
迁移应由历史仓库或服务负责,页面继续依赖 HistoryRecord[]。不要在 HistoryView 中根据字段缺失猜数据版本。
二十、为什么当前规模适合 Preferences
技术选型需要与数据形状对应。当前历史具有以下特点:只有五个简单字段;最多 500 条;启动时整批装载;查询只有类型过滤;删除靠稳定 id;没有跨表关系。将数组序列化到 Preferences,代码短、依赖少、离线行为清楚。
但每次新增、删除或清空都会序列化并重写整个数组。以下需求出现时,应考虑关系型存储:
| 新需求 | Preferences 的代价 | 更合适的能力 |
|---|---|---|
| 数万条记录 | 整体解析与重写变重 | 分页查询与增量写入 |
| 按日期区间搜索 | 每次遍历全部数组 | 索引与条件查询 |
| 按类型统计趋势 | 页面重复聚合 | 数据库聚合 |
| 多版本复杂迁移 | 大对象转换风险上升 | 明确表结构与迁移脚本 |
不要因为“数据库更专业”就提前迁移,也不要在数据量和查询需求已经变化后仍坚持单个 JSON。边界由真实访问方式决定。
二十一、自动化用例应围绕数据不变量
历史服务的核心不是某一条 ArkUI 样式,而是几条可验证的不变量:最新记录在最前;数量不超过 500;删除只影响目标 id;按类型筛选不改变原数组;清空范围与接口名一致;写入串行后连续新增不丢失。
it('keeps newest record first and caps list', 0, async () => {
for (let index = 0; index < 505; index++) {
await HistoryService.add('dice', '骰子', `${index}`);
}
const records = HistoryService.getAll();
expect(records.length).assertEqual(500);
expect(records[0].result).assertEqual('504');
});
还应给存储失败准备替身:让 putJson() 抛出异常,确认回滚策略或待重试状态符合约定。只验证正常写入无法暴露内存与磁盘分叉问题。
二十二、真实页面核验路径
完成历史链路后,可以按以下顺序核对:
- 冷启动应用,已有记录按上次保存结果恢复,首次列表不闪成错误空态。
- 分别完成转盘、抽取、硬币、骰子和趣味操作,最新记录出现在顶部。
- 退出并重新启动,五种类型仍存在,标题、结果和时间没有变化。
- 连续快速产生两条记录,两条都保留,顺序与完成时间一致。
- 切换六个筛选项,可见项只包含目标类型,全部数组未被改写。
- 侧滑删除一条记录,其他行身份和顺序保持稳定;重启后删除仍然生效。
- 在某个分类下执行批量清空,确认删除范围与按钮文案一致。
- 清空前出现明确确认,提交期间重复点击不会发起第二次操作。
- 模拟存储不可用,页面给出失败反馈,重启后行为与约定一致。
- 使用长标题、长结果和大字号,列表文本省略合理,分享内容完整。
二十三、常见问题与排查顺序
| 现象 | 先看哪里 | 常见原因 | 处理方式 |
|---|---|---|---|
| 冷启动总是空历史 | EntryAbility 初始化顺序 | load() 早于 Preferences 初始化 | 先等待 PreferencesStore.init() |
| 当前能看到,重启后消失 | put() 与 flush() 结果 | 未初始化时静默返回或写盘失败 | 未初始化显式失败,处理提交异常 |
| 连续两次只剩一条 | 写操作时序 | 两次都基于相同旧快照 | 串行执行读、改、写事务 |
| 删除后页面不刷新 | AppStorage 更新方式 | 原地改数组但未提交新引用 | 创建 next 并调用 setOrCreate() |
| 筛选骰子后其他类型也被清空 | 批量操作契约 | 页面调用无范围的 clear() | 分开 clearAll() 与 clearByType() |
| 列表出现无效日期 | 装载边界 | JSON 项字段缺失或类型错误 | 逐条规范化并丢弃坏记录 |
| 独立历史页出现双标题 | 页面与子视图所有权 | 两层都绘制标题栏 | 让容器拥有页面导航 |
| 长按分享标题为空 | 展示规则不一致 | 列表有兜底,分享没有 | 复用同一显示标题函数 |
排查时先确认存储实例,再确认装载快照,然后确认 AppStorage 当前值,最后查看筛选和组件渲染。这个顺序能把磁盘问题、内存问题和界面问题分开。
二十四、工程落地清单
- [ ]
PreferencesStore.init()在历史装载前完成。 - [ ] 磁盘键与 AppStorage 键各自表达清楚用途。
- [ ] JSON 解析后逐条规范化,不只判断顶层数组。
- [ ]
getAll()返回快照,调用方不能绕过服务修改共享数组。 - [ ] 新增记录头插,列表数量始终不超过 500。
- [ ] 增删清都创建新数组,驱动
@StorageLink刷新。 - [ ] 未初始化和
flush()失败不会被静默当作成功。 - [ ] 连续写操作串行执行,不基于同一份过期快照。
- [ ] “清空全部”与“清空当前分类”使用不同接口和文案。
- [ ] 批量删除有范围说明、确认步骤和进行中状态。
- [ ] 页面容器与可复用视图只有一层拥有页面级标题。
- [ ] 时间、空状态与分享文案都复用可信的模型字段。
- [ ] v1 键名对应明确迁移入口,而不只是名称后缀。
- [ ] 冷启动、重启恢复、连续新增、删除与存储失败都有用例。
总结
“转盘决定吧”的决定历史采用了一个很实用的双层结构:Preferences 保存跨启动的 JSON 快照,AppStorage.historyList 保存当前运行时快照,HistoryView 通过 @StorageLink 自动收到增删清变化。新增记录使用稳定 id、最新项头插和 500 条上限,侧滑删除与类型筛选都围绕同一数据模型工作。
继续把这条链路写稳,重点不在增加更多存储代码,而在明确状态转换:启动必须先初始化再装载;解析成功后仍要验证记录结构;每次写操作要基于最新快照串行提交;持久化失败不能被静默忽略;筛选状态下的清空范围必须与文案一致。做到这些,页面即时刷新和磁盘长期保存才真正属于同一套业务事实。
参考文件
entry/src/main/ets/entryability/EntryAbility.etsentry/src/main/ets/model/Models.etsentry/src/main/ets/service/PreferencesStore.etsentry/src/main/ets/service/HistoryService.etsentry/src/main/ets/pages/History.etsentry/src/main/ets/views/HistoryView.ets
更多推荐


所有评论(0)