玩转HarmonyOS NEXT之AppStorage应用全局UI状态存储

概述

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

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

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

@StorageProp

如果要建立AppStorage和自定义组件的联系,需要使用@StorageProp和@StorageLink装饰器。使用@StorageProp(key)/@StorageLink(key)装饰组件内的变量,key标识了AppStorage的属性。

装饰器使用规则说明

@StorageProp变量装饰器 说明
装饰器参数 key:常量字符串,必填(字符串需要有引号)。
允许装饰的变量类型 Object、class、string、number、boolean、enum类型,以及这些类型的数组。
同步类型 单向同步 :从AppStorage的对应属性到组件的状态变量。 组件本地的修改是允许的,但是AppStorage中给定的属性一旦发生变化,将覆盖本地的修改。
被装饰变量的初始值 必须指定,如果AppStorage实例中不存在属性,则用该初始值初始化该属性,并存入AppStorage中。

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

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

监听变化和行为表现

监听变化

  • 当装饰的数据类型为boolean、string、number类型时,可以监听到数值的变化。
  • 当装饰的数据类型为class或者Object时,可以监听到对象整体赋值 和对象属性变化。
  • 当装饰的对象是array时,可以监听到数组添加、删除、更新数组单元的变化。
  • 当装饰的对象是Date时,可以监听到Date整体的赋值,同时可通过调用Date的接口setFullYear, setMonth, setDate, setHours, setMinutes, setSeconds, setMilliseconds, setTime, setUTCFullYear, setUTCMonth, setUTCDate, setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds更新Date的属性。
  • 当装饰的变量是Map时,可以监听到Map整体的赋值 ,同时可通过调用Map的接口set, clear, delete 更新Map的值。
  • 当装饰的变量是Set时,可以观察到Set整体的赋值 ,同时可通过调用Set的接口add, clear, delete 更新Set的值。

框架行为

  • 当@StorageProp(key)装饰的数值改变被监听到时,修改不会被同步回·AppStorage`对应属性键值key的属性中。
  • 当前@StorageProp(key)单向绑定的数据会被修改,即仅限于当前组件的私有成员变量改变,其他的绑定该key的数据不会同步改变。
  • 当@StorageProp(key)装饰的数据本身是状态变量,它的改变虽然不会同步回AppStorage中,但是会引起所属的自定义组件的重新渲染。
  • 当AppStorage中key对应的属性发生改变时,会同步给所有@StorageProp(key)装饰的数据,@StorageProp(key)本地的修改将被覆盖。

@StorageLink(key)是和AppStorage中key对应的属性建立双向数据同步:

  • 本地修改发生,该修改会被写回AppStorage中;
  • AppStorage中的修改发生后,该修改会被同步到所有绑定AppStorage对应key的属性上,包括单向(@StorageProp和通过Prop创建的单向绑定变量)、双向(@StorageLink和通过Link创建的双向绑定变量)变量和其他实例(比如PersistentStorage)。

装饰器使用规则说明

@StorageLink变量装饰器 说明
装饰器参数 key:常量字符串,必填(字符串需要有引号)。
允许装饰的变量类型 Object、class、string、number、boolean、enum类型,以及这些类型的数组。
同步类型 双向同步:从AppStorage的对应属性到自定义组件,从自定义组件到AppStorage对应属性。
被装饰变量的初始值 必须指定,如果AppStorage实例中不存在属性,则用该初始值初始化该属性,并存入AppStorage中。

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

传递/访问 说明
从父节点初始化和更新 禁止。
初始化子节点 支持,可用于初始化常规变量、@State、@Link、@Prop、@Provide。
是否支持组件外访问 否

监听变化和行为表现

监听变化

  • 当装饰的数据类型为boolean、string、number类型时,可以监听到数值的变化。
  • 当装饰的数据类型为class或者Object时,可以监听到对象整体赋值 和对象属性变化。
  • 当装饰的对象是array时,可以监听到数组添加、删除、更新数组单元的变化。
  • 当装饰的对象是Date时,可以监听到Date整体的赋值,同时可通过调用Date的接口setFullYear, setMonth, setDate, setHours, setMinutes, setSeconds, setMilliseconds, setTime, setUTCFullYear, setUTCMonth, setUTCDate, setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds更新Date的属性。
  • 当装饰的变量是Map时,可以监听到Map整体的赋值 ,同时可通过调用Map的接口set, clear, delete 更新Map的值。
  • 当装饰的变量是Set时,可以观察到Set整体的赋值 ,同时可通过调用Set的接口add, clear, delete 更新Set的值。

框架行为

  • 当@StorageProp(key)装饰的数值改变被监听到时,修改将被同步回·AppStorage`对应属性键值key的属性中。
  • AppStorage中属性键值key对应的数据一旦改变,属性键值key绑定的所有的数据(包括双向@StorageLink和单向@StorageProp)都将同步修改。
  • 当@StorageLink(key)装饰的数据本身是状态变量,它的改变不仅仅会同步回AppStorage中,还会引起所属的自定义组件的重新渲染。
相关推荐
huang_xiaoen18 小时前
鸿蒙手机远程控制电脑哪个好用?2026鸿蒙远控软件横测推荐
华为·harmonyos·远程工作·远程工具·远程办公
爱写Bug的浮游2 天前
初识仓颉:5 分钟看懂核心语法
harmonyos·编程语言
程序猿追3 天前
鸿蒙 PC 的 Ionic 工单有两个错误,按下生成后光标该去哪儿
华为·harmonyos
KevinChaos3 天前
随手备忘录手记 04|HarmonyOS 7.0新特性实验:物品图鉴的加载逻辑
华为·harmonyos
Sirius_Ji3 天前
从硬解基座到字幕与滤镜链:ffmpeg-for-HarmonyOS v0.3.2
harmonyos
用户86194177207413 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
微信·harmonyos
码间留白3 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
uni-app·harmonyos·鸿蒙·uts插件·微信商家转账
GitCode官方4 天前
开源鸿蒙跨平台直播|AI 时代,用 cj-tauri 开发鸿蒙 PC 应用
人工智能·华为·harmonyos·atomgit
程序猿追4 天前
鸿蒙 PC 用 Tauri 做本地查找,怎样让慢请求给新请求让路
华为·状态模式·harmonyos
程序猿追4 天前
鸿蒙 PC 用 Ionic 做巡检目录,缩窄窗口后草稿还在吗
华为·harmonyos