1# 状态管理概述 2 3 4在前文的描述中，我们构建的页面多为静态界面。如果希望构建一个动态的、有交互的界面，就需要引入“状态”的概念。 5 6 7 **图1** 效果图 8 9 10 11 12上面的示例中，用户与应用程序的交互触发了文本状态变更，状态变更引起了UI渲染，UI从“Hello World”变更为“Hello ArkUI”。 13 14 15在声明式UI编程框架中，UI是程序状态的运行结果，用户构建了一个UI模型，其中应用的运行时的状态是参数。当参数改变时，UI作为返回结果，也将进行对应的改变。这些运行时的状态变化所带来的UI的重新渲染，在ArkUI中统称为状态管理机制。 16 17 18自定义组件拥有变量，变量必须被装饰器装饰才可以成为状态变量，状态变量的改变会引起UI的渲染刷新。如果不使用状态变量，UI只能在初始化时渲染，后续将不会再刷新。 下图展示了State和View（UI）之间的关系。 19 20 21 22 23 24- View(UI)：UI渲染，指将build方法内的UI描述和\@Builder装饰的方法内的UI描述映射到界面。 25 26- State：状态，指驱动UI更新的数据。用户通过触发组件的事件方法，改变状态数据。状态数据的改变，引起UI的重新渲染。 27 28 29## 基本概念 30 31- 状态变量：被状态装饰器装饰的变量，状态变量值的改变会引起UI的渲染更新。示例：@State num: number = 1,其中，@State是状态装饰器，num是状态变量。 32 33- 常规变量：没有被状态装饰器装饰的变量，通常应用于辅助计算。它的改变永远不会引起UI的刷新。以下示例中increaseBy变量为常规变量。 34 35- 数据源/同步源：状态变量的原始来源，可以同步给不同的状态数据。通常意义为父组件传给子组件的数据。以下示例中数据源为count: 1。 36 37- 命名参数机制：父组件通过指定参数传递给子组件的状态变量，为父子传递同步参数的主要手段。示例：CompA({ aProp: this.aProp })。 38 39- 从父组件初始化：父组件使用命名参数机制，将指定参数传递给子组件。子组件初始化的默认值在有父组件传值的情况下，会被覆盖。示例： 40 41 ```ts 42 @Component 43 struct MyComponent { 44 @State count: number = 0; 45 private increaseBy: number = 1; 46 47 build() { 48 } 49 } 50 51 @Entry 52 @Component 53 struct Parent { 54 build() { 55 Column() { 56 // 从父组件初始化，覆盖本地定义的默认值 57 MyComponent({ count: 1, increaseBy: 2 }) 58 } 59 } 60 } 61 ``` 62 63- 初始化子组件：父组件中状态变量可以传递给子组件，初始化子组件对应的状态变量。示例同上。 64 65- 本地初始化：在变量声明的时候赋值，作为变量的默认值。示例：\@State count: number = 0。 66 67## 状态管理（V1稳定版） 68 69开发者可以使用当前比较完整的状态管理V1版本进行应用开发。 70 71### 装饰器总览 72 73ArkUI状态管理V1提供了多种装饰器，通过使用这些装饰器，状态变量不仅可以观察在组件内的改变，还可以在不同组件层级间传递，比如父子组件、跨组件层级，也可以观察全局范围内的变化。根据状态变量的影响范围，将所有的装饰器可以大致分为： 74 75 76- 管理组件拥有状态的装饰器：组件级别的状态管理，可以观察组件内变化，和不同组件层级的变化，但需要唯一观察同一个组件树上，即同一个页面内。 77 78- 管理应用拥有状态的装饰器：应用级别的状态管理，可以观察不同页面，甚至不同UIAbility的状态变化，是应用内全局的状态管理。 79 80 81从数据的传递形式和同步类型层面看，装饰器也可分为： 82 83 84- 只读的单向传递； 85 86- 可变更的双向传递。 87 88 89图示如下，具体装饰器的介绍，可详见[管理组件拥有的状态](arkts-state.md)和[管理应用拥有的状态](arkts-application-state-management-overview.md)。开发者可以灵活地利用这些能力来实现数据和UI的联动。 90 91 92 93 94 95上图中，Components部分的装饰器为组件级别的状态管理，Application部分为应用的状态管理。开发者可以通过[@StorageLink](arkts-appstorage.md#storagelink)/[@LocalStorageLink](arkts-localstorage.md#localstoragelink)实现应用和组件状态的双向同步，通过[@StorageProp](arkts-appstorage.md#storageprop)/[@LocalStorageProp](arkts-localstorage.md#localstorageprop)实现应用和组件状态的单向同步。 96 97 98[管理组件拥有的状态](arkts-state.md)，即图中Components级别的状态管理： 99 100 101- [\@State](arkts-state.md)：\@State装饰的变量拥有其所属组件的状态，可以作为其子组件单向和双向同步的数据源。当其数值改变时，会引起相关组件的渲染刷新。 102 103- [\@Prop](arkts-prop.md)：\@Prop装饰的变量可以和父组件建立单向同步关系，\@Prop装饰的变量是可变的，但修改不会同步回父组件。 104 105- [\@Link](arkts-link.md)：\@Link装饰的变量可以和父组件建立双向同步关系，子组件中\@Link装饰变量的修改会同步给父组件中建立双向数据绑定的数据源，父组件的更新也会同步给\@Link装饰的变量。 106 107- [\@Provide/\@Consume](arkts-provide-and-consume.md)：\@Provide/\@Consume装饰的变量用于跨组件层级（多层组件）同步状态变量，可以不需要通过参数命名机制传递，通过alias（别名）或者属性名绑定。 108 109- [\@Observed](arkts-observed-and-objectlink.md)：\@Observed装饰class，需要观察多层嵌套场景的class需要被\@Observed装饰。单独使用\@Observed没有任何作用，需要和\@ObjectLink、\@Prop联用。 110 111- [\@ObjectLink](arkts-observed-and-objectlink.md)：\@ObjectLink装饰的变量接收\@Observed装饰的class的实例，应用于观察多层嵌套场景，和父组件的数据源构建双向同步。 112 113> **说明：** 114> 115> 仅[\@Observed/\@ObjectLink](arkts-observed-and-objectlink.md)可以观察嵌套场景，其他的状态变量仅能观察第一层，详情见各个装饰器章节的“观察变化和行为表现”小节。 116 117 118[管理应用拥有的状态](arkts-application-state-management-overview.md)，即图中Application级别的状态管理： 119 120 121- [AppStorage](arkts-appstorage.md)是应用程序中的一个特殊的单例[LocalStorage](arkts-localstorage.md)对象，是应用级的数据库，和进程绑定，通过[@StorageProp](arkts-appstorage.md#storageprop)和[@StorageLink](arkts-appstorage.md#storagelink)装饰器可以和组件联动。 122 123- AppStorage是应用状态的“中枢”，将需要与组件（UI）交互的数据存入AppStorage，比如持久化数据[PersistentStorage](arkts-persiststorage.md)和环境变量[Environment](arkts-environment.md)。UI再通过AppStorage提供的装饰器或者API接口，访问这些数据。 124 125- 框架还提供了LocalStorage，AppStorage是LocalStorage特殊的单例。LocalStorage是应用程序声明的应用状态的内存“数据库”，通常用于页面级的状态共享，通过[@LocalStorageProp](arkts-localstorage.md#localstorageprop)和[@LocalStorageLink](arkts-localstorage.md#localstoragelink)装饰器可以和UI联动。 126 127 128### 其他状态管理V1功能 129 130[\@Watch](arkts-watch.md)用于监听状态变量的变化。 131 132 133[$$运算符](arkts-two-way-sync.md)：给内置组件提供TS变量的引用，使得TS变量和内置组件的内部状态保持同步。 134 135### 相关实例 136 137针对页面状态管理，有以下相关实例可供参考： 138 139- [状态管理（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-5.0.1-Release/code/UI/ArkTsComponentCollection/StateManagement) 140 141- [目标管理（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/TargetManagement) 142 143## 状态管理（V2试用版） 144 145为了增强状态管理V1版本的部分能力，例如深度观察、属性级更新等，ArkUI推出状态管理（V2试用版）供开发者体验试用。 146 147>**说明：** 148> 149>当前状态管理（V2试用版）仍在逐步开发中，完整功能敬请期待。 150 151### 状态管理V1现状以及V2优点 152 153状态管理V1使用代理观察数据，当创建一个状态变量时，同时也创建了一个数据代理观察者。该观察者可感知代理变化，但无法感知实际数据变化，因此在使用上有如下限制： 154 155- 状态变量不能独立于UI存在，同一个数据被多个视图代理时，在其中一个视图的更改不会通知其他视图更新。 156- 只能感知对象属性第一层的变化，无法做到深度观测和深度监听。 157- 在更改对象中属性以及更改数组中元素的场景下存在冗余更新的问题。 158- 装饰器间配合使用限制多，不易用。组件中没有明确状态变量的输入与输出，不利于组件化。 159 160状态管理V2将观察能力增强到数据本身，数据本身就是可观察的，更改数据会触发相应的视图的更新。相较于状态管理V1，状态管理V2有如下优点： 161 162- 状态变量独立于UI，更改数据会触发相应视图的更新。 163 164- 支持对象的深度观测和深度监听，且深度观测机制不影响观测性能。 165 166- 支持对象中属性级精准更新及数组中元素的最小化更新。 167 168- 装饰器易用性高、拓展性强，在组件中明确输入与输出，有利于组件化。 169 170 171 172### 装饰器总览 173 174状态管理（V2试用版）提供了一套全新的装饰器。 175 176- [\@ObservedV2](arkts-new-observedV2-and-trace.md)：\@ObservedV2装饰器装饰class，使得被装饰的class具有深度监听的能力。\@ObservedV2和\@Trace配合使用可以使class中的属性具有深度观测的能力。 177 178- [\@Trace](arkts-new-observedV2-and-trace.md)：\@Trace装饰器装饰被\@ObservedV2装饰的class中的属性，被装饰的属性具有深度观测的能力。 179 180- [\@ComponentV2](arkts-new-componentV2.md)：使用\@ComponentV2装饰的struct中能使用新的装饰器。例如：\@Local、\@Param、\@Event、\@Once、\@Monitor、\@Provider、\@Consumer。 181 182- [\@Local](arkts-new-local.md)：\@Local装饰的变量为组件内部状态，无法从外部初始化。 183 184- [\@Param](arkts-new-param.md)：\@Param装饰的变量作为组件的输入，可以接受从外部传入初始化并同步。 185 186- [\@Once](arkts-new-once.md)：\@Once装饰的变量仅初始化时同步一次，需要与\@Param一起使用。 187 188- [\@Event](arkts-new-event.md)：\@Event装饰方法类型，作为组件输出，可以通过该方法影响父组件中变量。 189 190- [\@Monitor](arkts-new-monitor.md)：\@Monitor装饰器用于\@ComponentV2装饰的自定义组件或\@ObservedV2装饰的类中，能够对状态变量进行深度监听。 191 192- [\@Provider和\@Consumer](arkts-new-Provider-and-Consumer.md)：用于跨组件层级双向同步。 193 194- [\@Computed](arkts-new-Computed.md)：计算属性，在被计算的值变化的时候，只会计算一次。主要应用于解决UI多次重用该属性从而重复计算导致的性能问题。 195 196- [!!语法](arkts-new-binding.md)：双向绑定语法糖。 197 198### 使用限制 199 200由于状态管理V2采用了和状态管理V1不同的实现，因此不能将状态管理框架V2和状态管理V1混合使用，这项限制包括如下场景： 201 202- 将V2版本的装饰器装饰的变量传递给V1版本装饰器装饰的变量。 203- 将V1版本装饰器[\@Observed](arkts-observed-and-objectlink.md)、[\@Track](arkts-track.md)与V2版本装饰器[\@ObservedV2](arkts-new-observedV2-and-trace.md)、[\@Trace](arkts-new-observedV2-and-trace.md)混合使用。 204- 将V1版本装饰器\@State、\@Prop、\@Link、\@ObjectLink、\@Provide、\@Consume、\@StorageLink、\@StorageProp、\@LocalStorageLink、\@LocalStorageProp、\@Watch等在\@ComponentV2装饰的自定义组件中使用。 205- 将V2版本装饰器\@Local、\@Param、\@Once、\@Event、\@Monitor、\@Provider、\@Consumer在\@Component装饰的自定义组件中使用。 206- 将\@Component与\@ComponentV2同时使用。 207- 在\@Component装饰的自定义组件中通过\@State、\@Prop、\@Link、\@Provide、\@Consume、\@StorageLink、\@StorageProp、\@LocalStorageLink、\@LocalStorageProp装饰的变量并且该变量的类型为\@ObservedV2装饰的类。 208- 在\@ComponentV2装饰的自定义组件中通过\@Param、\@Local、\@Event、\@Provider()、\@Consumer()装饰的变量并且该变量的类型为\@Observed装饰的类。 209 210将V2装饰器与V1装饰器混合使用，会出现未定义行为，表现为冗余刷新、失去深度观测能力、失去自身属性观测能力、失去属性级更新能力等。因此，不能将状态管理V2与状态管理V1在以上提到的场景混合使用。 211 212
