本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、AppStorage 概述

AppStorage 是鸿蒙（HarmonyOS）应用框架中一个与应用进程绑定的全局单例UI状态存储中心。

  • 定位：作为应用的“中枢”，它是应用级全局状态共享的解决方案。
  • 创建时机：由UI框架在应用启动时自动创建，并将UI状态数据存储于运行内存中。
  • 核心价值：为开发者提供跨UIAbility的大范围UI状态数据共享能力。
  • 桥梁作用：它是PersistentStorage（持久化存储）和Environment（环境变量）与UI交互的中转桥梁。

二、核心特性

  1. 单例模式：AppStorage是在应用启动时创建的单例，在整个应用生命周期内都存在。
  2. 键值对存储：所有属性都通过唯一的字符串类型属性名（key） 来访问。
  3. UI与逻辑连接：存储的状态数据既可以与UI组件同步，也可以在应用的业务逻辑中被访问和操作，实现了UI与逻辑的解耦。
  4. 线程支持：支持在应用的主线程内多个UIAbility实例间共享UI状态数据。

三、与装饰器的关系

为了在UI组件中使用AppStorage中存储的状态，ArkUI提供了两个装饰器：

1. @StorageProp (单向同步)

项目 说明
装饰器参数 常量字符串（key），必填。注意：使用null和undefined作为key会被隐式转换为字符串，不建议这种用法。
同步类型 单向同步。AppStorage中对应属性的更改会同步到@StorageProp装饰的变量，并覆盖本地的修改；但组件内对该变量的修改不会同步回AppStorage。
允许装饰的变量类型 Object、class、string、number、boolean、enum类型及其数组。API Version 12及以上额外支持Map、Set、Date、undefined、null类型以及这些类型的联合类型（如`string
被装饰变量的初始值 必须指定。如果AppStorage中不存在对应的key，则会用此初始值在AppStorage中创建并初始化该属性。

备注：不支持装饰Function类型。

2. @StorageLink (双向同步)

项目 说明
装饰器参数 常量字符串（key），必填。
同步类型 双向同步。AppStorage中属性的更改会自动同步到所有@StorageLink装饰的变量；反之，任何@StorageLink变量的更改也会立即更新AppStorage中的对应属性，并进而同步到所有绑定此属性的其他组件或逻辑。
允许装饰的变量类型 与@StorageProp支持的类型完全相同。

备注：不支持装饰Function类型。

对比：

  • @StorageProp：类似于“只读”镜像，数据从AppStorage流向组件，组件内部的修改是临时的，会被AppStorage的更新覆盖。
  • @StorageLink：类似于“双向绑定”，组件和AppStorage的任何一方修改都会立即同步到另一方。

四、常用的API 

AppStorage提供了一套完整的API接口，允许开发者在自定义组件之外（例如在业务逻辑或服务中）手动对AppStorage中的属性进行增、删、改、查操作。

  • setOrCreate(): 设置或创建属性。
  • set(): 设置属性值。
  • get(): 获取属性值。
  • has(): 判断属性是否存在。
  • delete(): 删除属性。
  • clear(): 清空所有属性。
  • keys(): 获取所有属性的键名。
注意事项：setOrCreate 与 set 的行为差异：
  • setOrCreate(key: string, value: any): 如果设置的value与AppStorage中当前该key对应的值相同，则不会触发任何属性变更通知。这意味着，依赖此属性变化的UI组件（使用@StorageLink或@StorageProp）将不会重新渲染。
  • set(key: string, value: any): 此接口的行为应与setOrCreate类似，但具体细节需参考最新的官方API文档。通常，为了确保逻辑清晰，应特别注意值未实际变化时可能不会通知的情况。

建议：在调用setOrCreate或set接口更新值之前，可以先使用get接口获取当前值进行比较，如果值确实发生了变化，再调用设置接口，以避免不必要的渲染开销。

五、其他

  1. 与 PersistentStorage 的关系： AppStorage可以与PersistentStorage配合，将指定的属性持久化到本地磁盘。这意味着这些数据在应用重启后依然存在，实现了数据的持久化。

  2. 与 LocalStorage 的关系：

    • 范围不同：LocalStorage是页面级的存储，用于单个页面或多个页面间（通常在同一个UIAbility内）的状态共享。而AppStorage是应用级的存储，范围更大。
    • 生命周期不同：LocalStorage的生命周期由使用它的组件树决定，可能被回收。而AppStorage的生命周期与应用进程一致。

六、使用场景

  1. 跨UIAbility的主题/语言设置：例如，应用的主题色、语言偏好等全局设置可以存储在AppStorage中，所有UIAbility中的组件都可以通过@StorageLink或@StorageProp实时响应和更改这些设置。
  2. 用户登录状态管理：用户的登录Token、基本信息等全局状态可以放在AppStorage中，方便任何页面或业务逻辑访问和监听其变化。
  3. 应用全局的临时状态：例如一个全局的弹窗开关、网络状态标识等。

七、注意事项

  1. 键的命名：使用有明确意义的字符串作为key，避免使用null或undefined。
  2. 类型安全：设置和获取属性时，需确保值的类型与预期一致。
  3. 性能考虑：虽然AppStorage访问很快（内存操作），但应避免存储过大的数据对象，以免占用过多内存。
  4. 配合API使用：在非UI组件的业务逻辑中，记得使用AppStorage的API来进行操作。
  5. setOrCreate的注意事项：如前述，使用setOrCreate接口时，如果新值与旧值相同，则不会通知@StorageLink/@StorageProp，UI不会更新。务必注意这一行为。

八、总结

AppStorage 是鸿蒙应用开发中实现全局状态共享的核心工具。它通过内存存储提供了高效的数据访问，并通过 @StorageProp 和 @StorageLink 装饰器建立了UI与数据之间的便捷同步机制。

它与PersistentStorage结合可实现数据持久化，与LocalStorage形成页面级到应用级的完整状态管理层次。正确使用AppStorage可以有效管理应用的全局UI状态，简化跨组件、跨页面的数据传递和同步问题。

# harmonyos # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

HarmonyOS动态照片，简易环境助力高效开发

HarmonyOS动态照片的拍摄采用分段式拍照统一出图流程，旨在让相机类应用的用户体验与系统相机一致，通过统一拍照流程提升拍照体验。在图库和三方应用访问新拍摄动态照片的场景中，媒体库会高优先级触发动态照片的二段式任务。媒体库为应用提供了统一的动态照片访问接口requestMovingPhoto和MovingPhoto对象，支持应用读取动态照片。HarmonyOS允许用户在设备上查看和处理动态照片，

avatar HarmonyOS开发者社区

【HarmonyOS-媒体技术-Media Kit】HarmonyOS 音视频开发全栈解析

Media Kit 让开发者可以调用系统的音视频能力，涵盖播放、录制、录屏、元数据提取与转码六大核心功能模块，支撑系统应用与第三方应用在视频播放、内容创作、教学录屏、直播互动等典型场景下的音视频处理需求。AVMetadataExtractor 用于从音视频资源中提取元数据，如标题、艺术家、专辑、时长等信息，从视频中提取指定时间点的画面，生成缩略图。AVRecorder 可实现音频、视频、音视频混合

avatar HarmonyOS开发者社区

CodeGenie AI辅助鸿蒙应用调优，三类高频性能问题定位不再头疼

体验智慧调优最新功能。AI会列出某类较大的实例对象及各自大小，继续选中某个实例对象进行分析，AI会给出某实例对象的完整引用链（到GC Root），并给出问题疑似原因。配备了强大的专业工具库和案例库，助力AI在海量运行数据中快速聚焦关键指标与异常模式，明确诊断问题根源，为开发者提供精准的问题解释与优化建议。的文档查询、数据检索等基础重复工作，解放开发者创造力，助力开发者一键解锁流畅、高性能的鸿蒙应用

avatar HarmonyOS开发者社区