【HarmonyOS实战】 AppStorage：应用级全局状态共享怎么做？

文章目录前言一、HarmonyOS 的状态管理层级二、AppStorage 的基本操作2.1 写入数据在 EntryAbility 里2.2 在组件中读取StorageProp2.3 双向同步StorageLink三、为什么用 AppStorage 而不是普通全局变量四、数据流向图五、完整使用示例六、AppStorage 的注意事项6.1 Key 命名要规范6.2 值类型要一致6.3 App 重启后数据丢失七、State vs StorageProp 怎么选总结前言上一篇我们看到EntryAbility把状态栏高度存进了AppStorage然后GasStationPage用StorageProp读出来。不传参、不用全局变量两个毫不相干的地方就完成了数据共享——这就是AppStorage的魔力。这篇文章把 HarmonyOS 的状态管理体系从头讲清楚。项目预览一、HarmonyOS 的状态管理层级HarmonyOS 的状态管理分三个层级AppStorage应用级 ↕ 双向同步 └─ StorageProp / StorageLink页面/组件访问 AppStorage PersistentStorage持久化 └─ 数据写入磁盘App 重启后保留 LocalStorage页面级 └─ 页面内或页面树内共享比 AppStorage 范围小存储类型作用范围是否持久化典型用途State单个组件内部否组件自身的 UI 状态LocalStorage页面内部或子树否同一页面的多组件共享AppStorage整个应用全局否App关闭丢失全局配置、运行时数据PersistentStorage整个应用是写入磁盘用户设置、登录状态二、AppStorage 的基本操作2.1 写入数据在 EntryAbility 里// AppStorage.setOrCreate(key, defaultValue)// 如果 key 不存在创建并设置值// 如果 key 已存在更新值AppStorage.setOrCreate(bottomRectHeight,bottomRectHeight);AppStorage.setOrCreate(topRectHeight,topRectHeight);也可以用set只更新key 必须已存在AppStorage.set(bottomRectHeight,100);或者get读取letheight:number|undefinedAppStorage.getnumber(bottomRectHeight);2.2 在组件中读取StorageProp// GasStationPage.etsComponentstruct GasStationPage{// 从 AppStorage 读取 bottomRectHeight 的值// 如果 AppStorage 里的值变了这里也会自动更新StorageProp(bottomRectHeight)bottomRectHeight:number0;// 0 是默认值AppStorage里还没有值时使用StorageProp(topRectHeight)topRectHeight:number0;}StorageProp是单向同步AppStorage 变化 → 组件属性更新 → UI 刷新。但组件内部修改bottomRectHeight不会反向写回 AppStorage。2.3 双向同步StorageLink如果需要双向同步组件修改也写回 AppStorage用StorageLinkComponentstruct SomeComponent{StorageLink(userTheme)currentTheme:stringlight;// 修改这个会同步到 AppStorage}项目里用StorageProp而不是StorageLink因为安全区域高度只由系统决定不应该被组件随意修改单向读取更安全。三、为什么用 AppStorage 而不是普通全局变量你可能会想直接定义一个全局变量不香吗// 直接定义全局变量不推荐letglobalTopHeight:number0;letglobalBottomHeight:number0;全局变量的问题改了变量UI 不刷新——普通变量不是响应式的改值后还需要手动触发 UI 更新线程安全问题——多个地方同时修改可能出问题没有类型保护——容易写错 key或者类型不对AppStorage的优势响应式——值变化时StorageProp/StorageLink修饰的属性自动更新UI 自动重渲类型安全——有泛型支持AppStorage.getnumber(key)统一管理——所有全局状态都在一个地方四、数据流向图EntryAbility │ ├─ 读取状态栏高度 ├─ AppStorage.setOrCreate(topRectHeight, value) └─ AppStorage.setOrCreate(bottomRectHeight, value) │ │ AppStorage 作为中间层 │ ├─── MainPage │ StorageProp(topRectHeight) topRectHeight: number 0 │ StorageProp(bottomRectHeight) bottomRectHeight: number 0 │ └─── GasStationPage StorageProp(topRectHeight) topRectHeight: number 0 StorageProp(bottomRectHeight) bottomRectHeight: number 0当系统安全区域变化时avoidAreaChange事件EntryAbility更新AppStorage所有用StorageProp绑定了这个 key 的组件都会收到通知自动刷新 UI。整个流程不需要手动传参。五、完整使用示例假设你要在应用里共享用户选择的主题色// 1. 在 EntryAbility.onCreate() 里初始化onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{AppStorage.setOrCreate(primaryColor,#007AFF);// 初始化主题色}// 2. 在页面A里读取并显示Componentstruct PageA{StorageProp(primaryColor)primaryColor:string#007AFF;build(){Button(确认).backgroundColor(this.primaryColor)// 使用主题色}}// 3. 在设置页里修改双向同步Componentstruct SettingsPage{StorageLink(primaryColor)// 用 StorageLink 才能写回primaryColor:string#007AFF;build(){Button(切换蓝色).onClick((){this.primaryColor#007AFF;// 修改后自动同步到 AppStorage})Button(切换红色).onClick((){this.primaryColor#FF3B30;// PageA 的颜色也会自动更新})}}六、AppStorage 的注意事项6.1 Key 命名要规范AppStorage 是全局的如果不同模块用了同名的 key会互相覆盖// 不好的做法——容易冲突AppStorage.setOrCreate(height,100);// 推荐——带模块前缀AppStorage.setOrCreate(window_topRectHeight,100);AppStorage.setOrCreate(window_bottomRectHeight,60);6.2 值类型要一致// 设置时是 numberAppStorage.setOrCreate(topRectHeight,100);// 读取时类型要匹配StorageProp(topRectHeight)topRectHeight:number0;// ✅ 正确// 如果类型不匹配行为未定义StorageProp(topRectHeight)topRectHeight:string0;// ⚠️ 危险6.3 App 重启后数据丢失AppStorage的数据在内存里App 关闭后会消失。这也是为什么每次启动都要重新获取安全区域高度。如果需要持久化改用PersistentStorage// 持久化到磁盘App重启后依然有值PersistentStorage.persistProp(userSettings,{});七、State vs StorageProp 怎么选场景用什么只在当前组件用的数据State需要在多个页面/组件共享的数据AppStorageStorageProp父子组件传数据只读Prop父子组件传数据双向改Link需要持久化的数据PersistentStorageStorageProp总结AppStorage是 HarmonyOS 的全局响应式仓库写入AppStorage.setOrCreate(key, value)推荐或AppStorage.set(key, value)读取StorageProp(key)单向同步StorageLink(key)双向同步特点响应式值变化自动触发 UI 刷新无需手动传参局限App 关闭后数据消失持久化需用PersistentStorage下一篇讲Navigation 路由系统——从主页到地图页的页面跳转是怎么实现的。