文档开发者中心
我的

HarmonyOS 实用小 Demo:做一个支持保存与撤销的本地便签

浏览134发布于2026-09-29 07:08北京

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. 按顺序验收完整流程

  1. 在手机或模拟器上启动工程,等待“读取完成,可以编辑”。第一次使用时输入框为空,这是正常的默认结果。
  2. 输入“明天带上充电器”,点击保存,等到“已保存到本机”再进行下一步。
  3. 把文字改成“明天带上水杯”,但不保存,点击撤销。输入框应恢复成“明天带上充电器”。
  4. 结束应用进程,再从桌面重新启动,检查是否恢复已保存文字。仅切到后台再回来不足以证明持久化成功。
  5. 连续点击保存,保存期间应不可再次触发;输入框暂时禁用,结束后恢复。
  6. 如果确实需要清空便签,手动删掉全部文字,再点击保存。空字符串也会保存,下次启动应为空。这是主动覆盖当前内容,不提供历史版本恢复。

注意不要用“卸载重装”测试普通重启恢复。清理应用数据或卸载应用会影响沙箱数据;此 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。本文的单页便签流程、交互与异常处理为独立编写的教学示例。

收藏
3
回复
3
分享
全部评论
authorIcon
寻常老百姓
学习
回复于2026-09-29 08:48甘肃
authorIcon
初晨
大佬
1
回复于2026-09-29 08:43江苏
authorIcon
WH

小白一枚

回复于2026-09-29 11:12北京
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
1. 做一个关闭后还能找回的本地便签
2. 准备工程与运行环境
3. 先分清三份数据
4. 完整代码:替换 Index.ets
5. 按顺序验收完整流程
6. 取消、异常和页面离开怎么处理
7. 小练习与自查
8. 验证范围与官方资料
了解社区公约,与您携手共创和谐专业的开发者社区。