1. 做一个关闭后还能找回的本地便签
临时记下一句提醒,关闭应用再打开却没有了,原因通常是文字只放在页面变量里。这次做一个单页小工具:输入一段短文字,点击“保存到本机”,下次启动自动恢复;改错了但还没保存,可以撤销本次修改。
输入是最多 500 个字符的普通便签,操作入口是保存和撤销两个按钮,结果是本机保留一份最新内容。它适合学习短文本草稿保存,不包含多条笔记、附件、账号同步或后台自动保存。
2. 准备工程与运行环境
在 DevEco Studio 新建 ArkTS、Stage 模型的 Empty Ability 手机工程。本文使用状态管理 V1:@Component 与 @State,不要把部分字段替换成 V2 装饰器。
示例要求 API 12 或以上:获取页面上下文使用 this.getUIContext().getHostContext(),该接口从 API 12 提供。请使用与项目 SDK 配置兼容的 HarmonyOS 手机或模拟器,并具备 Preferences 能力。编辑器预览不能替代真实持久化验收。
文件分工如下:
entry/src/main/ets/pages/Index.ets:便签界面、读取、保存与撤销,下面完整替换此文件。entry/src/main/ets/entryability/EntryAbility.ets:保留模板,负责加载首页。entry/src/main/resources/base/profile/main_pages.json:保留模板中的pages/Index页面配置。entry/src/main/module.json5:保留模板,无需添加网络、相册或公共文件存储权限。
只使用系统提供的 ArkData 和 BasicServicesKit,不需要安装三方库。数据由 Preferences 放入应用沙箱,不写设备绝对路径,也不写示例包名。它不提供本例所需之外的加密能力,请用普通练习文字,不用于保存密码。
3. 先分清三份数据
draft 是正在编辑的文字;savedText 是本页面最近一次读到或确认保存成功的文字;Preferences 则负责本地持久化。
本例采用默认 XML 存储模式。put 修改 Preferences 实例中的值,flush 把数据提交到持久化文件。代码依次等待它们,只有 await store.flush() 成功后才显示“已保存到本机”。不能刚调用 put 就提示完成。
读取时用固定存储名称 quick_note,键为 content。键不存在时使用空字符串作为默认值。这个小工具只有一个页面在同一进程里写入,避免把单页示例直接当作多进程共享存储方案。
4. 完整代码:替换 Index.ets
首次进入时自动读取,读取完成前禁用编辑。保存开始后禁用输入框和按钮,并在方法内部再检查 busy,避免连续点击启动多个保存任务。代码中的注释说明了关键边界。
import { preferences } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
@State private draft: string = '';
@State private savedText: string = '';
@State private ready: boolean = false;
@State private busy: boolean = false;
@State private uncertain: boolean = false;
@State private message: string = '正在读取本地便签';
private store: preferences.Preferences | undefined = undefined;
private active: boolean = false;
aboutToAppear(): void {
this.active = true;
this.loadNote();
}
aboutToDisappear(): void {
// 页面离开后不再更新状态;这不会取消已经开始的存储操作。
this.active = false;
this.store = undefined;
}
private async loadNote(): Promise<void> {
if (this.busy || this.ready) {
return;
}
this.busy = true;
try {
const context = this.getUIContext().getHostContext();
if (!context) {
throw new Error('页面上下文不可用');
}
// name 是本应用中的存储名称,不是设备绝对路径。
const store = await preferences.getPreferences(context, { name: 'quick_note' });
const value = await store.get('content', '');
if (!this.active) {
return;
}
this.store = store;
this.savedText = typeof value === 'string' ? value : '';
this.draft = this.savedText;
this.ready = true;
this.message = '读取完成,可以编辑';
} catch (error) {
if (this.active) {
const detail = error as BusinessError;
this.message = `读取失败:${detail.message}。请点击重试读取。`;
}
} finally {
if (this.active) {
this.busy = false;
}
}
}
private async saveNote(): Promise<void> {
const store = this.store;
if (!this.ready || this.busy || !store) {
return;
}
// 点击时取快照,保存期间禁用编辑和其他操作。
const content = this.draft;
this.busy = true;
this.message = '正在保存,请等待完成';
try {
await store.put('content', content);
// 默认 XML 模式:必须等 flush 完成,才显示保存成功。
await store.flush();
if (this.active) {
this.savedText = content;
this.uncertain = false;
this.message = '已保存到本机';
}
} catch (error) {
if (this.active) {
const detail = error as BusinessError;
// 失败不等于自动回滚;保留草稿,让用户重试保存。
this.uncertain = true;
this.message = `保存未确认成功:${detail.message}。请保留内容并重试保存。`;
}
} finally {
if (this.active) {
this.busy = false;
}
}
}
private discardDraft(): void {
if (!this.ready || this.busy || this.uncertain) {
return;
}
// 只撤销尚未保存的界面修改,不删除持久化文件。
this.draft = this.savedText;
this.message = '已撤销未保存的修改';
}
build() {
Scroll() {
Column({ space: 16 }) {
Text('我的本地便签')
.fontSize(26)
.fontWeight(FontWeight.Bold)
Text('写一段短文字,点击保存后,下次打开继续查看。')
.fontSize(14)
.fontColor('#666666')
TextArea({ text: this.draft, placeholder: '例如:明天带上充电器' })
.height(200)
.maxLength(500)
.enabled(this.ready && !this.busy)
.onChange((value: string) => {
this.draft = value;
})
Text(this.uncertain ? '保存结果待确认,请重试保存' :
(this.draft === this.savedText ? '没有未保存的修改' : '有未保存的修改'))
.fontSize(14)
Button(this.busy ? '处理中' : '保存到本机')
.width('100%')
.enabled(this.ready && !this.busy)
.onClick(() => { this.saveNote(); })
Button('撤销未保存的修改')
.width('100%')
.enabled(this.ready && !this.busy && !this.uncertain)
.onClick(() => { this.discardDraft(); })
if (!this.ready) {
Button('重试读取')
.enabled(!this.busy)
.onClick(() => { this.loadNote(); })
}
Text(this.message)
.fontSize(14)
.fontColor('#444444')
}
.width('100%')
.padding(24)
.alignItems(HorizontalAlign.Start)
}
.width('100%')
.height('100%')
}
}
5. 按顺序验收完整流程
- 在手机或模拟器上启动工程,等待“读取完成,可以编辑”。第一次使用时输入框为空,这是正常的默认结果。
- 输入“明天带上充电器”,点击保存,等到“已保存到本机”再进行下一步。
- 把文字改成“明天带上水杯”,但不保存,点击撤销。输入框应恢复成“明天带上充电器”。
- 结束应用进程,再从桌面重新启动,检查是否恢复已保存文字。仅切到后台再回来不足以证明持久化成功。
- 连续点击保存,保存期间应不可再次触发;输入框暂时禁用,结束后恢复。
- 如果确实需要清空便签,手动删掉全部文字,再点击保存。空字符串也会保存,下次启动应为空。这是主动覆盖当前内容,不提供历史版本恢复。
注意不要用“卸载重装”测试普通重启恢复。清理应用数据或卸载应用会影响沙箱数据;此 demo 也没有云端备份。
6. 取消、异常和页面离开怎么处理
这里的取消是“撤销未保存的修改”,只把输入框恢复成 savedText,不会访问磁盘。保存过程中不能取消:这组 Promise 接口没有在本例中提供中止写入的能力,不能把隐藏进度或离开页面说成保存已取消。
如果 put 或 flush 抛错,输入内容保留,页面提示保存尚未确认成功。此时禁用撤销,避免用户把失败当作已经回滚。可以检查原因后再次点击保存,成功后恢复正常状态。失败不保证磁盘仍是旧值,也不能靠再次 get 读取同一个缓存实例来证明落盘成功。
读取失败时不开放保存入口,防止尚未读取旧便签就覆盖它;“重试读取”用于重新初始化。正式排查时结合错误信息、设备剩余空间和应用日志判断原因,不把便签正文写进日志。
aboutToDisappear 只清除页面持有的引用,并防止异步完成后继续更新已离开的页面;已经开始的保存仍可能继续。示例没有主动创建文件描述符、计时器或事件订阅,因此没有对应的 close、clear 或 off 操作。Preferences 还有系统管理的实例缓存,清空本页引用不等于移除该缓存,更不等于删除数据;不要为了“释放资源”调用删除存储文件的接口。
本例按单个首页组件的一次生命周期设计。扩展成多页面、多窗口或多个写入入口时,应把实例和写入队列放到统一的数据层,同时处理页面重新进入和异步任务归属,不能只复制每页一个 busy。
7. 小练习与自查
练习:保存一段包含换行的中文提醒,再修改第二行并撤销。预期原有换行和两行内容一起恢复。参考操作是输入两行、保存成功、修改第二行、点击撤销,代码无需增加额外文件。
- 为什么
@State不够?答:它负责界面响应,不自动完成本例的磁盘保存。 - 为什么撤销不重新读取 Preferences?答:撤销针对当前编辑,使用本页面已确认的快照即可;缓存读取也不是落盘验证。
- 能否把保存逻辑放进
onChange?答:会让每次输入都启动写入,还需要处理节流、顺序和失败;这个 demo 采用明确点击保存,方便观察每一步。 - 点保存后马上关闭应用是否一定成功?答:不保证。应等成功提示;强制结束进程时,尚未完成的异步写入不能算完成。
8. 验证范围与官方资料
本文接口与默认存储行为已对照华为官方指南及本机 API 26 SDK 声明核对。示例仍以 API 12 及以上为使用前提。已进行保存顺序、连续点击、失败保留草稿和撤销边界的模拟逻辑检查;模拟检查不等于 ArkTS 编译或设备验证,本次未进行完整工程编译、安装及真机运行。上面的运行结果是验收目标。
参考:华为官方:通过用户首选项实现数据持久化(ArkTS)、用户首选项 API。本文的单页便签流程、交互与异常处理为独立编写的教学示例。










































苏公安网备 32011402010933号