鸿蒙 UI 语法摘要2

@ComponentV2

@ComponentV2装饰的struct为V2自定义组件，可以使用状态管理V2版本装饰器的能力。

V2状态管理装饰器	装饰器说明
@ComponentV2	创建自定义组件。
@Local	组件内部状态。
@Param	组件外部输入。
@Once	初始化同步一次。
@Event	规范组件输出。
@Provider	与后代状态双向同步。
@Consumer	与祖先状态双向同步。
@Monitor	状态变量变化监听。
@Computed	计算属性。
@ObservedV2	标记类可观察
@Trace	标记类属性可观察。
@Type	标记类属性的类型。
@ReusableV2	标记组件可复用。

通用装饰器	装饰器说明
@Builder	自定义构建函数。
@LocalBuilder	维持组件关系。
@BuilderParam	引用@Builder函数。
@Styles	定义组件重用样式。
@Extend	定义扩展组件样式。
@AnimatableExtend	定义可动画属性。
@Require	校验构造传参。
@Env	环境变量。

旧版摘要Ui语法摘要1

在@ComponentV2装饰的自定义组件中，开发者仅可以使用全新的状态变量装饰器，包括@Local、@Param、@Once、@Event、@Provider、@Consumer等。
@ComponentV2装饰的自定义组件暂不支持LocalStorage等现有自定义组件的能力。
无法同时使用@ComponentV2与@Component装饰同一个struct结构。
@ComponentV2支持一个可选的ComponentOptions参数，来实现组件冻结功能

@Local表示组件内部的状态，使得自定义组件内部的变量具有观察变化的能力：

被@Local装饰的变量无法从外部初始化，因此必须在组件内部进行初始化。
当被@Local装饰的变量变化时，会刷新使用该变量的组件。
@Local支持观测number、boolean、string、Object、class等基本类型以及Array、Set、Map、Date等内置类型。
@Local的观测能力仅限于被装饰的变量本身。当装饰简单类型时，能够观测到对变量的赋值；当装饰对象类型时，仅能观测到对对象整体的赋值；当装饰数组类型时，能观测到数组整体以及数组元素项的变化；当装饰Array、Set、Map、Date等内置类型时，可以观测到通过API调用带来的变化。详见观察变化。
@Local支持null、undefined以及联合类型。

@Provider，即数据提供方，其所有的子组件都可以通过@Consumer绑定相同的key来获取@Provider提供的数据。

@Consumer，即数据消费方，可以通过绑定同样的key获取其最近父节点的@Provider的数据，当查找不到@Provider的数据时，使用本地默认值。图示如下。

能力	V2装饰器@Provider和@Consumer	V1装饰器@Provide和@Consume
@Consume(r)	必须本地初始化，当找不到@Provider时使用本地默认值。	API version 20以前，@Consume禁止本地初始化，当找不到对应@Provide的时候，会抛出异常；从API version 20开始，@Consume支持设置默认值，如果没有设置默认值，且找不到对应@Provide时，会抛出异常。
支持类型	支持function。	不支持function。
观察能力	仅能观察自身赋值变化，如果要观察嵌套场景，配合@Trace一起使用。	观察第一层变化，如果要观察嵌套场景，配合@Observed和@ObjectLink一起使用。
alias和属性名	alias是唯一匹配的key，缺省时默认属性名为alias。	alias和属性名都为key，优先匹配alias，匹配不到可以匹配属性名。
@Provide(r) 从父组件初始化	不允许。	允许。
@Provide(r)支持重载	默认开启，即@Provider可以重名，@Consumer向上查找最近的@Provider。	默认关闭，即在组件树上不允许有同名@Provide。如果需要重载，则需要配置allowOverride。

@Param表示组件从外部传入的状态，使得父子组件之间的数据能够进行同步：

