文章目录
- 一、引言
- 二、基本用法
- 2.1 初始化与设置
- 2.2 绑定到组件
- 2.3 外部修改
- 三、示例：管理用户登录状态
- 3.1 在应用入口初始化全局状态
- 3.2 登录页面组件
- 3.3 个人中心页面组件
- 四、进阶用法与注意事项
- 4.1 删除状态
- 4.2 清空与获取所有键
- 4.3 注意事项
- 五、总结
这是一个使用鸿蒙技术开发的本地原生记账应用，非常适合大家用来练手。相关源码已上传至 Github，点击此处查看项目。欢迎大家交流、指正，也欢迎提交 PR。
一、引言
在鸿蒙应用开发中，跨页面、跨组件的数据共享是一个常见需求。
想象一下，用户登录后，他的用户名需要在个人中心、订单页面、消息列表等多个地方展示。如果不使用全局状态管理，你需要把用户名一层层通过路由参数、函数参数等方式传递下去（即"Prop Drilling"），代码会变得非常冗长且难以维护。AppStorage就是为了解决这类问题而生的，它让你的组件可以随时"连接"到一个全局的数据仓库，直接读写，无需繁琐的中间传递。
AppStorage——一个应用级别的全局 UI 状态存储中心，由 UI 框架在应用启动时自动创建。它的核心作用是让不同页面、不同组件之间能够方便地共享和响应式更新数据。
二、基本用法
2.1 初始化与设置
使用AppStorage.setOrCreate(key, value)在应用启动时（如UIAbility的onCreate中）初始化一个全局状态。如果该 key 已存在，则不会覆盖；如果不存在，则创建。
onCreate(want,launchParam){// 设置一个全局的登录状态，默认为 falseAppStorage.setOrCreate('isLoggedIn',false);// 设置用户信息AppStorage.setOrCreate('userName','未登录用户');}2.2 绑定到组件
AppStorage提供了两种装饰器来将组件变量与全局状态绑定：
@StorageProp(key)：将组件变量与AppStorage中的属性进行单向绑定。组件内部修改该变量不会同步回AppStorage，适合只读场景。@StorageLink(key)：实现双向绑定。组件内部修改该变量会自动同步回AppStorage，并触发所有绑定该属性的组件更新。
@Entry@Componentstruct MyComponent{// 单向绑定：组件内修改不会影响全局@StorageProp('appTheme')theme:string='light';// 双向绑定：组件内修改会同步到全局@StorageLink('isLoggedIn')isLoggedIn:boolean=false;}2.3 外部修改
在组件外部（如非 UI 层的服务、工具类中），可以通过AppStorage.set(key, value)直接修改状态，所有绑定了该状态的组件会自动刷新。
// 在任意位置修改全局状态AppStorage.set('isLoggedIn',true);AppStorage.set('userName','张三');三、示例：管理用户登录状态
以下示例展示了如何使用AppStorage和@StorageLink实现一个全局的登录状态管理，实现跨页面的状态同步。
3.1 在应用入口初始化全局状态
// 1. 在应用入口（如 UIAbility）中初始化全局状态// 应用启动时，设置一个全局的登录状态，默认为 falseAppStorage.setOrCreate('isLoggedIn',false);3.2 登录页面组件
// 2. 在页面组件中使用 @StorageLink 进行双向绑定import{router}from'@kit.ArkUI';@Entry@Componentstruct LoginPage{// 双向绑定 AppStorage 中的 'isLoggedIn' 属性@StorageLink('isLoggedIn')isLoggedIn:boolean=false;build(){Column({space:20}){Text(`当前登录状态:${this.isLoggedIn?'已登录':'未登录'}`).fontSize(20)if(this.isLoggedIn){// 已登录状态Button('退出登录').width("80%").onClick(()=>{// 修改 @StorageLink 变量，会自动同步到 AppStoragethis.isLoggedIn=false;})}else{Button('登录').width("80%").onClick(()=>{// 修改 @StorageLink 变量，会自动同步到 AppStoragethis.isLoggedIn=true;router.push({url:"pages/ProfilePage"})})Button("个人中心").width("80%").onClick(()=>{router.push({url:"pages/ProfilePage"})})}}.width('100%').height('100%').justifyContent(FlexAlign.Center)}}3.3 个人中心页面组件
// 3. 在另一个页面中，也可以直接读取同一个全局状态@Entry@Componentstruct ProfilePage{// 同样绑定 'isLoggedIn' 属性@StorageLink('isLoggedIn')isLoggedIn:boolean=false;build(){Column(){Text(`当前登录状态:${this.isLoggedIn?'已登录':'未登录'}`).fontSize(20)}.width('100%').height('100%').justifyContent(FlexAlign.Center)}}在这个例子中，当用户在LoginPage点击“登录”按钮后，isLoggedIn变为true。这个变化会立即同步到AppStorage，并自动通知所有绑定了@StorageLink('isLoggedIn')的组件（如ProfilePage）进行重新渲染，从而实现了跨页面的状态同步。
运行效果：
四、进阶用法与注意事项
4.1 删除状态
使用AppStorage.delete(key)可以删除某个全局状态。
AppStorage.delete('userName');只要通过@StorageProp或@StorageLink引用了某个键，该键就无法被delete方法删除。这是为了防止因数据源被意外删除而导致 UI 显示异常。此时可以通过AppStorage.set更新其值。
4.2 清空与获取所有键
使用AppStorage.clear()可以清空AppStorage中的所有状态，此操作不可逆，请谨慎使用。
// 清空所有全局状态AppStorage.clear();使用AppStorage.keys()可以获取当前AppStorage中所有已存储的键名，返回一个字符串数组，便于调试或遍历处理。
// 获取所有键名constallKeys:string[]=AppStorage.keys();console.info('当前 AppStorage 中的键：',JSON.stringify(allKeys));4.3 注意事项
- 应用生命周期：
AppStorage在应用启动时创建，应用退出时销毁，适合存储应用级别的全局状态。 - 数据类型：支持基本类型（
number、string、boolean）以及Object、Array等复杂类型，但复杂类型的修改需要替换整个对象才能触发响应式更新。 - 性能考虑：不要将大量数据或频繁变化的数据全部放入
AppStorage，建议只存储跨页面共享的关键状态。 - 与 LocalStorage 的区别：
AppStorage是应用级全局单例，而LocalStorage是页面级共享存储，作用范围不同。
五、总结
AppStorage是鸿蒙 ArkTS 中非常实用的全局状态管理工具，通过@StorageProp和@StorageLink装饰器，可以轻松实现跨页面、跨组件的数据共享与响应式更新。合理使用AppStorage能够显著简化应用状态管理逻辑，提升开发效率。
