!17050 精品文档 3.2 release - 02

Merge pull request !17050 from zengyawen/OpenHarmony-3.2-Release

zh-cn/application-dev/quick-start/Readme-CN.md

@@ -41,12 +41,37 @@
 - [资源分类与访问](resource-categories-and-access.md)
 - 学习ArkTS语言
   - [初识ArkTS语言](arkts-get-started.md)
-  - ArkTS语法（声明式UI）
-    - [基本UI描述](arkts-basic-ui-description.md)
-    - 状态管理
-      - [基本概念](arkts-state-mgmt-concepts.md)
-      - [页面级变量的状态管理](arkts-state-mgmt-page-level.md)
-      - [应用级变量的状态管理](arkts-state-mgmt-application-level.md)
-    - [动态构建UI元素](arkts-dynamic-ui-elememt-building.md)
-    - [渲染控制](arkts-rendering-control.md)
-    - [使用限制与扩展](arkts-restrictions-and-extensions.md)
+  - 基本语法
+    - [基本语法概述](arkts-basic-syntax-overview.md)
+    - [声明式UI描述](arkts-declarative-ui-description.md)
+    - 自定义组件
+      - [创建自定义组件](arkts-create-custom-components.md)
+      - [页面和自定义组件生命周期](arkts-page-custom-components-lifecycle.md)
+    - [\@Builder：自定义构建函数](arkts-builder.md)
+    - [\@BuilderParam：引用\@Builder函数](arkts-builderparam.md)
+    - [\@Styles：定义组件重用样式](arkts-style.md)
\ No newline at end of file
+    - [\@Extend：定义扩展组件样式](arkts-extend.md)
+    - [stateStyles：多态样式](arkts-statestyles.md)
+  - 状态管理
+    - [状态管理概述](arkts-state-management-overview.md)
+    - 管理组件拥有的状态
+      - [\@State：组件内状态](arkts-state.md)
+      - [\@Prop：父子单向同步](arkts-prop.md)
+      - [\@Link：父子双向同步](arkts-link.md)
+      - [\@Provide和\@Consume：与后代组件双向同步](arkts-provide-and-consume.md)
+      - [\@Observed和\@ObjectLink：嵌套类对象属性变化](arkts-observed-and-objectlink.md)
+    - 管理应用拥有的状态
+      - [管理应用拥有的状态概述](arkts-application-state-management-overview.md)
+      - [LocalStorage：页面级UI状态存储](arkts-localstorage.md)
+      - [AppStorage：应用全局的UI状态存储](arkts-appstorage.md)
+      - [PersistentStorage：持久化存储UI状态](arkts-persiststorage.md)
+      - [Environment：设备环境查询](arkts-environment.md)
+    - 其他状态管理
+      - [其他状态管理概述](arkts-other-state-mgmt-functions-overview.md)
+      - [\@Watch：状态变量更改通知](arkts-watch.md)
+      - [$$语法：内置组件双向同步](arkts-two-way-sync.md)
+  - 渲染控制
+      - [渲染控制概述](arkts-rendering-control-overview.md)
+      - [if/else：条件渲染](arkts-rendering-control-ifelse.md)
+      - [ForEach：循环渲染](arkts-rendering-control-foreach.md)
+      - [LazyForEach：数据懒加载](arkts-rendering-control-lazyforeach.md)

zh-cn/application-dev/quick-start/arkts-application-state-management-overview.md

+# 管理应用拥有的状态概述
+
+
+上一个章节中介绍的装饰器仅能在页面内，即一个组件树上共享状态变量。如果开发者要实现应用级的，或者多个页面的状态数据共享，就需要用到应用级别的状态管理的概念。ArkTS根据不同特性，提供了多种应用状态管理的能力：
+
+
+- [LocalStorage](arkts-localstorage.md)：页面级UI状态存储，通常用于[UIAbility](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-app-ability-uiAbility.md)内、页面间的状态共享。
+
+- [AppStorage](arkts-appstorage.md)：特殊的单例LocalStorage对象，由UI框架在应用程序启动时创建，为应用程序UI状态属性提供中央存储；
+
+- [PersistentStorage](arkts-persiststorage.md)：持久化存储UI状态，通常和AppStorage配合使用，选择AppStorage存储的数据写入磁盘，以确保这些属性在应用程序重新启动时的值与应用程序关闭时的值相同；
+
+- [Environment](arkts-environment.md)：应用程序运行的设备的环境参数，环境参数会同步到AppStorage中，可以和AppStorage搭配使用。

zh-cn/application-dev/quick-start/arkts-appstorage.md

