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