HarmonyOS之LocalStorage

一、什么是 HarmonyOS 的 LocalStorage？

✅ 基本概念

在 HarmonyOS（ArkTS）中，LocalStorage 是一种轻量级的 页面级状态管理机制，用于在页面内部及其组件之间共享状态数据，并实现响应式 UI 更新。

它是一种 "状态存储"机制，而非传统的"本地数据持久化"机制 （例如文件、数据库或磁盘缓存）。其数据 存在于内存中，在页面销毁后自动释放，不会自动写入磁盘。

---

二、LocalStorage 的设计定位

维度	定位描述
使用场景	页面内共享状态（例如多个组件共享一个状态）
生命周期	生命周期绑定到页面或组件树，页面销毁则数据销毁
数据存储方式	内存存储，不持久化，不跨页面或应用
响应式特性	支持响应式绑定，数据更新自动触发界面刷新
组件通信模式	通过装饰器实现组件间的状态绑定与同步
和 AppStorage 区别	LocalStorage 是页面级，AppStorage 是应用级，全局共享状态（适合设置项、主题等）
和 PersistentStorage 区别	PersistentStorage 是可持久化存储，会将数据保存到本地设备磁盘中

---

三、LocalStorage 的核心功能

✅ 1. 键值对存储结构

const storage = new LocalStorage({
  key1: value1,
  key2: value2,
});

• 通过 key 访问数据；
• 类型必须与初始化时保持一致（比如 count 初始化为数字，就不能再赋字符串）；

✅ 2. 响应式 UI 联动

通过框架提供的装饰器（如 @LocalStorageProp, @LocalStorageLink），将状态字段与组件变量绑定，实现 状态变更 → UI 自动刷新。

✅ 3. 单向 / 双向绑定

装饰器	说明
@LocalStorageProp	单向绑定。仅在状态变化时更新字段，不会写回 storage
@LocalStorageLink	双向绑定。字段变化会同步写回 storage，同时监听状态变化

✅ 4. 支持跨组件访问（但不支持跨页面）

• 同一个页面内，所有子组件都可以访问同一个 LocalStorage 实例；
• 不同页面之间默认无法共享 LocalStorage（可通过 AppStorage 实现共享）；

---

四、使用方式详解

以下为 HarmonyOS ArkTS 中 标准的 LocalStorage 使用流程：

---

✅ 步骤 1：创建 LocalStorage 实例

在页面入口组件中创建 LocalStorage，并定义初始化数据：

const localStorage = new LocalStorage({
  count: 0,
  username: 'guest',
});

---

✅ 步骤 2：注入 LocalStorage 到页面

使用 @Entry(localStorage) 装饰页面组件，让 LocalStorage 注入整个组件树：

@Entry(localStorage)
@Component
struct HomePage {
  // ...
}

注 ：注入后，页面内部所有子组件都可以通过装饰器访问 localStorage 中的状态。

---

✅ 步骤 3：在组件中使用装饰器绑定状态

@Component
struct CounterComponent {
  // 单向绑定 count（只读）
  @LocalStorageProp('count')
  readonly count: number = 0;

  // 双向绑定 username（可读写）
  @LocalStorageLink('username')
  username: string = '';

  build() {
    Column() {
      Text(`当前计数：${this.count}`)

      Text(`用户名：${this.username}`)

      Button("切换用户").onClick(() => {
        this.username = this.username === 'guest' ? 'admin' : 'guest';
      });
    }
  }
}

---

✅ 步骤 4：修改状态自动刷新 UI

@Entry(localStorage)
@Component
struct HomePage {
  @LocalStorageLink('count')
  count: number = 0;

  build() {
    Column() {
      Text(`点击次数：${this.count}`)

      Button("点我加一").onClick(() => {
        this.count += 1;
      })

      CounterComponent()
    }
  }
}

运行结果：

• 每次点击按钮，count +1；
• 因为是响应式绑定，CounterComponent 中显示的 count 会自动更新，无需手动刷新。

---

五、完整示例代码

✅ 场景：在主页面中管理 count 和 username 状态，所有子组件共享状态

// step 1：创建 LocalStorage
const localStorage = new LocalStorage({
  count: 0,
  username: 'guest'
});

// step 2：页面入口注入
@Entry(localStorage)
@Component
struct HomePage {
  @LocalStorageLink('count')
  count: number = 0;

  @LocalStorageLink('username')
  username: string = '';

  build() {
    Column() {
      Text(`欢迎用户：${this.username}`)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)

      Button("修改用户名").onClick(() => {
        this.username = this.username === 'guest' ? 'Alice' : 'guest';
      })

      Button("前往详情页").onClick(() => {
        router.pushUrl('pages/DetailPage');
      })

      CounterComponent()
    }
  }
}

// 子组件：CounterComponent
@Component
struct CounterComponent {
  @LocalStorageLink('count')
  count: number = 0;

  build() {
    Column() {
      Text(`计数器：${this.count}`)

      Button("增加计数").onClick(() => {
        this.count += 1;
      });
    }
  }
}

---

六、LocalStorage 与其他存储方案对比

功能 / 特性	LocalStorage	AppStorage	PersistentStorage
作用范围	页面级	应用级（全局）	全局（可持久化）
是否可响应更新	✅ 是	✅ 是	✅ 是
是否持久化	❌ 否	❌ 否（需配合持久化）	✅ 是（写入本地磁盘）
生命周期	页面存活期	应用存活期	永久存储
是否支持组件共享状态	✅ 是	✅ 是	✅（需通过接口调用）
是否支持自动绑定 UI	✅ 是	✅ 是	❌ 否（需手动刷新）
用途建议	页面内部组件通信	全局设置、主题	登录信息、配置文件

---

七、使用建议

建议事项	内容说明
✅ 使用 LocalStorage 管理页面级状态，如表单输入、局部交互状态等
✅ 使用装饰器简化状态绑定，避免 props 层层传递
✅ 避免在组件之间通过 props 显式传递 LocalStorage，使用 @Entry() 注入
✅ 若需跨页面共享状态，考虑将数据提升至 AppStorage 或全局管理模块
❌ 不建议用 LocalStorage 存储敏感数据或大对象
❌ 不建议使用 LocalStorage 替代数据库或持久化方案

---

八、总结

项目	内容
技术名称	LocalStorage
所属体系	ArkTS（HarmonyOS ArkUI 状态管理）
用途	页面内组件共享状态，响应式 UI 联动
核心装饰器	@LocalStorageProp, @LocalStorageLink
生命周期	页面存活期间有效
是否持久化	否
是否响应式	是
推荐使用场景	表单共享、输入状态、临时配置等
不适用场景	大数据存储、持久化需求、用户登录凭据等