+# AppStorage：应用全局的UI状态存储
+
+
+AppStorage是应用全局的UI状态存储，是和应用的进程绑定的，由UI框架在应用程序启动时创建，为应用程序UI状态属性提供中央存储。
+
+
+和LocalStorage不同的是，LocalStorage是页面级的，通常应用于页面内的数据共享。而对于AppStorage，是应用级的全局状态共享。AppStorage还相当于整个应用的“中枢”，[持久化数据PersistentStorage](arkts-persiststorage.md)和[环境变量Environment](arkts-environment.md)都是通过和AppStorage中转，才可以和UI回交互。
+
+
+本文仅介绍AppStorage使用场景和相关的装饰器：\@StorageProp和\@StorageLink。
+
+
+## 概述
+
+AppStorage是LocalStorage是在应用启动的时候会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorage将在应用运行过程保留其属性。属性通过唯一的键字符串值访问。
+
+AppStorage可以和UI组件同步，且可以在应用业务逻辑中被访问。
+
+AppStorage中的属性可以被双向同步，数据可以是存在于本地或远程设备上，并具有不同的功能，比如数据持久化（详见[PersistentStorage](arkts-persiststorage.md)）。这些数据是通过业务逻辑中实现，与UI解耦，如果希望这些数据在UI中使用，需要用到[@StorageProp](#storageprop)和[@StorageLink](#storagelink)。
+
+
+## \@StorageProp
+
+在上文中已经提到，如果要建立AppStorage和自定义组件的联系，需要使用\@StorageProp和\@StorageLink装饰器。使用\@StorageProp(key)/\@StorageLink(key)装饰组件内的变量，key标识了AppStorage的属性。
+
+当自定义组件初始化的时候，\@StorageProp(key)/\@StorageLink(key)装饰的变量会通过给定的key，绑定在AppStorage对应是属性，完成初始化。本地初始化是必要的，因为无法保证AppStorage一定存在给定的key，这取决于应用逻辑，是否在组件初始化之前在AppStorage实例中存入对应的属性。
+
+
+\@StorageProp(key)是和AppStorage中key对应的属性建立单向数据同步，我们允许本地改变的发生，但是对于\@StorageProp，本地的修改永远不会同步回AppStorage中，相反，如果AppStorage给定key的属性发生改变，改变会被同步给\@StorageProp，并覆盖掉本地的修改。
+
+
+### 装饰器使用规则说明
+
+| \@StorageProp变量装饰器 | 说明                                       |
+| ------------------ | ---------------------------------------- |
+| 装饰器参数              | key：常量字符串，必填（字符串需要有引号）。                  |
+| 允许装饰的变量类型          | Object&nbsp;class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化和行为表现](#观察变化和行为表现)。<br/>类型必须被指定，且必须和LocalStorage中对应属性相同。不支持any，不允许使用undefined和null。 |
+| 同步类型               | 单向同步：从AppStorage的对应属性到组件的状态变量。<br/>组件本地的修改是允许的，但是AppStorage中给定的属性一旦发生变化，将覆盖本地的修改。 |
+| 被装饰变量的初始值          | 必须指定，如果AppStorage实例中不存在属性，则作为初始化默认值，并存入AppStorage中。 |
+
+
+### 变量的传递/访问规则说明
+
+| 传递/访问      | 说明                                       |
+| ---------- | ---------------------------------------- |
+| 从父节点初始化和更新 | 禁止，\@StorageProp不支持从父节点初始化，只能AppStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化 |
+| 初始化子节点     | 支持，可用于初始化\@State、\@Link、\@Prop、\@Provide。 |
+| 是否支持组件外访问  | 否。                                       |
+
+
+  **图1** \@StorageProp初始化规则图示  
+
+
+![zh-cn_image_0000001552978157](figures/zh-cn_image_0000001552978157.png)
+
+
+### 观察变化和行为表现
+
+**观察变化**
+
+
+- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。
+
+- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性。
+
+- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化。
+
+
+**框架行为**
+
+
+- 当\@StorageProp(key)装饰的数值改变被观察到时，修改不会被同步回AppStorage对应属性键值key的属性中。
+
+- 当前\@StorageProp(key)单向绑定的数据会被修改，即仅限于当前组件的私有成员变量改变，其他的绑定该key的数据不会同步改变。
+
+- 当\@StorageProp(key)装饰的数据本身是状态变量，它的改变虽然不会同步回AppStorage中，但是会引起所属的自定义组件的重新渲染。
+
+- 当AppStorage中key对应的属性发生改变时，会同步给所有\@StorageProp(key)装饰的数据，\@StorageProp(key)本地的修改将被覆盖。
+
+
+## \@StorageLink
+
+\@StorageLink(key)是和AppStorage中key对应的属性建立双向数据同步：
+
+1. 本地修改发生，该修改会被回AppStorage中；
+
+2. AppStorage中的修改发生后，该修改会被同步到所有绑定AppStorage对应key的属性上，包括单向（\@StorageProp和通过Prop创建的单向绑定变量）、双向（\@StorageLink和通过Link创建的双向绑定变量）变量和其他实例（比如PersistentStorage）。
+
+
+### 装饰器使用规则说明
+
+| \@StorageLink变量装饰器 | 说明                                       |
+| ------------------ | ---------------------------------------- |
+| 装饰器参数              | key：常量字符串，必填（字符串需要有引号）。                  |
+| 允许装饰的变量类型          | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化和行为表现](#观察变化和行为表现)。<br/>类型必须被指定，且必须和AppStorage中对应属性相同。不支持any，不允许使用undefined和null。 |
+| 同步类型               | 双向同步：从AppStorage的对应属性到自定义组件，从自定义组件到AppStorage对应属性。 |
+| 被装饰变量的初始值          | 必须指定，如果AppStorage实例中不存在属性，则作为初始化默认值，并存入AppStorage中。 |
+
+
+### 变量的传递/访问规则说明
+
+| 传递/访问      | 说明                                       |
+| ---------- | ---------------------------------------- |
+| 从父节点初始化和更新 | 禁止。                                      |
+| 初始化子节点     | 支持，可用于初始化常规变量、\@State、\@Link、\@Prop、\@Provide。 |
+| 是否支持组件外访问  | 否。                                       |
+
+
+  **图2** \@StorageLink初始化规则图示  
+
+
+![zh-cn_image_0000001501938718](figures/zh-cn_image_0000001501938718.png)
+
+
+### 观察变化和行为表现
+
+**观察变化**
+
+
+- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。
+
+- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性。
+
+- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化。
+
+
+**框架行为**
+
+
+1. 当\@StorageLink(key)装饰的数值改变被观察到时，修改将被同步回AppStorage对应属性键值key的属性中。
+
+2. AppStorage中属性键值key对应的数据一旦改变，属性键值key绑定的所有的数据（包括双向\@StorageLink和单向\@StorageProp）都将同步修改；
+
+3. 当\@StorageLink(key)装饰的数据本身是状态变量，它的改变不仅仅会同步回AppStorage中，还会引起所属的自定义组件的重新渲染。
+
+
+## 使用场景
+
+
+### 从应用逻辑使用AppStorage和LocalStorage
+
+AppStorage是单例，它的所有API都是静态的，使用方法类似于中LocalStorage对应的非静态方法。
+
+
+```ts
+AppStorage.SetOrCreate('PropA', 47);
+
+let storage: LocalStorage = new LocalStorage({ 'PropA': 17 });
+let propA: number = AppStorage.Get('PropA') // propA in AppStorage == 47, propA in LocalStorage == 17
+var link1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // link1.get() == 47
+var link2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // link2.get() == 47
+var prop: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); // prop.get() = 47
+
+link1.set(48); // two-way sync: link1.get() == link2.get() == prop.get() == 48
+prop.set(1); // one-way sync: prop.get()=1; but link1.get() == link2.get() == 48
+link1.set(49); // two-way sync: link1.get() == link2.get() == prop.get() == 49
+
+storage.get('PropA') // == 17 
+storage.set('PropA', 101);
+storage.get('PropA') // == 101
+
+AppStorage.Get('PropA') // == 49
+link1.get() // == 49
+link2.get() // == 49
+prop.get() // == 49
+```
+
+
+### 从UI内部使用AppStorage和LocalStorage
+
+\@StorageLink变量装饰器与AppStorage配合使用，正如\@LocalStorageLink与LocalStorage配合使用一样。此装饰器使用AppStorage中的属性创建双向数据同步。
+
+
+```ts
+AppStorage.SetOrCreate('PropA', 47);
+let storage = new LocalStorage({ 'PropA': 48 });
+
+@Entry(storage)
+@Component
+struct CompA {
+  @StorageLink('PropA') storLink: number = 1;
+  @LocalStorageLink('PropA') localStorLink: number = 1;
+
+  build() {
+    Column({ space: 20 }) {
+      Text(`From AppStorage ${this.storLink}`)
+        .onClick(() => this.storLink += 1)
+
+      Text(`From LocalStorage ${this.localStorLink}`)
+        .onClick(() => this.localStorLink += 1)
+    }
+  }
+}
+```
+
+
+## 限制条件
+
+AppStorage与[PersistentStorage](arkts-persiststorage.md)以及[Environment](arkts-environment.md)配合使用时，需要注意以下几点：
+
+- 在AppStorage中创建属性后，调用PersistentStorage.PersistProp()接口时，会使用在AppStorage中已经存在的值，并覆盖PersistentStorage中的同名属性，所以建议要使用相反的调用顺序，反例可见[在PersistentStorage之前访问AppStorage中的属性](arkts-persiststorage.md#在persistentstorage之前访问appstorage中的属性)；
+
+- 如果在AppStorage中已经创建属性后，再调用Environment.EnvProp()创建同名的属性，会调用失败。因为AppStorage已经有同名属性，Environment环境变量不会再写入AppStorage中，所以建议AppStorage中属性不要使用Environment预置环境变量名。

zh-cn/application-dev/quick-start/arkts-basic-syntax-overview.md

+# 基本语法概述
+
+
+在初步了解了ArkTS语言之后，我们以一个具体的示例来说明ArkTS的基本组成。如下图所示，当开发者点击按钮时，文本内容从“Hello World”变为“Hello ArkUI”。
+
+
+  **图1** 示例效果图  
+
+![Video_2023-03-06_152548](figures/Video_2023-03-06_152548.gif)
+
+
+本示例中，ArkTS的基本组成如下所示。
+
+
+  **图2** ArkTS的基本组成  
+
+![arkts-basic-grammar](figures/arkts-basic-grammar.png)
+
+
+- 装饰器： 用于装饰类、结构、方法以及变量，并赋予其特殊的含义。如上述示例中\@Entry、\@Component和\@State都是装饰器，\@Component表示自定义组件，\@Entry表示该自定义组件为入口组件，\@State表示组件中的状态变量，状态变量变化会触发UI刷新。
+
+- [UI描述](arkts-declarative-ui-description.md)：以声明式的方式来描述UI的结构，例如build()方法中的代码块。
+
+- [自定义组件](arkts-create-custom-components.md)：可复用的UI单元，可组合其他组件，如上述被\@Component装饰的struct Hello。
+
+- 系统组件：ArkUI框架中默认内置的基础和容器组件，可直接被开发者调用，比如示例中的Column 、 Text 、 Divider 、 Button。
+
+- 属性方法：组件可以通过链式调用配置多项属性，如fontSize()、width()、height()、color()等。
+
+- 事件方法：组件可以通过链式调用设置多个事件的响应逻辑，如跟随在Button后面的onClick()。
+
+
+除此之外，ArkTS扩展了多种语法范式来使开发更加便捷：
+
+
+- [@Builder](arkts-builder.md)/[@BuilderParam](arkts-builderparam.md)：特殊的封装UI描述的方法，细粒度的封装和复用UI描述。
+
+- [@Extend](arkts-extend.md)/[@Style](arkts-style.md)：扩展内置组件和封装属性样式，更灵活地组合内置组件。
+
+- [stateStyles](arkts-statestyles.md)：多态样式，可以依据组件的内部状态的不同，设置不同样式。

zh-cn/application-dev/quick-start/arkts-basic-ui-description.md

-# 基本UI描述
-
-ArkTS通过装饰器@Component和@Entry装饰struct关键字声明的数据结构，构成一个自定义组件。自定义组件中提供了一个build函数，开发者需在该函数内以链式调用的方式进行基本的UI描述，UI描述的方法请参考[UI描述规范](#ui描述规范)。
-
-## 基本概念
-
-- struct：自定义组件可以基于struct实现，不能有继承关系，对于struct的实例化，可以省略new。
-
-- 装饰器：装饰器给被装饰的对象赋予某一种能力，其不仅可以装饰类或结构体，还可以装饰类的属性。多个装饰器可以叠加到目标元素上，定义在同一行中或者分开多行，推荐分开多行定义。
-
-  ```ts
-  @Entry
-  @Component
-  struct MyComponent {
-  }
-  ```
-
-- build函数：自定义组件必须定义build函数，并且禁止自定义构造函数。build函数满足Builder构造器接口定义，用于定义组件的声明式UI描述。
-
-  ```ts
-  interface Builder {
-      build: () => void
-  }
-  ```
-
-- @Component：装饰struct，结构体在装饰后具有基于组件的能力，需要实现build方法来创建UI。
-
-- @Entry： 装饰struct，组件被装饰后作为页面的入口，页面加载时将被渲染显示。
-
-- @Preview：装饰struct， 用@Preview装饰的自定义组件可以在DevEco Studio的预览器上进行实时预览，加载页面时，将创建并显示@Preview装饰的自定义组件。
-
-  > **说明：** 在单个源文件中，最多可以使用10个@Preview装饰自定义组件，更多说明请参考[查看ArkTS组件预览效果](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-previewing-app-service-0000001218760596#section146052489820)。
-
-- 链式调用：以 "." 链式调用的方式配置UI组件的属性方法、事件方法等。
-
-## UI描述规范
-
-### 无参数构造配置
-
-如果组件的接口定义中不包含必选构造参数，组件后面的“()”中不需要配置任何内容。例如，Divider组件不包含构造参数： 
-
-```ts
-Column() {
-    Text('item 1')
-    Divider()
-    Text('item 2')
-}
-```
-
-### 有参数构造配置
-
-如果组件的接口定义中包含构造参数，则在组件后面的“()”中可配置相应参数，参数可以使用常量进行赋值。
-
-例如：
-
-- Image组件的必选参数src：
-
-  ```ts
-  Image('https://xyz/test.jpg')
-  ```
-
-- Text组件的参数content，该参数非必选，即配置或不配置均可：
-
-  ```ts
-  Text('test')
-  ```
-
-变量或表达式也可以用于参数赋值，其中表达式返回的结果类型必须满足参数类型要求，变量的定义详见[页面级变量的状态管理](arkts-state-mgmt-page-level.md)与[应用级变量的状态管理](arkts-state-mgmt-application-level.md)。例如，设置变量或表达式来构造Image和Text组件的参数：
-
-```ts
-Image(this.imagePath)
-Image('https://' + this.imageUrl)
-Text(`count: ${this.count}`)
-```
-
-### 属性配置
-
-使用属性方法配置组件的属性，属性方法紧随组件，并用"."运算符连接。
-
-- 配置Text组件的字体大小属性：
-
-  ```ts
-  Text('test')
-    .fontSize(12)
-  ```
-
-- 使用"."运算符进行链式调用并同时配置组件的多个属性，如下所示：
-
-  ```ts
-  Image('test.jpg')
-    .alt('error.jpg')    
-    .width(100)    
-    .height(100)
-  ```
-
-- 除了直接传递常量参数外，还可以传递变量或表达式，如下所示：
-
-  ```ts
-  Text('hello')
-    .fontSize(this.size)
-  Image('test.jpg')
-    .width(this.count % 2 === 0 ? 100 : 200)    
-    .height(this.offset + 100)
-  ```
-
--  对于系统内置组件，框架还为其属性预定义了一些[枚举类型](../reference/arkui-ts/ts-appendix-enums.md)供开发人员调用，枚举类型可以作为参数传递，且必须满足参数类型要求。例如，可以按以下方式配置Text组件的颜色和字体属性： 
-
-  ```ts
-  Text('hello')
-    .fontSize(20)
-    .fontColor(Color.Red)
-    .fontWeight(FontWeight.Bold)
-  ```
-
-### 事件配置
-
-通过事件方法可以配置组件支持的事件，事件方法紧随组件，并用"."运算符连接。
-
-- 使用lambda表达式配置组件的事件方法：
-
-  ```ts
-  Button('add counter')
-      .onClick(() => {
-          this.counter += 2
-      })
-  ```
-
-- 使用匿名函数表达式配置组件的事件方法，要求使用bind，以确保函数体中的this引用包含的组件：
-
-  ```ts
-  Button('add counter')
-      .onClick(function () {
-          this.counter += 2
-      }.bind(this))
-  ```
-
-- 使用组件的成员函数配置组件的事件方法：
-
-  ```ts
-  myClickHandler(): void {
-    this.counter += 2
-  }
-  
-  ...
-
-  Button('add counter')
-    .onClick(this.myClickHandler.bind(this))
-  ```
-
-### 子组件配置
-
-对于支持子组件配置的组件，例如容器组件，在"{ ... }"里为组件添加子组件的UI描述。Column、Row、Stack、Grid、List等组件都是容器组件。
-
-- 以下是简单的Column示例：
-
-  ```ts
-  Column() {
-      Text('Hello')
-        .fontSize(100)
-      Divider()
-      Text(this.myText)
-        .fontSize(100)
-        .fontColor(Color.Red)
-  }
-  ```
-
-- 容器组件之间也可以互相嵌套，实现相对复杂的多级嵌套效果：
-
-  ```ts
-  Column() {
-    Row() {
-      Image('test1.jpg')
-        .width(100)
-        .height(100)
-      Button('click +1')
-        .onClick(() => {
-          console.info('+1 clicked!')
-        })
-    }
-
-    Divider()
-    Row() {
-      Image('test2.jpg')
-        .width(100)
-        .height(100)
-      Button('click +2')
-        .onClick(() => {
-          console.info('+2 clicked!')
-        })
-    }
-
-    Divider()
-    Row() {
-      Image('test3.jpg')
-        .width(100)
-        .height(100)
-      Button('click +3')
-        .onClick(() => {
-          console.info('+3 clicked!')
-        })
-    }
-  }
-  ```
\ No newline at end of file

zh-cn/application-dev/quick-start/arkts-builder.md

+# \@Builder：自定义构建函数
+
+
+前面章节介绍了如何创建一个自定义组件。该自定义组件内部UI结构固定，仅与使用方进行数据传递。ArkUI还提供了一种更轻量的UI元素复用机制\@Builder，\@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。
+
+
+为了简化语言，我们将\@Builder装饰的函数也称为“自定义构建函数”。
+
+
+> **说明：**
+>
+> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+
+## 装饰器使用说明
+
+
+### 自定义组件内自定义构建函数
+
+定义的语法：
+
+
+```ts
+@Builder myBuilderFunction({ ... })
+```
+
+使用方法：
+
+
+```ts
+this.myBuilderFunction({ ... })
+```
+
+- 允许在自定义组件内定义一个或多个自定义构建函数，该函数被认为是该组件的私有、特殊类型的成员函数。
+
+- 自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。
+
+- 在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。
+
+
+### 全局自定义构建函数
+
+定义的语法：
+
+
+```ts
+@Builder function MyGlobalBuilderFunction({ ... })
+```
+
+使用方法：
+
+
+```ts
+MyGlobalBuilderFunction()
+```
+
+
+- 全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。
+
+- 如果不涉及组件状态变化，建议使用全局的自定义构建方法。
+
+
+## 参数传递规则
+
+自定义构建函数的参数传递有[按值传递](#按值传递参数)和[按引用传递](#按引用传递参数)两种，均需遵守以下规则：
+
+- 参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。
+
+- 在自定义构建函数内部，不允许改变参数值。如果需要改变参数值，且同步回调用点，建议使用[@Link](arkts-link.md)。
+
+- \@Builder内UI语法遵循[UI语法规则](arkts-create-custom-components.md#build函数)。
+
+
+### 按引用传递参数
+
+按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起\@Builder方法内的UI刷新。ArkUI提供$$作为按引用传递参数的范式。
+
+
+```ts
+ABuilder( $$ : { paramA1: string, paramB1 : string } );
+```
+
+
+
+```ts
+@Builder function ABuilder($$: { paramA1: string }) {
+  Row() {
+    Text(`UseStateVarByReference: ${$$.paramA1} `)
+  }
+}
+@Entry
+@Component
+struct Parent {
+  @State label: string = 'Hello';
+  build() {
+    Column() {
+      // 在Parent组件中调用ABuilder的时候，将this.label引用传递给ABuilder
+      ABuilder({ paramA1: this.label })
+      Button('Click me').onClick(() => {
+        // 点击“Click me”后，UI从“Hello”刷新为“ArkUI”
+        this.label = 'ArkUI';
+      })
+    }
+  }
+}
+```
+
+
+### 按值传递参数
+
+调用\@Builder装饰的函数默认按值传递。当传递的参数为状态变量时，状态变量的改变不会引起\@Builder方法内的UI刷新。所以当使用状态变量的时候，推荐使用[按引用传递](#按引用传递参数)。
+
+
+```ts
+@Builder function ABuilder(paramA1: string) {
+  Row() {
+    Text(`UseStateVarByValue: ${paramA1} `)
+  }
+}
+@Entry
+@Component
+struct Parent {
+  label: string = 'Hello';
+  build() {
+    Column() {
+      ABuilder(this.label)
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-builderparam.md

+# \@BuilderParam：引用\@Builder函数
+
+
+当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。若直接在组件内嵌入事件方法，将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题，ArkUI引入了\@BuilderParam装饰器，\@BuilderParam用来装饰指向\@Builder方法的变量，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素，类似slot占位符。
+
+
+> **说明：**
+>
+> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+
+## 装饰器使用说明
+
+
+### 初始化\@BuilderParam装饰的方法
+
+\@BuildParam装饰的方法只能被自定义构建函数（\@Builder装饰的方法）初始化。
+
+- 使用所属自定义组件的自定义构建函数或者全局的自定义构建函数，在本地初始化\@BuilderParam。
+
+  ```ts
+  @Builder function GlobalBuilder0() {}
+
+  @Component
+  struct Child {
+    @Builder doNothingBuilder() {};
+
+    @BuilderParam aBuilder0: () => void = this.doNothingBuilder;
+    @BuilderParam aBuilder1: () => void = GlobalBuilder0;
+    build(){}
+  }
+  ```
+
+- 用父组件自定义构建函数初始化子组件\@BuildParam装饰的方法。
+
+  ```ts
+  @Component
+  struct Child {
+    @BuilderParam aBuilder0: () => void;
+
+    build() {
+      Column() {
+        this.aBuilder0()
+      }
+    }
+  }
+
+  @Entry
+  @Component
+  struct Parent {
+    @Builder componentBuilder() {
+      Text(`Parent builder `)
+    }
+
+    build() {
+      Column() {
+        Child({ aBuilder0: this.componentBuilder })
+      }
+    }
+  }
+  ```
+
+
+- 需注意this指向正确。
+
+  以下示例中，Parent组件在调用this.componentBuilder()时，this.label指向其所属组件，即“Parent”。\@Builder componentBuilder()传给子组件\@BuilderParam aBuilder0，在Child组件中调用this.aBuilder0()时，this.label指向在Child的label，即“Child”。
+
+   >  **说明：**
+   >
+   >  开发者谨慎使用bind改变函数调用的上下文，可能会使this指向混乱。
+
+  ```ts
+  @Component
+  struct Child {
+    label: string = `Child`
+    @BuilderParam aBuilder0: () => void;
+
+    build() {
+      Column() {
+        this.aBuilder0()
+      }
+    }
+  }
+
+  @Entry
+  @Component
+  struct Parent {
+    label: string = `Parent`
+
+    @Builder componentBuilder() {
+      Text(`${this.label}`)
+    }
+
+    build() {
+      Column() {
+        this.componentBuilder()
+        Child({ aBuilder0: this.componentBuilder })
+      }
+    }
+  }
+  ```
+
+
+## 使用场景
+
+
+### 参数初始化组件
+
+\@BuilderParam装饰的方法可以是有参数和无参数的两种形式，需与指向的\@Builder方法类型匹配。\@BuilderParam装饰的方法类型需要和\@Builder方法类型一致。
+
+
+```ts
+@Builder function GlobalBuilder1($$ : {label: string }) {
+  Text($$.label)
+    .width(400)
+    .height(50)
+    .backgroundColor(Color.Blue)
+}
+
+@Component
+struct Child {
+  label: string = 'Child'
+  // 无参数类，指向的componentBuilder也是无参数类型
+  @BuilderParam aBuilder0: () => void;
+  // 有参数类型，指向的GlobalBuilder1也是有参数类型的方法
+  @BuilderParam aBuilder1: ($$ : { label : string}) => void;
+
+  build() {
+    Column() {
+      this.aBuilder0()
+      this.aBuilder1({label: 'global Builder label' } )
+    }
+  }
+}
+
+@Entry
+@Component
+struct Parent {
+  label: string = 'Parent'
+
+  @Builder componentBuilder() {
+    Text(`${this.label}`)
+  }
+
+  build() {
+    Column() {
+      this.componentBuilder()
+      Child({ aBuilder0: this.componentBuilder, aBuilder1: GlobalBuilder1 })
+    }
+  }
+}
+```
+
+
+### 尾随闭包初始化组件示例
+
+在自定义组件中使用\@BuilderParam装饰的属性时也可通过尾随闭包进行初始化。在初始化自定义组件时，组件后紧跟一个大括号“{}”形成尾随闭包场景。
+
+> **说明：**
+> 此场景下自定义组件内有且仅有一个使用\@BuilderParam装饰的属性。
+
+开发者可以将尾随闭包内的内容看做\@Builder装饰的函数传给\@BuilderParam。示例如下：
+
+
+```ts
+// xxx.ets
+@Component
+struct CustomContainer {
+  @Prop header: string;
+  @BuilderParam closer: () => void
+
+  build() {
+    Column() {
+      Text(this.header)
+        .fontSize(30)
+      this.closer()
+    }
+  }
+}
+
+@Builder function specificParam(label1: string, label2: string) {
+  Column() {
+    Text(label1)
+      .fontSize(30)
+    Text(label2)
+      .fontSize(30)
+  }
+}
+
+@Entry
+@Component
+struct CustomContainerUser {
+  @State text: string = 'header';
+
+  build() {
+    Column() {
+      // 创建CustomContainer，在创建CustomContainer时，通过其后紧跟一个大括号“{}”形成尾随闭包
+      // 作为传递给子组件CustomContainer @BuilderParam closer: () => void的参数
+      CustomContainer({ header: this.text }) {
+        Column() {
+          specificParam('testA', 'testB')
+        }.backgroundColor(Color.Yellow)
+        .onClick(() => {
+          this.text = 'changeHeader';
+        })
+      }
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-create-custom-components.md

+# 创建自定义组件
+
+
+在ArkUI中，UI显示的内容均为组件，由框架直接提供的称为系统组件，由开发者定义的称为自定义组件。在进行 UI 界面开发时，通常不是简单的将系统组件进行组合使用，而是需要考虑代码可复用性、业务逻辑与UI分离，后续版本演进等因素。因此，将UI和部分业务逻辑封装成自定义组件是不可或缺的能力。
+
+
+自定义组件具有以下特点：
+
+
+- 可组合：允许开发者组合使用系统组件、及其属性和方法。
+
+- 可重用：自定义组件可以被其他组件重用，并作为不同的实例在不同的父组件或容器中使用。
+
+- 数据驱动UI更新：通过状态变量的改变，来驱动UI的刷新。
+
+
+以下示例展示了自定义组件的基本用法。
+
+
+
+```ts
+@Component
+struct HelloComponent {
+  @State message: string = 'Hello, World!';
+
+  build() {
+    // HelloComponent自定义组件组合系统组件Row和Text
+    Row() {
+      Text(this.message)
+        .onClick(() => {
+          // 状态变量message的改变驱动UI刷新，UI从'Hello, World!'刷新为'Hello, ArkUI!'
+          this.message = 'Hello, ArkUI!';
+        })
+    }
+  }
+}
+```
+
+
+HelloComponent可以在其他自定义组件中的build()函数中多次创建，实现自定义组件的重用。
+
+
+
+```ts
+@Entry
+@Component
+struct ParentComponent {
+  build() {
+    Column() {
+      Text('ArkUI message')
+      HelloComponent({ message: 'Hello, World!' });
+      Divider()
+      HelloComponent({ message: '你好!' });
+    }
+  }
+}
+```
+
+
+要完全理解上面的示例，需要了解自定义组件的以下概念定义，本文将在后面的小节中介绍：
+
+
+- [自定义组件的基本结构](#自定义组件的基本结构)
+
+- [成员函数/变量](#成员函数变量)
+
+- [自定义组件的参数规定](#自定义组件的参数规定)
+
+- [build()函数](#build函数)
+
+- [自定义组件通用样式](#自定义组件通用样式)
+
+- [自定义属性方法](#自定义属性方法)
+
+
+## 自定义组件的基本结构
+
+- struct：自定义组件基于struct实现，struct + 自定义组件名 + {...}的组合构成自定义组件，不能有继承关系。对于struct的实例化，可以省略new。
+  > **说明：**
+  >
+  > 自定义组件名、类名、函数名不能和系统组件名相同。
+
+- \@Component：\@Component装饰器仅能装饰struct关键字声明的数据结构。struct被\@Component装饰后具备组件化的能力，需要实现build方法描述UI，一个struct只能被一个\@Component装饰。
+  > **说明：**
+  >
+  > 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+  ```ts
+  @Component
+  struct MyComponent {
+  }
+  ```
+
+- build()函数：build()函数用于定义自定义组件的声明式UI描述，自定义组件必须定义build()函数。
+
+  ```ts
+  @Component
+  struct MyComponent {
+    build() {
+    }
+  }
+  ```
+
+- \@Entry：\@Entry装饰的自定义组件将作为UI页面的入口。在单个UI页面中，最多可以使用\@Entry装饰一个自定义组件。\@Entry可以接受一个可选的[LocalStorage](arkts-localstorage.md)的参数。
+
+  > **说明：**
+  >
+  > 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+  ```ts
+  @Entry
+  @Component
+  struct MyComponent {
+  }
+  ```
+
+
+## 成员函数/变量
+
+自定义组件除了必须要实现build()函数外，还可以实现其他成员函数，成员函数具有以下约束：
+
+
+- 不支持静态函数。
+
+- 成员函数的访问始终是私有的，仅能定义private。定义访问权限是可选的，其他访问权限会带来语法错误。
+
+
+自定义组件可以包含成员变量，成员变量具有以下约束：
+
+
+- 不支持静态成员变量。
+
+- 所有成员变量都是私有的，变量的访问规则与成员函数的访问规则相同。
+
+- 自定义组件的成员变量本地初始化有些是可选的，有些是必选的。具体是否需要本地初始化，是否需要从父组件通过参数传递初始化子组件的成员变量，请参考[状态管理](arkts-state-management-overview.md)。
+
+
+## 自定义组件的参数规定
+
+从上文的示例中，我们已经了解到，可以在build方法或者[@Builder](arkts-builder.md)装饰的函数里创建自定义组件，在创建的过程中，参数可以被提供给组件。
+
+
+```ts
+@Component
+struct MyComponent {
+  private countDownFrom: number = 0;
+  private color: Color = Color.Blue;
+
+  build() {
+  }
+}
+
+@Entry
+@Component
+struct ParentComponent {
+  private someColor: Color = Color.Pink;
+
+  build() {
+    Column() {
+      // 创建MyComponent实例，并将创建MyComponent成员变量countDownFrom初始化为10，将成员变量color初始化为this.someColor
+      MyComponent({ countDownFrom: 10, color: this.someColor })
+    }
+  }
+}
+```
+
+
+## build()函数
+
+所有声明在build()函数的语言，我们统称为UI描述语言，UI描述语言需要遵循以下规则：
+
+- \@Entry装饰的自定义组件，其build()函数下的根节点唯一且必要，且必须为容器组件，其中ForEach禁止作为根节点。
+  \@Component装饰的自定义组件，其build()函数下的根节点唯一且必要，可以为非容器组件，其中ForEach禁止作为根节点。
+
+  ```ts
+  @Entry
+  @Component
+  struct MyComponent {
+    build() {
+      // 根节点唯一且必要，必须为容器组件
+      Row() {
+        ChildComponent() 
+      }
+    }
+  }
+
+  @Component
+  struct ChildComponent {
+    build() {
+      // 根节点唯一且必要，可为非容器组件
+      Image('test.jpg')
+    }
+  }
+  ```
+
+- 不允许声明本地变量，反例如下。
+
+  ```ts
+  build() {
+    // 反例：不允许声明本地变量
+    let a: number = 1;
+  }
+  ```
+
+- 不允许在UI描述里直接使用console.info，但允许在方法或者函数里使用，反例如下。
+
+  ```ts
+  build() {
+    // 反例：不允许console.info
+    console.info('print debug log');
+  }
+  ```
+
+- 不允许创建本地的作用域，反例如下。
+
+  ```ts
+  build() {
+    // 反例：不允许本地作用域
+    {
+      ...
+    }
+  }
+  ```
+
+- 不允许调用除了被\@Builder装饰以外的方法，允许系统组件的参数是TS方法的返回值。
+
+  ```ts
+  @Component
+  struct ParentComponent {
+    doSomeCalculations() {
+    }
+
+    calcTextValue(): string {
+      return 'Hello World';
+    }
+
+    @Builder doSomeRender() {
+      Text(`Hello World`)
+    }
+
+    build() {
+      Column() {
+        // 反例：不能调用没有用@Builder装饰的方法
+        this.doSomeCalculations();
+        // 正例：可以调用
+        this.doSomeRender();
+        // 正例：参数可以为调用TS方法的返回值
+        Text(this.calcTextValue())
+      }
+    }
+  }
+  ```
+
+- 不允许switch语法，如果需要使用条件判断，请使用if。反例如下。
+
+  ```ts
+  build() {
+    Column() {
+      // 反例：不允许使用switch语法
+      switch (expression) {
+        case 1:
+          Text('...')
+          break;
+        case 2:
+          Image('...')
+          break;
+        default:
+          Text('...')
+          break;
+      }
+    }
+  }
+  ```
+
+- 不允许使用表达式，反例如下。
+
+  ```ts
+  build() {
+    Column() {
+      // 反例：不允许使用表达式
+      (this.aVar > 10) ? Text('...') : Image('...')
+    }
+  }
+  ```
+
+
+## 自定义组件通用样式
+
+自定义组件通过“.”链式调用的形式设置通用样式。
+
+
+```ts
+@Component
+struct MyComponent2 {
+  build() {
+    Button(`Hello World`)
+  }
+}
+
+@Entry
+@Component
+struct MyComponent {
+  build() {
+    Row() {
+      MyComponent2()
+        .width(200)
+        .height(300)
+        .backgroundColor(Color.Red)
+    }
+  }
+}
+```
+
+> **说明：**
+>
+> ArkUI给自定义组件设置样式时，相当于给MyComponent2套了一个不可见的容器组件，而这些样式是设置在容器组件上的，而非直接设置给MyComponent2的Button组件。通过渲染结果我们可以很清楚的看到，背景颜色红色并没有直接生效在Button上，而是生效在Button所处的开发者不可见的容器组件上。
+
+
+## 自定义属性方法
+
+自定义组件不支持提供自定义属性方法，可以借助类似Controller控制器能力，提供自定义接口。
+
+
+```ts
+// 自定义controller
+export class MyComponentController {
+  item: MyComponent = null;
+
+  setItem(item: MyComponent) {
+    this.item = item;
+  }
+
+  changeText(value: string) {
+    this.item.value = value;
+  }
+}
+
+// 自定义组件
+@Component
+export default struct MyComponent {
+  public controller: MyComponentController = null;
+  @State value: string = 'Hello World';
+
+  build() {
+    Column() {
+      Text(this.value)
+        .fontSize(50)
+    }
+  }
+
+  aboutToAppear() {
+    if (this.controller)
+      this.controller.setItem(this); // 绑定controller
+  }
+}
+
+// 使用处逻辑
+@Entry
+@Component
+struct StyleExample {
+  controller = new MyComponentController();
+
+  build() {
+    Column() {
+      MyComponent({ controller: this.controller })
+    }
+    .onClick(() => {
+      this.controller.changeText('Text');
+    })
+  }
+}
+```
+
+在上面的示例中：
+
+1. 通过子组件MyComponent的aboutToAppear方法，把当前的this指针传递给MyComponentController的item成员变量。
+
+2. 在StyleExample父组件中持有controller实例，调用controller的changeText方法，即相当于通过controller持有的MyComponent子组件的this指针，改变MyComponent的状态变量value的值。
+
+通过controller的封装，MyComponent对外暴露了changeText的接口，所有持有controller的实例都可以通过调用changeText接口，改变MyComponent的状态变量value的值。

zh-cn/application-dev/quick-start/arkts-declarative-ui-description.md

+# 声明式UI描述
+
+
+ArkTS以声明方式组合和扩展组件来描述应用程序的UI，同时还提供了基本的属性、事件和子组件配置方法，帮助开发者实现应用交互逻辑。
+
+
+## 创建组件
+
+根据组件构造方法的不同，创建组件包含有参数和无参数两种方式。
+
+>  **说明：**
+>
+>  创建组件时不需要new运算符。
+
+
+### 无参数
+
+如果组件的接口定义没有包含必选构造参数，则组件后面的“()”不需要配置任何内容。例如，Divider组件不包含构造参数：
+
+
+```ts
+Column() {
+  Text('item 1')
+  Divider()
+  Text('item 2')
+}
+```
+
+
+### 有参数
+
+如果组件的接口定义包含构造参数，则在组件后面的“()”配置相应参数。
+
+- Image组件的必选参数src。
+
+  ```ts
+  Image('https://xyz/test.jpg')
+  ```
+
+
+- Text组件的非必选参数content。
+
+- ```ts
+  // string类型的参数
+  Text('test')
+  // $r形式引入应用资源，可应用于多语言场景
+  Text($r('app.string.title_value'))
+  // 无参数形式
+  Text()
+  ```
+
+
+- 变量或表达式也可以用于参数赋值，其中表达式返回的结果类型必须满足参数类型要求。
+    例如，设置变量或表达式来构造Image和Text组件的参数。
+
+    ```ts
+    Image(this.imagePath)
+    Image('https://' + this.imageUrl)
+    Text(`count: ${this.count}`)
+    ```
+
+
+## 配置属性
+
+属性方法以“.”链式调用的方式配置系统组件的样式和其他属性，建议每个属性方法单独写一行。
+
+
+- 配置Text组件的字体大小。
+
+  ```ts
+  Text('test')
+    .fontSize(12)
+  ```
+
+- 配置组件的多个属性。
+
+  ```ts
+  Image('test.jpg')
+    .alt('error.jpg')    
+    .width(100)    
+    .height(100)
+  ```
+
+- 除了直接传递常量参数外，还可以传递变量或表达式。
+
+  ```ts
+  Text('hello')
+    .fontSize(this.size)
+  Image('test.jpg')
+    .width(this.count % 2 === 0 ? 100 : 200)    
+    .height(this.offset + 100)
+  ```
+
+- 对于系统组件，ArkUI还为其属性预定义了一些枚举类型供开发者调用，枚举类型可以作为参数传递，但必须满足参数类型要求。
+  例如，可以按以下方式配置Text组件的颜色和字体样式。
+
+  ```ts
+  Text('hello')
+    .fontSize(20)
+    .fontColor(Color.Red)
+    .fontWeight(FontWeight.Bold)
+  ```
+
+
+## 配置事件
+
+事件方法以“.”链式调用的方式配置系统组件支持的事件，建议每个属性方法单独写一行。
+
+
+- 使用lambda表达式配置组件的事件方法。
+
+  ```ts
+  Button('Click me')
+    .onClick(() => {
+      this.myText = 'ArkUI';
+    })
+  ```
+
+- 使用匿名函数表达式配置组件的事件方法，要求使用bind，以确保函数体中的this指向当前组件。
+
+  ```ts
+  Button('add counter')
+    .onClick(function(){
+      this.counter += 2;
+    }.bind(this))
+  ```
+
+- 使用组件的成员函数配置组件的事件方法。
+
+  ```ts
+  myClickHandler(): void {
+    this.counter += 2;
+  }
+  ...
+  Button('add counter')
+    .onClick(this.myClickHandler.bind(this))
+  ```
+
+
+## 配置子组件
+
+如果组件支持子组件配置，则需在尾随闭包"{...}"中为组件添加子组件的UI描述。Column、Row、Stack、Grid、List等组件都是容器组件。
+
+
+- 以下是简单的Column组件配置子组件的示例。
+
+  ```ts
+  Column() {
+    Text('Hello')
+      .fontSize(100)
+    Divider()
+    Text(this.myText)
+      .fontSize(100)
+      .fontColor(Color.Red)
+  }
+  ```
+
+- 容器组件均支持子组件配置，可以实现相对复杂的多级嵌套。
+
+  ```ts
+  Column() {
+    Row() {
+      Image('test1.jpg')
+        .width(100)
+        .height(100)
+      Button('click +1')
+        .onClick(() => {
+          console.info('+1 clicked!');
+        })
+    }
+  }
+  ```

zh-cn/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md

-# 动态构建UI元素
-
-[基本UI描述](arkts-basic-ui-description.md)介绍的是如何创建一个内部UI结构固定的自定义组件，为了满足开发者自定义组件内部UI结构的需求，ArkTS同时提供了动态构建UI元素的能力。
-
-## @Builder
-
-可通过@Builder装饰器进行描述，该装饰器可以修饰一个函数，此函数可以在build函数之外声明，并在build函数中或其他@Builder修饰的函数中使用，从而实现在一个自定义组件内快速生成多个布局内容。使用方式如下面示例所示。
-
-```ts
-// xxx.ets
-@Component
-struct CompB {
-  @State CompValue: string = ''
-
-  aboutToAppear() {
-    console.info('CompB aboutToAppear.')
-  }
-
-  aboutToDisappear() {
-    console.info('CompB aboutToDisappear.')
-  }
-
-  build() {
-    Column() {
-      Button(this.CompValue)
-        .margin(5)
-    }
-  }
-}
-
-@Entry
-@Component
-struct CompA {
-  size1: number = 100
-  @State CompValue1: string = "Hello,CompValue1"
-  @State CompValue2: string = "Hello,CompValue2"
-  @State CompValue3: string = "Hello,CompValue3"
-
-  // @Builder装饰的函数CompC内使用自定义组件CompB
-  @Builder CompC(value: string) {
-    CompB({ CompValue: value })
-  }
-
-  @Builder SquareText(label: string) {
-    Text(label)
-      .fontSize(18)
-      .width(1 * this.size1)
-      .height(1 * this.size1)
-  }
-
-  // @Builder装饰的函数RowOfSquareTexts内使用@Builder装饰的函数SquareText
-  @Builder RowOfSquareTexts(label1: string, label2: string) {
-    Row() {
-      this.SquareText(label1)
-      this.SquareText(label2)
-    }
-    .width(2 * this.size1)
-    .height(1 * this.size1)
-  }
-
-  build() {
-    Column() {
-      Row() {
-        this.SquareText("A")
-        this.SquareText("B")
-      }
-      .width(2 * this.size1)
-      .height(1 * this.size1)
-
-      this.RowOfSquareTexts("C", "D")
-      Column() {
-        // 使用三次@Builder装饰的自定义组件
-        this.CompC(this.CompValue1)
-        this.CompC(this.CompValue2)
-        this.CompC(this.CompValue3)
-      }
-      .width(2 * this.size1)
-      .height(2 * this.size1)
-    }
-    .width(2 * this.size1)
-    .height(2 * this.size1)
-  }
-}
-```
-![builder](figures/builder.PNG)
-
-## @BuilderParam<sup>8+<sup>
-
-@BuilderParam装饰器用于修饰自定义组件内函数类型的属性（例如：`@BuilderParam noParam: () => void`），并且在初始化自定义组件时被@BuilderParam修饰的属性必须赋值。
-
-### 引入动机
-
-当开发者创建自定义组件，并想对该组件添加特定功能时（例如在自定义组件中添加一个点击跳转操作）。若直接在组件内嵌入事件方法，将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题，引入了@BuilderParam装饰器，此装饰器修饰的属性值可为@Builder装饰的函数，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。
-
-### 参数初始化组件
-
-通过参数初始化组件时，将@Builder装饰的函数赋值给@BuilderParam修饰的属性，并在自定义组件内调用该属性值。若@BuilderParam修饰的属性在进行赋值时不带参数（如：`noParam: this.specificNoParam`），则此属性的类型需定义为无返回值的函数（如：`@BuilderParam noParam: () => void`）；若带参数（如：`withParam: this.SpecificWithParam('WithParamA')`），则此属性的类型需定义成any（如：`@BuilderParam withParam: any`）。
-
-```ts
-// xxx.ets
-@Component
-struct CustomContainer {
-  header: string = ''
-  @BuilderParam noParam: () => void
-  @BuilderParam withParam: any
-  footer: string = ''
-
-  build() {
-    Column() {
-      Text(this.header)
-        .fontSize(30)
-      this.noParam()
-      this.withParam()
-      Text(this.footer)
-        .fontSize(30)
-    }
-  }
-}
-
-@Entry
-@Component
-struct CustomContainerUser {
-  @Builder specificNoParam() {
-    Column() {
-      Text('noParam').fontSize(30)
-    }
-  }
-
-  @Builder SpecificWithParam(label: string) {
-    Column() {
-      Text(label).fontSize(30)
-    }
-  }
-
-  build() {
-    Column() {
-      CustomContainer({
-        header: 'HeaderA',
-        noParam: this.specificNoParam,
-        withParam: this.SpecificWithParam('WithParamA'),
-        footer: 'FooterA'
-      })
-      Divider()
-        .strokeWidth(3)
-        .margin(10)
-      CustomContainer({
-        header: 'HeaderB',
-        noParam: this.specificNoParam,
-        withParam: this.SpecificWithParam('WithParamB'),
-        footer: 'FooterB'
-      })
-    }
-  }
-}
-```
-
-![builder1](figures/builder1.PNG)
-
-### 尾随闭包初始化组件
-
-在自定义组件中使用@BuilderParam修饰的属性时也可通过尾随闭包进行初始化（在初始化自定义组件时，组件后紧跟一个大括号“{}”形成尾随闭包场景（`CustomContainer(){}`）。开发者可把尾随闭包看做一个容器，向其中填充内容，如在闭包内增加组件（`{Column(){...}`），闭包内语法规范与build函数一致。此场景下自定义组件内有且仅有一个使用@BuilderParam修饰的属性。
-
-示例：在闭包内添加Column组件并设置点击事件，在Column组件内调用@Builder修饰的specificParam函数，点击Column组件后将自定义组件CustomContainer中header的属性值由“header”改变为“changeHeader”。在初始化自定义组件CustomContainer时，尾随闭包的内容会被赋值给@BuilderParam修饰的closer属性。
-
-```ts
-// xxx.ets
-@Component
-struct CustomContainer {
-  header: string = ''
-  @BuilderParam closer: () => void
-
-  build() {
-    Column() {
-      Text(this.header)
-        .fontSize(30)
-      this.closer()
-    }
-  }
-}
-
-@Builder function specificParam(label1: string, label2: string) {
-  Column() {
-    Text(label1)
-      .fontSize(30)
-    Text(label2)
-      .fontSize(30)
-  }
-}
-
-@Entry
-@Component
-struct CustomContainerUser {
-  @State text: string = 'header'
-
-  build() {
-    Column() {
-      CustomContainer({
-        header: this.text,
-      }) {
-        Column() {
-          specificParam('testA', 'testB')
-        }.backgroundColor(Color.Yellow)
-        .onClick(() => {
-          this.text = 'changeHeader'
-        })
-      }
-    }
-  }
-}
-```
-
-![builder2](figures/builder2.gif)
-
-## @Styles
-
-ArkTS为了避免开发者对重复样式的设置，通过@Styles装饰器可以将多个样式设置提炼成一个方法，直接在组件声明时调用，通过@Styles装饰器可以快速定义并复用自定义样式。当前@Styles仅支持通用属性。
-
-@Styles可以定义在组件内或组件外，在组件外定义时需在方法名前面添加function关键字，组件内定义时则不需要添加function关键字。
-
-```ts
-// xxx.ets
-@Styles function globalFancy () {
-  .width(150)
-  .height(100)
-  .backgroundColor(Color.Pink)
-}
-
-@Entry
-@Component
-struct FancyUse {
-  @Styles componentFancy() {
-    .width(100)
-    .height(200)
-    .backgroundColor(Color.Yellow)
-  }
-
-  build() {
-    Column({ space: 10 }) {
-      Text('FancyA')
-        .globalFancy()
-        .fontSize(30)
-      Text('FancyB')
-        .globalFancy()
-        .fontSize(20)
-      Text('FancyC')
-        .componentFancy()
-        .fontSize(30)
-      Text('FancyD')
-        .componentFancy()
-        .fontSize(20)
-    }
-  }
-}
-```
-
-![styles](figures/styles.PNG)
-
-@Styles还可以在[StateStyles](../reference/arkui-ts/ts-universal-attributes-polymorphic-style.md)属性内部使用，在组件处于不同的状态时赋予相应的属性。
-
-在StateStyles内可以直接调用组件外定义的@Styles方法，但需要通过this关键字调用组件内定义的@Styles方法。
-
-```ts
-// xxx.ets
-@Styles function globalFancy () {
-  .width(120)
-  .height(120)
-  .backgroundColor(Color.Green)
-}
-
-@Entry
-@Component
-struct FancyUse {
-  @Styles componentFancy() {
-    .width(80)
-    .height(80)
-    .backgroundColor(Color.Red)
-  }
-
-  build() {
-    Row({ space: 10 }) {
-      Button('Fancy')
-        .stateStyles({
-          normal: {
-            .width(100)
-            .height(100)
-            .backgroundColor(Color.Blue)
-          },
-          disabled: this.componentFancy,
-          pressed: globalFancy
-        })
-    }
-  }
-}
-```
-
-![styles1](figures/styles1.gif)
-
-## @Extend
-
-@Extend装饰器将新的属性方法添加到Text、Column、Button等内置组件上，通过@Extend装饰器可以快速地扩展原生组件。@Extend不能定义在自定义组件struct内。
-
-```ts
-// xxx.ets
-@Extend(Text) function fancy (fontSize: number) {
-  .fontColor(Color.Red)
-  .fontSize(fontSize)
-  .fontStyle(FontStyle.Italic)
-  .fontWeight(600)
-}
-
-@Entry
-@Component
-struct FancyUse {
-  build() {
-    Row({ space: 10 }) {
-      Text("Fancy")
-        .fancy(16)
-      Text("Fancy")
-        .fancy(24)
-      Text("Fancy")
-        .fancy(32)
-    }
-  }
-}
-
-```
-
-> **说明：**
->
-> - @Extend装饰器不能定义在自定义组件struct内。
-> - @Extend装饰器内仅支持属性方法设置。
-
-![extend](figures/extend.PNG)
-
-## @CustomDialog
-
-@CustomDialog装饰器用于装饰自定义弹窗组件，使得弹窗可以动态设置内容及样式。
-
-```ts
-// xxx.ets
-@CustomDialog
-struct DialogExample {
-  controller: CustomDialogController
-  action: () => void
-
-  build() {
-    Row() {
-      Button('Close CustomDialog')
-        .onClick(() => {
-          this.controller.close()
-          this.action()
-        })
-    }.padding(20)
-  }
-}
-
-@Entry
-@Component
-struct CustomDialogUser {
-  dialogController: CustomDialogController = new CustomDialogController({
-    builder: DialogExample({ action: this.onAccept }),
-    cancel: this.existApp,
-    autoCancel: true
-  });
-
-  onAccept() {
-    console.info('onAccept');
-  }
-
-  existApp() {
-    console.info('Cancel dialog!');
-  }
-
-  build() {
-    Column() {
-      Button('Click to open Dialog')
-        .onClick(() => {
-          this.dialogController.open()
-        })
-    }
-  }
-}
-```
-
-![customdialog](figures/customDialog.gif)
\ No newline at end of file

zh-cn/application-dev/quick-start/arkts-environment.md

+# Environment：设备环境查询
+
+
+开发者如果需要应用程序运行的设备的环境参数，以此来作出不同的场景判断，比如多语言，暗黑模式等，需要用到Environment设备环境查询。
+
+
+Environment是ArkUI框架在应用程序启动时创建的单例对象。它为AppStorage提供了一系列描述应用程序运行状态的属性。Environment的所有属性都是不可变的（即应用不可写入），所有的属性都是简单类型。
+
+
+## 使用场景
+
+
+### 从UI中访问Environment参数
+
+- 使用Environment.EnvProp将设备运行的环境变量存入AppStorage中：
+
+  ```ts
+  // 将设备的语言code存入AppStorage，默认值为en
+  // 后续设备的预览设置切换，都将同步到AppStorage中
+  Environment.EnvProp('languageCode', 'en');
+  ```
+
+- 可以使用\@StorageProp链接到Component中。Component会根据设备运行环境的变化而更新：
+
+  ```ts
+  @StorageProp('languageCode') lang : string = 'en';
+  ```
+
+设备环境到Component的更新链：Environment --> AppStorage -->Component。
+
+> **说明：**
+> \@StorageProp关联的环境参数可以在本地更改，但不能同步回AppStorage中，因为应用对环境变量参数是不可写的，只能在Environment中查询。
+
+
+```ts
+// 将设备languageCode存入AppStorage中
+Environment.EnvProp('languageCode', 'en');
+let enable = AppStorage.Get('languageCode');
+
+@Entry
+@Component
+struct Index {
+  @StorageProp('languageCode') languageCode: string = 'en';
+
+  build() {
+    Row() {
+      Column() {
+        // 输出当前设备的languageCode
+        Text(this.languageCode)
+      }
+    }
+  }
+}
+```
+
+
+### 应用逻辑使用Environment
+
+
+```ts
+// 使用Environment.EnvProp将设备运行languageCode存入AppStorage中；
+Environment.EnvProp('languageCode', 'en');
+// 从AppStorage获取单向绑定的languageCode的变量
+const lang: SubscribedAbstractProperty<string> = AppStorage.Prop('languageCode');
+
+if (lang.get() === 'zh') {
+  console.info('你好');
+} else {
+  console.info('Hello!');
+}
+```

zh-cn/application-dev/quick-start/arkts-extend.md

+# \@Extend：定义扩展组件样式
+
+
+在前文的示例中，可以使用\@Styles用于样式的扩展，在\@Styles的基础上，我们提供了\@Extend，用于扩展原生组件样式。
+
+
+> **说明：**
+> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+
+## 装饰器使用说明
+
+
+### 语法
+
+
+```ts
+@Extend(UIComponentName) function functionName { ... }
+```
+
+
+### 使用规则
+
+- 和\@Styles不同，\@Extend仅支持定义在全局，不支持在组件内部定义。
+
+- 和\@Styles不同，\@Extend支持封装指定的组件的私有属性和私有事件和预定义相同组件的\@Extend的方法。
+
+  ```ts
+  // @Extend(Text)可以支持Text的私有属性fontColor
+  @Extend(Text) function fancy () {
+    .fontColor(Color.Red)
+  }
+  // superFancyText可以调用预定义的fancy
+  @Extend(Text) function superFancyText(size:number) {
+      .fontSize(size)
+      .fancy()
+  }
+  ```
+
+
+- 和\@Styles不同，\@Extend装饰的方法支持参数，开发者可以在调用时传递参数，调用遵循TS方法传值调用。
+
+  ```ts
+  // xxx.ets
+  @Extend(Text) function fancy (fontSize: number) {
+    .fontColor(Color.Red)
+    .fontSize(fontSize)
+  }
+
+  @Entry
+  @Component
+  struct FancyUse {
+    build() {
+      Row({ space: 10 }) {
+        Text('Fancy')
+          .fancy(16)
+        Text('Fancy')
+          .fancy(24)
+      }
+    }
+  }
+  ```
+
+- \@Extend装饰的方法的参数可以为function，作为Event事件的句柄。
+
+  ```ts
+  @Extend(Text) function makeMeClick(onClick: () => void) {
+    .backgroundColor(Color.Blue)
+    .onClick(onClick)
+  }
+
+  @Entry
+  @Component
+  struct FancyUse {
+    @State label: string = 'Hello World';
+
+    onClickHandler() {
+      this.label = 'Hello ArkUI';
+    }
+
+    build() {
+      Row({ space: 10 }) {
+        Text(`${this.label}`)
+          .makeMeClick(this.onClickHandler.bind(this))
+      }
+    }
+  }
+  ```
+
+- \@Extend的参数可以为[状态变量](arkts-state-management-overview.md)，当状态变量改变时，UI可以正常的被刷新渲染。
+
+  ```ts
+  @Extend(Text) function fancy (fontSize: number) {
+    .fontColor(Color.Red)
+    .fontSize(fontSize)
+  }
+
+  @Entry
+  @Component
+  struct FancyUse {
+    @State fontSizeValue: number = 20
+    build() {
+      Row({ space: 10 }) {
+        Text('Fancy')
+          .fancy(this.fontSizeValue)
+          .onClick(() => {
+            this.fontSizeValue = 30
+          })
+      }
+    }
+  }
+  ```
+
+
+## 使用场景
+
+以下示例声明了3个Text组件，每个Text组件均设置了fontStyle、fontWeight和backgroundColor样式。
+
+
+```ts
+@Entry
+@Component
+struct FancyUse {
+  @State label: string = 'Hello World'
+
+  build() {
+    Row({ space: 10 }) {
+      Text(`${this.label}`)
+        .fontStyle(FontStyle.Italic)
+        .fontWeight(100)
+        .backgroundColor(Color.Blue)
+      Text(`${this.label}`)
+        .fontStyle(FontStyle.Italic)
+        .fontWeight(200)
+        .backgroundColor(Color.Pink)
+      Text(`${this.label}`)
+        .fontStyle(FontStyle.Italic)
+        .fontWeight(300)
+        .backgroundColor(Color.Orange)
+    }.margin('20%')
+  }
+}
+```
+
+\@Extend将样式组合复用，示例如下。
+
+
+```ts
+@Extend(Text) function fancyText(weightValue: number, color: Color) {
+  .fontStyle(FontStyle.Italic)
+  .fontWeight(weightValue)
+  .backgroundColor(color)
+}
+```
+
+通过\@Extend组合样式后，使得代码更加简洁，增强可读性。
+
+
+```ts
+@Entry
+@Component
+struct FancyUse {
+  @State label: string = 'Hello World'
+
+  build() {
+    Row({ space: 10 }) {
+      Text(`${this.label}`)
+        .fancyText(100, Color.Blue)
+      Text(`${this.label}`)
+        .fancyText(200, Color.Pink)
+      Text(`${this.label}`)
+        .fancyText(200, Color.Orange)
+    }.margin('20%')
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-get-started.md

 # 初识ArkTS语言
 
-ArkTS是OpenHarmony优选的主力应用开发语言。ArkTS基于TypeScript（简称TS）语言扩展而来，是TS的超集。 
 
-- ArkTS继承了TS的所有特性。
+ArkTS是OpenHarmony优选的主力应用开发语言。ArkTS围绕应用开发在[TypeScript](https://www.typescriptlang.org/)（简称TS）生态基础上做了进一步扩展，继承了TS的所有特性，是TS的超集。因此，在学习ArkTS语言之前，建议开发者具备TS语言开发能力。
 
-- 当前，ArkTS在TS的基础上主要扩展了[声明式UI](arkts-basic-ui-description.md)能力，让开发者能够以更简洁、更自然的方式开发高性能应用。
 
-  当前扩展的声明式UI能力包括如下特性。
+当前，ArkTS在TS的基础上主要扩展了如下能力：
 
-  - [基本UI描述](arkts-basic-ui-description.md)：ArkTS定义了各种装饰器、自定义组件、UI描述机制，再配合UI开发框架中的内置组件及其相关的事件方法、属性方法等共同构成了UI开发的主体。
-  - [状态管理](arkts-state-mgmt-page-level.md)：ArkTS提供了多维度的状态管理机制，在UI开发框架中，和UI相关联的数据，不仅可以在组件内使用，还可以在不同组件层级间传递，比如父子组件之间、爷孙组件之间，也可以是应用全局范围内的传递，还可以是跨设备传递。另外，从数据的传递形式来看，可分为只读的单向传递和可变更的双向传递。开发者可以灵活的利用这些能力来实现数据和UI的联动。
-  - [动态构建UI元素](arkts-dynamic-ui-elememt-building.md)：ArkTS提供了动态构建UI元素的能力，不仅可以自定义组件内部的UI结构，还可以复用组件样式，扩展原生组件。
-  - [渲染控制](arkts-rendering-control.md)：ArkTS提供了渲染控制的能力。条件渲染可根据应用的不同状态，渲染对应状态下的UI内容。循环渲染可从数据源中迭代获取数据，并在每次迭代过程中创建相应的组件。
-  - [使用限制与扩展](arkts-restrictions-and-extensions.md)：ArkTS在使用过程中存在限制与约束，同时也扩展了双向绑定等能力。
 
-- 未来，ArkTS会结合应用开发/运行的需求持续演进，逐步提供并行和并发能力增强、系统类型增强、分布式开发范式等更多特性。
+- [基本语法](arkts-basic-syntax-overview.md)：ArkTS定义了声明式UI描述、自定义组件和动态扩展UI元素的能力，再配合ArkUI开发框架中的系统组件及其相关的事件方法、属性方法等共同构成了UI开发的主体。
 
-下面我们以一个具体的示例来说明ArkTS的基本组成。如下图所示的代码示例，UI界面包含两段文本、一条分割线和一个按钮，当开发者点击按钮时，文本内容会从'Hello World'变为 'Hello ArkUI'。
+- [状态管理](arkts-state-management-overview.md)：ArkTS提供了多维度的状态管理机制。在UI开发框架中，与UI相关联的数据可以在组件内使用，也可以在不同组件层级间传递，比如父子组件之间、爷孙组件之间，还可以在应用全局范围内传递或跨设备传递。另外，从数据的传递形式来看，可分为只读的单向传递和可变更的双向传递。开发者可以灵活的利用这些能力来实现数据和UI的联动。
 
-![arkts-get-started](figures/arkts-get-started.png)
+- [渲染控制](arkts-rendering-control-overview.md)：ArkTS提供了渲染控制的能力。条件渲染可根据应用的不同状态，渲染对应状态下的UI内容。循环渲染可从数据源中迭代获取数据，并在每次迭代过程中创建相应的组件。数据懒加载从数据源中按需迭代数据，并在每次迭代过程中创建相应的组件。
 
-这个示例中所包含的ArkTS声明式开发范式的基本组成说明如下：
 
-- 装饰器： 用于装饰类、结构、方法以及变量，赋予其特殊的含义，如上述示例中@Entry、@Component和@State都是装饰器。 具体而言，@Component表示这是个自定义组件；@Entry则表示这是个入口组件；@State表示这是组件中的状态变量，这个变量变化会触发UI刷新。
-- 自定义组件：可复用的UI单元，可组合其他组件，如上述被@Component装饰的struct Hello。
-- UI描述：声明式的方法来描述UI的结构，例如build()方法中的代码块。
-- 内置组件：ArkTS中默认内置的基础组件、容器组件、媒体组件、绘制组件、画布组件等各种组件，开发者可以直接调用，如示例中的Column、Text、Divider、Button等。
-- 属性方法：用于组件属性的配置，如fontSize()、width()、height()、color()等，可通过链式调用的方式设置多项属性。
-- 事件方法：用于添加组件对事件的响应逻辑，如跟随在Button后面的onClick()，同样可以通过链式调用的方式设置多个事件响应逻辑。
+未来，ArkTS会结合应用开发/运行的需求持续演进，逐步提供并行和并发能力增强、系统类型增强、分布式开发范式等更多特性。

zh-cn/application-dev/quick-start/arkts-link.md

+# \@Link：父子双向同步
+
+
+子组件中被\@Link装饰的变量与其父组件中对应的数据源建立双向数据绑定。
+
+
+> **说明：**
+> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+
+## 概述
+
+\@Link装饰的变量与其父组件中的数据源共享相同的值。
+
+
+## 装饰器使用规则说明
+
+| \@Link变量装饰器 | 说明                                       |
+| ----------- | ---------------------------------------- |
+| 装饰器参数       | 无                                        |
+| 同步类型        | 双向同步。<br/>父组件中\@State,&nbsp;\@StorageLink和\@Link&nbsp;和子组件\@Link可以建立双向数据同步，反之亦然。 |
+| 允许装饰的变量类型   | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化](#观察变化)。<br/>类型必须被指定，且和双向绑定状态变量的类型相同。<br/>不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。<br/>**说明：**<br/>不支持Length、ResourceStr、ResourceColor类型，Length、ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。 |
+| 被装饰变量的初始值   | 无，禁止本地初始化。                               |
+
+
+## 变量的传递/访问规则说明
+
+| 传递/访问      | 说明                                       |
+| ---------- | ---------------------------------------- |
+| 从父组件初始化和更新 | 必选。与父组件\@State,&nbsp;\@StorageLink和\@Link&nbsp;建立双向绑定。允许父组件中\@State、\@Link、\@Prop、\@Provide、\@Consume、\@ObjectLink、\@StorageLink、\@StorageProp、\@LocalStorageLink和\@LocalStorageProp装饰变量初始化子组件\@Link。<br/>从API&nbsp;version&nbsp;9开始，\@Link子组件从父组件初始化\@State的语法为Comp({&nbsp;aLink:&nbsp;this.aState&nbsp;})。同样Comp({aLink:&nbsp;$aState})也支持。 |
+| 用于初始化子组件   | 允许，可用于初始化常规变量、\@State、\@Link、\@Prop、\@Provide。 |
+| 是否支持组件外访问  | 私有，只能在所属组件内访问。                           |
+
+  **图1** 初始化规则图示  
+
+![zh-cn_image_0000001502092556](figures/zh-cn_image_0000001502092556.png)
+
+
+## 观察变化和行为表现
+
+
+### 观察变化
+
+- 当装饰的数据类型为boolean、string、number类型时，可以同步观察到数值的变化，示例请参考[简单类型和类对象类型的@Link](#简单类型和类对象类型的link)。
+
+- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性，示例请参考[简单类型和类对象类型的@Link](#简单类型和类对象类型的link)。
+
+- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化，示例请参考[数组类型的@Link](#数组类型的link)。
+
+
+### 框架行为
+
+\@Link装饰的变量和其所述的自定义组件共享生命周期。
+
+为了了解\@Link变量初始化和更新机制，有必要先了解父组件和和拥有\@Link变量的子组件的关系，初始渲染和双向更新的流程（以父组件为\@State为例）。
+
+1. 初始渲染：执行父组件的build()函数后将创建子组件的新实例。初始化过程如下：
+   1. 必须指定父组件中的\@State变量，用于初始化子组件的\@Link变量。子组件的\@Link变量值与其父组件的数据源变量保持同步（双向数据同步）。
+   2. 父组件的\@State状态变量包装类通过构造函数传给子组件，子组件的\@Link包装类拿到父组件的\@State的状态变量后，将当前\@Link包装类this指针注册给父组件的\@State变量。
+
+2. \@Link的数据源的更新：即父组件中状态变量更新，引起相关子组件的\@Link的更新。处理步骤：
+   1. 通过初始渲染的步骤可知，子组件\@Link包装类把当前this指针注册给父组件。父组件\@State变量变更后，会遍历更新所有依赖它的系统组件（elementid）和状态变量（比如\@Link包装类）。
+   2. 通知\@Link包装类更新后，子组件中所有依赖\@Link状态变量的系统组件（elementId）都会被通知更新。以此实现父组件对子组件的状态数据同步。
+
+3. \@Link的更新：当子组件中\@Link更新后，处理步骤如下（以父组件为\@State为例）：
+   1. \@Link更新后，调用父组件的\@State包装类的set方法，将更新后的数值同步回父组件。
+   2. 子组件\@Link和父组件\@State分别遍历依赖的系统组件，进行对应的UI的更新。以此实现子组件\@Link同步回父组件\@State。
+
+
+## 使用场景
+
+
+### 简单类型和类对象类型的\@Link
+
+以下示例中，点击父组件ShufflingContainer中的“Parent View: Set yellowButton”和“Parent View: Set GreenButton”，可以从父组件将变化同步给子组件，子组件GreenButton和YellowButton中\@Link装饰变量的变化也会同步给其父组件。
+
+
+```ts
+class GreenButtonState {
+  width: number = 0;
+  constructor(width: number) {
+    this.width = width;
+  }
+}
+@Component
+struct GreenButton {
+  @Link greenButtonState: GreenButtonState;
+  build() {
+    Button('Green Button')
+      .width(this.greenButtonState.width)
+      .height(150.0)
+      .backgroundColor('#00ff00')
+      .onClick(() => {
+        if (this.greenButtonState.width < 700) {
+          // 更新class的属性，变化可以被观察到同步回父组件
+          this.greenButtonState.width += 125;
+        } else {
+          // 更新class，变化可以被观察到同步回父组件
+          this.greenButtonState = new GreenButtonState(100);
+        }
+      })
+  }
+}
+@Component
+struct YellowButton {
+  @Link yellowButtonState: number;
+  build() {
+    Button('Yellow Button')
+      .width(this.yellowButtonState)
+      .height(150.0)
+      .backgroundColor('#ffff00')
+      .onClick(() => {
+        // 子组件的简单类型可以同步回父组件
+        this.yellowButtonState += 50.0;
+      })
+  }
+}
+@Entry
+@Component
+struct ShufflingContainer {
+  @State greenButtonState: GreenButtonState = new GreenButtonState(300);
+  @State yellowButtonProp: number = 100;
+  build() {
+    Column() {
+      // 简单类型从父组件@State向子组件@Link数据同步
+      Button('Parent View: Set yellowButton')
+        .onClick(() => {
+          this.yellowButtonProp = (this.yellowButtonProp < 700) ? this.yellowButtonProp + 100 : 100;
+        })
+      // class类型从父组件@State向子组件@Link数据同步
+      Button('Parent View: Set GreenButton')
+        .onClick(() => {
+          this.greenButtonState.width = (this.greenButtonState.width < 700) ? this.greenButtonState.width + 100 : 100;
+        })
+      // class类型初始化@Link
+      GreenButton({ greenButtonState: $greenButtonState })
+      // 简单类型初始化@Link
+      YellowButton({ yellowButtonState: $yellowButtonProp })
+    }
+  }
+}
+```
+
+
+### 数组类型的\@Link
+
+
+```ts
+@Component
+struct Child {
+  @Link items: number[];
+
+  build() {
+    Column() {
+      Button(`Button1: push`).onClick(() => {
+        this.items.push(this.items.length + 1);
+      })
+      Button(`Button2: replace whole item`).onClick(() => {
+        this.items = [100, 200, 300];
+      })
+    }
+  }
+}
+
+@Entry
+@Component
+struct Parent {
+  @State arr: number[] = [1, 2, 3];
+
+  build() {
+    Column() {
+      Child({ items: $arr })
+      ForEach(this.arr,
+        item => {
+          Text(`${item}`)
+        },
+        item => item.toString()
+      )
+    }
+  }
+}
+```
+
+
+上文所述，ArkUI框架可以观察到数组元素的添加，删除和替换。在该示例中\@State和\@Link的类型是相同的number[]，不允许将\@Link定义成number类型（\@Link item : number），并在父组件中用\@State数组中每个数据项创建子组件。如果要使用这个场景，可以参考[\@Prop](arkts-prop.md)和\@Observed。

zh-cn/application-dev/quick-start/arkts-localstorage.md

+# LocalStorage：页面级UI状态存储
+
+
+LocalStorage是页面级的UI状态存储，通过\@Entry装饰器接受的参数可以在页面内共享同一个LocalStorage实例。LocalStorage也可以在UIAbility内，页面间共享状态。
+
+
+本文仅介绍LocalStorage使用场景和相关的装饰器：\@LocalStorageProp和\@LocalStorageLink。
+
+
+> **说明：**
+>
+> 本模块从API version 9开始支持。
+
+
+## 概述
+
+LocalStorage是ArkTS为构建页面级别状态变量提供存储的内存内“数据库”。
+
+- 应用程序可以创建多个LocalStorage实例，LocalStorage实例可以在页面内共享，也可以通过GetShared接口，获取在UIAbility里创建的GetShared，实现跨页面、UIAbility内共享。
+
+- 组件树的根节点，即被\@Entry装饰的\@Component，可以被分配一个LocalStorage实例，此组件的所有子组件实例将自动获得对该LocalStorage实例的访问权限；
+
+- 被\@Component装饰的组件最多可以访问一个LocalStorage实例和[AppStorage](arkts-appstorage.md)，未被\@Entry装饰的组件不可被独立分配LocalStorage实例，只能接受父组件通过\@Entry传递来的LocalStorage实例。一个LocalStorage实例在组件树上可以被分配给多个组件。
+
+- LocalStorage中的所有属性都是可变的。
+
+应用程序决定LocalStorage对象的生命周期。当应用释放最后一个指向LocalStorage的引用时，比如销毁最后一个自定义组件，LocalStorage将被JS Engine垃圾回收。
+
+LocalStorage根据与\@Component装饰的组件的的同步类型不同，提供了两个装饰器：
+
+- [@LocalStorageProp](#localstorageprop)：\@LocalStorageProp装饰的变量和与LocalStorage中给定属性建立单行同步关系。
+
+- [@LocalStorageLink](#localstoragelink)：\@LocalStorageLink装饰的变量和在\@Component中创建与LocalStorage中给定属性建立双向同步关系。
+
+
+## 限制条件
+
+LocalStorage创建后，命名属性的类型不可更改。后续调用Set时必须使用相同类型的值。
+
+
+## \@LocalStorageProp
+
+在上文中已经提到，如果要建立LocalStorage和自定义组件的联系，需要使用\@LocalStorageProp和\@LocalStorageLink装饰器。使用\@LocalStorageProp(key)/\@LocalStorageLink(key)装饰组件内的变量，key标识了LocalStorage的属性。
+
+
+当自定义组件初始化的时候，\@LocalStorageProp(key)/\@LocalStorageLink(key)装饰的变量会通过给定的key，绑定在LocalStorage对应是属性，完成初始化。本地初始化是必要的，因为无法保证LocalStorage一定存在给定的key（这取决于应用逻辑，是否在组件初始化之前在LocalStorage实例中存入对应的属性）。
+
+
+> **说明：**
+>
+> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+
+\@LocalStorageProp(key)是和LocalStorage中key对应的属性建立单向数据同步，我们允许本地改变的发生，但是对于\@LocalStorageProp，本地的修改永远不会同步回LocalStorage中，相反，如果LocalStorage给定key的属性发生改变，改变会被同步给\@LocalStorageProp，并覆盖掉本地的修改。
+
+
+### 装饰器使用规则说明
+
+| \@LocalStorageProp变量装饰器 | 说明                                       |
+| ----------------------- | ---------------------------------------- |
+| 装饰器参数                   | key：常量字符串，必填（字符串需要有引号）。                  |
+| 允许装饰的变量类型               | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化和行为表现](#观察变化和行为表现)。<br/>类型必须被指定，且必须和LocalStorage中对应属性相同。不支持any，不允许使用undefined和null。 |
+| 同步类型                    | 单向同步：从LocalStorage的对应属性到组件的状态变量。组件本地的修改是允许的，但是LocalStorage中给定的属性一旦发生变化，将覆盖本地的修改。 |
+| 被装饰变量的初始值               | 必须指定，如果LocalStorage实例中不存在属性，则作为初始化默认值，并存入LocalStorage中。 |
+
+
+### 变量的传递/访问规则说明
+
+| 传递/访问      | 说明                                       |
+| ---------- | ---------------------------------------- |
+| 从父节点初始化和更新 | 禁止，\@LocalStorageProp不支持从父节点初始化，只能从LocalStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
+| 初始化子节点     | 支持，可用于初始化\@State、\@Link、\@Prop、\@Provide。 |
+| 是否支持组件外访问  | 否。                                       |
+
+  **图1** \@LocalStorageProp初始化规则图示  
+
+![zh-cn_image_0000001501936014](figures/zh-cn_image_0000001501936014.png)
+
+
+### 观察变化和行为表现
+
+**观察变化**
+
+
+- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。
+
+- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性。
+
+- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化。
+
+
+**框架行为**
+
+
+- 当\@LocalStorageProp(key)装饰的数值改变被观察到时，修改不会被同步回LocalStorage对应属性键值key的属性中。
+
+- 当前\@LocalStorageProp(key)单向绑定的数据会被修改，即仅限于当前组件的私有成员变量改变，其他的绑定该key的数据不会同步改变。
+
+- 当\@LocalStorageProp(key)装饰的数据本身是状态变量，它的改变虽然不会同步回LocalStorage中，但是会引起所属的自定义组件的重新渲染。
+
+- 当LocalStorage中key对应的属性发生改变时，会同步给所有\@LocalStorageProp(key)装饰的数据，\@LocalStorageProp(key)本地的修改将被覆盖。
+
+
+## \@LocalStorageLink
+
+如果我们需要将自定义组件的状态变量的更新同步回LocalStorage，就需要用到\@LocalStorageLink。
+
+\@LocalStorageLink(key)是和LocalStorage中key对应的属性建立双向数据同步：
+
+1. 本地修改发生，该修改会被回LocalStorage中；
+
+2. LocalStorage中的修改发生后，该修改会被同步到所有绑定LocalStorage对应key的属性上，包括单向（\@LocalStorageProp和通过prop创建的单向绑定变量）、双向（\@LocalStorageLink和通过link创建的双向绑定变量）变量。
+
+
+### 装饰器使用规则说明
+
+| \@LocalStorageLink变量装饰器 | 说明                                       |
+| ----------------------- | ---------------------------------------- |
+| 装饰器参数                   | key：常量字符串，必填（字符串需要有引号）。                  |
+| 允许装饰的变量类型               | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化和行为表现](#观察变化和行为表现)。<br/>类型必须被指定，且必须和LocalStorage中对应属性相同。不支持any，不允许使用undefined和null。 |
+| 同步类型                    | 双向同步：从LocalStorage的对应属性到自定义组件，从自定义组件到LocalStorage对应属性。 |
+| 被装饰变量的初始值               | 必须指定，如果LocalStorage实例中不存在属性，则作为初始化默认值，并存入LocalStorage中。 |
+
+
+### 变量的传递/访问规则说明
+
+| 传递/访问      | 说明                                       |
+| ---------- | ---------------------------------------- |
+| 从父节点初始化和更新 | 禁止，\@LocalStorageLink不支持从父节点初始化，只能从LocalStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
+| 初始化子节点     | 支持，可用于初始化\@State、\@Link、\@Prop、\@Provide。 |
+| 是否支持组件外访问  | 否。                                       |
+
+
+  **图2** \@LocalStorageLink初始化规则图示  
+
+
+![zh-cn_image_0000001552855957](figures/zh-cn_image_0000001552855957.png)
+
+
+### 观察变化和行为表现
+
+**观察变化**
+
+
+- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。
+
+- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性。
+
+- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化。
+
+
+**框架行为**
+
+
+1. 当\@LocalStorageLink(key)装饰的数值改变被观察到时，修改将被同步回LocalStorage对应属性键值key的属性中。
+
+2. LocalStorage中属性键值key对应的数据一旦改变，属性键值key绑定的所有的数据（包括双向\@LocalStorageLink和单向\@LocalStorageProp）都将同步修改；
+
+3. 当\@LocalStorageLink(key)装饰的数据本身是状态变量，它的改变不仅仅会同步回LocalStorage中，还会引起所属的自定义组件的重新渲染。
+
+
+## 使用场景
+
+
+### 应用逻辑使用LocalStorage
+
+
+```ts
+let storage = new LocalStorage({ 'PropA': 47 }); // 创建新实例并使用给定对象初始化
+let propA = storage.get('PropA') // propA == 47
+let link1 = storage.link('PropA'); // link1.get() == 47
+let link2 = storage.link('PropA'); // link2.get() == 47
+let prop = storage.prop('PropA'); // prop.get() = 47
+link1.set(48); // two-way sync: link1.get() == link2.get() == prop.get() == 48
+prop.set(1); // one-way sync: prop.get()=1; but link1.get() == link2.get() == 48
+link1.set(49); // two-way sync: link1.get() == link2.get() == prop.get() == 49
+```
+
+
+### 从UI内部使用LocalStorage
+
+除了应用程序逻辑使用LocalStorage，还可以借助LocalStorage相关的两个装饰器\@LocalStorageProp和\@LocalStorageLink，在UI组件内部获取到LocalStorage实例中存储的状态变量。
+
+本示例以\@LocalStorage为例，展示了：
+
+- 使用构造函数创建LocalStorage实例storage；
+
+- 使用\@Entry装饰器将storage添加到CompA顶层组件中；
+
+- \@LocalStorageLink绑定LocalStorage对给定的属性，建立双向数据同步。
+
+  ```ts
+  // 创建新实例并使用给定对象初始化
+  let storage = new LocalStorage({ 'PropA': 47 });
+
+  @Component
+  struct Child {
+    // @LocalStorageLink变量装饰器与LocalStorage中的'ProA'属性建立双向绑定
+    @LocalStorageLink('PropA') storLink2: number = 1;
+
+    build() {
+      Button(`Child from LocalStorage ${this.storLink2}`)
+        // 更改将同步至LocalStorage中的'ProA'以及Parent.storLink1
+        .onClick(() => this.storLink2 += 1)
+    }
+  }
+  // 使LocalStorage可从@Component组件访问
+  @Entry(storage)
+  @Component
+  struct CompA {
+    // @LocalStorageLink变量装饰器与LocalStorage中的'ProA'属性建立双向绑定
+    @LocalStorageLink('PropA') storLink1: number = 1;
+
+    build() {
+      Column({ space: 15 }) {
+        Button(`Parent from LocalStorage ${this.storLink1}`) // initial value from LocalStorage will be 47, because 'PropA' initialized already
+          .onClick(() => this.storLink1 += 1)
+        // @Component子组件自动获得对CompA LocalStorage实例的访问权限。
+        Child()
+      }
+    }
+  }
+  ```
+
+
+### \@LocalStorageProp和LocalStorage单向同步的简单场景
+
+在下面的示例中，CompA 组件和Child组件分别在本地创建了与storage的'PropA'对应属性的单向同步的数据，我们可以看到：
+
+- CompA中对this.storProp1的修改，只会在CompA中生效，并没有同步回storage；
+
+- Child组件中，Text绑定的storProp2 依旧显示47。
+
+  ```ts
+  // 创建新实例并使用给定对象初始化
+  let storage = new LocalStorage({ 'PropA': 47 });
+  // 使LocalStorage可从@Component组件访问
+  @Entry(storage)
+  @Component
+  struct CompA {
+    // @LocalStorageProp变量装饰器与LocalStorage中的'ProA'属性建立单向绑定
+    @LocalStorageProp('PropA') storProp1: number = 1;
+
+    build() {
+      Column({ space: 15 }) {
+        // 点击后从47开始加1，只改变当前组件显示的storProp1，不会同步到LocalStorage中
+        Button(`Parent from LocalStorage ${this.storProp1}`)
+          .onClick(() => this.storProp1 += 1)
+        Child()
+      }
+    }
+  }
+
+  @Component
+  struct Child {
+    // @LocalStorageProp变量装饰器与LocalStorage中的'ProA'属性建立单向绑定
+    @LocalStorageProp('PropA') storProp2: number = 2;
+
+    build() {
+      Column({ space: 15 }) {
+        // 当CompA改变时，当前storProp2不会改变，显示47
+        Text(`Parent from LocalStorage ${this.storProp2}`)
+      }
+    }
+  }
+  ```
+
+
+### \@LocalStorageLink和LocalStorage双向同步的简单场景
+
+下面的示例展示了\@LocalStorageLink装饰的数据和LocalStorage双向同步的场景
+
+
+```ts
+// 构造LocalStorage实例
+let storage = new LocalStorage({ 'PropA': 47 });
+// 调用link9+接口构造'PropA'的双向同步数据，linkToPropA 是全部变量
+let linkToPropA = storage.link('PropA');
+
+@Entry(storage)
+@Component
+struct CompA {
+
+  // @LocalStorageLink('PropA')在CompA自定义组件中创建'PropA'的双向同步数据，初始值为47，因为在构造LocalStorage已经给“PropA”设置47
+  @LocalStorageLink('PropA') storLink: number = 1;
+
+  build() {
+    Column() {
+      Text(`incr @LocalStorageLink variable`)
+        // 点击“incr @LocalStorageLink variable”，this.storLink加1，改变同步回storage，全局变量linkToPropA也会同步改变 
+
+        .onClick(() => this.storLink += 1)
+
+      // 并不建议在组件内使用全局变量linkToPropA.get()，因为可能会有生命周期不同引起的错误。
+      Text(`@LocalStorageLink: ${this.storLink} - linkToPropA: ${linkToPropA.get()}`)
+    }
+  }
+}
+```
+
+
+### 兄弟节点之间同步状态变量
+
+下面的示例展示了通过\@LocalStorageLink双向同步兄弟节点之间的状态。
+
+先看Parent自定义组件中发生的变化：
+
+1. 点击“countStorage ${this.playCount} incr by 1”，this.playCount减1，修改同步回LocalStorage中，Child组件中的playCountLink绑定的组件会同步刷新；
+
+2. 点击“countStorage ${this.playCount} incr by 1”，调用LocalStorage的set接口，更新LocalStorage中“countStorage”对应的属性，Child组件中的playCountLink绑定的组件会同步刷新；
+
+3. Text组件“playCount in LocalStorage for debug ${storage.get&lt;number&gt;('countStorage')}”没有同步刷新，原因是因为storage.get&lt;number&gt;('countStorage')返回的是常规变量，常规变量的更新并不会引起Text组件的重新渲染。
+
+Child自定义组件中的变化：
+
+1. playCountLink的刷新会同步回LocalStorage，并且引起兄弟组件和父组件相应的刷新。
+
+   ```ts
+   let storage = new LocalStorage({ countStorage: 1 });
+
+   @Component
+   struct Child {
+     // 子组件实例的名字
+     label: string = 'no name';
+     // 和LocalStorage中“countStorage”的双向绑定数据
+     @LocalStorageLink('countStorage') playCountLink: number = 0;
+
+     build() {
+       Row() {
+         Text(this.label)
+           .width(50).height(60).fontSize(12)
+         Text(`playCountLink ${this.playCountLink}: inc by 1`)
+           .onClick(() => {
+             this.playCountLink += 1;
+           })
+           .width(200).height(60).fontSize(12)
+       }.width(300).height(60)
+     }
+   }
+
+   @Entry(storage)
+   @Component
+   struct Parent {
+     @LocalStorageLink('countStorage') playCount: number = 0;
+
+     build() {
+       Column() {
+         Row() {
+           Text('Parent')
+             .width(50).height(60).fontSize(12)
+           Text(`playCount ${this.playCount} dec by 1`)
+             .onClick(() => {
+               this.playCount -= 1;
+             })
+             .width(250).height(60).fontSize(12)
+         }.width(300).height(60)
+
+         Row() {
+           Text('LocalStorage')
+             .width(50).height(60).fontSize(12)
+           Text(`countStorage ${this.playCount} incr by 1`)
+             .onClick(() => {
+               storage.set<number>('countStorage', 1 + storage.get<number>('countStorage'));
+             })
+             .width(250).height(60).fontSize(12)
+         }.width(300).height(60)
+
+         Child({ label: 'ChildA' })
+         Child({ label: 'ChildB' })
+
+         Text(`playCount in LocalStorage for debug ${storage.get<number>('countStorage')}`)
+           .width(300).height(60).fontSize(12)
+       }
+     }
+   }
+   ```
+
+
+### 将LocalStorage实例从UIAbility共享到一个或多个视图
+
+上面的实例中，LocalStorage的实例仅仅在一个\@Entry装饰的组件和其所属的子组件（一个页面）中共享，如果希望其在多个视图中共享，可以在所属UIAbility中创建LocalStorage实例，并调用windowStage.[loadContent](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-window.md#loadcontent9)。
+
+
+```ts
+// EntryAbility.ts
+import UIAbility from '@ohos.app.ability.UIAbility';
+import window from '@ohos.window';
+
+export default class EntryAbility extends UIAbility {
+  storage: LocalStorage = new LocalStorage({
+    'PropA': 47
+  });
+
+  onWindowStageCreate(windowStage: window.WindowStage) {
+    windowStage.loadContent('pages/Index', this.storage);
+  }
+}
+```
+
+在UI页面通过GetShared接口获取在通过loadContent共享的LocalStorage实例。
+
+
+```ts
+// 通过GetShared接口获取stage共享的Storage实例
+let storage = LocalStorage.GetShared()
+
+@Entry(storage)
+@Component
+struct CompA {
+  // can access LocalStorage instance using 
+  // @LocalStorageLink/Prop decorated variables
+  @LocalStorageLink('PropA') varA: number = 1;
+
+  build() {
+    Column() {
+      Text(`${this.varA}`).fontSize(50)
+    }
+  }
+}
+```
+
+
+> **说明：**
+>
+> 对于开发者更建议使用这个方式来构建LocalStorage的实例，并且在创建LocalStorage实例的时候就写入默认值，因为默认值可以作为运行异常的备份，也可以用作页面的单元测试。

zh-cn/application-dev/quick-start/arkts-observed-and-objectlink.md

+# \@Observed和\@ObjectLink：嵌套类对象属性变化
+
+
+上文所述的装饰器仅能观察到第一层的变化，但是在实际应用开发中，应用会根据开发需要，封装自己的数据模型。对于多层嵌套的情况，比如二维数组，或者数组项class，或者class的属性是class，他们的第二层的属性变化是无法观察到的。这就引出了\@Observed/\@ObjectLink装饰器。
+
+
+> **说明：**
+> 从API version 9开始，这两个装饰器支持在ArkTS卡片中使用。
+
+
+## 概述
+
+\@ObjectLink和\@Observed类装饰器用于在涉及嵌套对象或数组的场景中进行双向数据同步：
+
+- 被\@Observed装饰的类，可以被观察到属性的变化；
+
+- 子组件中\@ObjectLink装饰器装饰的状态变量用于接受\@Observed装饰的类的实例，和父组件中对应的状态变量建立双向数据绑定。这个实例可以是数组中的被\@Observed装饰的项，或者是class object中是属性，这个属性同样也需要被\@Observed装饰。
+
+- 单独使用\@Observed是没有任何作用的，需要搭配\@ObjectLink或者[\@Prop](arkts-prop.md)使用。
+
+
+## 装饰器说明
+
+| \@Observed类装饰器 | 说明                                |
+| -------------- | --------------------------------- |
+| 装饰器参数          | 无                                 |
+| 类装饰器           | 装饰class。需要放在class的定义前，使用new创建类对象。 |
+
+| \@ObjectLink变量装饰器 | 说明                                       |
+| ----------------- | ---------------------------------------- |
+| 装饰器参数             | 无                                        |
+| 同步类型              | 不与父组件中的任何类型同步变量。                         |
+| 允许装饰的变量类型         | 必须为被\@Observed装饰的class实例，必须指定类型。<br/>不支持简单类型，可以使用[\@Prop](arkts-prop.md)。<br/>\@ObjectLink的属性是可以改变的，但是变量的分配是不允许的，也就是说这个装饰器装饰变量是只读的，不能被改变。 |
+| 被装饰变量的初始值         | 不允许。                                     |
+
+\@ObjectLink装饰的数据为可读示例。
+
+
+```ts
+// 允许@ObjectLink装饰的数据属性赋值
+this.objLink.a= ...
+// 不允许@ObjectLink装饰的数据自身赋值
+this.objLink= ...
+```
+
+> **说明：**
+>
+> \@ObjectLink装饰的变量不能被赋值，如果要使用赋值操作，请使用[@Prop](arkts-prop.md)。
+>
+> - \@Prop装饰的变量和数据源的关系是是单向同步，\@Prop装饰的变量在本地拷贝了数据源，所以它允许本地更改，如果父组件中的数据源有更新，\@Prop装饰的变量本地的修改将被覆盖；
+>
+> - \@ObjectLink装饰的变量和数据源的关系是双向同步，\@ObjectLink装饰的变量相当于指向数据源的指针。如果一旦发生\@ObjectLink装饰的变量的赋值，则同步链将被打断。
+
+
+## 变量的传递/访问规则说明
+
+| \@ObjectLink传递/访问 | 说明                                       |
+| ----------------- | ---------------------------------------- |
+| 从父组件初始化           | 必须指定。<br/>初始化\@ObjectLink装饰的变量必须同时满足以下场景：<br/>-&nbsp;类型必须是\@Observed装饰的class。<br/>-&nbsp;初始化的数值需要是数组项，或者class的属性。<br/>-&nbsp;同步源的class或者数组必须是\@State，\@Link，\@Provide，\@Consume或者\@ObjectLink装饰的数据。<br/>同步源是数组项的示例请参考[对象数组](#对象数组)。初始化的class的示例请参考[嵌套对象](#嵌套对象)。 |
+| 与源对象同步            | 双向。                                      |
+| 可以初始化子组件          | 允许，可用于初始化常规变量、\@State、\@Link、\@Prop、\@Provide |
+
+
+  **图1** 初始化规则图示  
+
+
+![zh-cn_image_0000001502255262](figures/zh-cn_image_0000001502255262.png)
+
+
+## 观察变化和行为表现
+
+
+### 观察的变化
+
+\@Observed装饰的类，如果其属性为非简单类型，比如class、Object或者数组，也需要被\@Observed装饰，否则将观察不到其属性的变化。
+
+
+```ts
+class ClassA {
+  public c: number;
+
+  constructor(c: number) {
+    this.c = c;
+  }
+}
+
+@Observed
+class ClassB {
+  public a: ClassA;
+  public b: number;
+
+  constructor(a: ClassA, b: number) {
+    this.a = a;
+    this.b = b;
+  }
+}
+```
+
+以上示例中，ClassB被\@Observed装饰，其成员变量的赋值的变化是可以被观察到的，但对于ClassA，没有被\@Observed装饰，其属性的修改不能被观察到。
+
+
+```ts
+@ObjectLink b: ClassB
+
+// 赋值变化可以被观察到
+this.b.a = new ClassA(5)
+this.b.b = 5
+
+// ClassA没有被@Observed装饰，其属性的变化观察不到
+this.b.a.c = 5
+```
+
+\@ObjectLink：\@ObjectLink只能接受被\@Observed装饰class的实例，可以观察到：
+
+- 其属性的数值的变化，其中属性是指Object.keys(observedObject)返回的所有属性，示例请参考[嵌套对象](#嵌套对象)。
+
+- 如果数据源是数组，则可以观察到数组item的替换，如果数据源是class，可观察到class的属性的变化，示例请参考[对象数组](#对象数组)。
+
+
+### 框架行为
+
+1. 初始渲染：
+   1. \@Observed装饰的class的实例会被不透明的代理对象包装，代理了class上的属性的setter和getter方法
+   2. 子组件中\@ObjectLink装饰的从父组件初始化，接受被\@Observed装饰的class的实例，\@ObjectLink的包装类会将自己注册给\@Observed class。
+
+2. 属性更新：当\@Observed装饰的class属性改变时，会走到代理的setter和getter，然后遍历依赖它的\@ObjectLink包装类，通知数据更新。
+
+
+## 使用场景
+
+
+### 嵌套对象
+
+以下是嵌套类对象的数据结构。
+
+
+```ts
+// objectLinkNestedObjects.ets
+let NextID: number = 1;
+
+@Observed
+class ClassA {
+  public id: number;
+  public c: number;
+
+  constructor(c: number) {
+    this.id = NextID++;
+    this.c = c;
+  }
+}
+
+@Observed
+class ClassB {
+  public a: ClassA;
+
+  constructor(a: ClassA) {
+    this.a = a;
+  }
+}
+```
+
+
+  以下组件层次结构呈现的是此数据结构
+
+```ts
+@Component
+struct ViewA {
+  label: string = 'ViewA1';
+  @ObjectLink a: ClassA;
+
+  build() {
+    Row() {
+      Button(`ViewA [${this.label}] this.a.c=${this.a.c} +1`)
+        .onClick(() => {
+          this.a.c += 1;
+        })
+    }
+  }
+}
+
+@Entry
+@Component
+struct ViewB {
+  @State b: ClassB = new ClassB(new ClassA(0));
+
+  build() {
+    Column() {
+      ViewA({ label: 'ViewA #1', a: this.b.a })
+      ViewA({ label: 'ViewA #2', a: this.b.a })
+
+      Button(`ViewB: this.b.a.c+= 1`)
+        .onClick(() => {
+          this.b.a.c += 1;
+        })
+      Button(`ViewB: this.b.a = new ClassA(0)`)
+        .onClick(() => {
+          this.b.a = new ClassA(0);
+        })
+      Button(`ViewB: this.b = new ClassB(ClassA(0))`)
+        .onClick(() => {
+          this.b = new ClassB(new ClassA(0));
+        })
+    }
+  }
+}
+```
+
+
+ViewB中的事件句柄：
+
+
+- this.b.a = new ClassA(0) 和this.b = new ClassB(new ClassA(0))： 对\@State装饰的变量b和其属性的修改。
+
+- this.b.a.c = ... ：该变化属于第二次的变化，[@State](arkts-state.md#观察变化)无法观察到第二层的变化，但是ClassA被\@Observed装饰，ClassA的属性c的变化可以被\@ObjectLink观察到。
+
+
+ViewA中的事件句柄：
+
+
+- this.a.c += 1：对\@ObjectLink变量a的修改，将触发Button组件的刷新。\@ObjectLink和\@Prop不同，\@ObjectLink不拷贝来自父组件的数据源，而是在本地构建了指向其数据源的引用。
+
+- \@ObjectLink变量是只读的，this.a = new ClassA(...)是不允许的，因为一旦赋值操作发生，指向数据源的引用将被重置，同步将被打断。
+
+
+### 对象数组
+
+对象数组是一种常用的数据结构。以下示例展示了数组对象的用法。
+
+
+```ts
+@Component
+struct ViewA {
+  // 子组件ViewA的@ObjectLink的类型是ClassA
+  @ObjectLink a: ClassA;
+  label: string = 'ViewA1';
+
+  build() {
+    Row() {
+      Button(`ViewA [${this.label}] this.a.c = ${this.a.c} +1`)
+        .onClick(() => {
+          this.a.c += 1;
+        })
+    }
+  }
+}
+
+@Entry
+@Component
+struct ViewB {
+  // ViewB中有@State装饰的ClassA[]
+  @State arrA: ClassA[] = [new ClassA(0), new ClassA(0)];
+
+  build() {
+    Column() {
+      ForEach(this.arrA,
+        (item) => {
+          ViewA({ label: `#${item.id}`, a: item })
+        },
+        (item) => item.id.toString()
+      )
+      // 使用@State装饰的数组的数组项初始化@ObjectLink，其中数组项是被@Observed装饰的ClassA的实例
+      ViewA({ label: `ViewA this.arrA[first]`, a: this.arrA[0] })
+      ViewA({ label: `ViewA this.arrA[last]`, a: this.arrA[this.arrA.length-1] })
+
+      Button(`ViewB: reset array`)
+        .onClick(() => {
+          this.arrA = [new ClassA(0), new ClassA(0)];
+        })
+      Button(`ViewB: push`)
+        .onClick(() => {
+          this.arrA.push(new ClassA(0))
+        })
+      Button(`ViewB: shift`)
+        .onClick(() => {
+          this.arrA.shift()
+        })
+      Button(`ViewB: chg item property in middle`)
+        .onClick(() => {
+          this.arrA[Math.floor(this.arrA.length / 2)].c = 10;
+        })
+      Button(`ViewB: chg item property in middle`)
+        .onClick(() => {
+          this.arrA[Math.floor(this.arrA.length / 2)] = new ClassA(11);
+        })
+    }
+  }
+}
+```
+
+- this.arrA[Math.floor(this.arrA.length/2)] = new ClassA(..) ：该状态变量的改变触发2次更新：
+  1. ForEach：数组项的赋值导致ForEach的[itemGenerator](arkts-rendering-control-foreach.md#接口描述)被修改，因此数组项被识别为有更改，ForEach的item builder将执行，创建新的ViewA组件实例。
+  2. ViewA({ label: `ViewA this.arrA[first]`, a: this.arrA[0] })：上述更改改变了数组中第一个元素，所以绑定this.arrA[0]的ViewA将被更新；
+
+- this.arrA.push(new ClassA(0)) ： 将触发2次不同效果的更新：
+  1. ForEach：新添加的ClassA对象对于ForEach是未知的[itemGenerator](arkts-rendering-control-foreach.md#接口描述)，ForEach的item builder将执行，创建新的ViewA组件实例。
+  2. ViewA({ label: `ViewA this.arrA[last]`, a: this.arrA[this.arrA.length-1] })：数组的最后一项有更改，因此引起第二个ViewA的实例的更改。对于ViewA({ label: `ViewA this.arrA[first]`, a: this.arrA[0] })，数组的更改并没有触发一个数组项更改的改变，所以第一个ViewA不会刷新。
+
+- this.arrA[Math.floor(this.arrA.length/2)].c：[@State](arkts-state.md#观察变化)无法观察到第二层的变化，但是ClassA被\@Observed装饰，ClassA的属性的变化将被\@ObjectLink观察到。
+
+
+### 二维数组
+
+使用\@Observed观察二维数组的变化。可以声明一个被\@Observed装饰的继承Array的子类。
+
+
+```ts
+@Observed
+class StringArray extends Array<String> {
+}
+```
+
+使用new StringArray()来构造StringArray的实例，new运算符使得\@Observed生效，\@Observed观察到StringArray的属性变化。
+
+声明一个从Array扩展的类class StringArray extends Array&lt;String&gt; {}，并创建StringArray的实例。\@Observed装饰的类需要使用new运算符来构建class实例。
+
+
+```ts
+@Observed
+class StringArray extends Array<String> {
+}
+
+@Component
+struct ItemPage {
+  @ObjectLink itemArr: StringArray;
+
+  build() {
+    Row() {
+      Text('ItemPage')
+        .width(100).height(100)
+
+      ForEach(this.itemArr,
+        item => {
+          Text(item)
+            .width(100).height(100)
+        },
+        item => item
+      )
+    }
+  }
+}
+
+@Entry
+@Component
+struct IndexPage {
+  @State arr: Array<StringArray> = [new StringArray(), new StringArray(), new StringArray()];
+
+  build() {
+    Column() {
+      ItemPage({ itemArr: this.arr[0] })
+      ItemPage({ itemArr: this.arr[1] })
+      ItemPage({ itemArr: this.arr[2] })
+
+      Divider()
+
+      ForEach(this.arr,
+        itemArr => {
+          ItemPage({ itemArr: itemArr })
+        },
+        itemArr => itemArr[0]
+      )
+
+      Divider()
+
+      Button('update')
+        .onClick(() => {
+          console.error('Update all items in arr');
+          if (this.arr[0][0] !== undefined) {
+            // 正常情况下需要有一个真实的ID来与ForEach一起使用，但此处没有
+            // 因此需要确保推送的字符串是唯一的。
+            this.arr[0].push(`${this.arr[0].slice(-1).pop()}${this.arr[0].slice(-1).pop()}`);
+            this.arr[1].push(`${this.arr[1].slice(-1).pop()}${this.arr[1].slice(-1).pop()}`);
+            this.arr[2].push(`${this.arr[2].slice(-1).pop()}${this.arr[2].slice(-1).pop()}`);
+          } else {
+            this.arr[0].push('Hello');
+            this.arr[1].push('World');
+            this.arr[2].push('!');
+          }
+        })
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-other-state-mgmt-functions-overview.md

+# 其他状态管理概述
+
+
+除了前面章节提到的组件状态管理和应用状态管理，ArkTS还提供了\@Watch和$$来为开发者提供更多功能：
+
+
+- \@Watch用于监听状态变量的变化。
+
+- $$运算符：给内置组件提供TS变量的引用，使得TS变量和内置组件的内部状态保持同步。

zh-cn/application-dev/quick-start/arkts-page-custom-components-lifecycle.md

+# 页面和自定义组件生命周期
+
+
+在开始之前，我们先明确自定义组件和页面的关系：
+
+
+- 自定义组件：\@Component装饰的UI单元，可以组合多个系统组件实现UI的复用。
+
+- 页面：即应用的UI页面。可以由一个或者多个自定义组件组成，\@Entry装饰的自定义组件为页面的入口组件，即页面的根节点，一个页面有且仅能有一个\@Entry。只有被\@Entry装饰的组件才可以调用页面的生命周期。
+
+
+页面生命周期，即被\@Entry装饰的组件生命周期，提供以下生命周期接口：
+
+
+- [onPageShow](../reference/arkui-ts/ts-custom-component-lifecycle.md#onpageshow)：页面每次显示时触发。
+
+- [onPageHide](../reference/arkui-ts/ts-custom-component-lifecycle.md#onpagehide)：页面每次隐藏时触发一次。
+
+- [onBackPress](../reference/arkui-ts/ts-custom-component-lifecycle.md#onbackpress)：当用户点击返回按钮时触发。
+
+
+组件生命周期，即一般用\@Component装饰的自定义组件，提供以下生命周期接口：
+
+
+- [aboutToAppear](../reference/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear)：组件即将出现时回调该接口，具体时机为在创建自定义组件的新实例后，在执行其build()函数之前执行。
+
+- [aboutToDisappear](../reference/arkui-ts/ts-custom-component-lifecycle.md#abouttodisappear)：在自定义组件即将析构销毁时执行。
+
+
+生命周期流程如下图所示，下图展示的是被\@Entry装饰的组件（首页）生命周期。
+
+
+![zh-cn_image_0000001502372786](figures/zh-cn_image_0000001502372786.png)
+
+
+根据上面的流程图，我们从自定义组件的初始创建、重新渲染和删除来详细解释。
+
+
+## 自定义组件的创建和渲染流程
+
+1. 自定义组件的创建：自定义组件的实例由ArkUI框架创建。
+
+2. 初始化自定义组件的成员变量：通过本地默认值或者构造方法传递参数来初始化自定义组件的成员变量，初始化顺序为成员变量的定义顺序。
+
+3. 如果开发者定义了aboutToAppear，则执行aboutToAppear方法。
+
+4. 在首次渲染的时候，执行build方法渲染系统组件，如果有自定义子组件，则创建自定义组件的实例。在执行build()函数的过程中，框架会观察每个状态变量的读取状态，将保存两个map：
+   1. 状态变量 -> UI组件（包括ForEach和if）。
+   2. UI组件 -> 此组件的更新函数，即一个lambda方法，作为build()函数的子集，创建对应的UI组件并执行其属性方法，示意如下。
+
+
+   ```ts
+   build() {
+     ...
+     this.observeComponentCreation(() => {
+       Button.create();
+     })
+
+     this.observeComponentCreation(() => {
+       Text.create();
+     })
+     ...
+   }
+   ```
+
+
+当应用在后台启动时，此时应用进程并没有销毁，所以仅需要执行onPageShow。
+
+
+## 自定义组件重新渲染
+
+当事件句柄被触发（比如设置了点击事件，即触发点击事件）改变了状态变量时，或者LocalStorage / AppStorage中的属性更改，并导致绑定的状态变量更改其值时：
+
+
+1. 框架观察到了变化，将启动重新渲染。
+
+2. 根据框架持有的两个map（自定义组件的创建和渲染流程中第4步），框架可以知道该状态变量管理了哪些UI组件，以及这些UI组件对应的更新函数。执行这些UI组件的更新函数，实现最小化更新。
+
+
+## 自定义组件的删除
+
+如果if组件的分支改变，或者ForEach循环渲染中数组的个数改变，组件将被删除：
+
+
+1. 在删除组件之前，将调用其aboutToDisappear生命周期函数，标记着该节点将要被销毁。ArkUI的节点删除机制是：后端节点直接从组件树上摘下，后端节点被销毁，对前端节点解引用，当前端节点已经没有引用时，将被JS虚拟机垃圾回收。
+
+2. 自定义组件和它的变量将被删除，如果其有同步的变量，比如[@Link](arkts-link.md)、[@Prop](zh-cn_topic_0000001524296665.xml)、[@StorageLink](arkts-appstorage.md#storagelink)，将从[同步源](arkts-state-management-overview.md#基本概念)上取消注册。
+
+
+不建议在生命周期aboutToDisappear内使用async await，如果在生命周期的aboutToDisappear使用异步操作（Promise或者回调方法），自定义组件将被保留在Promise的闭包中，直到回调方法被执行完，这个行为阻止了自定义组件的垃圾回收。
+
+
+以下示例展示了生命周期的调用时机：
+
+
+
+```ts
+// Index.ets
+import router from '@ohos.router';
+
+@Entry
+@Component
+struct MyComponent {
+  @State showChild: boolean = true;
+
+  // 只有被@Entry装饰的组件才可以调用页面的生命周期
+  onPageShow() {
+    console.info('Index onPageShow');
+  }
+  // 只有被@Entry装饰的组件才可以调用页面的生命周期
+  onPageHide() {
+    console.info('Index onPageHide');
+  }
+
+  // 只有被@Entry装饰的组件才可以调用页面的生命周期
+  onBackPress() {
+    console.info('Index onBackPress');
+  }
+
+  // 组件生命周期
+  aboutToAppear() {
+    console.info('MyComponent aboutToAppear');
+  }
+
+  // 组件生命周期
+  aboutToDisappear() {
+    console.info('MyComponent aboutToDisappear');
+  }
+
+  build() {
+    Column() {
+      // this.showChild为true，创建Child子组件，执行Child aboutToAppear
+      if (this.showChild) {
+        Child()
+      }
+      // this.showChild为false，删除Child子组件，执行Child aboutToDisappear
+      Button('create or delete Child').onClick(() => {
+        this.showChild = false;
+      })
+      // push到Page2页面，执行onPageHide
+      Button('push to next page')
+        .onClick(() => {
+          router.pushUrl({ url: 'pages/Page2' });
+        })
+    }
+
+  }
+}
+
+@Component
+struct Child {
+  @State title: string = 'Hello World';
+  // 组件生命周期
+  aboutToDisappear() {
+    console.info('[lifeCycle] Child aboutToDisappear')
+  }
+  // 组件生命周期
+  aboutToAppear() {
+    console.info('[lifeCycle] Child aboutToAppear')
+  }
+
+  build() {
+    Text(this.title).fontSize(50).onClick(() => {
+      this.title = 'Hello ArkUI';
+    })
+  }
+}
+```
+
+
+以上示例中，Index页面包含两个自定义组件，一个是被\@Entry装饰的MyComponent，也是页面的入口组件，即页面的根节点；一个是Child，是MyComponent的子组件。只有\@Entry装饰的节点才可以生效页面的生命周期方法，所以MyComponent中声明了当前Index页面的页面生命周期函数。MyComponent和其子组件Child也同时也声明了组件的生命周期函数。
+
+
+- 应用冷启动的初始化流程为：MyComponent aboutToAppear --> MyComponent build --> Child aboutToAppear --> Child build --> Child build执行完毕 --> MyComponent build执行完毕 --> Index onPageShow。
+
+- 点击“delete Child”，if绑定的this.showChild变成false，删除Child组件，会执行Child aboutToDisappear方法。
+
+
+- 点击“push to next page”，调用router.pushUrl接口，跳转到另外一个页面，当前Index页面隐藏，执行页面生命周期Index onPageHide。此处调用的是router.pushUrl接口，Index页面被隐藏，并没有销毁，所以只调用onPageHide。跳转到新页面后，执行初始化新页面的生命周期的流程。
+
+- 如果调用的是router.replaceUrl，则当前Index页面被销毁，执行的生命周期流程将变为：Index onPageHide --> MyComponent aboutToDisappear --> Child aboutToDisappear。上文已经提到，组件的销毁是从组件树上直接摘下子树，所以先调用父组件的aboutToDisappear，再调用子组件的aboutToDisAppear，然后执行初始化新页面的生命周期流程。
+
+- 点击返回按钮，触发页面生命周期Index onBackPress。最小化应用或者应用进入后台，触发Index onPageHide。这两个状态下应用都没有被销毁，所以并不会执行组件的aboutToDisappear 。应用回到前台，执行Index onPageShow。
+
+
+- 退出应用，执行Index onPageHide --> MyComponent aboutToDisappear --> Child aboutToDisappear。

zh-cn/application-dev/quick-start/arkts-persiststorage.md

+# PersistentStorage：持久化存储UI状态
+
+
+前两个小节介绍的LocalStorage和AppStorage都是运行时的内存，但是在应用退出再次启动后，依然能保存选定的结果，是应用开发中十分常见的现象，这就需要用到PersistentStorage。
+
+
+PersistentStorage是应用程序中的可选单例对象。此对象的作用是持久化存储选定的AppStorage属性，以确保这些属性在应用程序重新启动时的值与应用程序关闭时的值相同。
+
+
+## 概述
+
+PersistentStorage将选定的AppStorage属性保留在设备磁盘上。应用程序通过API，以决定哪些AppStorage属性应借助PersistentStorage持久化。UI和业务逻辑不直接访问PersistentStorage中的属性，所有属性访问都是对AppStorage的访问，AppStorage中的更改会自动同步到PersistentStorage。
+
+PersistentStorage和AppStorage中的属性建立双向同步。应用开发通常通过AppStorage访问PersistentStorage，另外还有一些接口可以用于管理持久化属性，但是业务逻辑始终是通过AppStorage获取和设置属性的。
+
+
+## 限制条件
+
+持久化数据是一个相对缓慢的操作，应用程序应避免以下情况：
+
+- 持久化大型数据集。
+
+- 持久化经常变化的变量。
+
+当持久化更改的过程变得太繁重时，PersistentStorage实现可能会限制持久化属性更改的频率。
+
+
+## 使用场景
+
+
+### 从AppStorage中访问PersistentStorage初始化的属性
+
+1. 初始化PersistentStorage：
+
+   ```ts
+   PersistentStorage.PersistProp('aProp', 47);
+   ```
+
+2. 在AppStorage获取对应属性：
+
+   ```ts
+   AppStorage.Get('aProp'); // returns 47
+   ```
+
+   或在组件内部定义：
+
+
+   ```ts
+   @StorageLink('aProp') aProp: number = 48;
+   ```
+
+完整代码如下：
+
+
+```ts
+PersistentStorage.PersistProp('aProp', 47);
+
+@Entry
+@Component
+struct Index {
+  @State message: string = 'Hello World'
+  @StorageLink('aProp') aProp: number = 48
+
+  build() {
+    Row() {
+      Column() {
+        Text(this.message)
+        // 应用退出时会保存当前结果。重新启动后，会显示上一次的保存结果
+        Text(`${this.aProp}`)
+          .onClick(() => {
+            this.aProp += 1;
+          })
+      }
+    }
+  }
+}
+```
+
+- 新应用安装后首次启动运行：
+  1. 调用PersistProp初始化PersistentStorage，首先查询在PersistentStorage本地文件中是否存在“aProp”，查询结果为不存在，因为应用是第一次安装。；
+  2. 接着查询属性“aProp”在AppStorage中是否存在，依旧不存在；
+  3. 在AppStorge中创建名为“aProp”的number类型属性，属性初始值是定义的默认值47；
+  4. PersistentStorage将属性“aProp”和值47写入磁盘，AppStorage中“aProp”对应的值和其后续的更改将被持久化；
+  5. 在Index组件中创建状态变量\@StorageLink('aProp') aProp，和AppStorage中“aProp”双向绑定，在创建的过程中会在AppStorage中查找，成功找到“aProp”，所以使用其在AppStorage找到的值47。
+
+  **图1** PersistProp初始化流程  
+
+![zh-cn_image_0000001553348833](figures/zh-cn_image_0000001553348833.png)
+
+- 触发点击事件后：
+  1. 状态变量\@StorageLink('aProp') aProp改变，触发Text组件重新刷新；
+  2. \@StorageLink装饰的变量是和AppStorage中建立双向同步的，所以\@StorageLink('aProp') aProp的变化会被同步回AppStorage中；
+  3. AppStorage中“aProp”属性的改变会同步到所有绑定该“aProp”的单向或者双向变量，在本示例中没有其他的绑定“aProp”的变量；
+  4. 因为“aProp”对应的属性已经被持久化，所以在AppStorage中“aProp”的改变会触发PersistentStorage将新的改变写会本地磁盘。
+
+- 后续启动应用：
+  1. 执行PersistentStorage.PersistProp('aProp', 47)，在首先查询在PersistentStorage本地文件查询“aProp”属性，成功查询到；
+  2. 将在PersistentStorage查询到的值写入AppStorage中；
+  3. 在Index组件里，\@StorageLink绑定的“aProp”为PersistentStorage写入AppStorage中的值，即为上一次退出引用存入的值。
+
+
+### 在PersistentStorage之前访问AppStorage中的属性
+
+该示例为反例。在调用PersistentStorage.PersistProp或者PersistProps之前使用接口访问AppStorage中的属性是错误的，因为这样的调用顺序会丢失上一次应用程序运行中的属性值：
+
+
+```ts
+let aProp = AppStorage.SetOrCreate('aProp', 47);
+PersistentStorage.PersistProp('aProp', 48);
+```
+
+应用在非首次运行时，先执行AppStorage.SetOrCreate('aProp', 47)：属性“aProp”在AppStorage中创建，其类型为number，其值设置为指定的默认值47。'aProp'是持久化的属性，所以会被写回PersistentStorage磁盘中，PersistentStorage存储的上次退出应用的值丢失。
+
+PersistentStorage.PersistProp('aProp', 48)：在PersistentStorage中查找到“aProp”，找到，值为47。

zh-cn/application-dev/quick-start/arkts-prop.md

+# \@Prop：父子单向同步
+
+
+\@Prop装饰的变量可以和父组件建立单向的同步关系。\@Prop装饰的变量是可变的，但是变化不会同步回其父组件。
+
+
+> **说明：**
+>
+> 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
+
+
+## 概述
+
+\@Prop装饰的变量和父组件建立单向的同步关系：
+
+- \@Prop变量允许在本地修改，但修改后的变化不会同步回父组件。
+
+- 当父组件中的数据源更改时，与之相关的\@Prop装饰的变量都会自动更新。如果子组件已经在本地修改了\@Prop装饰的相关变量值，而在父组件中对应的\@State装饰的变量被修改后，子组件本地修改的\@Prop装饰的相关变量值将被覆盖。
+
+
+## 装饰器使用规则说明
+
+| \@Prop变量装饰器 | 说明                                       |
+| ----------- | ---------------------------------------- |
+| 装饰器参数       | 无                                        |
+| 同步类型        | 单向同步：对父组件状态变量值的修改，将同步给子组件\@Prop装饰的变量，子组件\@Prop变量的修改不会同步到父组件的状态变量上 |
+| 允许装饰的变量类型   | string、number、boolean、enum类型。<br/>不支持any，不允许使用undefined和null。<br/>必须指定类型。<br/>在父组件中，传递给\@Prop装饰的值不能为undefined或者null，反例如下所示。<br/>CompA&nbsp;({&nbsp;aProp:&nbsp;undefined&nbsp;})<br/>CompA&nbsp;({&nbsp;aProp:&nbsp;null&nbsp;})<br/>\@Prop和[数据源](arkts-state-management-overview.md#基本概念)类型需要相同，有以下三种情况（数据源以\@State为例）：<br/>-&nbsp;\@Prop装饰的变量和父组件状态变量类型相同，即\@Prop&nbsp;:&nbsp;S和\@State&nbsp;:&nbsp;S，示例请参考[父组件@State到子组件@Prop简单数据类型同步](#父组件state到子组件prop简单数据类型同步)。<br/>-&nbsp;当父组件的状态变量为数组时，\@Prop装饰的变量和父组件状态变量的数组项类型相同，即\@Prop&nbsp;:&nbsp;S和\@State&nbsp;:&nbsp;Array&lt;S&gt;，示例请参考[父组件@State数组中的项到子组件@Prop简单数据类型同步](#父组件state数组项到子组件prop简单数据类型同步)；<br/>-&nbsp;当父组件状态变量为Object或者class时，\@Prop装饰的变量和父组件状态变量的属性类型相同，即\@Prop&nbsp;:&nbsp;S和\@State&nbsp;:&nbsp;{&nbsp;propA:&nbsp;S&nbsp;}，示例请参考[从父组件中的@State类对象属性到@Prop简单类型的同步](#从父组件中的state类对象属性到prop简单类型的同步)。 |
+| 被装饰变量的初始值   | 允许本地初始化。                                 |
+
+
+## 变量的传递/访问规则说明
+
+| 传递/访问     | 说明                                       |
+| --------- | ---------------------------------------- |
+| 从父组件初始化   | 如果本地有初始化，则是可选的。没有的话，则必选，支持父组件中的常规变量、\@State、\@Link、\@Prop、\@Provide、\@Consume、\@ObjectLink、\@StorageLink、\@StorageProp、\@LocalStorageLink和\@LocalStorageProp去初始化子组件中的\@Prop变量。 |
+| 用于初始化子组件  | \@Prop支持去初始化子组件中的常规变量、\@State、\@Link、\@Prop、\@Provide。 |
+| 是否支持组件外访问 | \@Prop装饰的变量是私有的，只能在组件内访问。                |
+
+
+  **图1** 初始化规则图示  
+
+
+![zh-cn_image_0000001552972029](figures/zh-cn_image_0000001552972029.png)
+
+
+## 观察变化和行为表现
+
+
+### 观察变化
+
+\@Prop装饰的数据可以观察到以下变化。
+
+- 当装饰的类型是允许的类型，即string、number、boolean、enum类型都可以观察到的赋值变化；
+
+  ```ts
+  // 简单类型
+  @Prop count: number;
+  // 赋值的变化可以被观察到
+  this.count = 1;
+  ```
+
+对于\@State和\@Prop的同步场景：
+
+- 使用父组件中\@State变量的值初始化子组件中的\@Prop变量。当\@State变量变化时，该变量值也会同步更新至\@Prop变量。
+
+- \@Prop装饰的变量的修改不会影响其数据源\@State装饰变量的值。
+
+- 除了\@State，数据源也可以用\@Link或\@Prop装饰，对\@Prop的同步机制是相同的。
+
+- 数据源和\@Prop变量的类型需要相同。
+
+
+### 框架行为
+
+要理解\@Prop变量值初始化和更新机制，有必要了解父组件和拥有\@Prop变量的子组件初始渲染和更新流程。
+
+1. 初始渲染：
+   1. 执行父组件的build()函数将创建子组件的新实例，将数据源传递给子组件；
+   2. 初始化子组件\@Prop装饰的变量。
+
+2. 更新：
+   1. 子组件\@Prop更新时，更新仅停留在当前子组件，不会同步回父组件；
+   2. 当父组件的数据源更新时，子组件的\@Prop装饰的变量将被来自父组件的数据源重置，所有\@Prop装饰的本地的修改将被父组件的更新覆盖。
+
+
+## 使用场景
+
+
+### 父组件\@State到子组件\@Prop简单数据类型同步
+
+
+以下示例是\@State到子组件\@Prop简单数据同步，父组件ParentComponent的状态变量countDownStartValue初始化子组件CountDownComponent中\@Prop装饰的count，点击“Try again”，count的修改仅保留在CountDownComponent 不会同步给父组件CountDownComponent。
+
+
+ParentComponent的状态变量countDownStartValue的变化将重置CountDownComponent的count。
+
+
+
+```ts
+@Component
+struct CountDownComponent {
+  @Prop count: number;
+  costOfOneAttempt: number = 1;
+
+  build() {
+    Column() {
+      if (this.count > 0) {
+        Text(`You have ${this.count} Nuggets left`)
+      } else {
+        Text('Game over!')
+      }
+      // @Prop装饰的变量不会同步给父组件
+      Button(`Try again`).onClick(() => {
+        this.count -= this.costOfOneAttempt;
+      })
+    }
+  }
+}
+
+@Entry
+@Component
+struct ParentComponent {
+  @State countDownStartValue: number = 10;
+
+  build() {
+    Column() {
+      Text(`Grant ${this.countDownStartValue} nuggets to play.`)
+      // 父组件的数据源的修改会同步给子组件
+      Button(`+1 - Nuggets in New Game`).onClick(() => {
+        this.countDownStartValue += 1;
+      })
+      // 父组件的修改会同步给子组件
+      Button(`-1  - Nuggets in New Game`).onClick(() => {
+        this.countDownStartValue -= 1;
+      })
+
+      CountDownComponent({ count: this.countDownStartValue, costOfOneAttempt: 2 })
+    }
+  }
+}
+```
+
+
+在上面的示例中：
+
+
+1. CountDownComponent子组件首次创建时其\@Prop装饰的count变量将从父组件\@State装饰的countDownStartValue变量初始化；
+
+2. 按“+1”或“-1”按钮时，父组件的\@State装饰的countDownStartValue值会变化，这将触发父组件重新渲染，在父组件重新渲染过程中会刷新使用countDownStartValue状态变量的UI组件并单向同步更新CountDownComponent子组件中的count值；
+
+3. 更新count状态变量值也会触发CountDownComponent的重新渲染，在重新渲染过程中，评估使用count状态变量的if语句条件（this.count &gt; 0），并执行true分支中的使用count状态变量的UI组件相关描述来更新Text组件的UI显示；
+
+4. 当按下子组件CountDownComponent的“Try again”按钮时，其\@Prop变量count将被更改，但是count值的更改不会影响父组件的countDownStartValue值；
+
+5. 父组件的countDownStartValue值会变化时，父组件的修改将覆盖掉子组件CountDownComponent中count本地的修改。
+
+
+### 父组件\@State数组项到子组件\@Prop简单数据类型同步
+
+
+父组件中\@State如果装饰的数组，其数组项也可以初始化\@Prop。以下示例中父组件Index中\@State装饰的数组arr，将其数组项初始化子组件Child中\@Prop装饰的value。
+
+
+
+```ts
+@Component
+struct Child {
+  @Prop value: number;
+
+  build() {
+    Text(`${this.value}`)
+      .fontSize(50)
+      .onClick(()=>{this.value++})
+  }
+}
+
+@Entry
+@Component
+struct Index {
+  @State arr: number[] = [1,2,3];
+
+  build() {
+    Row() {
+      Column() {
+        Child({value: this.arr[0]})
+        Child({value: this.arr[1]})
+        Child({value: this.arr[2]})
+
+        Divider().height(5)
+
+        ForEach(this.arr, 
+          item => {
+            Child({value: item})
+          }, 
+          item => item.toString()
+        )
+        Text('replace entire arr')
+        .fontSize(50)
+        .onClick(()=>{
+          // 两个数组都包含项“3”。
+          this.arr = this.arr[0] == 1 ? [3,4,5] : [1,2,3];
+        })
+      }
+    }
+  }
+}
+```
+
+
+初始渲染创建6个子组件实例，每个\@Prop装饰的变量初始化都在本地拷贝了一份数组项。子组件onclick事件处理程序会更改局部变量值。
+
+
+假设我们点击了多次，所有变量的本地取值都是“7”。
+
+
+
+```
+7
+7
+7
+----
+7
+7
+7
+```
+
+
+单击replace entire arr后，屏幕将显示以下信息。
+
+
+
+```
+3
+4
+5
+----
+7
+4
+5
+```
+
+
+- 在子组件Child中做的所有的修改都不会同步回父组件Index组件，所以即使6个组件显示都为7，但在父组件Index中，this.arr保存的值依旧是[1,2,3]。
+
+- 点击replace entire arr，this.arr[0] == 1成立，将this.arr赋值为[3, 4, 5]；
+
+- 因为this.arr[0]已更改，Child({value: this.arr[0]})组件将this.arr[0]更新同步到实例\@Prop装饰的变量。Child({value: this.arr[1]})和Child({value: this.arr[2]})的情况也类似。
+
+
+- this.arr的更改触发ForEach更新，this.arr更新的前后都有数值为3的数组项：[3, 4, 5] 和[1, 2, 3]。根据diff机制，数组项“3”将被保留，删除“1”和“2”的数组项，添加为“4”和“5”的数组项。这就意味着，数组项“3”的组件不会重新生成，而是将其移动到第一位。所以“3”对应的组件不会更新，此时“3”对应的组件数值为“7”，ForEach最终的渲染结果是“7”，“4”，“5”。
+
+
+### 从父组件中的\@State类对象属性到\@Prop简单类型的同步
+
+如果图书馆有一本图书和两位用户，每位用户都可以将图书标记为已读，此标记行为不会影响其它读者用户。从代码角度讲，对\@Prop图书对象的本地更改不会同步给图书馆组件中的\@State图书对象。
+
+
+```ts
+class Book {
+  public title: string;
+  public pages: number;
+  public readIt: boolean = false;
+
+  constructor(title: string, pages: number) {
+    this.title = title;
+    this.pages = pages;
+  }
+}
+
+@Component
+struct ReaderComp {
+  @Prop title: string;
+  @Prop readIt: boolean;
+
+  build() {
+    Row() {
+      Text(this.title)
+      Text(`... ${this.readIt ? 'I have read' : 'I have bot read it'}`)
+        .onClick(() => this.readIt = true)
+    }
+  }
+}
+
+@Entry
+@Component
+struct Library {
+  @State book: Book = new Book('100 secrets of C++', 765);
+
+  build() {
+    Column() {
+      ReaderComp({ title: this.book.title, readIt: this.book.readIt })
+      ReaderComp({ title: this.book.title, readIt: this.book.readIt })
+    }
+  }
+}
+```
+
+
+### \@Prop本地初始化不和父组件同步
+
+为了支持\@Component装饰的组件复用场景，\@Prop支持本地初始化，这样可以让\@Prop是否与父组件建立同步关系变得可选。当且仅当\@Prop有本地初始化时，从父组件向子组件传递\@Prop的数据源才是可选的。
+
+下面的示例中，子组件包含两个\@Prop变量：
+
+- \@Prop customCounter没有本地初始化，所以需要父组件提供数据源去初始化\@Prop，并当父组件的数据源变化时，\@Prop也将被更新；
+
+- \@Prop customCounter2有本地初始化，在这种情况下，\@Prop依旧允许但非强制父组件同步数据源给\@Prop。
+
+
+```ts
+@Component
+struct MyComponent {
+  @Prop customCounter: number;
+  @Prop customCounter2: number = 5;
+
+  build() {
+    Column() {
+      Row() {
+        Text(`From Main: ${this.customCounter}`).width(90).height(40).fontColor('#FF0010')
+      }
+
+      Row() {
+        Button('Click to change locally !').width(480).height(60).margin({ top: 10 })
+          .onClick(() => {
+            this.customCounter2++
+          })
+      }.height(100).width(480)
+
+      Row() {
+        Text(`Custom Local: ${this.customCounter2}`).width(90).height(40).fontColor('#FF0010')
+      }
+    }
+  }
+}
+
+@Entry
+@Component
+struct MainProgram {
+  @State mainCounter: number = 10;
+
+  build() {
+    Column() {
+      Row() {
+        Column() {
+          Button('Click to change number').width(480).height(60).margin({ top: 10, bottom: 10 })
+            .onClick(() => {
+              this.mainCounter++
+            })
+        }
+      }
+
+      Row() {
+        Column(       
+          // customCounter必须从父组件初始化，因为MyComponent的customCounter成员变量缺少本地初始化；此处，customCounter2可以不做初始化。
+          MyComponent({ customCounter: this.mainCounter })
+          // customCounter2也可以从父组件初始化，父组件初始化的值会覆盖子组件customCounter2的本地初始化的值
+          MyComponent({ customCounter: this.mainCounter, customCounter2: this.mainCounter })
+        }.width('40%')
+      }
+
+      Row() {
+        Text('').width(480).height(10)
+      }
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-provide-and-consume.md

+# \@Provide和\@Consume：与后代组件双向同步
+
+
+\@Provide和\@Consume，应用于与后代组件的双向数据同步，应用于状态数据在多个层级之间传递的场景。不同于上文提到的父子组件之间通过命名参数机制传递，\@Provide和\@Consume摆脱参数传递机制的束缚，实现跨层级传递。
+
+
+其中\@Provide装饰的变量是在祖先节点中，可以理解为被“提供”给后代的状态变量。\@Consume装饰的变量是在后代组件中，去“消费（绑定）”祖先节点提供的变量。
+
+
+> **说明：**
+>
+> 从API version 9开始，这两个装饰器支持在ArkTS卡片中使用。
+
+
+## 概述
+
+\@Provide/\@Consume装饰的状态变量有以下特性：
+
+- \@Provide装饰的状态变量自动对其所有后代组件可用，即该变量被“provide”给他的后代组件。由此可见，\@Provide的方便之处在于，开发者不需要多次在组件之间传递变量。
+
+- 后代通过使用\@Consume去获取\@Provide提供的变量，建立在\@Provide和\@Consume之间的双向数据同步，与\@State/\@Link不同的是，前者可以在多层级的父子组件之间传递。
+
+- \@Provide和\@Consume可以通过相同的变量名或者相同的变量别名绑定，变量类型必须相同。
+
+
+```ts
+// 通过相同的变量名绑定
+@Provide a: number = 0;
+@Consume a: number;
+
+// 通过相同的变量别名绑定
+@Provide('a') b: number = 0;
+@Consume('a') c: number;
+```
+
+
+\@Provide和\@Consume通过相同的变量名或者相同的变量别名绑定时，\@Provide修饰的变量和\@Consume修饰的变量是一对多的关系。不允许在同一个自定义组件内，包括其子组件中声明多个同名或者同别名的\@Provide装饰的变量。
+
+
+## 装饰器说明
+
+\@State的规则同样适用于\@Provide，差异为\@Provide还作为多层后代的同步源。
+
+| \@Provide变量装饰器 | 说明                                       |
+| -------------- | ---------------------------------------- |
+| 装饰器参数          | 别名：常量字符串，可选。<br/>如果指定了别名，则通过别名来绑定变量；如果未指定别名，则通过变量名绑定变量。 |
+| 同步类型           | 双向同步。<br/>从\@Provide变量到所有\@Consume变量以及相反的方向的数据同步。双向同步的操作与\@State和\@Link的组合相同。 |
+| 允许装饰的变量类型      | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化](#观察变化)。<br/>不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。<br/>必须指定类型。\@Provide变量的\@Consume变量的类型必须相同。<br/>**说明：**<br/>不支持Length、ResourceStr、ResourceColor类型，Length、ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。 |
+| 被装饰变量的初始值      | 必须指定。                                    |
+
+| \@Consume变量装饰器 | 说明                                       |
+| -------------- | ---------------------------------------- |
+| 装饰器参数          | 别名：常量字符串，可选。<br/>如果提供了别名，则必须有\@Provide的变量和其有相同的别名才可以匹配成功；否则，则需要变量名相同才能匹配成功。 |
+| 同步类型           | 双向：从\@Provide变量（具体请参见\@Provide）到所有\@Consume变量，以及相反的方向。双向同步操作与\@State和\@Link的组合相同。 |
+| 允许装饰的变量类型      | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化](#观察变化)。<br/>不支持any，不允许使用undefined和null。<br/>必须指定类型。\@Provide变量的\@Consume变量的类型必须相同。<br/>**说明：**<br/>-&nbsp;\@Consume装饰的变量，在其父节点或者祖先节点上，必须有对应的属性和别名的\@Provide装饰的变量。 |
+| 被装饰变量的初始值      | 无，禁止本地初始化。                               |
+
+
+## 变量的传递/访问规则说明
+
+
+| \@Provide传递/访问 | 说明                                       |
+| -------------- | ---------------------------------------- |
+| 从父组件初始化和更新     | 可选，允许父组件中常规变量、\@State、\@Link、\@Prop、\@Provide、\@Consume、\@ObjectLink、\@StorageLink、\@StorageProp、\@LocalStorageLink和\@LocalStorageProp装饰的变量装饰变量初始化子组件\@Provide。 |
+| 用于初始化子组件       | 允许，可用于初始化\@State、\@Link、\@Prop、\@Provide。 |
+| 和父组件同步         | 否。                                       |
+| 和后代组件同步        | 和\@Consume双向同步。                          |
+| 是否支持组件外访问      | 私有，仅可以在所属组件内访问。                          |
+
+
+  **图1** \@Provide初始化规则图示  
+
+
+![zh-cn_image_0000001552614217](figures/zh-cn_image_0000001552614217.png)
+
+
+| \@Consume传递/访问 | 说明                                       |
+| -------------- | ---------------------------------------- |
+| 从父组件初始化和更新     | 禁止。通过相同的变量名和alias（别名）从\@Provide初始化。      |
+| 用于初始化子组件       | 允许，可用于初始化\@State、\@Link、\@Prop、\@Provide。 |
+| 和祖先组件同步        | 和\@Provide双向同步。                          |
+| 是否支持组件外访问      | 私有，仅可以在所属组件内访问                           |
+
+
+  **图2** \@Consume初始化规则图示  
+
+
+![zh-cn_image_0000001502094666](figures/zh-cn_image_0000001502094666.png)
+
+
+## 观察变化和行为表现
+
+
+### 观察变化
+
+- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。
+
+- 当装饰的数据类型为class或者Object的时候，可以观察到赋值和属性赋值的变化（属性为Object.keys(observedObject)返回的所有属性）。
+
+- 当装饰的对象是array的时候，可以观察到数组的添加、删除、更新数组单元。
+
+
+### 框架行为
+
+1. 初始渲染：
+   1. \@Provide装饰的变量会以map的形式，传递给当前\@Provide所属组件的所有子组件；
+   2. 子组件中如果使用\@Consume变量，则会在map中查找是否有该变量名/alias（别名）对应的\@Provide的变量，如果查找不到，框架会抛出JS ERROR;
+   3. 在初始化\@Consume变量时，和\@State/\@Link的流程类似，\@Consume变量会保存在map中查找到的\@Provide变量，并把自己注册给\@Provide。
+
+2. 当\@Provide装饰的数据变化时：
+   1. 通过初始渲染的步骤可知，子组件\@Consume已把自己注册给父组件。父组件\@Provide变量变更后，会遍历更新所有依赖它的系统组件（elementid）和状态变量（\@Consume）；
+   2. 通知\@Consume更新后，子组件所有依赖\@Consume的系统组件（elementId）都会被通知更新。以此实现\@Provide对\@Consume状态数据同步。
+
+3. 当\@Consume装饰的数据变化时：
+   1. 通过初始渲染的步骤可知，子组件\@Consume持有\@Provide的实例。在\@Consume更新后调用\@Provide的更新方法，将更新的数值同步回\@Provide，以此实现\@Consume向\@Provide的同步更新。
+
+
+## 使用场景
+
+在下面的示例是与后代组件双向同步状态\@Provide和\@Consume场景。当分别点击CompA和CompD组件内Button时，reviewVotes 的更改会双向同步在CompA和CompD中。
+
+
+
+```ts
+@Component
+struct CompD {
+  // @Consume装饰的变量通过相同的属性名绑定其祖先组件CompA内的@Provide装饰的变量
+  @Consume reviewVotes: number;
+
+  build() {
+    Column() {
+      Text(`reviewVotes(${this.reviewVotes})`)
+      Button(`reviewVotes(${this.reviewVotes}), give +1`)
+        .onClick(() => this.reviewVotes += 1)
+    }
+    .width('50%')
+  }
+}
+
+@Component
+struct CompC {
+  build() {
+    Row({ space: 5 }) {
+      CompD()
+      CompD()
+    }
+  }
+}
+
+@Component
+struct CompB {
+  build() {
+    CompC()
+  }
+}
+
+@Entry
+@Component
+struct CompA {
+  // @Provide装饰的变量reviewVotes由入口组件CompA提供其后代组件
+  @Provide reviewVotes: number = 0;
+
+  build() {
+    Column() {
+      Button(`reviewVotes(${this.reviewVotes}), give +1`)
+        .onClick(() => this.reviewVotes += 1)
+      CompB()
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-rendering-control-foreach.md

+# ForEach：循环渲染
+
+
+ForEach基于数组类型数据执行循环渲染。
+
+
+## 接口描述
+
+
+```ts
+ForEach(
+  arr: any[], 
+  itemGenerator: (item: any, index?: number) => void,
+  keyGenerator?: (item: any, index?: number) => string 
+)
+```
+
+
+| 参数名           | 参数类型                                     | 必填   | 参数描述                                     |
+| ------------- | ---------------------------------------- | ---- | ---------------------------------------- |
+| arr           | Array                                    | 是    | 必须是数组，允许设置为空数组，空数组场景下将不会创建子组件。同时允许设置返回值为数组类型的函数，例如arr.slice(1, 3)，设置的函数不得改变包括数组本身在内的任何状态变量，如Array.splice、Array.sort或Array.reverse这些改变原数组的函数。 |
+| itemGenerator | (item:&nbsp;any,&nbsp;index?:&nbsp;number)&nbsp;=&gt;&nbsp;void | 是    | 生成子组件的lambda函数，为数组中的每一个数据项创建一个或多个子组件，单个子组件或子组件列表必须包括在大括号“{...}”中。<br/>**说明：**<br/>-&nbsp;子组件的类型必须是ForEach的父容器组件所允许的（例如，只有当ForEach父级为List组件时，才允许LitemItem子组件）。<br/>-&nbsp;允许子类构造函数返回if或另一个ForEach。ForEach可以在if内的任意位置。<br/>-&nbsp;可选index参数如在函数体中使用，则必须仅在函数签名中指定。 |
+| keyGenerator  | (item:&nbsp;any,&nbsp;index?:&nbsp;number)&nbsp;=&gt;&nbsp;string | 否    | 匿名函数，用于给数组中的每一个数据项生成唯一且固定的键值。键值生成器的功能是可选的，但是，为了使开发框架能够更好地识别数组更改，提高性能，建议提供。如将数组反向时，如果没有提供键值生成器，则ForEach中的所有节点都将重建。<br/>**说明：**<br/>-&nbsp;同一数组中的不同项绝对不能计算出相同的ID。<br/>-&nbsp;如果未使用index参数，则项在数组中的位置变动不得改变项的键值。如果使用了index参数，则当项在数组中的位置有变动时，键值必须更改。<br/>-&nbsp;当某个项目被新项替换（值不同）时，被替换的项键值和新项的键值必须不同。<br/>-&nbsp;在构造函数中使用index参数时，键值生成函数也必须使用该参数。<br>-&nbsp;键值生成函数不允许改变任何组件状态。 |
+
+
+## 使用限制
+
+- ForEach必须在容器组件内使用。
+
+- 生成的子组件应当是允许包含在ForEach父容器组件中的子组件。
+
+- 允许子组件生成器函数中包含if/else条件渲染，同时也允许ForEach包含在if/else条件渲染语句中。
+
+- itemGenerator函数的调用顺序不一定和数组中的数据项相同，在开发过程中不要假设itemGenerator和keyGenerator函数是否执行及其执行顺序。例如，以下示例可能无法正确运行：
+
+  ```ts
+  ForEach(anArray.map((item1, index1) => { return { i: index1 + 1, data: item1 }; }), 
+    item => Text(`${item.i}. item.data.label`),
+    item => item.data.id.toString())
+  ```
+
+
+## 开发者的建议
+
+- 建议开发者不要假设项构造函数的执行顺序。执行顺序可能不能是数组中项的排列顺序。
+
+- 不要假设数组项是否是初始渲染。ForEach的初始渲染在\@Component首次渲染时构建所有数组项。后续框架版本中可能会将此行为更改为延迟加载模式。
+
+- 使用 index参数对UI更新性能有严重的负面影响，请尽量避免。
+
+- 如果项构造函数中使用index参数，则项索引函数中也必须使用该参数。否则，如果项索引函数未使用index参数，ForEach在生成实际的键值时，框架也会把index考虑进来，默认将index拼接在后面。
+
+
+## 使用场景
+
+
+### 简单ForEach示例
+
+根据arr数据分别创建3个Text和Divide组件。
+
+
+```ts
+@Entry
+@Component
+struct MyComponent {
+  @State arr: number[] = [10, 20, 30];
+
+  build() {
+    Column({ space: 5 }) {
+      Button('Reverse Array')
+        .onClick(() => {
+          this.arr.reverse();
+        })
+      ForEach(this.arr, (item: number) => {
+        Text(`item value: ${item}`).fontSize(18)
+        Divider().strokeWidth(2)
+      }, (item: number) => item.toString())
+    }
+  }
+}
+```
+
+
+### 复杂ForEach示例
+
+
+```ts
+@Component
+struct CounterView {
+  label: string;
+  @State count: number = 0;
+
+  build() {
+    Button(`${this.label}-${this.count} click +1`)
+      .width(300).height(40)
+      .backgroundColor('#a0ffa0')
+      .onClick(() => {
+        this.count++;
+      })
+  }
+}
+
+@Entry
+@Component
+struct MainView {
+  @State arr: number[] = Array.from(Array(10).keys()); // [0.,.9]
+  nextUnused: number = this.arr.length;
+
+  build() {
+    Column() {
+      Button(`push new item`)
+        .onClick(() => {
+          this.arr.push(this.nextUnused++)
+        })
+        .width(300).height(40)
+      Button(`pop last item`)
+        .onClick(() => {
+          this.arr.pop()
+        })
+        .width(300).height(40)
+      Button(`prepend new item (unshift)`)
+        .onClick(() => {
+          this.arr.unshift(this.nextUnused++)
+        })
+        .width(300).height(40)
+      Button(`remove first item (shift)`)
+        .onClick(() => {
+          this.arr.shift()
+        })
+        .width(300).height(40)
+      Button(`insert at pos ${Math.floor(this.arr.length / 2)}`)
+        .onClick(() => {
+          this.arr.splice(Math.floor(this.arr.length / 2), 0, this.nextUnused++);
+        })
+        .width(300).height(40)
+      Button(`remove at pos ${Math.floor(this.arr.length / 2)}`)
+        .onClick(() => {
+          this.arr.splice(Math.floor(this.arr.length / 2), 1);
+        })
+        .width(300).height(40)
+      Button(`set at pos ${Math.floor(this.arr.length / 2)} to ${this.nextUnused}`)
+        .onClick(() => {
+          this.arr[Math.floor(this.arr.length / 2)] = this.nextUnused++;
+        })
+        .width(300).height(40)
+      ForEach(this.arr,
+        (item) => {
+          CounterView({ label: item.toString() })
+        },
+        (item) => item.toString()
+      )
+    }
+  }
+}
+```
+
+MainView拥有一个\@State装饰的数字数组。添加、删除和替换数组项是可观察到的变化事件，当这些事件发生时，MainView内的ForEach都会更新。
+
+项目索引函数为每个数组项创建唯一且持久的键值，ArkUI框架通过此键值确定数组中的项是否有变化，只要键值相同，数组项的值就假定不变，但其索引位置可能会更改。此机制的运行前提是不同的数组项不能有相同的键值。
+
+使用计算出的ID，框架可以对添加、删除和保留的数组项加以区分：
+
+1. 框架将删除已删除数组项的UI组件。
+
+2. 框架仅对新添加的数组项执行项构造函数。
+
+3. 框架不会为保留的数组项执行项构造函数。如果数组中的项索引已更改，框架将仅根据新顺序移动其UI组件，但不会更新该UI组件。
+
+建议使用项目索引函数，但这是可选的。生成的ID必须是唯一的，这意味着不能为数组中的不同项计算出相同的ID。即使两个数组项具有相同的值，其ID也必须不同。
+
+如果数组项值更改，则ID必须更改。
+如前所述，id生成函数是可选的。以下是不带项索引函数的ForEach：
+
+  ```ts
+  ForEach(this.arr,
+    (item) => {
+      CounterView({ label: item.toString() })
+    }
+  )
+  ```
+
+如果没有提供项ID函数，则框架会尝试在更新ForEach时智能检测数组更改。但是，它可能会删除子组件，并为在数组中移动（索引被更改）的数组项重新执行项构造函数。在上面的示例中，这将更改应用程序针对CounterView counter状态的行为。创建新的CounterView实例时，counter的值将初始化为0。
+
+
+### 使用\@ObjectLink的ForEach示例
+
+当需要保留重复子组件的状态时，\@ObjectLink可将状态在组件树中向父组件推送。
+
+
+```ts
+let NextID: number = 0;
+
+@Observed
+class MyCounter {
+  public id: number;
+  public c: number;
+
+  constructor(c: number) {
+    this.id = NextID++;
+    this.c = c;
+  }
+}
+
+@Component
+struct CounterView {
+  @ObjectLink counter: MyCounter;
+  label: string = 'CounterView';
+
+  build() {
+    Button(`CounterView [${this.label}] this.counter.c=${this.counter.c} +1`)
+      .width(200).height(50)
+      .onClick(() => {
+        this.counter.c += 1;
+      })
+  }
+}
+
+@Entry
+@Component
+struct MainView {
+  @State firstIndex: number = 0;
+  @State counters: Array<MyCounter> = [new MyCounter(0), new MyCounter(0), new MyCounter(0),
+    new MyCounter(0), new MyCounter(0)];
+
+  build() {
+    Column() {
+      ForEach(this.counters.slice(this.firstIndex, this.firstIndex + 3),
+        (item) => {
+          CounterView({ label: `Counter item #${item.id}`, counter: item })
+        },
+        (item) => item.id.toString()
+      )
+      Button(`Counters: shift up`)
+        .width(200).height(50)
+        .onClick(() => {
+          this.firstIndex = Math.min(this.firstIndex + 1, this.counters.length - 3);
+        })
+      Button(`counters: shift down`)
+        .width(200).height(50)
+        .onClick(() => {
+          this.firstIndex = Math.max(0, this.firstIndex - 1);
+        })
+    }
+  }
+}
+```
+
+当增加firstIndex的值时，Mainview内的ForEach将更新，并删除与项ID firstIndex-1关联的CounterView子组件。对于ID为firstindex + 3的数组项，将创建新的CounterView子组件实例。由于CounterView子组件的状态变量counter值由父组件Mainview维护，故重建CounterView子组件实例不会重建状态变量counter值。
+
+> **说明：**
+>
+> 违反上述数组项ID规则是最常见的应用开发错误，尤其是在Array&lt;number&gt;场景下，因为执行过程中很容易添加重复的数字。
+
+
+### ForEach的嵌套使用
+
+允许将ForEach嵌套在同一组件中的另一个ForEach中，但更推荐将组件拆分为两个，每个构造函数只包含一个ForEach。下面为ForEach嵌套使用反例。
+
+
+```ts
+class Month {
+  year: number;
+  month: number;
+  days: number[];
+
+  constructor(year: number, month: number, days: number[]) {
+    this.year = year;
+    this.month = month;
+    this.days = days;
+  }
+}
+@Component
+struct CalendarExample {
+  // 模拟6个月
+  @State calendar : Month[] = [
+    new Month(2020, 1, [...Array(31).keys()]),
+    new Month(2020, 2, [...Array(28).keys()]),
+    new Month(2020, 3, [...Array(31).keys()]),
+    new Month(2020, 4, [...Array(30).keys()]),
+    new Month(2020, 5, [...Array(31).keys()]),
+    new Month(2020, 6, [...Array(30).keys()])
+  ]
+  build() {
+    Column() {
+      Button() {
+        Text('next month')
+      }.onClick(() => {
+        this.calendar.shift()
+        this.calendar.push(new Month(year: 2020, month: 7, days: [...Array(31).keys()]))
+      })
+      ForEach(this.calendar,
+        (item: Month) => {
+          ForEach(item.days,
+            (day : number) => {
+              // 构建日期块
+            },
+            (day : number) => day.toString()
+          )// 内部ForEach
+        },
+        (item: Month) => (item.year * 12 + item.month).toString() // 字段与年和月一起使用，作为月份的唯一ID。
+      )// 外部ForEach
+    }
+  }
+}
+```
+
+以上示例存在两个问题：
+
+1. 代码可读性差。
+
+2. 对于上述的年月份数据的数组结构形式，由于框架无法观察到针对该数组中Month数据结构的改变（比如day数组变化），从而内层的ForEach无法刷新日期显示。
+
+建议应用设计时将Calendar拆分为Year、Month和Day子组件。定义一个“Day”模型类，以保存有关day的信息，并用\@Observed装饰此类。DayView组件利用ObjectLink装饰变量以绑定day数据。对MonthView和Month模型类执行同样的操作。
+
+
+### ForEach中使用可选index参数示例
+
+可以在构造函数和ID生成函数中使用可选的index参数。
+
+
+```ts
+@Entry
+@Component
+struct ForEachWithIndex {
+  @State arr: number[] = [4, 3, 1, 5];
+
+  build() {
+    Column() {
+      ForEach(this.arr,
+        (it, indx) => {
+          Text(`Item: ${indx} - ${it}`)
+        },
+        (it, indx) => {
+          return `${indx} - ${it}`
+        }
+      )
+    }
+  }
+}
+```
+
+必须正确构造ID生成函数。当在项构造函数中使用index参数时，ID生成函数也必须使用index参数，以生成唯一ID和给定源数组项的ID。当数组项在数组中的索引位置发生变化时，其ID会发生变化。
+
+此示例还说明了index参数会造成显著性能下降。即使项在源数组中移动而不做修改，因为索引发生改变，依赖该数组项的UI仍然需要重新渲染。例如，使用索引排序时，数组只需要将ForEach未修改的子UI节点移动到正确的位置，这对于框架来说是一个轻量级操作。而使用索引时，所有子UI节点都需要重新构建，这操作负担要重得多。

zh-cn/application-dev/quick-start/arkts-rendering-control-ifelse.md

+# if/else：条件渲染
+
+
+ArkTS提供了渲染控制的能力。条件渲染可根据应用的不同状态，使用if、else和else if渲染对应状态下的UI内容。
+
+
+## 使用规则
+
+- 支持if、else和else if语句。
+
+- if、else if后跟随的条件语句可以使用状态变量。
+
+- 允许在容器组件内使用，通过条件渲染语句构建不同的子组件。
+
+- 条件渲染语句在涉及到组件的父子关系时是“透明”的，当父组件和子组件之间存在一个或多个if语句时，必须遵守父组件关于子组件使用的规则。
+
+- 每个分支内部的构建函数必须遵循构建函数的规则，并创建一个或多个组件。无法创建组件的空构建函数会产生语法错误。
+
+- 某些容器组件限制子组件的类型或数量，将条件渲染语句用于这些组件内时，这些限制将同样应用于条件渲染语句内创建的组件。例如，Grid容器组件的子组件仅支持GridItem组件，在Grid内使用条件渲染语句时，条件渲染语句内仅允许使用GridItem组件。
+
+
+## 更新机制
+
+当if、else if后跟随的状态判断中使用的状态变量值变化时，条件渲染语句会进行更新，更新步骤如下：
+
+1. 评估if和else if的状态判断条件，如果分支没有变化，请无需执行以下步骤。如果分支有变化，则执行2、3步骤：
+
+2. 删除此前构建的所有子组件。
+
+3. 执行新分支的构造函数，将获取到的组件添加到if父容器中。如果缺少适用的else分支，则不构建任何内容。
+
+条件可以包括Typescript表达式。对于构造函数中的表达式，此类表达式不得更改应用程序状态。
+
+
+## 使用场景
+
+
+### 使用if进行条件渲染
+
+
+```ts
+@Entry
+@Component
+struct ViewA {
+  @State count: number = 0;
+
+  build() {
+    Column() {
+      Text(`count=${this.count}`)
+
+      if (this.count > 0) {
+        Text(`count is positive`)
+          .fontColor(Color.Green)
+      }
+
+      Button('increase count')
+        .onClick(() => {
+          this.count++;
+        })
+
+      Button('decrease count')
+        .onClick(() => {
+          this.count--;
+        })
+    }
+  }
+}
+```
+
+if语句的每个分支都包含一个构建函数。此类构建函数必须创建一个或多个子组件。在初始渲染时，if语句会执行构建函数，并将生成的子组件添加到其父组件中。
+
+每当if或else if条件语句中使用的状态变量发生变化时，条件语句都会更新并重新评估新的条件值。如果条件值评估发生了变化，这意味着需要构建另一个条件分支。此时ArkUI框架将：
+
+1. 删除所有以前渲染的（早期分支的）组件。
+
+2. 执行新分支的构造函数，将生成的子组件添加到其父组件中。
+
+在以上示例中，如果count从0增加到1，那么if语句更新，条件count > 0将重新评估，评估结果将从false更改为true。因此，将执行条件为真分支的构造函数，创建一个Text组件，并将它添加到父组件Column中。如果后续count更改为0，则Text组件将从Column组件中删除。由于没有else分支，因此不会执行新的构造函数。
+
+
+### if ... else ...语句和子组件状态
+
+以下示例包含if ... else ...语句与拥有\@State装饰变量的子组件。
+
+
+```ts
+@Component
+struct CounterView {
+  @State counter: number = 0;
+  label: string = 'unknown';
+
+  build() {
+    Row() {
+      Text(`${this.label}`)
+      Button(`counter ${this.counter} +1`)
+        .onClick(() => {
+          this.counter += 1;
+        })
+    }
+  }
+}
+
+@Entry
+@Component
+struct MainView {
+  @State toggle: boolean = true;
+
+  build() {
+    Column() {
+      if (this.toggle) {
+        CounterView({ label: 'CounterView #positive' })
+      } else {
+        CounterView({ label: 'CounterView #negative' })
+      }
+      Button(`toggle ${this.toggle}`)
+        .onClick(() => {
+          this.toggle = !this.toggle;
+        })
+    }
+  }
+}
+```
+
+CounterView（label为 'CounterView \#positive'）子组件在初次渲染时创建。此子组件携带名为counter的状态变量。当修改CounterView.counter状态变量时，CounterView（label为 'CounterView \#positive'）子组件重新渲染时并保留状态变量值。当MainView.toggle状态变量的值更改为false时，MainView父组件内的if语句将更新，随后将删除CounterView（label为 'CounterView \#positive'）子组件。与此同时，将创建新的CounterView（label为 'CounterView \#negative'）实例。而它自己的counter状态变量设置为初始值0。
+
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+> CounterView（label为 'CounterView \#positive'）和CounterView（label为 'CounterView \#negative'）是同一自定义组件的两个不同实例。if分支的更改，不会更新现有子组件，也不会保留状态。
+
+以下示例展示了条件更改时，若需要保留counter值所做的修改。
+
+
+```
+@Component
+struct CounterView {
+  @Link counter: number;
+  label: string = 'unknown';
+
+  build() {
+    Row() {
+      Text(`${this.label}`)
+      Button(`counter ${this.counter} +1`)
+        .onClick(() => {
+          this.counter += 1;
+        })
+    }
+  }
+}
+
+@Entry
+@Component
+struct MainView {
+  @State toggle: boolean = true;
+  @State counter: number = 0;
+
+  build() {
+    Column() {
+      if (this.toggle) {
+        CounterView({ counter: $counter, label: 'CounterView #positive' })
+      } else {
+        CounterView({ counter: $counter, label: 'CounterView #negative' })
+      }
+      Button(`toggle ${this.toggle}`)
+        .onClick(() => {
+          this.toggle = !this.toggle;
+        })
+    }
+  }
+}
+```
+
+此处，\@State counter变量归父组件所有。因此，当CounterView组件实例被删除时，该变量不会被销毁。CounterView组件通过\@Link装饰器引用状态。状态必须从子级移动到其父级（或父级的父级），以避免在条件内容或重复内容被销毁时丢失状态。
+
+
+### 嵌套if语句
+
+条件语句的嵌套对父组件的相关规则没有影响。
+
+
+```ts
+@Entry
+@Component
+struct CompA {
+  @State toggle: boolean = false;
+  @State toggleColor: boolean = false;
+
+  build() {
+    Column() {
+      Text('Before')
+        .fontSize(15)
+      if (this.toggle) {
+        Text('Top True, positive 1 top')
+          .backgroundColor('#aaffaa').fontSize(20)
+        // 内部if语句
+        if (this.toggleColor) {
+          Text('Top True, Nested True, positive COLOR  Nested ')
+            .backgroundColor('#00aaaa').fontSize(15)
+        } else {
+          Text('Top True, Nested False, Negative COLOR  Nested ')
+            .backgroundColor('#aaaaff').fontSize(15)
+        }
+      } else {
+        Text('Top false, negative top level').fontSize(20)
+          .backgroundColor('#ffaaaa')
+        if (this.toggleColor) {
+          Text('positive COLOR  Nested ')
+            .backgroundColor('#00aaaa').fontSize(15)
+        } else {
+          Text('Negative COLOR  Nested ')
+            .backgroundColor('#aaaaff').fontSize(15)
+        }
+      }
+      Text('After')
+        .fontSize(15)
+      Button('Toggle Outer')
+        .onClick(() => {
+          this.toggle = !this.toggle;
+        })
+      Button('Toggle Inner')
+        .onClick(() => {
+          this.toggleColor = !this.toggleColor;
+        })
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-rendering-control-lazyforeach.md

+# LazyForEach：数据懒加载
+
+
+LazyForEach从提供的数据源中按需迭代数据，并在每次迭代过程中创建相应的组件。当LazyForEach在滚动容器中使用了，框架会根据滚动容器可视区域按需创建组件，当组件划出可视区域外时，框架会进行组件销毁回收以降低内存占用。
+
+
+## 接口描述
+
+
+```ts
+LazyForEach(
+    dataSource: IDataSource,             // 需要进行数据迭代的数据源 
+    itemGenerator: (item: any) => void,  // 子组件生成函数
+    keyGenerator?: (item: any) => string // (可选) .键值生成函数
+): void
+interface IDataSource {
+    totalCount(): number;                                             // Get total count of data
+    getData(index: number): any;                                      // Get single data by index
+    registerDataChangeListener(listener: DataChangeListener): void;   // Register listener to listening data changes
+    unregisterDataChangeListener(listener: DataChangeListener): void; // Unregister listener
+}
+interface DataChangeListener {
+    onDataReloaded(): void;                      // Called while data reloaded
+    onDataAdd(index: number): void;            // Called while single data added
+    onDataMove(from: number, to: number): void; // Called while single data moved
+    onDataDelete(index: number): void;          // Called while single data deleted
+    onDataChange(index: number): void;          // Called while single data changed
+}
+```
+
+**参数：**
+
+
+| 参数名           | 参数类型                                    | 必填   | 参数描述                                     |
+| ------------- | --------------------------------------- | ---- | ---------------------------------------- |
+| dataSource    | IDataSource                             | 是    | LazyForEach数据源，需要开发者实现相关接口。              |
+| itemGenerator | (item:&nbsp;any)&nbsp;=&gt;&nbsp;void   | 是    | 子组件生成函数，为数组中的每一个数据项创建一个子组件。<br/>**说明：**<br/>itemGenerator的函数体必须使用大括号{...}。itemGenerator每次迭代只能并且必须生成一个子组件。itemGenerator中可以使用if语句，但是必须保证if语句每个分支都会创建一个相同类型的子组件。itemGenerator中不允许使用ForEach和LazyForEach语句。 |
+| keyGenerator  | (item:&nbsp;any)&nbsp;=&gt;&nbsp;string | 否    | 键值生成函数，用于给数据源中的每一个数据项生成唯一且固定的键值。当数据项在数组中的位置更改时，其键值不得更改，当数组中的数据项被新项替换时，被替换项的键值和新项的键值必须不同。键值生成器的功能是可选的，但是，为了使开发框架能够更好地识别数组更改，提高性能，建议提供。如将数组反向时，如果没有提供键值生成器，则LazyForEach中的所有节点都将重建。<br/>**说明：**<br/>数据源中的每一个数据项生成的键值不能重复。 |
+
+
+## IDataSource类型说明
+
+
+```ts
+interface IDataSource {
+    totalCount(): number;
+    getData(index: number): any; 
+    registerDataChangeListener(listener: DataChangeListener): void;
+    unregisterDataChangeListener(listener: DataChangeListener): void;
+}
+```
+
+| 接口声明                                     | 参数类型               | 说明                                    |
+| ---------------------------------------- | ------------------ | ------------------------------------- |
+| totalCount():&nbsp;number                | -                  | 获得数据总数。                               |
+| getData(index:&nbsp;number):&nbsp;any    | number             | 获取索引值index对应的数据。<br/>index：获取数据对应的索引值 |
+| registerDataChangeListener(listener:DataChangeListener):&nbsp;void | DataChangeListener | 注册数据改变的监听器。<br/>listener：数据变化监听器      |
+| unregisterDataChangeListener(listener:DataChangeListener):&nbsp;void | DataChangeListener | 注销数据改变的监听器。<br/>listener：数据变化监听器      |
+
+
+## DataChangeListener类型说明
+
+
+```ts
+interface DataChangeListener {
+    onDataReloaded(): void;
+    onDataAdded(index: number): void;
+    onDataMoved(from: number, to: number): void;
+    onDataDeleted(index: number): void;
+    onDataChanged(index: number): void;
+    onDataAdd(index: number): void;
+    onDataMove(from: number, to: number): void;
+    onDataDelete(index: number): void;
+    onDataChange(index: number): void;
+}
+```
+
+| 接口声明                                     | 参数类型                                   | 说明                                       |
+| ---------------------------------------- | -------------------------------------- | ---------------------------------------- |
+| onDataReloaded():&nbsp;void              | -                                      | 通知组件重新加载所有数据。                            |
+| onDataAdded(index:&nbsp;number):void     | number                                 | 通知组件index的位置有数据添加。<br/>index：数据添加位置的索引值  |
+| onDataMoved(from:&nbsp;number,&nbsp;to:&nbsp;number):&nbsp;void | from:&nbsp;number,<br/>to:&nbsp;number | 通知组件数据有移动。<br/>from:&nbsp;数据移动起始位置，to:&nbsp;数据移动目标位置。<br/>**说明：**<br/>数据移动前后键值要保持不变，如果键值有变化，应使用删除数据和新增数据接口。 |
+| onDataChanged(index:&nbsp;number):&nbsp;void | number                                 | 通知组件index的位置有数据有变化。<br/>index：数据变化监听器。   |
+| onDataAdd(index:&nbsp;number):&nbsp;void | number                                 | 通知组件index的位置有数据添加。<br/>index：数据添加位置的索引值  |
+| onDataMove(from:&nbsp;number,&nbsp;to:&nbsp;number):&nbsp;void | from:&nbsp;number,<br/>to:&nbsp;number | 通知组件数据有移动。<br/>from:&nbsp;数据移动起始位置，to:&nbsp;数据移动目标位置。<br/>**说明：**<br/>数据移动前后键值要保持不变，如果键值有变化，应使用删除数据和新增数据接口。 |
+| onDataChanged(index:&nbsp;number):&nbsp;void | number                                 | 通知组件index的位置有数据有变化。<br/>index：数据变化位置的索引值 |
+
+
+## 使用限制
+
+- LazyForEach必须在容器组件内使用，仅有List、Grid以及Swiper组件支持数据懒加载（即只加载可视部分以及其前后少量数据用于缓冲），其他组件仍然是一次性加载所有的数据。
+
+- LazyForEach在每次迭代中，必须创建且只允许创建一个子组件。
+
+- 生成的子组件必须是允许包含在LazyForEach父容器组件中的子组件。
+
+- 允许LazyForEach包含在if/else条件渲染语句中，也允许LazyForEach中出现if/else条件渲染语句。
+
+- 键值生成器必须针对每个数据生成唯一的值，如果键值相同，将导致键值相同的UI组件被框架忽略，从而无法在父容器内显示。
+
+- LazyForEach必须使用DataChangeListener对象来进行更新，第一个参数dataSource使用状态变量时，状态变量改变不会触发LazyForEach的UI刷新。
+
+- 为了高性能渲染，通过DataChangeListener对象的onDataChange方法来更新UI时，需要生成不同于原来的键值来触发组件刷新。
+
+- itemGenerator函数的调用顺序不一定和数据源中的数据项相同，在开发过程中不要假设itemGenerator和keyGenerator函数是否执行及其执行顺序。例如，以下示例可能无法正常运行：
+
+
+  ```ts
+  LazyForEach(dataSource, 
+    item => Text(`${item.i}. item.data.label`),
+    item => item.data.id.toString())
+  ```
+
+
+## 示例
+
+
+```ts
+// Basic implementation of IDataSource to handle data listener
+class BasicDataSource implements IDataSource {
+  private listeners: DataChangeListener[] = [];
+
+  public totalCount(): number {
+    return 0;
+  }
+
+  public getData(index: number): any {
+    return undefined;
+  }
+
+  registerDataChangeListener(listener: DataChangeListener): void {
+    if (this.listeners.indexOf(listener) < 0) {
+      console.info('add listener');
+      this.listeners.push(listener);
+    }
+  }
+
+  unregisterDataChangeListener(listener: DataChangeListener): void {
+    const pos = this.listeners.indexOf(listener);
+    if (pos >= 0) {
+      console.info('remove listener');
+      this.listeners.splice(pos, 1);
+    }
+  }
+
+  notifyDataReload(): void {
+    this.listeners.forEach(listener => {
+      listener.onDataReloaded();
+    })
+  }
+
+  notifyDataAdd(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataAdd(index);
+    })
+  }
+
+  notifyDataChange(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataChange(index);
+    })
+  }
+
+  notifyDataDelete(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataDelete(index);
+    })
+  }
+
+  notifyDataMove(from: number, to: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataMove(from, to);
+    })
+  }
+}
+
+class MyDataSource extends BasicDataSource {
+  private dataArray: string[] = ['/path/image0', '/path/image1', '/path/image2', '/path/image3'];
+
+  public totalCount(): number {
+    return this.dataArray.length;
+  }
+
+  public getData(index: number): any {
+    return this.dataArray[index];
+  }
+
+  public addData(index: number, data: string): void {
+    this.dataArray.splice(index, 0, data);
+    this.notifyDataAdd(index);
+  }
+
+  public pushData(data: string): void {
+    this.dataArray.push(data);
+    this.notifyDataAdd(this.dataArray.length - 1);
+  }
+}
+
+@Entry
+@Component
+struct MyComponent {
+  private data: MyDataSource = new MyDataSource();
+
+  build() {
+    List({ space: 3 }) {
+      LazyForEach(this.data, (item: string) => {
+        ListItem() {
+          Row() {
+            Image(item).width('30%').height(50)
+            Text(item).fontSize(20).margin({ left: 10 })
+          }.margin({ left: 10, right: 10 })
+        }
+        .onClick(() => {
+          this.data.pushData('/path/image' + this.data.totalCount());
+        })
+      }, item => item)
+    }
+  }
+}
+```

zh-cn/application-dev/quick-start/arkts-rendering-control-overview.md

+# 渲染控制概述
+
+
+ArkUI通过[自定义组件](arkts-create-custom-components.md)的build()函数和[@builder装饰器](arkts-builder.md)中的声明式UI描述语句构建相应的UI。在声明式描述语句中开发者除了使用系统组件外，还可以使用渲染控制语句来辅助UI的构建，这些渲染控制语句包括控制组件是否显示的条件渲染语句，基于数组数据快速生成组件的循环渲染语句以及针对大数据量场景的数据懒加载语句。

zh-cn/application-dev/quick-start/arkts-rendering-control.md

-# 渲染控制
-
-ArkTS也提供了渲染控制的能力。条件渲染可根据应用的不同状态，渲染对应状态下的UI内容。循环渲染可从数据源中迭代获取数据，并在每次迭代过程中创建相应的组件。
-
-## 条件渲染
-
-使用if/else进行条件渲染。
-
-
-> **说明：**
->
-> - if/else条件语句可以使用状态变量。
->
-> - 使用if/else可以使子组件的渲染依赖条件语句。
->
-> - 必须在容器组件内使用。
->
-> - 某些容器组件限制子组件的类型或数量，将if/else用于这些组件内时，这些限制将同样应用于if/else语句内创建的组件。例如，Grid容器组件的子组件仅支持GridItem组件，在Grid内使用if/else时，则if/else语句内也仅允许使用GridItem组件。
-
-
-```ts
-Column() {
-  if (this.count < 0) {
-    Text('count is negative').fontSize(14)
-  } else if (this.count % 2 === 0) {
-    Text('count is even').fontSize(14)
-  } else {
-    Text('count is odd').fontSize(14)
-  }
-}
-```
-
-## 循环渲染
-
-通过循环渲染（ForEach）从数组中获取数据，并为每个数据项创建相应的组件，可减少代码复杂度。
-
-```ts
-ForEach(
-  arr: any[], 
-  itemGenerator: (item: any, index?: number) => void,
-  keyGenerator?: (item: any, index?: number) => string 
-)
-```
-
-从API version 9开始，该接口支持在ArkTS卡片中使用。
-
-**参数：**
-
-| 参数名        | 参数类型                              | 必填 | 参数描述                                                     |
-| ------------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
-| arr           | any[]                                 | 是   | 必须是数组，允许设置为空数组，空数组场景下将不会创建子组件。同时允许设置返回值为数组类型的函数，例如arr.slice(1, 3)，设置的函数不得改变包括数组本身在内的任何状态变量，如Array.splice、Array.sort或Array.reverse这些改变原数组的函数。 |
-| itemGenerator | (item: any, index?: number) => void   | 是   | 生成子组件的lambda函数，为数组中的每一个数据项创建一个或多个子组件，单个子组件或子组件列表必须包括在大括号“{...}”中。 |
-| keyGenerator  | (item: any, index?: number) => string | 否   | 匿名函数，用于给数组中的每一个数据项生成唯一且固定的键值。当数据项在数组中的位置更改时，其键值不得更改，当数组中的数据项被新项替换时，被替换项的键值和新项的键值必须不同。键值生成器的功能是可选的，但是，为了使开发框架能够更好地识别数组更改，提高性能，建议提供。如将数组反向时，如果没有提供键值生成器，则ForEach中的所有节点都将重建。 |
-
-> **说明：**
->
-> - ForEach必须在容器组件内使用。
->
-> - 生成的子组件应当是允许包含在ForEach父容器组件中的子组件。
->
-> - 允许子组件生成器函数中包含if/else条件渲染，同时也允许ForEach包含在if/else条件渲染语句中。
->
-> - itemGenerator函数的调用顺序不一定和数组中的数据项相同，在开发过程中不要假设itemGenerator和keyGenerator函数是否执行及其执行顺序。例如，以下示例可能无法正常工作：
->
->   ```ts
->   ForEach(anArray.map((item1, index1) => { return { i: index1 + 1, data: item1 }; }), 
->     item => Text(`${item.i}. item.data.label`),
->     item => item.data.id.toString())
->   ```
-
-## 示例
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct MyComponent {
-  @State arr: number[] = [10, 20, 30]
-
-  build() {
-    Column({ space: 5 }) {
-      Button('Reverse Array')
-        .onClick(() => {
-          this.arr.reverse()
-        })
-
-      ForEach(this.arr, (item: number) => {
-        Text(`item value: ${item}`).fontSize(18)
-        Divider().strokeWidth(2)
-      }, (item: number) => item.toString())
-    }
-  }
-}
-```
-
-![forEach1](figures/forEach1.gif)
-
-## 数据懒加载
-
-通过数据懒加载（LazyForEach）从提供的数据源中按需迭代数据，并在每次迭代过程中创建相应的组件。
-
-```ts
-LazyForEach(
-  dataSource: IDataSource,             
-  itemGenerator: (item: any) => void,  
-  keyGenerator?: (item: any) => string 
-): void
-
-interface IDataSource {
-  totalCount(): number;                                           
-  getData(index: number): any;                                   
-  registerDataChangeListener(listener: DataChangeListener): void;   
-  unregisterDataChangeListener(listener: DataChangeListener): void;
-}
-
-interface DataChangeListener {
-  onDataReloaded(): void;                      
-  onDataAdd(index: number): void;            
-  onDataMove(from: number, to: number): void; 
-  onDataDelete(index: number): void;         
-  onDataChange(index: number): void;          
-}
-```
-
-**参数：**
-
-| 参数名        | 参数类型              | 必填 | 参数描述                                                     |
-| ------------- | --------------------- | ---- | ------------------------------------------------------------ |
-| dataSource    | IDataSource           | 是   | 实现IDataSource接口的对象，需要开发者实现相关接口。          |
-| itemGenerator | (item: any, index?: number) => void   | 是   | 生成子组件的lambda函数，为数组中的每一个数据项创建一个或多个子组件，单个子组件或子组件列表必须包括在大括号“{...}”中。 |
-| keyGenerator  | (item: any, index?: number) => string | 否   | 匿名函数，用于给数组中的每一个数据项生成唯一且固定的键值。当数据项在数组中的位置更改时，其键值不得更改，当数组中的数据项被新项替换时，被替换项的键值和新项的键值必须不同。键值生成器的功能是可选的，但是，为了使开发框架能够更好地识别数组更改，提高性能，建议提供。如将数组反向时，如果没有提供键值生成器，则LazyForEach中的所有节点都将重建。 |
-
-### IDataSource类型说明
-
-| 名称                                                         | 描述                   |
-| ------------------------------------------------------------ | ---------------------- |
-| totalCount(): number                                         | 获取数据总数。         |
-| getData(index: number): any                                  | 获取索引值index对应的数据。   |
-| registerDataChangeListener(listener:DataChangeListener): void | 注册数据改变的监听器。 |
-| unregisterDataChangeListener(listener:DataChangeListener): void | 注销数据改变的监听器。 |
-
-### DataChangeListener类型说明
-
-| 名称                                                     | 描述                                   |
-| -------------------------------------------------------- | -------------------------------------- |
-| onDataReloaded(): void                                   | 重新加载所有数据。                     |
-| onDataAdded(index: number): void<sup>deprecated</sup>           | 通知组件index的位置有数据添加。从API Version 8开始废弃，建议使用onDataAdd。       |
-| onDataMoved(from: number, to: number): void<sup>deprecated</sup> | 通知组件数据从from的位置移到to的位置。从API Version 8开始废弃，建议使用onDataMove。 |
-| onDataDeleted(index: number): void<sup>deprecated</sup>         | 通知组件index的位置有数据删除。从API Version 8开始废弃，建议使用onDataDelete。        |
-| onDataChanged(index: number): void<sup>deprecated</sup>          | 通知组件index的位置有数据变化。 从API Version 8开始废弃，建议使用onDataChange。       |
-| onDataAdd(index: number): void<sup>8+</sup>                     | 通知组件index的位置有数据添加。        |
-| onDataMove(from: number, to: number): void<sup>8+</sup>           | 通知组件数据从from的位置移到to的位置。 |
-| onDataDelete(index: number): void<sup>8+</sup>                     | 通知组件index的位置有数据删除。        |
-| onDataChange(index: number): void<sup>8+</sup>                     | 通知组件index的位置有数据变化。        |
-
-## 示例
-
-```ts
-// xxx.ets
-class BasicDataSource implements IDataSource {
-  private listeners: DataChangeListener[] = []
-
-  public totalCount(): number {
-    return 0
-  }
-
-  public getData(index: number): any {
-    return undefined
-  }
-
-  registerDataChangeListener(listener: DataChangeListener): void {
-    if (this.listeners.indexOf(listener) < 0) {
-      console.info('add listener')
-      this.listeners.push(listener)
-    }
-  }
-
-  unregisterDataChangeListener(listener: DataChangeListener): void {
-    const pos = this.listeners.indexOf(listener);
-    if (pos >= 0) {
-      console.info('remove listener')
-      this.listeners.splice(pos, 1)
-    }
-  }
-
-  notifyDataReload(): void {
-    this.listeners.forEach(listener => {
-      listener.onDataReloaded()
-    })
-  }
-
-  notifyDataAdd(index: number): void {
-    this.listeners.forEach(listener => {
-      listener.onDataAdd(index)
-    })
-  }
-
-  notifyDataChange(index: number): void {
-    this.listeners.forEach(listener => {
-      listener.onDataChange(index)
-    })
-  }
-
-  notifyDataDelete(index: number): void {
-    this.listeners.forEach(listener => {
-      listener.onDataDelete(index)
-    })
-  }
-
-  notifyDataMove(from: number, to: number): void {
-    this.listeners.forEach(listener => {
-      listener.onDataMove(from, to)
-    })
-  }
-}
-
-class MyDataSource extends BasicDataSource {
-  // 初始化数据列表
-  private dataArray: string[] = ['/path/image0.png', '/path/image1.png', '/path/image2.png', '/path/image3.png']
-
-  public totalCount(): number {
-    return this.dataArray.length
-  }
-
-  public getData(index: number): any {
-    return this.dataArray[index]
-  }
-
-  public addData(index: number, data: string): void {
-    this.dataArray.splice(index, 0, data)
-    this.notifyDataAdd(index)
-  }
-
-  public pushData(data: string): void {
-    this.dataArray.push(data)
-    this.notifyDataAdd(this.dataArray.length - 1)
-  }
-}
-
-@Entry
-@Component
-struct MyComponent {
-  private data: MyDataSource = new MyDataSource()
-
-  build() {
-    List({ space: 3 }) {
-      LazyForEach(this.data, (item: string) => {
-        ListItem() {
-          Row() {
-            Image(item).width(50).height(50)
-            Text(item).fontSize(20).margin({ left: 10 })
-          }.margin({ left: 10, right: 10 })
-        }
-        .onClick(() => {
-          // 每点击一次列表项，数据增加一项
-          this.data.pushData('/path/image' + this.data.totalCount() + '.png')
-        })
-      }, item => item)
-    }.height('100%').width('100%')
-  }
-}
-```
-
-> **说明：**
->
-> - LazyForEach必须在容器组件内使用，目前仅有List、Grid以及Swiper组件支持数据懒加载（即只加载可视部分以及其前后少量数据用于缓冲），其他组件仍然是一次性加载所有的数据。
->
-> - LazyForEach在每次迭代中，必须创建且只允许创建一个子组件。
->
-> - 生成的子组件必须是允许包含在LazyForEach父容器组件中的子组件。
->
-> - 允许LazyForEach包含在if/else条件渲染语句中。
->
-> - 为了高性能渲染，通过DataChangeListener对象的onDataChange方法来更新UI时，仅当itemGenerator中创建的子组件内使用了状态变量时，才会触发组件刷新。
->
-> - itemGenerator函数的调用顺序不一定和数据源中的数据项相同，在开发过程中不要假设itemGenerator和keyGenerator函数是否执行及其执行顺序。例如，以下示例可能无法正常工作：
->
->   ```ts
->   LazyForEach(dataSource, 
->     item => Text(`${item.i}. item.data.label`),
->     item => item.data.id.toString())
->   ```
-
-![lazyForEach](figures/lazyForEach.gif)
\ No newline at end of file