@Param装饰的变量支持本地初始化，但不允许在组件内部直接修改。
被@Param装饰的变量能够在初始化自定义组件时从外部传入，当数据源也是状态变量时，数据源的修改会同步给@Param。
@Param可以接受任意类型的数据源，包括普通变量、状态变量、常量、函数返回值等。
@Param装饰的变量变化时，会刷新该变量关联的组件。
@Param支持对基本类型（如number、boolean、string、Object、class）、内嵌类型（如Array、Set、Map、Date），以及null、undefined和联合类型进行观测。
对于复杂类型如类对象，@Param会接受数据源的引用。在组件内可以修改类对象中的属性，该修改会同步到数据源。
@Param的观测能力仅限于被装饰的变量本身。详见观察变化。

状态管理V1存在多种可接受外部传入的装饰器，常用的有@State、@Prop、@Link、@ObjectLink。这些装饰器使用有限制且不易区分，不当使用会导致性能问题。

@Param变量装饰器	说明
装饰器参数	无。
能否本地修改	否。若需要修改值，可使用@Param搭配@Once修改子组件的本地值。或通过@Event装饰器，修改@Param数据源的值。
同步类型	由父到子单向同步。
允许装饰的变量类型	Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型。支持null、undefined以及联合类型。
被装饰变量的初始值	允许本地初始化，若不在本地初始化，则需要和@Require装饰器一起使用，要求必须从外部传入初始化。

传递规则	说明
从父组件初始化	@Param装饰的变量允许本地初始化，若无本地初始化则必须从外部传入初始化。当同时存在本地初始值与外部传入值时，优先使用外部传入值进行初始化。
初始化子组件	@Param装饰的变量可以初始化子组件中@Param装饰的变量。
同步	@Param可以和父组件传入的状态变量数据源（即@Local或@Param装饰的变量）进行同步，当数据源发生变化时，会将修改同步给子组件的@Param。

想要实现仅从外部初始化一次且不接受后续同步变化的能力，可以使用@Once装饰器搭配@Param装饰器。

@Once装饰器在变量初始化时接受外部传入值进行初始化，后续数据源更改不会同步给子组件：

@Once必须搭配@Param使用，单独使用或搭配其他装饰器使用都是不允许的。
@Once不影响@Param的观测能力，仅针对数据源的变化做拦截。
@Once与@Param装饰变量的先后顺序不影响使用功能。
@Once与@Param搭配使用时，可以在本地修改@Param变量的值。

为了实现子组件向父组件要求更新@Param装饰变量的能力，开发者可以使用@Event装饰器。使用@Event装饰回调方法是一种规范，表明子组件需要传入更新数据源的回调。

@Event主要配合@Param实现数据的双向同步

由于@Param装饰的变量在本地无法更改，使用@Event装饰器装饰回调方法并调用，可以实现更新数据源的变量，再通过@Local的同步机制，将修改同步回@Param装饰的变量，以此达到主动更新@Param装饰变量的效果。

@Event用于装饰组件对外输出的方法：

@Event装饰的回调方法中参数以及返回值由开发者决定。
@Event装饰非回调类型的变量不会生效。当@Event没有初始化时，会自动生成一个空的函数作为默认回调。
当@Event未被外部初始化，但本地有默认值时，会使用本地默认的函数进行处理。

@Param标志着组件的输入，表明该变量受父组件影响，而@Event标志着组件的输出，可以通过该方法影响父组件。使用@Event装饰回调方法是一种规范，表明该回调作为自定义组件的输出。父组件需要判断是否提供对应方法用于子组件更改@Param变量的数据源。

@Event用于装饰组件对外输出的方法：

@Event装饰的回调方法中参数以及返回值由开发者决定。
@Event装饰非回调类型的变量不会生效。当@Event没有初始化时，会自动生成一个空的函数作为默认回调。
当@Event未被外部初始化，但本地有默认值时，会使用本地默认的函数进行处理。

自定义组件冻结功能

当@ComponentV2装饰的自定义组件处于非激活状态时，状态变量将不响应更新，即@Monitor不会调用，状态变量关联的节点不会刷新。该冻结机制在复杂UI场景下能显著优化性能，避免非激活组件因状态变量更新进行无效刷新，从而减少资源消耗。通过freezeWhenInactive属性来决定是否使用冻结功能，不传参数时默认不使用。支持的场景有：页面路由、TabContent、Navigation、Repeat。