目录

状态管理概述

在前文的描述中,构建的页面主要为静态界面。如果要构建一个动态的、有交互的界面,就需要引入“状态”的概念。

图1 效果图

上面的示例中,用户与应用程序的交互触发了文本状态变更,状态变更引起了UI渲染,UI从“Hello World”变更为“Hello ArkUI”。

在声明式UI编程框架中,UI是程序状态的运行结果,用户构建了一个UI模型,其中应用的运行时状态作为参数。当参数改变时,UI作为返回结果,也将进行对应的改变。这些运行时的状态变化导致的UI重新渲染,在ArkUI中统称为状态管理机制。

自定义组件中的变量,必须使用装饰器装饰,才能成为状态变量,状态变量的改变会引起UI的渲染刷新。如果不使用状态变量,UI只能在初始化时渲染,后续将不会再刷新。下图展示了State和View(UI)之间的关系。

在阅读状态管理文档前,开发者需要了解UI范式基本语法。建议提前阅读基本语法概述、声明式UI描述、状态管理术语和自定义组件-创建自定义组件。

当前状态管理的功能仅支持在UI主线程使用,不能在子线程、Worker、TaskPool中使用。

状态管理版本介绍

当前状态管理分为V1、V2两个版本。

  1. V2是V1的增强版本,正在持续迭代优化来为开发者提供更多功能和灵活性。
  2. 对于新开发的应用,建议直接使用V2版本范式来进行开发。
  3. 对于已经使用V1的应用,如果V1的功能和性能已能满足需求,则不必立即切换到V2。

状态管理(V1)

开发者可以选择使用状态管理V1版本进行应用开发。

[h2]装饰器总览

ArkUI状态管理V1提供了多种装饰器,通过使用这些装饰器,状态变量不仅可以观察组件内的改变,还可以在不同组件层级间传递,比如父子组件、跨组件层级,也可以观察全局范围内的变化。根据状态变量的影响范围,将所有的装饰器可以大致分为:

装饰器可按数据传递形式和同步类型分为:只读的单向传递和可变更的双向传递。

图示如下,具体装饰器的介绍,可详见管理组件拥有的状态和管理应用拥有的状态。开发者可以利用这些能力来实现数据和UI的联动。

上图中,Components部分的装饰器为组件级别的状态管理,Application部分为应用的状态管理。开发者可以通过@StorageLink/@LocalStorageLink实现应用和组件状态的双向同步,通过@StorageProp/@LocalStorageProp实现应用和组件状态的单向同步。

管理组件拥有的状态,即图中Components级别的状态管理:

仅@Observed/@ObjectLink可以观察嵌套场景,其他的状态变量仅能观察第一层,详情见各个装饰器章节的“观察变化和行为表现”小节。

管理应用拥有的状态,即图中Application级别的状态管理:

[h2]其他状态管理V1功能

@Watch用于监听状态变量的变化。

$$运算符:给系统组件提供TS变量的引用,使得TS变量和系统组件的内部状态保持同步。

状态管理(V2)

为了增强状态管理V1版本的部分能力,例如深度观察、属性级更新等,ArkUI推出状态管理V2供开发者使用。

[h2]状态管理V1现状以及V2优点

状态管理V1使用代理观察数据,创建状态变量时,会同时创建一个数据代理观察者。该观察者可以感知代理变化,但无法感知实际数据变化,因此存在以下限制:

状态管理V2增强了数据的观察能力,使数据本身可观察。更改数据时,会触发相应视图的更新。相较于状态管理V1,状态管理V2有如下优点:

[h2]装饰器总览

状态管理(V2)提供了一套全新的装饰器。

[h2]状态管理V1与V2能力对比

V1能力 V2能力 说明
@Observed @ObservedV2

表明当前对象为可观察对象。但两者能力并不相同。

@Observed可观察第一层的属性,需要搭配@ObjectLink使用才能生效。

@ObservedV2本身无观察能力,仅代表当前class可被观察,如果要观察其属性,需要搭配@Trace使用。

@Track @Trace

V1装饰器@Track为精确观察,可以不依赖@Observed单独使用。不使用则无法做到类属性的精准观察。

V2@Trace装饰的属性可以被精确跟踪观察。

@Component @ComponentV2

@Component为搭配V1状态变量使用的自定义组件装饰器。

@ComponentV2为搭配V2状态变量使用的自定义组件装饰器。

@State

无外部初始化:@Local

外部初始化一次:@Param@Once

@State和@Local类似都是数据源的概念,区别是@State可以外部传入初始化,而@Local无法外部传入初始化。
@Prop @Param @Prop和@Param类似都是自定义组件参数的概念。当输入参数为复杂类型时,@Prop为深拷贝,@Param为引用。
@Link @Param@Event @Link是框架自己封装实现的双向同步,对于V2开发者可以通过@Param@Event自己实现双向同步。
@ObjectLink @Param 直接兼容,@ObjectLink需要被@Observed装饰的class的实例初始化,@Param没有此限制。
@Provide @Provider 兼容。
@Consume @Consumer 兼容。
@Watch @Monitor

@Watch用于监听V1状态变量的变化,具有监听状态变量本身和其第一层属性变化的能力。状态变量可观察到的变化会触发其@Watch监听事件。

@Monitor用于监听V2状态变量的变化,搭配@Trace使用,可有深层监听的能力。状态变量在一次事件中多次变化时,仅会以最终的结果判断是否触发@Monitor监听事件。

LocalStorage 全局@ObservedV2@Trace 兼容。
AppStorage AppStorageV2 兼容。
Environment 调用Ability接口获取系统环境变量 Environment获取环境变量能力和AppStorage耦合。在V2中可直接调用Ability接口获取系统环境变量。
PersistentStorage PersistenceV2 PersistentStorage持久化能力和AppStorage耦合,PersistenceV2持久化能力可独立使用。
自定义组件生命周期 自定义组件生命周期 均支持。aboutToAppear、onDidBuild、aboutToDisappear。
页面生命周期 页面生命周期 均支持。onPageShow、onPageHide、onBackPress。
@Reusable @ReusableV2 组件复用。包括:aboutToReuse、aboutToRecycle。
$$ !! 双向绑定。V2建议使用!!实现双向绑定。
@CustomDialog openCustomDialog接口 自定义弹窗。V2建议使用openCustomDialog实现自定义弹窗功能。
WithTheme WithTheme

主题。用于设置应用局部页面自定义主题风格。包括:onWillApplyTheme。

从API version 18开始,该接口支持在状态管理V2组件中使用。

系统预置UI组件库 系统预置UI组件库

系统预置UI组件库 。支持V1的系统预置UI组件,例如:Dialog、ProgressButton、SegmentButton。

从API version 18开始,系统预置UI组件支持在状态管理V2组件中使用,例如:DialogV2、ProgressButtonV2、SegmentButtonV2。

animateTo 部分场景不支持 当前某些场景下,在状态管理V2中使用animateTo动画,会产生异常效果,详见:在状态管理V2中使用animateTo动画效果异常。

有关V1向V2的迁移可参考迁移指导,有关V1与V2的混用可参考状态管理V1和V2混用场景。