当前位置: 首页 > news >正文

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 会自动更新,无需手动刷新。

五、完整示例代码

✅ 场景:在主页面中管理 countusername 状态,所有子组件共享状态

// 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 与其他存储方案对比

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

七、使用建议

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

八、总结

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

相关文章:

  • Spring Boot Logback:实现定时任务日志与业务日志隔离 - Higurashi
  • 网络流 最小割 Dinic算法
  • 15.VLANIF(2025年9月30日) - 教程
  • 树莓派搭建NAS之一:安装系统
  • 新手Markdown学习
  • 马云归来,“新零售”不死 - 指南
  • RNN
  • 10.2笔记
  • Shell / Bash 学习
  • 【Linux 架构探幽:从入门到内核・系统编程开篇】基础指令与权限精讲,筑牢框架制作根基
  • 使用 Dart 进行验证码识别
  • 用 Rust 进行验证码识别
  • teset3
  • Java并发编程(5)
  • 定时任务详解
  • 华为wlan无线配置 - 教程
  • PINN训练新思路:把初始条件和边界约束嵌入网络架构,解决多目标优化难题
  • 可持久化数据结构
  • 2025.10.2——1黄
  • 图的匹配
  • Tarjan 算法
  • Mondriaans Dream题解
  • 网络流 最大流 Dinic 算法
  • 2025.10.2 测试
  • 数学章节总结
  • 软件工程_作业一
  • CF VP 记录
  • LabVIEW与PLC 汽车驻车制动自动调整 - 实践
  • 04. 布局管理
  • 关于安装博客园皮肤中有关于配置音乐播放器的补充(awescnb)