一、什么是 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 |
| 生命周期 | 页面存活期间有效 |
| 是否持久化 | 否 |
| 是否响应式 | 是 |
| 推荐使用场景 | 表单共享、输入状态、临时配置等 |
| 不适用场景 | 大数据存储、持久化需求、用户登录凭据等 |
