鸿蒙编辑器—arkts状态持久化-PersistentStorage

ArkTS开发中的PersistentStorage作为核心持久化组件，采用键值对存储模型支持多种数据类型，包括复杂结构。通过setItem/getItem/removeItem等接口实现数据读写管理，支持Promise异步操作。其设计特点包括：沙盒隔离确保数据安全，建议敏感数据额外加密；内置缓存优化读取性能；需注意不支持部分数据类型及嵌套对象的局部更新。该组件与AppStorage形成互补，前者

ab1569063968

1282人浏览 · 2025-05-27 20:17:42

ab1569063968 · 2025-05-27 20:17:42 发布

一、核心概念与应用价值

在 ArkTS 开发体系中，PersistentStorage作为状态持久化的核心组件，肩负着数据长期存储与管理的重要使命。其核心功能在于确保应用数据在设备重启、应用关闭等场景下不丢失，极大提升了应用的可用性与用户体验。无论是记录用户个性化配置，还是保存应用运行状态数据，PersistentStorage都为应用提供了稳定的数据存储基石。

二、存储模型与数据类型支持

PersistentStorage采用经典的键值对（Key-Value）存储模型，以直观、高效的方式实现数据的读写。开发者通过定义唯一的键（Key）标识数据，以值（Value）存储具体信息。在数据类型支持上，它不仅涵盖字符串、数字、布尔值等基本类型，还可处理对象、数组等复杂数据结构。例如，在新闻类应用中，可将用户浏览历史以 JSON 格式序列化后存储，读取时反序列化还原数据结构，便于后续分析与展示。

三、核心操作接口详解

3.1 数据写入（setItem）

setItem方法用于将数据写入存储，接收键和值作为参数，返回 Promise 对象用于处理操作结果。通过then方法可执行写入成功后的逻辑，catch方法捕获写入过程中的错误。如将用户设置的主题模式存储时，可调用PersistentStorage.setItem('theme_mode', 'dark')，并在then回调中提示用户设置成功。

实例：LocalStorage和AppStorage都是运行时的内存，在应用退出后就没有了，如果要在应用退出后再次启动依然能保存选定的结果，这就需要用到PersistentStorage。

PersistentStorage.persistProp<string>('info','宇智波带土·白面具')

@Entry
@Component
struct PersistentStoragePage01 {
  @StorageLink('info')
  info:string=''

  build() {
    Row() {
      Column() {
        Text(this.info)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(()=>{
            this.info+='!'
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

核心步骤：

初始化PersistentStorage
通过 AppStorage 获取并修改数据
重启应用，检测结果

3.2 数据读取（getItem）

getItem方法用于从存储中获取数据，传入键后返回 Promise 对象。在then回调中可获取对应值，若键不存在则返回null。例如，在启动应用时，通过PersistentStorage.getItem('theme_mode')获取用户主题设置，据此渲染应用界面。

注意

可以存储被JSON.stringify()和JSON.parse()重构的对象。Date, Map, Set等内置类型则不支持，以及对象的属性方法不支持持久化。
如果是嵌套对象（对象数组，对象的属性是对象等）。修改单个属性无法写回到PersistentStorage中, 需要替换整个对象。
不支持 undefined 和 null

interface fruits {
  name: string
  price: number
}

// 初始化仓库
PersistentStorage.persistProp<fruits[]>('fruits', [
  { name: '西瓜', price: 22 },
  { name: '桃子', price: 11 },
  { name: '菠萝', price: 15 }
])


@Entry
@Component
struct Index {
  @StorageLink('foods')
  fruits: fruits[] = []

  build() {
    Column({ space: 20 }) {
      ForEach(this.fruits, (item: fruits) => {
        Text('name: ' + item.name)
          .fontSize(30)
          .onClick(() => {
            // AppStorage.set('foods', [{ name: '西瓜-加冰', price: 12 }])
            this.fruits[0] = { name: '西瓜-加冰-沙瓤', price: 12 }
          })
      })

    }
    .width('100%')
    .height('100%')
  }
}