OpenHarmony应用全局的UI状态存储：AppStorage

最新推荐文章于 2025-07-10 09:17:27 发布

OpenHarmony_小贾

最新推荐文章于 2025-07-10 09:17:27 发布

阅读量1k

点赞数 22

CC 4.0 BY-SA版权

分类专栏： OpenHarmony 鸿蒙开发 HarmonyOS 文章标签： ui 鸿蒙开发 OpenHarmony 移动开发前端 arkui

本文链接：https://blog.youkuaiyun.com/maniuT/article/details/139441322

AppStorage是应用全局的UI状态存储，是和应用的进程绑定的，由UI框架在应用程序启动时创建，为应用程序UI状态属性提供中央存储。

和AppStorage不同的是，LocalStorage是页面级的，通常应用于页面内的数据共享。而AppStorage是应用级的全局状态共享，还相当于整个应用的“中枢”，持久化数据PersistentStorage 和环境变量Environment 都是通过AppStorage中转，才可以和UI交互。

本文仅介绍AppStorage使用场景和相关的装饰器：@StorageProp和@StorageLink。

概述

AppStorage是在应用启动的时候会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorage将在应用运行过程保留其属性。属性通过唯一的键字符串值访问。

AppStorage可以和UI组件同步，且可以在应用业务逻辑中被访问。

AppStorage中的属性可以被双向同步，数据可以是存在于本地或远程设备上，并具有不同的功能，比如数据持久化（详见 PersistentStorage ）。这些数据是通过业务逻辑中实现，与UI解耦，如果希望这些数据在UI中使用，需要用到 @StorageProp 和 @StorageLink 。

@StorageProp

在上文中已经提到，如果要建立AppStorage和自定义组件的联系，需要使用@StorageProp和@StorageLink装饰器。使用@StorageProp(key)/@StorageLink(key)装饰组件内的变量，key标识了AppStorage的属性。

当自定义组件初始化的时候，会使用AppStorage中对应key的属性值将@StorageProp(key)/@StorageLink(key)装饰的变量初始化。由于应用逻辑的差异，无法确认是否在组件初始化之前向AppStorage实例中存入了对应的属性，所以AppStorage不一定存在key对应的属性，因此@StorageProp(key)/@StorageLink(key)装饰的变量进行本地初始化是必要的。

@StorageProp(key)是和AppStorage中key对应的属性建立单向数据同步，允许本地改变，但是对于@StorageProp，本地的修改永远不会同步回AppStorage中，相反，如果AppStorage给定key的属性发生改变，改变会被同步给@StorageProp，并覆盖掉本地的修改。

装饰器使用规则说明

@StorageProp变量装饰器	说明
装饰器参数	key：常量字符串，必填（字符串需要有引号）。
允许装饰的变量类型	Object class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考观察变化和行为表现。类型必须被指定，建议和AppStorage中对应属性类型相同，否则会发生类型隐式转换，从而导致应用行为异常。不支持any，不允许使用undefined和null。
同步类型	单向同步：从AppStorage的对应属性到组件的状态变量。组件本地的修改是允许的，但是AppStorage中给定的属性一旦发生变化，将覆盖本地的修改。
被装饰变量的初始值	必须指定，如果AppStorage实例中不存在属性，则作为初始化默认值，并存入AppStorage中。

变量的传递/访问规则说明

传递/访问	说明
从父节点初始化和更新	禁止，@StorageProp不支持从父节点初始化，只能AppStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化
初始化子节点	支持，可用于初始化@State、@Link、@Prop、@Provide。
是否支持组件外访问	否。