diff --git a/en/application-dev/Readme-EN.md b/en/application-dev/Readme-EN.md
index d854b82e015d4bbf670b773670fd41ed1b856d03..95504e593a1ae40a3f8853ca28f3067c71729315 100644
--- a/en/application-dev/Readme-EN.md
+++ b/en/application-dev/Readme-EN.md
@@ -41,18 +41,46 @@
- [Resource Categories and Access](quick-start/resource-categories-and-access.md)
- Learning ArkTS
- [Getting Started with ArkTS](quick-start/arkts-get-started.md)
- - ArkTS Syntax (Declarative UI)
- - [Basic UI Description](quick-start/arkts-basic-ui-description.md)
- - State Management
- - [Basic Concepts](quick-start/arkts-state-mgmt-concepts.md)
- - [State Management with Page-level Variables](quick-start/arkts-state-mgmt-page-level.md)
- - [State Management with Application-level Variables](quick-start/arkts-state-mgmt-application-level.md)
- - [Dynamic UI Element Building](quick-start/arkts-dynamic-ui-elememt-building.md)
- - [Rendering Control](quick-start/arkts-rendering-control.md)
- - [Restrictions and Extensions](quick-start/arkts-restrictions-and-extensions.md)
+ - Basic Syntax
+ - [Basic Syntax Overview](quick-start/arkts-basic-syntax-overview.md)
+ - [Declarative UI Description](quick-start/arkts-declarative-ui-description.md)
+ - Custom Component
+ - [Creating a Custom Component](quick-start/arkts-create-custom-components.md)
+ - [Page and Custom Component Lifecycle](quick-start/arkts-page-custom-components-lifecycle.md)
+ - [\@Builder: Custom Builder Function](quick-start/arkts-builder.md)
+ - [\@BuilderParam: @Builder Function Reference](quick-start/arkts-builderparam.md)
+ - [\@Styles: Definition of Resusable Styles](quick-start/arkts-style.md)
+ - [\@Extend: Extension of Built-in Components](quick-start/arkts-extend.md)
+ - [stateStyles: Polymorphic Style](quick-start/arkts-statestyles.md)
+ - State Management
+ - [State Management Overview](quick-start/arkts-state-management-overview.md)
+ - Component State Management
+ - [\@State: State Owned by Component](quick-start/arkts-state.md)
+ - [\@Prop: One-Way Synchronization from Parent to Child Components](quick-start/arkts-prop.md)
+ - [\@Link: Two-Way Synchronization Between Parent and Child Components](quick-start/arkts-link.md)
+ - [\@Provide and \@Consume: Two-Way Synchronization with Descendant Components](quick-start/arkts-provide-and-consume.md)
+ - [\@Observed and \@ObjectLink: Observing Attribute Changes in Nested Class Objects](quick-start/arkts-observed-and-objectlink.md)
+ - Application State Management
+ - [Application State Management Overview](quick-start/arkts-application-state-management-overview.md)
+ - [LocalStorage: UI State Storage](quick-start/arkts-localstorage.md)
+ - [AppStorage: Application-wide UI State Storage](quick-start/arkts-appstorage.md)
+ - [PersistentStorage: Application State Persistence](quick-start/arkts-persiststorage.md)
+ - [Environment: Device Environment Query](quick-start/arkts-environment.md)
+ - Other State Management Features
+ - [Overview of Other State Management Features](quick-start/arkts-other-state-mgmt-functions-overview.md)
+ - [\@Watch: Getting Notified of State Variable Changes](quick-start/arkts-watch.md)
+ - [$$ Syntax: Two-Way Synchronization of Built-in Components](quick-start/arkts-two-way-sync.md)
+ - Rendering Control
+ - [Rendering Control Overview](quick-start/arkts-rendering-control-overview.md)
+ - [if/else: Conditional Rendering](quick-start/arkts-rendering-control-ifelse.md)
+ - [ForEach: Rendering of Repeated Content](quick-start/arkts-rendering-control-foreach.md)
+ - [LazyForEach: Lazy Data Loading](quick-start/arkts-rendering-control-lazyforeach.md)
+
+
- Development
- [Application Models](application-models/Readme-EN.md)
- [UI Development](ui/Readme-EN.md)
+ - [Web](web/Readme-EN.md)
- [Notification](notification/Readme-EN.md)
- [Window Manager](windowmanager/Readme-EN.md)
- [WebGL](webgl/Readme-EN.md)
@@ -86,6 +114,7 @@
- [ArkTS and JS APIs](reference/apis/Readme-EN.md)
- [Error Codes](reference/errorcodes/Readme-EN.md)
- Native APIs
+ - [Native APIs](reference/native-apis/Readme-EN.md)
- [Standard Libraries](reference/native-lib/third_party_libc/musl.md)
- [Node_API](reference/native-lib/third_party_napi/napi.md)
- [FAQs](faqs/Readme-EN.md)
diff --git a/en/application-dev/database/Readme-EN.md b/en/application-dev/database/Readme-EN.md
index b397b5b38682c9910724ea70e4759fe9a9aaf06e..77e1d8f9738d949ce9b0f0396bf66f99b9bf924e 100644
--- a/en/application-dev/database/Readme-EN.md
+++ b/en/application-dev/database/Readme-EN.md
@@ -5,7 +5,7 @@
- [Overview of Application Data Persistence](app-data-persistence-overview.md)
- [Persisting Preferences Data](data-persistence-by-preferences.md)
- [Persisting KV Store Data](data-persistence-by-kv-store.md)
- - [Persisting RDB Store Data] (data-persistence-by-rdb-store.md)
+ - [Persisting RDB Store Data](data-persistence-by-rdb-store.md)
- Distributed Application Data Synchronization
- [Distributed Application Data Synchronization Overview](sync-app-data-across-devices-overview.md)
- [Cross-Device Synchronization of KV Stores](data-sync-of-kv-store.md)
@@ -16,7 +16,7 @@
- [Database Backup and Restoration](data-backup-and-restore.md)
- [Database Encryption](data-encryption.md)
- [Access Control by Device and Data Level](access-control-by-device-and-data-level.md)
-- Cross-Application Data Sharing (Available Only for System Applications)
+- Cross-Application Data Sharing (for System Applications Only)
- [Cross-Application Data Sharing Overview](share-device-data-across-apps-overview.md)
- [Sharing Data Using DataShareExtensionAbility](share-data-by-datashareextensionability.md)
- [Sharing Data in Silent Access](share-data-by-silent-access.md)
diff --git a/en/application-dev/file-management/Readme-EN.md b/en/application-dev/file-management/Readme-EN.md
index 1e644dbac0ff2cf0e9f9deb205d234abc716ac08..bdc1bc7c1b00195bc24c71396f4fed78b93de15a 100644
--- a/en/application-dev/file-management/Readme-EN.md
+++ b/en/application-dev/file-management/Readme-EN.md
@@ -1,4 +1,4 @@
-# File
+# File Management
- [File Management Overview](file-management-overview.md)
- Application File
@@ -20,4 +20,4 @@
- Distributed File System
- [Distributed File System Overview](distributed-fs-overview.md)
- [Setting the Security Level of a Distributed File](set-security-label.md)
- - [Access Files Across Devices](file-access-across-devices.md)
+ - [Accessing Files Across Devices](file-access-across-devices.md)
diff --git a/en/application-dev/file-management/file-access-across-devices.md b/en/application-dev/file-management/file-access-across-devices.md
index 434af1a2920a9f9144dfa6e29bcf57edbd57bd93..840078f5f982d55a9d9a3713fafa49d632d352f8 100644
--- a/en/application-dev/file-management/file-access-across-devices.md
+++ b/en/application-dev/file-management/file-access-across-devices.md
@@ -1,4 +1,4 @@
-# Access Files Across Devices
+# Accessing Files Across Devices
The distributed file system provides cross-device file access capabilities for applications. For the same application installed on multiple devices, you can implement read and write of the files in the application's distributed directory (**/data/storage/el2/distributedfiles/**) across devices by using [ohos.file.fs](app-file-access.md). For example, device A and device B are installed with the same application. After device A and device B are connected to form a Virtual Device, the application on device A can access the files of the same application on Device B. What you need to do is place the files to the distributed directory.
diff --git a/en/application-dev/media/Readme-EN.md b/en/application-dev/media/Readme-EN.md
index f3a233ca129527db112459ab5110df49b8e1052d..efc78832291fda395506dc0864af4fae0f068621 100755
--- a/en/application-dev/media/Readme-EN.md
+++ b/en/application-dev/media/Readme-EN.md
@@ -45,11 +45,11 @@
- [Session Management](camera-session-management.md)
- [Camera Preview](camera-preview.md)
- [Camera Photographing](camera-shooting.md)
- - [Video Recording](camera-recording.md)
+ - [Camera Recording](camera-recording.md)
- [Camera Metadata](camera-metadata.md)
- Best Practices
- [Camera Photographing Sample](camera-shooting-case.md)
- - [Video Recording Sample](camera-recording-case.md)
+ - [Camera Recording Sample](camera-recording-case.md)
- Image
- [Image Overview](image-overview.md)
- [Image Decoding](image-decoding.md)
diff --git a/en/application-dev/media/camera-recording-case.md b/en/application-dev/media/camera-recording-case.md
index 4d284f7e675fe0693240bbb678391147926652e7..7aedbf5688812c47542ee627329b137325f17bbc 100644
--- a/en/application-dev/media/camera-recording-case.md
+++ b/en/application-dev/media/camera-recording-case.md
@@ -1,4 +1,4 @@
-# Video Recording Sample
+# Camera Recording Sample
## Development Process
diff --git a/en/application-dev/media/camera-recording.md b/en/application-dev/media/camera-recording.md
index 421ff990bf45b372dd39cd3346e29b636f292762..208b0664204ef2f74bb1160702053bde61fdf316 100644
--- a/en/application-dev/media/camera-recording.md
+++ b/en/application-dev/media/camera-recording.md
@@ -1,4 +1,4 @@
-# Video Recording
+# Camera Recording
Video recording is also an important function of the camera application. Video recording is the process of cyclic capturing of frames. To smooth videos, you can follow step 4 in [Camera Photographing](camera-shooting.md) to set the resolution, flash, focal length, photo quality, and rotation angle.
diff --git a/en/application-dev/quick-start/Readme-EN.md b/en/application-dev/quick-start/Readme-EN.md
index a60e0f7ef7b15e9b6a32f066a6c3eecbc32f6528..b7d98534c97fbf95b23ff1fb53ba67319696ef40 100644
--- a/en/application-dev/quick-start/Readme-EN.md
+++ b/en/application-dev/quick-start/Readme-EN.md
@@ -39,17 +39,37 @@
- [Resource Categories and Access](resource-categories-and-access.md)
- Learning ArkTS
- [Getting Started with ArkTS](arkts-get-started.md)
- - ArkTS Syntax (Declarative UI)
- - [Basic UI Description](arkts-basic-ui-description.md)
- - State Management
- - [Basic Concepts](arkts-state-mgmt-concepts.md)
- - [State Management with Page-level Variables](arkts-state-mgmt-page-level.md)
- - [State Management with Application-level Variables](arkts-state-mgmt-application-level.md)
- - [Dynamic UI Element Building](arkts-dynamic-ui-elememt-building.md)
- - [Rendering Control](arkts-rendering-control.md)
- - [Restrictions and Extensions](arkts-restrictions-and-extensions.md)
-- FAQs
- - [Full SDK Compilation Guide](full-sdk-compile-guide.md)
- - [Guide to Switching to Full SDK](full-sdk-switch-guide.md)
-- Tools
- - [DevEco Studio (OpenHarmony) User Guide](deveco-studio-user-guide-for-openharmony.md)
\ No newline at end of file
+ - Basic Syntax
+ - [Basic Syntax Overview](arkts-basic-syntax-overview.md)
+ - [Declarative UI Description](arkts-declarative-ui-description.md)
+ - Custom Component
+ - [Creating a Custom Component](arkts-create-custom-components.md)
+ - [Page and Custom Component Lifecycle](arkts-page-custom-components-lifecycle.md)
+ - [\@Builder: Custom Builder Function](arkts-builder.md)
+ - [\@BuilderParam: @Builder Function Reference](arkts-builderparam.md)
+ - [\@Styles: Definition of Resusable Styles](arkts-style.md)
+ - [\@Extend: Extension of Built-in Components](arkts-extend.md)
+ - [stateStyles: Polymorphic Style](arkts-statestyles.md)
+ - State Management
+ - [State Management Overview](arkts-state-management-overview.md)
+ - Component State Management
+ - [\@State: State Owned by Component](arkts-state.md)
+ - [\@Prop: One-Way Synchronization from Parent to Child Components](arkts-prop.md)
+ - [\@Link: Two-Way Synchronization Between Parent and Child Components](arkts-link.md)
+ - [\@Provide and \@Consume: Two-Way Synchronization with Descendant Components](arkts-provide-and-consume.md)
+ - [\@Observed and \@ObjectLink: Observing Attribute Changes in Nested Class Objects](arkts-observed-and-objectlink.md)
+ - Application State Management
+ - [Application State Management Overview](arkts-application-state-management-overview.md)
+ - [LocalStorage: UI State Storage](arkts-localstorage.md)
+ - [AppStorage: Application-wide UI State Storage](arkts-appstorage.md)
+ - [PersistentStorage: Application State Persistence](arkts-persiststorage.md)
+ - [Environment: Device Environment Query](arkts-environment.md)
+ - Other State Management Features
+ - [Overview of Other State Management Features](arkts-other-state-mgmt-functions-overview.md)
+ - [\@Watch: Getting Notified of State Variable Changes](arkts-watch.md)
+ - [$$ Syntax: Two-Way Synchronization of Built-in Components](arkts-two-way-sync.md)
+ - Rendering Control
+ - [Rendering Control Overview](arkts-rendering-control-overview.md)
+ - [if/else: Conditional Rendering](arkts-rendering-control-ifelse.md)
+ - [ForEach: Rendering of Repeated Content](arkts-rendering-control-foreach.md)
+ - [LazyForEach: Lazy Data Loading](arkts-rendering-control-lazyforeach.md)
diff --git a/en/application-dev/quick-start/arkts-application-state-management-overview.md b/en/application-dev/quick-start/arkts-application-state-management-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..b481f79298e585c00a8a6e5c80f1c6a5cc092949
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-application-state-management-overview.md
@@ -0,0 +1,13 @@
+# Application State Management Overview
+
+
+The decorators described in the previous topics are used to share state variables within a page, that is, within a component tree. If you want to share state data at the application level or across multiple pages, you would need to apply application-level state management. ArkTS provides a wide variety of application state management capabilities:
+
+
+- [LocalStorage](arkts-localstorage.md): API for storing the UI state, usually used for state sharing within a [UIAbility](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md) or between pages.
+
+- [AppStorage](arkts-appstorage.md): special, singleton LocalStorage object within the application, which is created by the UI framework at application startup and provides the central storage for application UI state attributes.
+
+- [PersistentStorage](arkts-persiststorage.md): API for persisting application attributes. It is usually used together with AppStorage to persist selected AppStorage attributes to the disk so that their values are the same upon application re-start as they were when the application was closed.
+
+- [Environment](arkts-environment.md): a range of environment parameters regarding the device where the application runs. The environment parameters are synchronized to the AppStorage and can be used together with the AppStorage.
diff --git a/en/application-dev/quick-start/arkts-appstorage.md b/en/application-dev/quick-start/arkts-appstorage.md
new file mode 100644
index 0000000000000000000000000000000000000000..c5f6196fc66ceaeb8630342b4256d7350e5fd2a0
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-appstorage.md
@@ -0,0 +1,203 @@
+# AppStorage: Application-wide UI State Storage
+
+
+AppStorage provides the central storage for mutable application UI state attributes. It is bound to the application process and is created by the UI framework at application startup.
+
+
+Unlike LocalStorage, which is usually used for page-level state sharing, AppStorage enables application-wide UI state sharing. AppStorage is equivalent to the hub of the entire application. [PersistentStorage](arkts-persiststorage.md) and [Environment](arkts-environment.md) data is passed first to AppStorage and then from AppStorage to the UI component.
+
+
+This topic describes only the AppStorage application scenarios and related decorators: \@StorageProp and \@StorageLink.
+
+
+## Overview
+
+AppStorage is a singleton LocalStorage object that is created by the UI framework at application startup. Its purpose is to provide the central storage for mutable application UI state attributes. AppStorage retains all those attributes and their values as long as the application remains running. Attributes are accessed using a unique key string value.
+
+UI components synchronize application state attributes with the AppStorage. Implementation of application business logic can access AppStorage as well.
+
+Selected state attributes of AppStorage can be synched with different data sources or data sinks. Those data sources and sinks can be on a local or remote device, and have different capabilities, such as data persistence (see [PersistentStorage](arkts-persiststorage.md)). These data sources and sinks are implemented in the business logic, separate from the UI. Link those AppStorage attributes to [@StorageProp](#storageprop) and [@StorageLink](#storagelink) whose values should be kept until application re-start.
+
+
+## \@StorageProp
+
+As mentioned above, if you want to establish a binding between AppStorage and a custom component, you need to use the \@StorageProp and \@StorageLink decorators. Use \@StorageProp(key) or \@StorageLink(key) to decorate variables in the component. **key** identifies the attribute in AppStorage.
+
+When a custom component is initialized, the \@StorageProp(key)/\@StorageLink(key) decorated variable is initialized with the value of the attribute with the given key in AppStorage. Local initialization is mandatory. If an attribute with the given key is missing from AppStorage, it will be added with the stated initializing value. (Whether the attribute with the given key exists in AppStorage depends on the application logic.)
+
+
+By decorating a variable with \@StorageProp(key), a one-way data synchronization is established with the attribute with the given key in AppStorage. A local change can be made, but it will not be synchronized to AppStorage. An update to the attribute with the given key in AppStorage will overwrite local changes.
+
+
+### Rules of Use
+
+| \@StorageProp Decorator| Description |
+| ------------------ | ---------------------------------------- |
+| Decorator parameters | **key**: constant string, mandatory (note, the string is quoted) |
+| Allowed variable types | Object, class, string, number, Boolean, enum, and array of these types. For details about the scenarios of nested objects, see [Observed Changes and Behavior](#observed-changes-and-behavior). = AppStorage.Link('PropA'); // link1.get() == 47
+var link2: SubscribedAbstractProperty = AppStorage.Link('PropA'); // link2.get() == 47
+var prop: SubscribedAbstractProperty = 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
+```
+
+
+### Example of Using AppStorage and LocalStorage from Inside the UI
+
+\@StorageLink works together with the AppStorage in the same way as \@LocalStorageLink works together with LocalStorage. It creates two-way data synchronization with an attribute in 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)
+ }
+ }
+}
+```
+
+
+## Restrictions
+
+When using AppStorage together with [PersistentStorage](arkts-persiststorage.md) and [Environment](arkts-environment.md), pay attention to the following:
+
+- A call to **PersistentStorage.PersistProp()** after creating the attribute in AppStorage uses the type and value in AppStorage and overwrites any attribute with the same name in PersistentStorage. In light of this, the opposite order of calls is recommended. For an example of incorrect usage, see [Accessing Attribute in AppStorage Before PersistentStorage](arkts-persiststorage.md#accessing-attribute-in-appstorage-before-persistentstorage).
+
+- A call to **Environment.EnvProp()** after creating the attribute in AppStorage will fail. This is because AppStorage already has an attribute with the same name, and the environment variable will not be written into AppStorage. Therefore, you are advised not to use the preset environment variable name in AppStorage.
diff --git a/en/application-dev/quick-start/arkts-basic-syntax-overview.md b/en/application-dev/quick-start/arkts-basic-syntax-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..59dd8e9e0ebb02f4f76b59985fe45e2e6b1f4cdd
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-basic-syntax-overview.md
@@ -0,0 +1,40 @@
+# Basic Syntax Overview
+
+
+With a basic understanding of the ArkTS language, let's look into the basic composition of ArkTS through an example. As shown below, when the user clicks the button, the text content changes from **Hello World** to **Hello ArkUI**.
+
+
+ **Figure 1** Example effect drawing
+
+
+
+
+In this example, the basic composition of ArkTS is as follows.
+
+
+ **Figure 2** Basic composition of ArkTS
+
+
+
+
+- Decorator: design pattern used to decorate classes, structures, methods, and variables to assign special meanings to them. In the preceding sample code, \@Entry, \@Component, and \@State are decorators. \@Component indicates a custom component, \@Entry indicates that the custom component is an entry component, and \@State indicates a state variable in the component, whose change will trigger the UI to re-render.
+
+- [UI description](arkts-declarative-ui-description.md): declarative description of the UI structure, such as the code block of the **build()** method.
+
+- [Custom component](arkts-create-custom-components.md): reusable UI unit, which can be combined with other components, such as the struct **Hello** decorated by @Component.
+
+- Built-in component: default basic or container component preset in ArkTS, which can be directly invoked, such as** \**,** \**, **\**, and **\** components in the sample code.
+
+- Attribute method: method used to configure component attributes, such as **fontSize()**, **width()**, **height()**, and **color()**. You can configure multiple attributes of a component in method chaining mode.
+
+- Event method: method used to add the logic for a component to respond to an event. In the sample code, **onClick()** following **Button** is an event method. You can configure response logic for multiple events in method chaining mode.
+
+
+ArkTS extends multiple syntax paradigms to make development a more enjoyable experience.
+
+
+- [@Builder](arkts-builder.md)/[@BuilderParam](arkts-builderparam.md): special method for encapsulating UI descriptions. It enables UI descriptions to be encapsulated and reused in a fine-grained manner.
+
+- [@Extend](arkts-extend.md)/[@Style](arkts-style.md): decorator that extends built-in components and encapsulates attribute styles to combine built-in components more flexibly.
+
+- [stateStyles](arkts-statestyles.md): polymorphic style, which can be set based on the internal state of the component.
diff --git a/en/application-dev/quick-start/arkts-basic-ui-description.md b/en/application-dev/quick-start/arkts-basic-ui-description.md
deleted file mode 100644
index 4ef7f97c280d7fcac0771a304359e58c26183d34..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-basic-ui-description.md
+++ /dev/null
@@ -1,205 +0,0 @@
-# Basic UI Description
-
-In ArkTS, you define a custom component by using decorators **@Component** and **@Entry** to decorate a data structure declared with the **struct** keyword. A custom component provides a **build** function, where you must write the basic UI description in chain call mode. For details about the UI description, see [UI Description Specifications](#ui-description-specifications).
-
-## Basic Concepts
-
-- struct: a data structure that can be used to implement custom components and cannot have inheritance. The **new** keyword can be omitted when initializing a struct.
-
-- Decorator: a special type of declaration that can be applied to classes, structures, or class attributes to add new functionality to them. Multiple decorators can be applied to the same target element and defined on a single line or multiple lines. It is recommended that the decorators be defined on multiple lines.
-
- ```ts
- @Entry
- @Component
- struct MyComponent {
- }
- ```
-
-- **build** function: A custom component must implement the **build** function and must implement no constructor. The **build** function meets the definition of the **Builder** API and is used to define the declarative UI description of components.
-
- ```ts
- interface Builder {
- build: () => void
- }
- ```
-
-- **@Component**: a decorator applied to a struct to equip it with the component-based capability. The **build** method must be implemented for UI creation.
-
-- **@Entry**: a decorator applied to a struct to make it the entry to a page, which is rendered and displayed when the page is loaded.
-
-- **@Preview**: a decorator applied to struct to make it previewable in the DevEco Studio Previewer. The decorated component is created and displayed when the residing page is loaded.
-
- > **NOTE**
- >
- > In a single source file, you can use up to 10 **@Preview** decorators to decorate custom components. For details, see [Previewing ArkTS Components](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-previewing-app-service-0000001218760596#section146052489820).
-
-- Chain call: a syntax for configuring the attribute methods, event methods, and more of UI components by using the dot notation.
-
-## UI Description Specifications
-
-### Structs Without Parameters
-
-A struct without parameters is a component whose API definition has empty parentheses. No parameter needs to be passed to this type of component, for example, the **Divider** component in the following snippet:
-
-```ts
-Column() {
- Text('item 1')
- Divider()
- Text('item 2')
-}
-```
-
-### Structs with Parameters
-
-A struct with parameters is a component whose API definition expects parameters enclosed in the parentheses. You can use constants to assign values to the parameters.
-
-Sample code:
-
-- Set the mandatory parameter **src** of the **\** component as follows:
-
- ```ts
- Image('https://xyz/test.jpg')
- ```
-
-- Set the optional parameter **content** of the **\** component as follows:
-
- ```ts
- Text('test')
- ```
-
-You can use variables or expressions to assign values to parameters. The result type returned by an expression must meet the parameter type requirements. For details about the variables, see [State Management with Page-level Variables](arkts-state-mgmt-page-level.md) and [State Management with Application-level Variables](arkts-state-mgmt-application-level.md). For example, set a variable or expression to construct the **\** and **\** components:
-
-```ts
-Image(this.imagePath)
-Image('https://' + this.imageUrl)
-Text(`count: ${this.count}`)
-```
-
-### Attribute Configuration
-
-Component attributes are configured using an attribute method, which follows the corresponding component and is bound to the component using the "**.**" operator.
-
-- Example of configuring the font size attribute of the **\** component:
-
- ```ts
- Text('test')
- .fontSize(12)
- ```
-
-- Example of configuring multiple attributes at the same time by using the "**.**" operator to implement chain call:
-
- ```ts
- Image('test.jpg')
- .alt('error.jpg')
- .width(100)
- .height(100)
- ```
-
-- Example of passing variables or expressions in addition to constants:
-
- ```ts
- Text('hello')
- .fontSize(this.size)
- Image('test.jpg')
- .width(this.count % 2 === 0 ? 100 : 200)
- .height(this.offset + 100)
- ```
-
-- For attributes of built-in components, ArkUI also provides some predefined [enumeration types](../reference/arkui-ts/ts-appendix-enums.md), which you can pass as parameters to methods if they meet the parameter type requirements. For example, you can configure the font color and weight attributes of the **\** component as follows:
-
- ```ts
- Text('hello')
- .fontSize(20)
- .fontColor(Color.Red)
- .fontWeight(FontWeight.Bold)
- ```
-
-### Event Configuration
-
-Events supported by components are configured using event methods, which each follow the corresponding component and are bound to the component using the "**.**" operator.
-
-- Example of using a lambda expression to configure the event of a component:
-
- ```ts
- Button('add counter')
- .onClick(() => {
- this.counter += 2;
- })
- ```
-
-- Example of using an anonymous function expression to configure the event of a component (**bind** must be used to ensure that the contained components are referenced by **this** in the function body):
-
- ```ts
- Button('add counter')
- .onClick(function () {
- this.counter += 2;
- }.bind(this))
- ```
-
-- Example of using a component's member function to configure the event of the component:
-
- ```ts
- myClickHandler(): void {
- this.counter += 2;
- }
-
- ...
-
- Button('add counter')
- .onClick(this.myClickHandler.bind(this))
- ```
-
-### Child Component Configuration
-
-For a component that supports child components, for example, a container component, add the UI descriptions of the child components inside parentheses. The **\**, **\**, **\**, **\**, and **\** components are all container components.
-
-- Simple example of the **\** component:
-
- ```ts
- Column() {
- Text('Hello')
- .fontSize(100)
- Divider()
- Text(this.myText)
- .fontSize(100)
- .fontColor(Color.Red)
- }
- ```
-
-- Example of nesting multiple child components in the **\** component:
-
- ```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!');
- })
- }
- }
- ```
diff --git a/en/application-dev/quick-start/arkts-builder.md b/en/application-dev/quick-start/arkts-builder.md
new file mode 100644
index 0000000000000000000000000000000000000000..0155cbe0cc2bfce54f79ca85c46c11083cf91923
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-builder.md
@@ -0,0 +1,130 @@
+# \@Builder: Custom Builder Function
+
+
+After a custom component is created, its internal UI structure is fixed and allows only data passing with its caller. ArkUI also provides a more lightweight mechanism for reusing UI elements: \@Builder. An \@Builder decorated function is a special function that serves similar purpose as the build function. The \@Builder function body follows the same syntax rules as the **build** function. You can abstract reusable UI elements into a method and call the method in **build**.
+
+
+To simplify language, here we refer to an \@Builder decorated function also as a custom builder function.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Rules of Use
+
+
+### Custom Builder Function
+
+Syntax:
+
+
+```ts
+@Builder myBuilderFunction({ ... })
+```
+
+Usage:
+
+
+```ts
+this.myBuilderFunction({ ... })
+```
+
+- Defining one or more custom builder (\@Builder decorated) functions inside a custom component is allowed. Such a custom builder function can be considered as a private, special type of member functions of that component.
+
+- The custom builder function can be called from the owning component's** build** or another custom builder (within that custom component) function only.
+
+- Inside the custom builder function body, **this** refers to the owning component. Component state variables are accessible from within the custom builder function implementation. Using the custom components' state variables is recommended over parameter passing.
+
+
+### Global Custom Builder Function
+
+Syntax:
+
+
+```ts
+@Builder function MyGlobalBuilderFunction({ ... })
+```
+
+Usage:
+
+
+```ts
+MyGlobalBuilderFunction()
+```
+
+
+- A global custom builder function is accessible from the entire application. **this** and the **bind** method are not allowed.
+
+- Use of a global custom builder function is recommended if no own state is required.
+
+
+## Parameter Passing Rules
+
+There are two types of parameter passing for custom builder functions: [by-value parameter passing](#by-value-parameter-passing) and [by-reference parameter passing](#by-reference-parameter-passing). Both of them must comply with the following rules:
+
+- The parameter type must be the same as the declared parameter type. The **undefined** or **null** constants as well as expressions evaluating to these values are not allowed.
+
+- All parameters are immutable inside the custom builder function. If mutability and synchronization of the mutation is required, the custom builder should be replaced by a custom component with a [@Link](arkts-link.md) decorated variable.
+
+- The \@Builder function body follows the same [syntax rules](arkts-create-custom-components.md#build-function) as the **build** function.
+
+
+### By-Reference Parameter Passing
+
+In by-reference parameter passing, the passed parameters can be state variables, and the change of these state variables causes the UI re-rendering in the \@Builder method. ArkUI provides $$ as a paradigm for by-reference parameter passing.
+
+
+```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() {
+ // Pass the this.label reference to the ABuilder component when the ABuilder component is called in the Parent component.
+ ABuilder({ paramA1: this.label })
+ Button('Click me').onClick(() => {
+ // After Click me is clicked, the UI text changes from Hello to ArkUI.
+ this.label = 'ArkUI';
+ })
+ }
+ }
+}
+```
+
+
+### By-Value Parameter Passing
+
+By default, parameters in the \@Builder decorated functions are passed by value. When the passed parameter is a state variable, the change of the state variable does not cause the UI re-rendering in the \@Builder method. Therefore, when using state variables, you are advised to use [by-reference parameter passing](#by-reference-parameter-passing).
+
+
+```ts
+@Builder function ABuilder(paramA1: string) {
+ Row() {
+ Text(`UseStateVarByValue: ${paramA1} `)
+ }
+}
+@Entry
+@Component
+struct Parent {
+ label: string = 'Hello';
+ build() {
+ Column() {
+ ABuilder(this.label)
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-builderparam.md b/en/application-dev/quick-start/arkts-builderparam.md
new file mode 100644
index 0000000000000000000000000000000000000000..26f25044c2968a5417fdc73fd355bd24997d14df
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-builderparam.md
@@ -0,0 +1,210 @@
+# \@BuilderParam: @Builder Function Reference
+
+
+In certain circumstances, you may need to add a specific function, such as a click-to-jump action, to a custom component. However, embedding an event method directly inside of the component will add the function to all places where the component is imported. This is where the \@BuilderParam decorator comes into the picture. \@BuilderParam is used to decorate a custom component member variable of type reference to an \@Builder method. When initializing a custom component, you can assign a value to the variable, thereby adding the specific function to the custom component. This decorator can be used to declare an element of any UI description, similar to a slot placeholder.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Rules of Use
+
+
+### Initializing \@BuilderParam Decorated Method
+
+An \@BuildParam decorated method can be initialized only by an \@Builder function reference.
+
+- Local initialization with the owning component's custom \@Builder function or a global \@Builder function reference
+
+ ```ts
+ @Builder function GlobalBuilder0() {}
+
+ @Component
+ struct Child {
+ @Builder doNothingBuilder() {};
+
+ @BuilderParam aBuilder0: () => void = this.doNothingBuilder;
+ @BuilderParam aBuilder1: () => void = GlobalBuilder0;
+ build(){}
+ }
+ ```
+
+- Initialization from the parent component
+
+ ```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** in the function body points to the correct object.
+
+ In the following example, when the **Parent** component calls **this.componentBuilder()**, **this.label** points to the owning component, that is, **Parent**. With **\@BuilderParam aBuilder0** passed to the **Child** component from **\@Builder componentBuilder()**, when the **Child** component calls **this.aBuilder0()**, **this.label** points to the label of the **Child** component, that is, **Child**.
+
+ > **NOTE**
+ >
+ > Exercise caution when using **bind** to change the context of function invoking, which may cause **this** to point to an incorrect object.
+
+ ```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 })
+ }
+ }
+ }
+ ```
+
+
+## Application Scenarios
+
+
+### Component Initialization Through Parameters
+
+An \@BuilderParam decorated method can be a method with or without parameters. Whether it contains parameters should match that of the assigned \@Builder method. The type of the \@BuilderParam decorated method must also match that of the assigned \@Builder method.
+
+
+```ts
+@Builder function GlobalBuilder1($$ : {label: string }) {
+ Text($$.label)
+ .width(400)
+ .height(50)
+ .backgroundColor(Color.Blue)
+}
+
+@Component
+struct Child {
+ label: string = 'Child'
+ // Without parameters. The pointed componentBuilder is also without parameters.
+ @BuilderParam aBuilder0: () => void;
+ // With parameters. The pointed GlobalBuilder1 is also with parameters.
+ @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 })
+ }
+ }
+}
+```
+
+
+### Example of Component Initialization Through Trailing Closure
+
+In a custom component, the \@BuilderParam decorated attribute can be initialized using a trailing closure. During initialization, the component name is followed by a pair of braces ({}) to form a trailing closure.
+
+> **NOTE**
+> In this scenario, the custom component has one and only one \@BuilderParam decorated attribute.
+
+You can pass the content in the trailing closure to \@BuilderParam as an \@Builder decorated method. Example:
+
+
+```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() {
+ // Create the CustomContainer component. During initialization, append a pair of braces ({}) to the component name to form a trailing closure.
+ // Used as the parameter passed to CustomContainer @BuilderParam closer: () => void.
+ CustomContainer({ header: this.text }) {
+ Column() {
+ specificParam('testA', 'testB')
+ }.backgroundColor(Color.Yellow)
+ .onClick(() => {
+ this.text = 'changeHeader';
+ })
+ }
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-create-custom-components.md b/en/application-dev/quick-start/arkts-create-custom-components.md
new file mode 100644
index 0000000000000000000000000000000000000000..f9219121d87e8281fd9ebcdd244b8c2c66b5b1b9
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-create-custom-components.md
@@ -0,0 +1,380 @@
+# Creating a Custom Component
+
+
+In ArkUI, components are what's displayed on the UI. They can be classified as built-in components – those directly provided by ArkUI framework, and custom components – those defined by developers. Defining the entire application UI with just built-in components would lead to a monolithic design, low code maintainability, and poor execution performance. A good UI is the result of a well-thought-out development process, with such factors as code reusability, separation of service logic from the UI, and version evolution carefully considered. Creating custom components that encapsulate the UI and some business logic is a critical step in this process.
+
+
+The custom component has the following features:
+
+
+- Combinable: allows you to combine built-in components and other components, as well as their attributes and methods.
+
+- Reusable: can be reused by other components and used as different instances in different parent components or containers.
+
+- Data-driven update: holds some state and triggers UI re-rendering with the change of state variables.
+
+
+The following example shows the basic usage of a custom component.
+
+
+
+```ts
+@Component
+struct HelloComponent {
+ @State message: string = 'Hello, World!';
+
+ build() {
+ // The HelloComponent custom component combines the and built-in components.
+ Row() {
+ Text(this.message)
+ .onClick(() => {
+ // The change of the state variable message drives the UI to be re-rendered. As a result, the text changes from "Hello, World!" to "Hello, ArkUI!".
+ this.message = 'Hello, ArkUI!';
+ })
+ }
+ }
+}
+```
+
+
+Multiple **HelloComponent** instances can be created in the **build()** function of other custom components. In this way, **HelloComponent** is reused by those custom components.
+
+
+
+```ts
+@Entry
+@Component
+struct ParentComponent {
+ build() {
+ Column() {
+ Text('ArkUI message')
+ HelloComponent({ message: 'Hello, World!' });
+ Divider()
+ HelloComponent ({ message: 'Hello!' });
+ }
+ }
+}
+```
+
+
+To fully understand the preceding example, a knowledge of the following concepts is essential:
+
+
+- [Basic Structure of a Custom Component](#basic-structure-of-a-custom-component)
+
+- [Member Functions/Variables](#member-functionsvariables)
+
+- [Rules of for Custom Component Parameters](#rules-of-for-custom-component-parameters)
+
+- [build Function](#build-function)
+
+- [Universal Style of a Custom Component](#universal-style-of-a-custom-component)
+
+- [Custom Attribute Methods](#custom-attribute-methods)
+
+
+## Basic Structure of a Custom Component
+
+- struct: The definition of a custom component must start with the \@Component struct followed by the component name, and then component body enclosed by curly brackets {....}. No inheritance is allowed. You can omit the **new** operator when instantiating a struct.
+ > **NOTE**
+ >
+ > The name or its class or function name of a custom component must be different from that of any built-in components.
+
+- \@Component: The \@Component decorator can decorate only the data structures declared by the **struct** keyword. After being decorated by \@Component, a struct has the componentization capability. It must implement the **build** function to describe the UI. One struct can be decorated by only one \@Component.
+ > **NOTE**
+ >
+ > Since API version 9, this decorator is supported in ArkTS widgets.
+
+ ```ts
+ @Component
+ struct MyComponent {
+ }
+ ```
+
+- build(): The **build()** function is used to define the declarative UI description of a custom component. Every custom component must define a **build()** function.
+
+ ```ts
+ @Component
+ struct MyComponent {
+ build() {
+ }
+ }
+ ```
+
+- \@Entry: A custom component decorated with \@Entry is used as the default entry component of the page. At most one component can be decorated with \@Entry in a single source file. The \@Entry decorator accepts an optional parameter of type [LocalStorage](arkts-localstorage.md).
+
+ > **NOTE**
+ >
+ > Since API version 9, this decorator is supported in ArkTS widgets.
+
+ ```ts
+ @Entry
+ @Component
+ struct MyComponent {
+ }
+ ```
+
+
+## Member Functions/Variables
+
+In addition to the mandatory** build()** function, a custom component may implement other member functions with the following restrictions:
+
+
+- Static functions are not supported.
+
+- Access to the member functions is always private. Defining **private** access is optional. Defining access other than **private** is a syntax error.
+
+
+A custom component can also implement member variables with the following restrictions:
+
+
+- Static member variables are not supported.
+
+- Access to the member variables is always private.The access rules of member variables are the same as those of member functions.
+
+- Local initialization is optional for some member variables and mandatory for others. For details about whether local initialization or initialization from the parent component is required, see [State Management](arkts-state-management-overview.md).
+
+
+## Rules of for Custom Component Parameters
+
+As can be learnt from preceding examples, a custom component can be created from a **build** or [@Builder](arkts-builder.md) function, and during the creation, parameters can be supplied to the component.
+
+
+```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() {
+ // Create an instance of MyComponent and initialize its countDownFrom variable with the value 10 and its color variable with the value this.someColor.
+ MyComponent({ countDownFrom: 10, color: this.someColor })
+ }
+ }
+}
+```
+
+
+## build Function
+
+All languages declared in the **build** function are called UI description languages. The UI description languages must comply with the following rules:
+
+- For an \@Entry decorated custom component, exactly one root component is required under the **build** function. This root component must be a container component. **ForEach** is not allowed at the top level.
+ For an \@Component decorated custom component, exactly one root component is required under the **build** function. This root component is not necessarily a container component. **ForEach** is not allowed at the top level.
+
+ ```ts
+ @Entry
+ @Component
+ struct MyComponent {
+ build() {
+ // Exactly one root component is required, and it must be a container component.
+ Row() {
+ ChildComponent()
+ }
+ }
+ }
+
+ @Component
+ struct ChildComponent {
+ build() {
+ // Exactly one root component is required, and it is not necessarily a container component.
+ Image('test.jpg')
+ }
+ }
+ ```
+
+- Local variable declaration is not allowed. The following example is invalid:
+
+ ```ts
+ build() {
+ // Invalid: Local variable declaration is not allowed.
+ let a: number = 1;
+ }
+ ```
+
+- **console.info** cannot be directly used in the UI description, but can be used in methods or functions. The following is an example:
+
+ ```ts
+ build() {
+ // Invalid: Use of console.info is not allowed.
+ console.info('print debug log');
+ }
+ ```
+
+- Creation of a local scope is not allowed. The following example is invalid:
+
+ ```ts
+ build() {
+ // Invalid: Creation of local scope is not allowed.
+ {
+ ...
+ }
+ }
+ ```
+
+- Calling a function other than the \@Builder decorated is not allowed. The parameters of built-in components can be the return values of TS methods.
+
+ ```ts
+ @Component
+ struct ParentComponent {
+ doSomeCalculations() {
+ }
+
+ calcTextValue(): string {
+ return 'Hello World';
+ }
+
+ @Builder doSomeRender() {
+ Text(`Hello World`)
+ }
+
+ build() {
+ Column() {
+ // Invalid: No function calls except @Builder functions.
+ this.doSomeCalculations();
+ // Valid: The function can be called.
+ this.doSomeRender();
+ // Valid: The parameter can be the return value of a TS method.
+ Text(this.calcTextValue())
+ }
+ }
+ }
+ ```
+
+- The **switch** syntax is not allowed. Use **if** instead. The following example is invalid:
+
+ ```ts
+ build() {
+ Column() {
+ // Invalid: The switch syntax is not allowed.
+ switch (expression) {
+ case 1:
+ Text('...')
+ break;
+ case 2:
+ Image('...')
+ break;
+ default:
+ Text('...')
+ break;
+ }
+ }
+ }
+ ```
+
+- Expressions are not allowed. The following example is invalid:
+
+ ```ts
+ build() {
+ Column() {
+ // Invalid: Expressions are not allowed.
+ (this.aVar > 10) ? Text('...') : Image('...')
+ }
+ }
+ ```
+
+
+## Universal Style of a Custom Component
+
+The universal style of a custom component is configured by invoking chainable attribute methods.
+
+
+```ts
+@Component
+struct MyComponent2 {
+ build() {
+ Button(`Hello World`)
+ }
+}
+
+@Entry
+@Component
+struct MyComponent {
+ build() {
+ Row() {
+ MyComponent2()
+ .width(200)
+ .height(300)
+ .backgroundColor(Color.Red)
+ }
+ }
+}
+```
+
+> **NOTE**
+>
+> When ArkUI sets styles for custom components, an invisible container component is set for **MyComponent2**. These styles are set on the container component instead of the **\** component of **MyComponent2**. As seen from the rendering result, the red background color is not directly applied to the button. Instead, it is applied to the container component that is invisible to users where the button is located.
+
+
+## Custom Attribute Methods
+
+Custom components do not support custom attribute methods. You can use the Controller capability to implement custom APIs.
+
+
+```ts
+// Custom controller
+export class MyComponentController {
+ item: MyComponent = null;
+
+ setItem(item: MyComponent) {
+ this.item = item;
+ }
+
+ changeText(value: string) {
+ this.item.value = value;
+ }
+}
+
+// Custom component
+@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); // Link to the controller.
+ }
+}
+
+// Processing logic
+@Entry
+@Component
+struct StyleExample {
+ controller = new MyComponentController();
+
+ build() {
+ Column() {
+ MyComponent({ controller: this.controller })
+ }
+ .onClick(() => {
+ this.controller.changeText('Text');
+ })
+ }
+}
+```
+
+In the preceding example:
+
+1. The **aboutToAppear** method of the **MyComponent** child component passes the current **this** pointer to the **item** member variable of **MyComponentController**.
+
+2. The **StyleExample** parent component holds a **Controller** instance and with which calls the **changeText** API of **Controller**. That is, the value of the state variable **value** of **MyComponent** is changed through the **this** pointer of the **MyComponent** child component held by the controller.
+
+Through the encapsulation of the controller, **MyComponent** exposes the **changeText** API. All instances that hold the controller can call the **changeText** API to change the value of the **MyComponent** state variable **value**.
diff --git a/en/application-dev/quick-start/arkts-declarative-ui-description.md b/en/application-dev/quick-start/arkts-declarative-ui-description.md
new file mode 100644
index 0000000000000000000000000000000000000000..1e73c239fa2146eb934886edfed1405d0f97fc13
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-declarative-ui-description.md
@@ -0,0 +1,172 @@
+# Declarative UI Description
+
+
+ArkTS declaratively combines and extends components to describe the UI of an application. It also provides basic methods for configuring attributes, events, and child components to help you implement application interaction logic.
+
+
+## Creating a Component
+
+Depending on the builder, you can create components with or without mandatory parameters.
+
+> **NOTE**
+>
+> The **new** operator is not required when you create a component.
+
+
+### Without Mandatory Parameters
+
+A struct without mandatory parameters is a component whose API definition has empty parentheses. No parameter needs to be passed to this type of component, for example, the **Divider** component in the following snippet:
+
+
+```ts
+Column() {
+ Text('item 1')
+ Divider()
+ Text('item 2')
+}
+```
+
+
+### With Mandatory Parameters
+
+A struct with mandatory parameters is a component whose API definition expects parameters enclosed in the parentheses.
+
+- Set the mandatory parameter **src** of the **\** component as follows:
+
+ ```ts
+ Image('https://xyz/test.jpg')
+ ```
+
+
+- Set the optional parameter **content** of the **\** component.
+
+ ```ts
+ // Parameter of the string type
+ Text('test')
+ // Add application resources in $r format, which can be used in multi-language scenarios.
+ Text($r('app.string.title_value'))
+ // No mandatory parameters
+ Text()
+ ```
+
+
+- You can also use variables or expressions to assign values to parameters. The result type returned by an expression must meet the parameter type requirements.
+ For example, to set a variable or expression to construct the **\** and **\** components:
+
+ ```ts
+ Image(this.imagePath)
+ Image('https://' + this.imageUrl)
+ Text(`count: ${this.count}`)
+ ```
+
+
+## Configuring Attributes
+
+Use chainable attribute methods to configure the style and other attributes of built-in components. It is recommended that a separate line be used for each attribute method.
+
+
+- Example of configuring the **fontSize** attribute for the **\** component:
+
+ ```ts
+ Text('test')
+ .fontSize(12)
+ ```
+
+- Example of configuring multiple attributes for the **\** component:
+
+ ```ts
+ Image('test.jpg')
+ .alt('error.jpg')
+ .width(100)
+ .height(100)
+ ```
+
+- Attribute methods accept expressions and variables as well constant parameters.
+
+ ```ts
+ Text('hello')
+ .fontSize(this.size)
+ Image('test.jpg')
+ .width(this.count % 2 === 0 ? 100 : 200)
+ .height(this.offset + 100)
+ ```
+
+- For built-in components, ArkUI also predefines some enumeration types. These enumeration types can be passed as parameters, as long as they meet the parameter type requirements.
+ Example of configuring the font color and style of the **\** component:
+
+ ```ts
+ Text('hello')
+ .fontSize(20)
+ .fontColor(Color.Red)
+ .fontWeight(FontWeight.Bold)
+ ```
+
+
+## Handling Events
+
+Use chainable event methods to configure events supported by built-in components. It is recommended that a separate line be used for each event method.
+
+
+- Example of using a lambda expression to configure the event of a component:
+
+ ```ts
+ Button('Click me')
+ .onClick(() => {
+ this.myText = 'ArkUI';
+ })
+ ```
+
+- Example of using an anonymous function expression to configure the event of a component (**bind** must be used to ensure that the current components are referenced by **this **in the function body):
+
+ ```ts
+ Button('add counter')
+ .onClick(function(){
+ this.counter += 2;
+ }.bind(this))
+ ```
+
+- Example of using a component's member function to configure the event of the component:
+
+ ```ts
+ myClickHandler(): void {
+ this.counter += 2;
+ }
+ ...
+ Button('add counter')
+ .onClick(this.myClickHandler.bind(this))
+ ```
+
+
+## Configuring Child Components
+
+For a component that supports child components, for example, a container component, add the UI descriptions of the child components inside parentheses. The **\**, **\**, **\**, **\**, and **\** components are all container components.
+
+
+- Simple example of configuring child components for the **\** component:
+
+ ```ts
+ Column() {
+ Text('Hello')
+ .fontSize(100)
+ Divider()
+ Text(this.myText)
+ .fontSize(100)
+ .fontColor(Color.Red)
+ }
+ ```
+
+- Example of nesting multiple child components in the **\** component:.
+
+ ```ts
+ Column() {
+ Row() {
+ Image('test1.jpg')
+ .width(100)
+ .height(100)
+ Button('click +1')
+ .onClick(() => {
+ console.info('+1 clicked!');
+ })
+ }
+ }
+ ```
diff --git a/en/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md b/en/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md
deleted file mode 100644
index a781f1d81c83a306c135b412b14ded55d032cb02..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md
+++ /dev/null
@@ -1,385 +0,0 @@
-# Dynamic UI Element Building
-
-After you've created a custom component (as described in [Basic UI Description](arkts-basic-ui-description.md)), you can customize the internal UI structure for the component, by drawing on the capability of dynamic UI element building.
-
-## @Builder
-
-The **@Builder** decorator is used to decorate a function for quickly generating multiple layouts in a custom component. This function can be declared outside the **build** function and used in the **build** function or other **@Builder** decorated functions. The following example shows how to use **@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"
-
- // Use the custom component CompB in the @Builder decorated function CompC.
- @Builder CompC(value: string) {
- CompB({ CompValue: value })
- }
-
- @Builder SquareText(label: string) {
- Text(label)
- .fontSize(18)
- .width(1 * this.size1)
- .height(1 * this.size1)
- }
-
- // Use the @Builder decorated function SquareText in the @Builder decorated function RowOfSquareTexts.
- @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() {
- // Use the @Builder decorated custom components three times.
- 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)
- }
-}
-```
-
-
-## @BuilderParam8+
-
-The **@BuilderParam** decorator is used to decorate the function type attributes (for example, **@BuilderParam noParam: () => void**) in a custom component. When the custom component is initialized, the attributes decorated by **@BuilderParam** must be assigned values.
-
-### Background
-
-In certain circumstances, you may need to add a specific function, such as a click-to-jump action, to a custom component. However, embedding an event method directly inside of the component will add the function to all places where the component is imported. This is where the **@BuilderParam** decorator comes into the picture. When initializing a custom component, you can assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute, thereby adding the specific function to the custom component.
-
-### Component Initialization Through Parameters
-
-When initializing a custom component through parameters, assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute — **content**, and call the value of **content** in the custom component. If no parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **noParam: this.specificNoParam**), define the type of the attribute as a function without a return value (for example, **@BuilderParam noParam: () => void**). If any parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **withParam: this.SpecificWithParam('WithParamA')**), define the type of the attribute as **any** (for example, **@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'
- })
- }
- }
-}
-```
-
-
-
-### Component Initialization Through Trailing Closure
-
-In a custom component, the **@BuilderParam** decorated attribute can be initialized using a trailing closure. During initialization, the component name is followed by a pair of braces ({}) to form a trailing closure (**CustomContainer(){}**). You can consider a trailing closure as a container and add content to it. For example, you can add a component (**{Column(){...}**) to the closure. The syntax of the closure is the same as that of **build**. In this scenario, the custom component has one and only one **@BuilderParam** decorated attribute.
-
-Example: Add a **\** component and a click event to the closure, and call the **specificParam** method decorated by **@Builder** in the new **\** component. After the **\** component is clicked, the value of the **CustomContainer** component's **header** attribute will change from **header** to **changeHeader**. When the component is initialized, the content of the trailing closure will be assigned to the **closer** attribute decorated by **@BuilderParam**.
-
-```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'
- })
- }
- }
- }
-}
-```
-
-
-
-## @Styles
-
-The **@Styles** decorator helps avoid repeated style setting, by extracting multiple style settings into one method. When declaring a component, you can invoke this method and use the **@Styles** decorator to quickly define and reuse the custom styles of a component. **@Styles** supports only universal attributes.
-
-**@Styles** can be defined inside or outside a component declaration. When it is defined outside a component declaration, the component name must be preceded by the keyword **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** can also be used inside the **[StateStyles](../reference/arkui-ts/ts-universal-attributes-polymorphic-style.md)** attribute declaration of a component, to assign state-specific attributes to the component.
-
-In **StateStyles**, **@Styles** decorated methods defined outside the component can be directly called, while those defined inside can be called only with the keyword **this**.
-
-```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
- })
- }
- }
-}
-```
-
-
-
-## @Extend
-
-The **@Extend** decorator adds new attribute methods to built-in components, such as **\**, **\**, and **\**. In this way, the built-in components are extended instantly.
-
-```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)
- }
- }
-}
-
-```
-
-> **NOTE**
->
-> - The **@Extend** decorator cannot be defined inside the struct of a custom component.
-> - The **@Extend** decorator supports only attribute methods.
-
-
-
-## @CustomDialog
-
-The **@CustomDialog** decorator is used to decorate custom dialog boxes, enabling their content and styles to be dynamically set.
-
-```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()
- })
- }
- }
-}
-```
-
-
diff --git a/en/application-dev/quick-start/arkts-environment.md b/en/application-dev/quick-start/arkts-environment.md
new file mode 100644
index 0000000000000000000000000000000000000000..e31c54b463e0d5d2fa40b46e0451e2377e405845
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-environment.md
@@ -0,0 +1,72 @@
+# Environment: Device Environment Query
+
+
+You may want your application to behave differently based on the device environment where the application is running, for example, switching to dark mode or a specific language. In this case, you need Environment for device environment query.
+
+
+Environment is a singleton object created by the ArkUI framework at application start. It provides a range of application state attributes to AppStorage that describe the device environment in which the application is running. Environment and its attributes are immutable. All property values are of simple type only.
+
+
+## Application Scenarios
+
+
+### Accessing Environment Parameters from UI
+
+- Use **Environment.EnvProp** to save the environment variables of the device to AppStorage.
+
+ ```ts
+ // Save the language code of the device to AppStorage. The default value is en.
+ // Whenever its value changes in the device environment, it will update its value in AppStorage.
+ Environment.EnvProp('languageCode', 'en');
+ ```
+
+- To keep a component variable updated with changes in the device environment, this variable should be decorated with \@StorageProp.
+
+ ```ts
+ @StorageProp('languageCode') lang : string = 'en';
+ ```
+
+The chain of updates is as follows: Environment > AppStorage > Component.
+
+> **NOTE**
+>
+> An \@StorageProp decorated variable can be locally modified, but the change will not be updated to AppStorage. This is because the environment variable parameters are read-only to the application.
+
+
+```ts
+// Save the device language code to AppStorage.
+Environment.EnvProp('languageCode', 'en');
+let enable = AppStorage.Get('languageCode');
+
+@Entry
+@Component
+struct Index {
+ @StorageProp('languageCode') languageCode: string = 'en';
+
+ build() {
+ Row() {
+ Column() {
+ // Output the current device language code.
+ Text(this.languageCode)
+ }
+ }
+ }
+}
+```
+
+
+### Using Environment in Application Logic
+
+
+```ts
+// Use Environment.EnvProp to save the device language code to AppStorage.
+Environment.EnvProp('languageCode', 'en');
+// Obtain the one-way bound languageCode variable from AppStorage.
+const lang: SubscribedAbstractProperty = AppStorage.Prop('languageCode');
+
+if (lang.get() === 'en') {
+ console.info('Hi');
+} else {
+ console.info('Hello!');
+}
+```
diff --git a/en/application-dev/quick-start/arkts-extend.md b/en/application-dev/quick-start/arkts-extend.md
new file mode 100644
index 0000000000000000000000000000000000000000..b6fd53b321a03305ed1a23de34d4119254160d0b
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-extend.md
@@ -0,0 +1,177 @@
+# \@Extend: Extension of Built-in Components
+
+
+Apart from\@Styles used to extend styles, AkrUI also provides \@Extend, which allows you to add a new attribute feature to a built-in component.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Rules of Use
+
+
+### Syntax
+
+
+```ts
+@Extend(UIComponentName) function functionName { ... }
+```
+
+
+### Rules of Use
+
+- Unlike \@Styles, \@Extend can be defined only globally, that is, outside a component declaration.
+
+- Unlike \@Styles, \@Extend can encapsulate private attributes and events of specified components and predefine \@Extend decorated methods of the same component.
+
+ ```ts
+ // @Extend(Text) supports the private attribute fontColor of the component.
+ @Extend(Text) function fancy () {
+ .fontColor(Color.Red)
+ }
+ // superFancyText can call the predefined fancy method.
+ @Extend(Text) function superFancyText(size:number) {
+ .fontSize(size)
+ .fancy()
+ }
+ ```
+
+
+- Unlike \@Styles, \@Extend decorated methods support parameters. You can pass parameters when calling such methods. Regular TypeScript provisions for method parameters apply.
+
+ ```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)
+ }
+ }
+ }
+ ```
+
+- A function can be passed as a parameter in an \@Extend decorated method to be used as the handler of the 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))
+ }
+ }
+ }
+ ```
+
+- A [state variable](arkts-state-management-overview.md) can be passed as a parameter in an \@Extend decorated method. When the state variable changes, the UI is updated and re-rendered.
+
+ ```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
+ })
+ }
+ }
+ }
+ ```
+
+
+## Application Scenarios
+
+The following example declares three **\** components. The **fontStyle**, **fontWeight**, and **backgroundColor** styles are set for each **\** component.
+
+
+```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 combines and reuses styles. The following is an example:
+
+
+```ts
+@Extend(Text) function fancyText(weightValue: number, color: Color) {
+ .fontStyle(FontStyle.Italic)
+ .fontWeight(weightValue)
+ .backgroundColor(color)
+}
+```
+
+With the use of \@Extend, the code readability is enhanced.
+
+
+```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%')
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-get-started.md b/en/application-dev/quick-start/arkts-get-started.md
index 3535650f871975be76fe4b24d9471a8d7895a255..2f8d2e93d4839f16c9986dc140cb115af5cbb6db 100644
--- a/en/application-dev/quick-start/arkts-get-started.md
+++ b/en/application-dev/quick-start/arkts-get-started.md
@@ -1,30 +1,17 @@
# Getting Started with ArkTS
-As its name implies, ArkTS is a superset of TypeScript. It is the preferred, primary programming language for application development in OpenHarmony.
-- ArkTS offers all the features of TS.
+ArkTS is the preferred main programming language for application development in OpenHarmony. ArkTS is a superset of [TypeScript](https://www.typescriptlang.org/) (TS for short). It contains all TS features and added features. Before getting started with ArkTS, it would be helpful if you have experience with TS development.
-- ArkTS extends TS mainly by adding [declarative UI](arkts-basic-ui-description.md) capabilities, which allow you to develop high-performance applications in a more natural and intuitive manner.
- The declarative UI capabilities offered by ArkTS include the following:
+The added features offered by ArkTS include the following:
- - [Basic UI description](arkts-basic-ui-description.md): A wide variety of decorators, custom components, and UI description mechanisms work with the built-in components, event methods, and attribute methods in ArkUI, jointly underpinning UI development.
- - [State management](arkts-state-mgmt-page-level.md): In the multi-dimensional state management mechanism for ArkUI, UI-related data can be used not only within a component, but also be transferred between different component levels (for example, between parent and child components, between grandparent and grandchild components, or globally) in a device or even across devices. In addition, data transfer can be classified as one-way (read-only) or two-way (mutable). You can use these capabilities at your disposal to implement linkage between data and the UI.
- - [Dynamic UI element building](arkts-dynamic-ui-elememt-building.md): In ArkTS, you can dynamically build UI elements, customizing the internal UI structure of components or extending the native components with custom component styles.
- - [Rendering control](arkts-rendering-control.md): ArkTS provides conditional rendering and loop rendering. Conditional rendering can render state-specific content based on the application status. Loop rendering iteratively obtains data from the data source and creates the corresponding component during each iteration.
- - [Restrictions and extensions](arkts-restrictions-and-extensions.md): ArkTS provides extensions, such as two-way binding. However, it is not without its restrictions.
-- ArkTS will continue to evolve to accommodate changing application development and running requirements, and gradually adds more features, such as parallelism and concurrency enhancement, typed system enhancement, and distributed development paradigm.
+- [Basic syntax](arkts-basic-syntax-overview.md): ArkTS defines declarative UI description, custom components, and dynamic extension of UI elements. All these, together with built-in components, event methods, and attribute methods in ArkUI, jointly underpin UI development.
-Below is sample code to illustrate the building blocks of ArkTS. It implements a simple UI with two text segments, one divider, and one button. When the user clicks the button, the text content changes from "Hello World" to "Hello ArkUI".
+- [State management](arkts-state-management-overview.md): In the multi-dimensional state management mechanism for ArkUI, UI-related data can be used not only within a component, but also be transferred between different component levels (for example, between parent and child components, between grandparent and grandchild components, or globally) in a device or even across devices. In addition, data transfer can be classified as one-way (read-only) or two-way (mutable). You can use these capabilities at your disposal to implement linkage between data and the UI.
-
+- [Rendering control](arkts-rendering-control-overview.md): ArkTS provides rendering control. Conditional rendering can render state-specific content based on the application status. **ForEach** iteratively obtains data from the data source and creates the corresponding component during each iteration. **LazyForEach** iterates over provided data sources and creates corresponding components during each iteration.
-As shown above, ArkTS has the following building blocks:
-- Decorators: used to decorate classes, structures, methods, and variables for custom definitions. In the preceding sample code, **@Entry**, **@Component**, and **@State** are decorators. Specifically, **@Component** indicates a custom component, **@Entry** indicates an entry component, and **@State** indicates a state variable in the component, whose change will trigger re-rendering of the UI.
-- Custom components: reusable UI units that can be used in flexible combinations. In the preceding sample code, the structure **Hello** decorated by **@Component** is a custom component.
-- UI description: declarative description of the UI structure, such as the code block of the **build()** method.
-- Built-in components: basic, container, media, drawing, and canvas components preset in ArkTS. You can directly invoke such components as **\**, **\**, **\**, and **\** components in the sample code.
-- Attribute methods: methods used to configure component attributes, such as **fontSize()**, **width()**, **height()**, and **color()**. You can configure multiple attributes of a component in method chaining mode.
-- Event methods: methods used to add the logic for a component to respond to an event. In the sample code, **onClick()** following **Button** is an event method. You can configure response logic for multiple events in method chaining mode.
+ArkTS will continue to evolve to accommodate changing application development and running requirements, and gradually adds more features, such as parallelism and concurrency enhancement, typed system enhancement, and distributed development paradigm.
diff --git a/en/application-dev/quick-start/arkts-link.md b/en/application-dev/quick-start/arkts-link.md
new file mode 100644
index 0000000000000000000000000000000000000000..28f91403ec2799d372d15ddf6daffa2241345dc8
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-link.md
@@ -0,0 +1,186 @@
+# \@Link: Two-Way Synchronization Between Parent and Child Components
+
+
+An \@Link decorated variable can create two-way synchronization with a variable of its parent component.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Overview
+
+An \@Link decorated variable in a child component shares the same value with a variable in its parent component.
+
+
+## Rules of Use
+
+| \@Link Decorator| Description |
+| ----------- | ---------------------------------------- |
+| Decorator parameters | None. |
+| Synchronization type | Two-way:** component is not updated synchronously, because **storage.get('countStorage')** returns a regular variable. The update of a regular variable does not cause the **\** component to be re-rendered.
+
+Changes in the **Child** custom component:
+
+1. The update of **playCountLink** is synchronized to LocalStorage, and the parent and sibling child custom components are re-rendered accordingly.
+
+ ```ts
+ let storage = new LocalStorage({ countStorage: 1 });
+
+ @Component
+ struct Child {
+ // Name the child component instance.
+ label: string = 'no name';
+ // Two-way synchronization with countStorage in LocalStorage.
+ @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('countStorage', 1 + storage.get('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('countStorage')}`)
+ .width(300).height(60).fontSize(12)
+ }
+ }
+ }
+ ```
+
+
+### Sharing a LocalStorage Instance from UIAbility to One or More Pages
+
+In the preceding examples, the LocalStorage instance is shared only in an \@Entry decorated component and its owning child component (a page). To enable a LocalStorage instance to be shared across pages, you can create a LocalStorage instance in the owning UIAbility and call windowStage.[loadContent](https://gitee.com/openharmony/docs/blob/master/en/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);
+ }
+}
+```
+
+On the page, call the **GetShared** API to obtain the LocalStorage instance shared through **loadContent**.
+
+
+```ts
+// Use the GetShared API to obtain the Storage instance shared by stage.
+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)
+ }
+ }
+}
+```
+
+
+> **NOTE**
+>
+> It is good practice to always create a LocalStorage instance with meaningful default values, which serve as a backup when execution exceptions occur and are also useful for unit testing of pages.
diff --git a/en/application-dev/quick-start/arkts-observed-and-objectlink.md b/en/application-dev/quick-start/arkts-observed-and-objectlink.md
new file mode 100644
index 0000000000000000000000000000000000000000..8b9beadc5fec17c0196dfeaae2ef28caea648042
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-observed-and-objectlink.md
@@ -0,0 +1,383 @@
+# \@Observed and \@ObjectLink: Observing Attribute Changes in Nested Class Objects
+
+
+The decorators described above can observe only the changes of the first layer. However, in real-world application development, the application may encapsulate its own data model based on development requirements. In the case of multi-layer nesting, for example, a two-dimensional array, an array item class, or a class insider another class as an attribute, the attribute changes at the second layer cannot be observed. This is where the \@Observed and \@ObjectLink decorators come in handy.
+
+
+> **NOTE**
+>
+> Since API version 9, these two decorators are supported in ArkTS widgets.
+
+
+## Overview
+
+\@ObjectLink and \@Observed class decorators are used for two-way data synchronization in scenarios involving nested objects or arrays:
+
+- Regarding classes decorated by \@Observed, the attribute changes can be observed.
+
+- The \@ObjectLink decorated state variable in the child component is used to accept the instance of the \@Observed decorated class and establish two-way data binding with the corresponding state variable in the parent component. The instance can be an \@Observed decorated item in the array or an \@Observeddecorated attribute in the class object.
+
+- Using \@Observed alone has no effect. Combined use with \@ObjectLink for two-way synchronization or with [\@Prop](arkts-prop.md) for one-way synchronization is required.
+
+
+## Decorator Description
+
+| \@Observed Decorator| Description |
+| -------------- | --------------------------------- |
+| Decorator parameters | None. |
+| Class decorator | Decorates a class. You must use **new** to create a class object before defining the class.|
+
+| \@ObjectLink Decorator| Description |
+| ----------------- | ---------------------------------------- |
+| Decorator parameters | None. |
+| Synchronization type | No synchronization with the parent component. |
+| Allowed variable types | Objects of \@Observed decorated classes. The type must be specified. {
+}
+```
+
+
+
+Declare a class that extends from** Array**: **class StringArray extends Array\ {}** and create an instance of **StringArray**. The use of the **new** operator is required for the \@Observed class decorator to work properly.
+
+
+```ts
+@Observed
+class StringArray extends Array {
+}
+
+@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 = [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) {
+ // We should have a real ID to use with ForEach, but we do no.
+ // Therefore, we need to make sure the pushed strings are unique.
+ 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('!');
+ }
+ })
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-other-state-mgmt-functions-overview.md b/en/application-dev/quick-start/arkts-other-state-mgmt-functions-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..89383e7ea4377d1ee56a1d8a365c0f9ac87d3379
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-other-state-mgmt-functions-overview.md
@@ -0,0 +1,9 @@
+# Overview of Other State Management Features
+
+
+In addition to the component state and application state management mentioned in previous topics, ArkTS also provides \@Watch and $$ for state management.
+
+
+- [\@Watch](arkts-watch.md) is used to listen for the changes of state variables.
+
+- [$$operator](arkts-two-way-sync.md) provides a TS variable by-reference to a built-in component so that the variable value and the internal state of that component are kept in sync.
diff --git a/en/application-dev/quick-start/arkts-page-custom-components-lifecycle.md b/en/application-dev/quick-start/arkts-page-custom-components-lifecycle.md
new file mode 100644
index 0000000000000000000000000000000000000000..2b8f2293918bef081b6f6377a99d6fdb2e35a03e
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-page-custom-components-lifecycle.md
@@ -0,0 +1,186 @@
+# Page and Custom Component Lifecycle
+
+
+Before we dive into the page and custom component lifecycle, it would be helpful to learn the relationship between custom components and pages.
+
+
+- Custom component: \@Component decorated UI unit, which can combine multiple built-in components for component reusability.
+
+- Page: UI page of an application. A page can consist of one or more custom components. A custom component decorated with \@Entry is used as the default entry component of the page. Exactly one component can be decorated with \@Entry in a single source file. Only components decorated by \@Entry can call the lifecycle callbacks of a page.
+
+
+The following lifecycle callbacks are provided for the lifecycle of a page, that is, the lifecycle of a custom component decorated with \@Entry:
+
+
+- [onPageShow](../reference/arkui-ts/ts-custom-component-lifecycle.md#onpageshow): Invoked when the page is displayed.
+
+- [onPageHide](../reference/arkui-ts/ts-custom-component-lifecycle.md#onpagehide): Invoked when the page is hidden.
+
+- [onBackPress](../reference/arkui-ts/ts-custom-component-lifecycle.md#onbackpress): Invoked when the user clicks the Back button.
+
+
+The following lifecycle callbacks are provided for the lifecycle of a custom component, which is one decorated with \@Component:
+
+
+- [aboutToAppear](../reference/arkui-ts/ts-custom-component-lifecycle.md#abouttoappear): Invoked when the custom component is about to appear. Specifically, it is invoked after a new instance of the custom component is created and before its **build** function is executed.
+
+- [aboutToDisappear](../reference/arkui-ts/ts-custom-component-lifecycle.md#abouttodisappear): Invoked before the destructor of the custom component is consumed.
+
+
+The following figure shows the lifecycle of a component (home page) decorated with \@Entry.
+
+
+
+
+
+Based on the preceding figure, let's look into the initial creation, re-rendering, and deletion of a custom component.
+
+
+## Custom Component Creation and Rendering
+
+1. Custom component creation: An instance of a custom component is created by the ArkUI framework.
+
+2. Initialization of custom component member variables: The member variables are initialized with locally defined default values or component constructor parameters. The initialization happens in the document order, which is the order in which the member variables are defined.
+
+3. If defined, the component's **aboutToAppear** callback is invoked.
+
+4. On initial render, the **build** function of a component is executed for rendering. The rendering creates instances of further child components. While executing the **build** function, the framework observes read access on each state variable and then constructs two mapping tables:
+ 1. State variable -> UI component (including **ForEach** and **if**)
+ 2. UI component -> Update function for this component, which is a lambda. As a subset of the **build** function, the lambda creates one UI component and executes its attribute methods.
+
+
+ ```ts
+ build() {
+ ...
+ this.observeComponentCreation(() => {
+ Button.create();
+ })
+
+ this.observeComponentCreation(() => {
+ Text.create();
+ })
+ ...
+ }
+ ```
+
+
+When the application is started in the background, since the application process is not destroyed, only the **onPageShow** callback is invoked.
+
+
+## Custom Component Re-rendering
+
+When an event handle is triggered (for example, the click event is triggered), the state variable of the component is changed, or the attribute in LocalStorage or AppStorage is changed, which causes the value of the linked state variable to be changed.
+
+
+1. The framework observes the variable change and marks the component for re-rendering.
+
+2. Using the two mapping tables created in step 4 of the custom component creation and rendering process, the framework knows which UI components are managed by the state variable and the update functions corresponding to these UI components. With this knowledge, the framework executes only the update functions of these UI components.
+
+
+## Custom Component Deletion
+
+A custom component is deleted when the branch of the **if** statement or the number of arrays in **ForEach** changes.
+
+
+1. Before the component is deleted, the **aboutToDisappear** callback is invoked to mark the component for deletion. The component deletion mechanism of ArkUI is as follows: (1) The backend component is directly removed from the component tree and destroyed; (2) The reference to the destroyed component is released from the frontend components; (3) The JS Engine garbage collects the destroyed component.
+
+2. The custom component and all its variables are deleted. Any variables linked to this component, such as [@Link](arkts-link.md), [@Prop](arkts-prop.md), or [@StorageLink](arkts-appstorage.md#storagelink) decorated variables, are unregistered from their [synchronization sources](arkts-state-management-overview.md#basic-concepts).
+
+
+Use of **async await** is not recommended inside the **aboutToDisappear** callback. In case of an asynchronous operation (a promise or a callback) being started from the **aboutToDisappear** callback, the custom component will remain in the Promise closure until the function has been called, which prevents the component from being garbage collected.
+
+
+The following example when the lifecycle callbacks are invoked:
+
+
+
+```ts
+// Index.ets
+import router from '@ohos.router';
+
+@Entry
+@Component
+struct MyComponent {
+ @State showChild: boolean = true;
+
+ // Only components decorated by @Entry can call the lifecycle callbacks of a page.
+ onPageShow() {
+ console.info('Index onPageShow');
+ }
+ // Only components decorated by @Entry can call the lifecycle callbacks of a page.
+ onPageHide() {
+ console.info('Index onPageHide');
+ }
+
+ // Only components decorated by @Entry can call the lifecycle callbacks of a page.
+ onBackPress() {
+ console.info('Index onBackPress');
+ }
+
+ // Component lifecycle
+ aboutToAppear() {
+ console.info('MyComponent aboutToAppear');
+ }
+
+ // Component lifecycle
+ aboutToDisappear() {
+ console.info('MyComponent aboutToDisappear');
+ }
+
+ build() {
+ Column() {
+ // When this.showChild is true, the Child child component is created, and Child aboutToAppear is invoked.
+ if (this.showChild) {
+ Child()
+ }
+ // When this.showChild is false, the Child child component is deleted, and Child aboutToDisappear is invoked.
+ Button('create or delete Child').onClick(() => {
+ this.showChild = false;
+ })
+ // Because of the pushing from the current page to Page2, onPageHide is invoked.
+ Button('push to next page')
+ .onClick(() => {
+ router.pushUrl({ url: 'pages/Page2' });
+ })
+ }
+
+ }
+}
+
+@Component
+struct Child {
+ @State title: string = 'Hello World';
+ // Component lifecycle
+ aboutToDisappear() {
+ console.info('[lifeCycle] Child aboutToDisappear')
+ }
+ // Component lifecycle
+ aboutToAppear() {
+ console.info('[lifeCycle] Child aboutToAppear')
+ }
+
+ build() {
+ Text(this.title).fontSize(50).onClick(() => {
+ this.title = 'Hello ArkUI';
+ })
+ }
+}
+```
+
+
+In the preceding example, the **Index** page contains two custom components. One is **MyComponent** decorated with \@Entry, which is also the entry component (root node) of the page. The other is **Child**, which is a child component of **MyComponent**. Only components decorated by \@Entry can call the lifecycle callbacks of a page.Therefore, the page lifecycle callbacks of the **Index** page are declared in **MyComponent**. **MyComponent** and its child components also declare the lifecycle callbacks of the respective component.
+
+
+- The initialization process of application cold start is as follows: MyComponent aboutToAppear -> MyComponent build -> Child aboutToAppear -> Child build -> Child build execution completed -> MyComponent build execution completed -> Index onPageShow.
+
+- When **delete Child** is clicked, the value of **this.showChild** linked to **if** changes to **false**. As a result, the **Child** component is deleted, and the **Child aboutToDisappear** callback is invoked.
+
+
+- When **push to next page** is clicked, the **router.pushUrl** API is called to jump to the next page. As a result, the **Index** page is hidden, and the **Index onPageHide** callback is invoked. As the called API is **router.pushUrl**, which results in the Index page being hidden, but not destroyed, only the **onPageHide** callback is invoked. After a new page is displayed, the process of initializing the lifecycle of the new page is executed.
+
+- If **router.replaceUrl** is called, the **Index** page is destroyed. In this case, the execution of lifecycle callbacks changes to: Index onPageHide -> MyComponent aboutToDisappear -> Child aboutToDisappear. As aforementioned, a component is destroyed by directly removing it from the component tree. Therefore, **aboutToDisappear** of the parent component is called first, followed by **aboutToDisAppear** of the child component, and then the process of initializing the lifecycle of the new page is executed.
+
+- When the Back button is clicked, the **Index onBackPress** callback is invoked. When the application is minimized or switched to the background, the **Index onPageHide** callback is invoked. The application is not destroyed in these two states. Therefore, the **aboutToDisappear** callback of the component is not executed. When the application returns to the foreground, the **Index onPageShow** callback is invoked.
+
+
+- When the application exits, the following callbacks are executed in order: Index onPageHide -> MyComponent aboutToDisappear -> Child aboutToDisappear.
diff --git a/en/application-dev/quick-start/arkts-persiststorage.md b/en/application-dev/quick-start/arkts-persiststorage.md
new file mode 100644
index 0000000000000000000000000000000000000000..cff8f9aa3bc83f9e1f34be3c50652c925ecd0437
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-persiststorage.md
@@ -0,0 +1,114 @@
+# PersistentStorage: Application State Persistence
+
+
+During application development, you may want selected attributes to persist even when the application is closed. In this case, you'll need PersistentStorage.
+
+
+PersistentStorage is an optional singleton object within an application. Its purpose is to persist selected AppStorage attributes so that their values are the same upon application re-start as they were when the application was closed.
+
+
+## Overview
+
+PersistentStorage retains the selected AppStorage attributes on the device disk. The application uses the API to determine which AppStorage attributes should be persisted with PersistentStorage. The UI and business logic do not directly access attributes in PersistentStorage. All attribute access is to AppStorage. Changes in AppStorage are automatically synchronized to PersistentStorage.
+
+PersistentStorage creates a two-way synchronization with attributes in AppStorage. A frequently used API function is to access AppStorage through PersistentStorage. Additional API functions include managing persisted attributes. The business logic always obtains or sets attributes through AppStorage.
+
+
+## Restrictions
+
+Persistence of data is a relatively slow operation. Applications should avoid the following situations:
+
+- Persistence of large data sets
+
+- Persistence of variables that change frequently
+
+The preceding situations may overload the change process of persisted data. As a result, the PersistentStorage implementation may limit the change frequency of persisted attributes.
+
+
+## Application Scenarios
+
+
+### Accessing PersistentStorage Initialized Attribute from AppStorage
+
+1. Initialize the PersistentStorage instance.
+
+ ```ts
+ PersistentStorage.PersistProp('aProp', 47);
+ ```
+
+2. Obtain the corresponding attribute from AppStorage.
+
+ ```ts
+ AppStorage.Get('aProp'); // returns 47
+ ```
+
+ Alternatively, apply local definition within the component:
+
+
+ ```ts
+ @StorageLink('aProp') aProp: number = 48;
+ ```
+
+The complete code is as follows:
+
+
+```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)
+ // The current result is saved when the application exits. After the restart, the last saved result is displayed.
+ Text(`${this.aProp}`)
+ .onClick(() => {
+ this.aProp += 1;
+ })
+ }
+ }
+ }
+}
+```
+
+- First running after fresh application installation:
+ 1. **PersistProp** is called to initialize PersistentStorage. A search for the **aProp** attribute on the PersistentStorage disk returns no result, because the application has just been installed.
+ 2. A search for the attribute **aProp** in AppStorage still returns no result.
+ 3. Create the **aProp** attribute of the number type in AppStorge and initialize it with the value 47.
+ 4. PersistentStorage writes the **aProp** attribute and its value **47** to the disk. The value of **aProp** in AppStorage and its subsequent changes are persisted.
+ 5. Create the state variable **\@StorageLink('aProp') aProp** in the **\** component, which creates a two-way synchronization with the **aProp** attribute in AppStorage. During the creation, the search in AppStorage for the **aProp** attribute succeeds, and therefore, the state variable is initialized with the value **47** found in AppStorage.
+
+ **Figure 1** PersistProp initialization process
+
+
+
+- After a click event is triggered:
+ 1. The state variable **\@StorageLink('aProp') aProp** is updated, triggering the **\** component to be re-rendered.
+ 2. The two-way synchronization between the \@StorageLink decorated variable and AppStorage results in the change of the **\@StorageLink('aProp') aProp** being synchronized back to AppStorage.
+ 3. The change of the **aProp** attribute in AppStorage triggers any other one-way or two-way bound variables to be updated. (In this example, there are no such other variables.)
+ 4. Because the attribute corresponding to **aProp** has been persisted, the change of the **aProp** attribute in AppStorage triggers PersistentStorage to write the attribute and its changed value to the device disk.
+
+- Subsequent application running:
+ 1. **PersistentStorage.PersistProp('aProp', 47)** is called. A search for the **aProp** attribute on the PersistentStorage disk succeeds.
+ 2. The attribute is added to AppStorage with the value found on the PersistentStorage disk.
+ 3. In the **\** component, the value of the @StorageLink decorated **aProp** attribute is the value written by PersistentStorage to AppStorage, that is, the value stored when the application was closed last time.
+
+
+### Accessing Attribute in AppStorage Before PersistentStorage
+
+This example is an incorrect use. It is incorrect to use the API to access the attributes in AppStorage before calling **PersistentStorage.PersistProp** or **PersistProps**, because such a call sequence will result in loss of the attribute values used in the previous application run:
+
+
+```ts
+let aProp = AppStorage.SetOrCreate('aProp', 47);
+PersistentStorage.PersistProp('aProp', 48);
+```
+
+**AppStorage.SetOrCreate('aProp', 47)**: The **aProp** attribute is created in AppStorage, its type is number, and its value is set to the specified default value **47**. **aProp** is a persisted attribute. Therefore, it is written back to the PersistentStorage disk, and the value stored in the PersistentStorage disk from the previous run is lost.
+
+**PersistentStorage.PersistProp('aProp', 48)**: An attribute with same name **aProp** is available in PersistentStorage.
diff --git a/en/application-dev/quick-start/arkts-prop.md b/en/application-dev/quick-start/arkts-prop.md
new file mode 100644
index 0000000000000000000000000000000000000000..9ec7914c4937a2e2d779a7520fea12c23d859385
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-prop.md
@@ -0,0 +1,367 @@
+# \@Prop: One-Way Synchronization from Parent to Child Components
+
+
+An \@Prop decorated variable can create one-way synchronization with a variable of its parent component. \@Prop decorated variables are mutable, but changes are not synchronized to the parent component.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Overview
+
+For an \@Prop decorated variable, the value synchronization is uni-directional from the parent component to the owning component.
+
+- An @Prop variable is allowed to be modified locally, but the change does not propagate back to its parent component.
+
+- Whenever that data source changes, the @Prop decorated variable gets updated, and any locally made changes are overwritten.
+
+
+## Rules of Use
+
+| \@Prop Decorator| Description |
+| ----------- | ---------------------------------------- |
+| Decorator parameters | None. |
+| Synchronization type | One-way: from the data source provided by the parent component to the @Prop decorated variable.|
+| Allowed variable types | string, number, boolean, or enum type.. For examples, see [Simple Type @Prop Synched from @State Array Item in Parent Component](#simple-type-prop-synched-from-state-array-item-in-parent-component).** child component inside the **if** would be updated.
+
+4. When **Try again** in the **CountDownComponent** child component is touched, the value of the **count** variable is modified, but the change remains within the child component and does not affect the **countDownStartValue** in the parenet component.
+
+5. Updating **countDownStartValue** will overwrite the local value changes of the @Prop decorated **count** in the **CountDownComponent** child component.
+
+
+### Simple Type @Prop Synched from @State Array Item in Parent Component
+
+
+The \@State decorated array an array item in the parent component can be used as data source to initialize and update a @Prop decorated variable. In the following example, the \@State decorated array **arr** in the parent component **Index** initializes the \@Prop decorated **value** variable in the child component **Child**.
+
+
+
+```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(()=>{
+ // Both arrays contain item "3".
+ this.arr = this.arr[0] == 1 ? [3,4,5] : [1,2,3];
+ })
+ }
+ }
+ }
+}
+```
+
+
+Initial render creates six instances of the **Child** component. Each \@Prop decorated variable is initialized with a copy of an array item. The **onclick** event handler of the **Child** component changes the local variable value.
+
+
+Assume that we clicked so many times that all local values be '7'.
+
+
+
+```
+7
+7
+7
+----
+7
+7
+7
+```
+
+
+After **replace entire arr** is clicked, the following information is displayed:
+
+
+
+```
+3
+4
+5
+----
+7
+4
+5
+```
+
+
+- Changes made in the **Child** component are not synchronized to the parent component **Index**. Therefore, even if the values of the six intances of the **Child** component are 7, the value of **this.arr** in the **Index** component is still **[1,2,3]**.
+
+- After **replace entire arr** is clicked, if **this.arr[0] == 1** is true, **this.arr** is set to **[3, 4, 5]**.
+
+- Because **this.arr[0]** has been changed, the **Child({value: this.arr[0]})** component synchronizes the update of **this.arr[0]** to the instance's \@Prop decorated variable. The same happens for **Child({value: this.arr[1]})** and **Child({value: this.arr[2]})**.
+
+
+- The change of **this.arr** causes **ForEach** to update: The array item with the ID **3** is retained in this update, array items with IDs **1** and **2** are deleted, and array items with IDs **4** and **5** are added. The array before and after the update is **[1, 2, 3]** and **[3, 4, 5]**, respectively. This implies that the **Child** instance generated for item **3** will be moved to the first place, but not updated. In this case, the component value corresponding to **3** is **7**, and the final render result of **ForEach** is **7**, **4**, and **5**.
+
+
+### Class Object Type @Prop Synchedd from @State Class Object Property in Parent Component
+
+In a library with one book and two users, each user can mark the book as read, but this does not affect the other user reader. Technically speaking, local changes to the \@Prop decorated **book** object do not sync back to the @State decorated **book** in the **Library** component.
+
+
+```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 })
+ }
+ }
+}
+```
+
+
+### Simple Type @Prop with Local Initialization and No Sync from Parent Parent
+
+To enable an \@Component decorated component to be reusable, \@Prop allows for optional local initialization. This makes the synchronization with a variable in the parent component a choice, rather than mandatory. Providing a data source in the parent component is optional only when local initialization is provided for the \@Prop decorated variable.
+
+The following example includes two @Prop decorated variables in child component.
+
+- The @Prop decorated variable **customCounter** has no local initialization, and therefore it requires a synchronization source in its parent component. When the source value changes, the @Prop decorated variable is udpated.
+
+- The @Prop decorated variable **customCounter2** has local initialization. In this case, specifying a synchronization source in the parent component is allowed but not mandatory.
+
+
+```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 must be initialized from the parent component due to lack of local initialization. Here, customCounter2 does not need to be initialized.
+ MyComponent({ customCounter: this.mainCounter })
+ // customCounter2 of the child component can also be initialized from the parent component. The value from the parent component overwrites the locally assigned value of customCounter2 during initialization.
+ MyComponent({ customCounter: this.mainCounter, customCounter2: this.mainCounter })
+ }.width('40%')
+ }
+
+ Row() {
+ Text('').width(480).height(10)
+ }
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-provide-and-consume.md b/en/application-dev/quick-start/arkts-provide-and-consume.md
new file mode 100644
index 0000000000000000000000000000000000000000..d8dc8f5b41748c06982e6d339a88e0b2261dbd69
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-provide-and-consume.md
@@ -0,0 +1,172 @@
+# \@Provide and \@Consume: Two-Way Synchronization with Descendant Components
+
+
+\@Provide and \@Consume are used for two-way data synchronization with descendant components in scenarios where state data needs to be transferred between multiple levels. They do not involve passing a variable from component to component multiple times.
+
+
+An \@Provide decorated state variable exists in the ancestor component and is said to be "provided" to descendent components. An \@Consume decorated state variable is used in a descendent component. It is linked to ("consumes") the provided state variable in its ancestor component.
+
+
+> **NOTE**
+>
+> Since API version 9, these two decorators are supported in ArkTS widgets.
+
+
+## Overview
+
+\@Provide/\@Consume decorated state variables have the following features:
+
+- An \@Provide decorated state variable becomes available to all descendent components of the providing component automatically. The variable is said to be "provided" to other components. This means that you do not need to pass a variable from component to component multiple times.
+
+- A descendent component gains access to the provided state variable by decorating a variable with \@Consume. This establishes a two-way data synchronization between the provided and the consumed variable. This synchronization works the same as a combination of \@State and \@Link does. The only difference is that the former allows transfer across multiple levels of the UI parent-child hierarchy.
+
+- \@Provide and \@Consume can be bound using the same variable name or variable alias. The variable types must be the same.
+
+
+```ts
+// Binding through the same variable name
+@Provide a: number = 0;
+@Consume a: number;
+
+// Binding through the same variable alias
+@Provide('a') b: number = 0;
+@Consume('a') c: number;
+```
+
+
+When \@Provide and \@Consume are bound through the same variable name or variable alias, the variables decorated by \@Provide and \@Consume are in a one-to-many relationship. A custom component, including its child components, cannot contain multiple \@Provide decorated variables under the same name or alias.
+
+
+## Decorator Description
+
+The rules of \@State also apply to \@Provide. The difference is that \@Provide also functions as a synchronization source for multi-layer descendants.
+
+| \@Provide Decorator| Description |
+| -------------- | ---------------------------------------- |
+| Decorator parameters | Alias: constant string, optional.** child component is allowed only when the parent container component of **ForEach** is **\**.** and **\** components based on the **arr** data.
+
+
+```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())
+ }
+ }
+}
+```
+
+
+### Complex ForEach Example
+
+
+```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** has an \@State decorated array of numbers. Adding, deleting, and replacing array items are observed mutation events. Whenever one of these events occurs, **ForEach** in **MainView** is updated.
+
+The item index function creates a unique and persistent ID for each array item. The ArkUI framework uses this ID to determine whether an item in the array changes. As long as the ID is the same, the item value is assumed to remain unchanged, but its index position may have changed. For this mechanism to work, different array items cannot have the same ID.
+
+Using the item ID obtained through computation, the framework can distinguish newly created, removed, and retained array items.
+
+1. The framework removes UI components for a removed array item.
+
+2. The framework executes the item build function only for newly added array items.
+
+3. The framework does not execute the item build function for retained array items. If the item index within the array has changed, the framework will just move its UI components according to the new order, but will not update that UI components.
+
+The item index function is recommended, but optional. The generated IDs must be unique. This means that the same ID must not be computed for any two items within the array. The ID must be different even if the two array items have the same value.
+
+If the array item value changes, the ID must be changed.
+As mentioned earlier, the ID generation function is optional. The following example shows **ForEach** without the item index function:
+
+ ```ts
+ ForEach(this.arr,
+ (item) => {
+ CounterView({ label: item.toString() })
+ }
+ )
+ ```
+
+If no item ID function is provided, the framework attempts to intelligently detect array changes when updating **ForEach**. However, it might remove child components and re-execute the item build function for array items that have been moved (with indexes changed). In the preceding example, this changes the application behavior in regard to the **counter** state of **CounterView**. When a new **CounterView** instance is created, the value of **counter** is initialized with **0**.
+
+
+### Example of ForEach Using \@ObjectLink
+
+If your application needs to preserve the state of repeated child components, you can use \@ObjectLink to enable the state to be "pushed up the component tree."
+
+
+```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 = [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);
+ })
+ }
+ }
+}
+```
+
+When the value of **firstIndex** is increased, **ForEach** within **Mainview** is updated, and the **CounterView** child component associated with the item ID **firstIndex-1** is removed. For the array item whose ID is **firstindex + 3**, a new** CounterView** child component instance is created. The value of the state variable **counter** of the **CounterView** child component is preserved by the **Mainview** parent component. Therefore, **counter** is not rebuilt when the **CounterView** child component instance is rebuilt.
+
+> **NOTE**
+>
+> The most common mistake application developers make in connection with **ForEach** is that the ID generation function returns the same value for two array items, especially in the Array\ scenario.
+
+
+### Nested Use of ForEach
+
+While nesting **ForEach** inside another **ForEach** in the same component is allowed, it is not recommended. It is better to split the component into two and have each build function include just one ForEach. The following is a poor example of nested use of **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 {
+ // Simulate with six months.
+ @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) => {
+ // Build a date block.
+ },
+ (day : number) => day.toString()
+ )// Inner ForEach
+ },
+ (item: Month) => (item.year * 12 + item.month).toString() // This field is used together with the year and month as the unique ID of the month.
+ )// Outer ForEach
+ }
+ }
+}
+```
+
+The preceding example has two issues:
+
+1. The code readability is poor.
+
+2. For a data structure of months and days of a year, the framework cannot observe the attribute changes to **Month** objects, including any changes to the **days** array. As a result, the inner **ForEach** will not update the date.
+
+The recommended application design is to split **Calendar** into **Year**, **Month**, and **Day** child components. Define a **Day** model class to hold information about a day and decorate the class with \@Observed. The **DayView** component uses an \@ObjectLink decorated variable to link to the data about a day. Perform the same operations on the **MonthView** and **Month** model classes.
+
+
+### Example of Using the Optional index Parameter in ForEach
+
+You can use the optional **index** parameter in item build and ID generation functions.
+
+
+```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}`
+ }
+ )
+ }
+ }
+}
+```
+
+The correct construction of the ID generation function is essential. When **index** is used in the item generation function, it should also be used in the ID generation function to produce unique IDs and an ID for given source array item that changes when its index position within the array changes.
+
+This example also illustrates that the **index** parameter can cause significant performance degradation. If an item is moved in the source array without modification, the dependent UI still requires rebuilding because of the changed index. For example, with the use of index sorting, the array only requires the unmodified child UI node of **ForEach** to be moved to the correct slot, which is a lightweight operation for the framework. When **index** is used, all child UI nodes need to be rebuilt, which is much more heavy weight.
diff --git a/en/application-dev/quick-start/arkts-rendering-control-ifelse.md b/en/application-dev/quick-start/arkts-rendering-control-ifelse.md
new file mode 100644
index 0000000000000000000000000000000000000000..a88e6d190a2c8a2769386804411b6efc98ea5219
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-rendering-control-ifelse.md
@@ -0,0 +1,229 @@
+# if/else: Conditional Rendering
+
+
+ArkTS provides conditional rendering. Use the **if**, **else**, and **else if** statements to enable your application to display different content based on the condition or state.
+
+> **NOTE**
+>
+> Since API version 9, this API is supported in ArkTS widgets.
+
+## Rules of Use
+
+- The **if**, **else**, and **else if** statements are supported.
+
+- The conditional statements following **if** and **else if** can use state variables.
+
+- Use of the conditional statements within a container component is allowed for building different child components.
+
+- Conditional statements are "transparent" when it comes to the parent-child relationship of components. Rules about permissible child components must be followed when there is one or more **if** statements between the parent and child components.
+
+- The build function inside each branch must follow the special rules for build functions. Each of such build functions must create one or more components. An empty build function that creates no components will result in a syntax error.
+
+- Some container components impose restrictions on the type or number of child components. When conditional statements are used in such components, these restrictions also apply to the components created in conditional statements. For example, when a conditional statement is used in the **\** container component, whose child components can only be **\**, only the **\** component can be used in the conditional statement.
+
+
+## Update Mechanism
+
+A conditional statement updates whenever a state variable used inside the **if** condition or the **else if** condition changes. Specifically:
+
+1. The conditional statement re-evaluates the conditions. If the evaluation of the conditions changes, steps 2 and 3 are performed. Otherwise, no follow-up operation is required.
+
+2. The framework removes all child components that have been built.
+
+3. The framework executes the build function of the branch again to add the generated child component to its parent component. If an applicable **else** branch is missing, no new build function will be executed.
+
+A condition can include Typescript expressions. As for any expression inside build functions, such an expression must not change any application state.
+
+
+## Application Scenarios
+
+
+### Using if for Conditional Rendering
+
+
+```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--;
+ })
+ }
+ }
+}
+```
+
+Each branch of the **if** statement includes a build function. Each of such build functions must create one or more components. On initial render, **if** will execute a build function and add the generated child component to its parent component.
+
+**if** updates whenever a state variable used inside the **if** condition or the **else if** condition changes and re-evaluates the conditions. If the evaluation of the conditions changes, it means that another branch of **if** needs to be built. In this case, the ArkUI framework will:
+
+1. Remove all previously rendered components (of the earlier branch).
+
+2. Execute the build function of the branch and add the generated child component to its parent component.
+
+In the preceding example, if **count** increases from 0 to 1, then, **if** updates, the condition **count > 0** is re-evaluated, and the evaluation result changes from **false** to **true**. Therefore, the positive branch build function will be executed, which creates a **\** component and adds it to the **\** parent component. If **count** changes back to 0 later, then, the **\** component will be removed from the **\** component. Since there is no **else** branch, no new build function will be executed.
+
+
+### if ... else ... and Child Component State
+
+This example involves **if...** **else...** and a child component with an \@State decorated variable.
+
+
+```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;
+ })
+ }
+ }
+}
+```
+
+On first render, the **CounterView** (label: **'CounterView \#positive'**) child component is created. This child component carries the \@State decorated variable **counter**. When the **CounterView.counter** state variable is updated, the **CounterView** (label: **'CounterView \#positive'**) child component is re-rendered, with its state variable value preserved. When the value of the **MainView.toggle** state variable changes to **false**, the **if** statement inside the **MainView** parent component gets updated, and subsequently the **CounterView** (label: **'CounterView \#positive'**) child component will be removed. At the same time, a new **CounterView** (label: **'CounterView \#negative'**) child component will be created. Its own **counter** state variable is set to the initial value **0**.
+
+> **NOTE**
+>
+> **CounterView** (label: **'CounterView \#positive'**) and **CounterView** (label: **'CounterView \#negative'**) are two distinct instances of the same custom component. When the **if** branch changes, there is no updating of an existing child component and no preservation of state.
+
+The following example shows the required modifications if the value of **counter** be preserved when the **if** condition changes:
+
+
+```
+@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;
+ })
+ }
+ }
+}
+```
+
+Here, the \@State decorated variable **counter** is owned by the parent component. Therefore, it is not destroyed when a **CounterView** component instance is removed. The **CounterView** component refers to the state by an \@Link decorator. This technique is sometimes referred to as "pushing up the state in the component tree." The state must be moved from a child to its parent (or parent of parent) to avoid losing it when the conditional content (or repeated content) is destroyed.
+
+
+### Nested if Statements
+
+The nesting of **if** statements makes no difference to the rule about the parent component.
+
+
+```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)
+ // Inner if statement
+ 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;
+ })
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-rendering-control-lazyforeach.md b/en/application-dev/quick-start/arkts-rendering-control-lazyforeach.md
new file mode 100644
index 0000000000000000000000000000000000000000..7086569f912a0c447228643958c38b3bd16e0045
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-rendering-control-lazyforeach.md
@@ -0,0 +1,220 @@
+# LazyForEach: Lazy Data Loading
+
+
+**LazyForEach** iterates over provided data sources and creates corresponding components during each iteration. When **LazyForEach** is used in a scrolling container, the framework creates components as required within the visible area of the scrolling container. When a component is out of the visible area, the framework destroys and reclaims the component to reduce memory usage.
+
+
+## API Description
+
+
+```ts
+LazyForEach(
+ dataSource: IDataSource, // Data source to iterate over
+ itemGenerator: (item: any) => void, // Child component generation function
+ keyGenerator?: (item: any) => string // (Optional). ID generation function
+): 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
+}
+```
+
+**Parameters**
+
+
+| Name | Type | Mandatory | Description |
+| ------------- | --------------------------------------- | ---- | ---------------------------------------- |
+| dataSource | IDataSource | Yes | **LazyForEach** data source. You need to implement related APIs. |
+| itemGenerator | (item: any) => void | Yes | Child component generation function, which generates a child component for each data item in the array.**, **\**, and **\** components support lazy loading (that is, only the visible part and a small amount of data before and after the visible part are loaded for caching). For other components, all data is loaded at the same time.
+
+- **LazyForEach** must create one and only one child component in each iteration.
+
+- The generated child components must be allowed in the parent container component of **LazyForEach**.
+
+- **LazyForEach** can be included in an **if/else** statement, and can also contain such a statement.
+
+- The ID generation function must generate a unique value for each piece of data. If the IDs are the same, the framework ignores the UI components with the same key value. As a result, these UI components cannot be displayed in the parent container.
+
+- **LazyForEach** must be updated using a **DataChangeListener** object. When the first parameter **dataSource** uses a state variable, a state variable change does not trigger the UI update of **LazyForEach**.
+
+- For better rendering performance, when the **onDataChange** API of the **DataChangeListener** object is used to update the UI, an ID different from the original one needs to be generated to trigger component re-rendering.
+
+- The call sequence of **itemGenerator** functions may be different from the order of the data items in the data source. Therefore, do not assume whether or when the **itemGenerator** and **keyGenerator** functions are executed. For example, the following example may not run properly:
+
+
+ ```ts
+ LazyForEach(dataSource,
+ item => Text(`${item.i}. item.data.label`),
+ item => item.data.id.toString())
+ ```
+
+
+## Example
+
+
+```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)
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-rendering-control-overview.md b/en/application-dev/quick-start/arkts-rendering-control-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..95febe4736e91ab5fd0b84ea28369ba9bd3f0325
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-rendering-control-overview.md
@@ -0,0 +1,4 @@
+# Rendering Control Overview
+
+
+ArkUI uses the **build()** function of [custom components](arkts-create-custom-components.md) and declarative UI description statements in the [@builder decorator](arkts-builder.md) to build the corresponding UI. In declarative description statements, you can use rendering control statements in addition to system components to accelerate UI construction. These rendering control statements include conditional statements that control whether components are displayed, rendering statements for repeated content that quickly generate components based on array data, and lazy loading statements for scenarios involving a large amount of data.
diff --git a/en/application-dev/quick-start/arkts-rendering-control.md b/en/application-dev/quick-start/arkts-rendering-control.md
deleted file mode 100644
index 13904097ef69fc988fe3b1ed8d5a98714c38c2aa..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-rendering-control.md
+++ /dev/null
@@ -1,284 +0,0 @@
-# Rendering Control
-
-ArkTS provides conditional rendering and loop rendering. Conditional rendering can render state-specific UI content based on the application status. Loop rendering iteratively obtains data from the data source and creates the corresponding component during each iteration.
-
-## Conditional Rendering
-
-Use **if/else** for conditional rendering.
-
-
-> **NOTE**
->
-> - State variables can be used in the **if/else** statement.
->
-> - The **if/else** statement can be used to implement rendering of child components.
->
-> - The **if/else** statement must be used in container components.
->
-> - Some container components limit the type or number of subcomponents. When **if/else** is placed in these components, the limitation applies to components created in **if/else** statements. For example, when **if/else** is used in the **\** container component, whose child components can only be **\**, only the **\** component can be used in the **if/else** statement.
-
-
-```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)
- }
-}
-```
-
-## Loop Rendering
-
-You can use **ForEach** to obtain data from arrays and create components for each data item.
-
-```ts
-ForEach(
- arr: any[],
- itemGenerator: (item: any, index?: number) => void,
- keyGenerator?: (item: any, index?: number) => string
-)
-```
-
-Since API version 9, this API is supported in ArkTS widgets.
-
-**Parameters**
-
-| Name | Type | Mandatory| Description |
-| ------------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
-| arr | any[] | Yes | An array, which can be empty, in which case no child component is created. The functions that return array-type values are also allowed, for example, **arr.slice (1, 3)**. The set functions cannot change any state variables including the array itself, such as **Array.splice**, **Array.sort**, and **Array.reverse**.|
-| itemGenerator | (item: any, index?: number) => void | Yes | A lambda function used to generate one or more child components for each data item in an array. A single child component or a list of child components must be included in parentheses.|
-| keyGenerator | (item: any, index?: number) => string | No | An anonymous function used to generate a unique and fixed key value for each data item in an array. This key value must remain unchanged for the data item even when the item is relocated in the array. When the item is replaced by a new item, the key value of the new item must be different from that of the existing item. This key-value generator is optional. However, for performance reasons, it is strongly recommended that the key-value generator be provided, so that the development framework can better identify array changes. For example, if no key-value generator is provided, a reverse of an array will result in rebuilding of all nodes in **ForEach**.|
-
-> **NOTE**
->
-> - **ForEach** must be used in container components.
->
-> - The generated child components should be allowed in the parent container component of **ForEach**.
->
-> - The **itemGenerator** function can contain an **if/else** statement, and an **if/else** statement can contain **ForEach**.
->
-> - The call sequence of **itemGenerator** functions may be different from that of the data items in the array. During the development, do not assume whether or when the **itemGenerator** and **keyGenerator** functions are executed. The following is an example of incorrect usage:
->
-> ```ts
-> ForEach(anArray.map((item1, index1) => { return { i: index1 + 1, data: item1 }; }),
-> item => Text(`${item.i}. item.data.label`),
-> item => item.data.id.toString())
-> ```
-
-## Example
-
-```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())
- }
- }
-}
-```
-
-
-
-## Lazy Loading
-
-You can use **LazyForEach** to iterate over provided data sources and create corresponding components during each iteration.
-
-```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;
-}
-```
-
-**Parameters**
-
-| Name | Type | Mandatory| Description |
-| ------------- | --------------------- | ---- | ------------------------------------------------------------ |
-| dataSource | IDataSource | Yes | Object used to implement the **IDataSource** API. You need to implement related APIs. |
-| itemGenerator | (item: any, index?: number) => void | Yes | A lambda function used to generate one or more child components for each data item in an array. A single child component or a list of child components must be included in parentheses.|
-| keyGenerator | (item: any, index?: number) => string | No | An anonymous function used to generate a unique and fixed key value for each data item in an array. This key value must remain unchanged for the data item even when the item is relocated in the array. When the item is replaced by a new item, the key value of the new item must be different from that of the existing item. This key-value generator is optional. However, for performance reasons, it is strongly recommended that the key-value generator be provided, so that the development framework can better identify array changes. For example, if no key-value generator is provided, a reverse of an array will result in rebuilding of all nodes in **LazyForEach**.|
-
-### Description of IDataSource
-
-| Name | Description |
-| ------------------------------------------------------------ | ---------------------- |
-| totalCount(): number | Obtains the total number of data records. |
-| getData(index: number): any | Obtains the data corresponding to the specified index. |
-| registerDataChangeListener(listener:DataChangeListener): void | Registers a listener for data changes.|
-| unregisterDataChangeListener(listener:DataChangeListener): void | Deregisters a listener for data changes.|
-
-### Description of DataChangeListener
-
-| Name | Description |
-| -------------------------------------------------------- | -------------------------------------- |
-| onDataReloaded(): void | Invoked when all data is reloaded. |
-| onDataAdded(index: number): voiddeprecated | Invoked when data is added to the position indicated by the specified index. This API is deprecated since API version 8. You are advised to use **onDataAdd**. |
-| onDataMoved(from: number, to: number): voiddeprecated | Invoked when data is moved from the **from** position to the **to** position. This API is deprecated since API version 8. You are advised to use **onDataMove**.|
-| onDataDeleted(index: number): voiddeprecated | Invoked when data is deleted from the position indicated by the specified index. This API is deprecated since API version 8. You are advised to use **onDataDelete**. |
-| onDataChanged(index: number): voiddeprecated | Invoked when data in the position indicated by the specified index is changed. This API is deprecated since API version 8. You are advised to use **onDataChange**. |
-| onDataAdd(index: number): void8+ | Invoked when data is added to the position indicated by the specified index. |
-| onDataMove(from: number, to: number): void8+ | Invoked when data is moved from the **from** position to the **to** position.|
-| onDataDelete(index: number): void8+ | Invoked when data is deleted from the position indicated by the specified index. |
-| onDataChange(index: number): void8+ | Invoked when data in the position indicated by the specified index is changed. |
-
-## Example
-
-```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 {
- // Initialize the data list.
- 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(() => {
- // The count increases by one each time the list is clicked.
- this.data.pushData('/path/image' + this.data.totalCount() + '.png')
- })
- }, item => item)
- }.height('100%').width('100%')
- }
-}
-```
-
-> **NOTE**
->
-> - **LazyForEach** must be used in the container component. Currently, only the **\**, **\**, and **\** components support lazy loading (that is, only the visible part and a small amount of data before and after the visible part are loaded for caching). For other components, all data is loaded at a time.
->
-> - **LazyForEach** must create one and only one child component in each iteration.
->
-> - The generated child components must be the ones allowed in the parent container component of **LazyForEach**.
->
-> - **LazyForEach** can be included in an **if/else** statement.
->
-> - For the purpose of high-performance rendering, when the **onDataChange** method of the **DataChangeListener** object is used to update the UI, the component update is triggered only when the state variable is used in the child component created by **itemGenerator**.
->
-> - The call sequence of **itemGenerator** functions may be different from that of the data items in the data source. During the development, do not assume whether or when the **itemGenerator** and **keyGenerator** functions are executed. The following is an example of incorrect usage:
->
-> ```ts
-> LazyForEach(dataSource,
-> item => Text(`${item.i}. item.data.label`),
-> item => item.data.id.toString())
-> ```
-
-
diff --git a/en/application-dev/quick-start/arkts-restrictions-and-extensions.md b/en/application-dev/quick-start/arkts-restrictions-and-extensions.md
deleted file mode 100644
index 1c1a9a2ed4066f2d55badd2a02e0421a9a01f09b..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-restrictions-and-extensions.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# Restrictions and Extensions
-
-## Restrictions on Using ArkTS in Generators
-
-ArkTS has the following restrictions on generators:
-
-- Expressions can be used only in character strings (${expression}), **if/else** statements, **ForEach** parameters, and component parameters.
-
-- No expressions should cause any application state variables (that is, variables decorated by **@State**, **@Link**, and **@Prop**) to change. Otherwise, undefined and potentially unstable framework behavior may occur.
-
-- The generator function cannot contain local variables.
-
-None of the above restrictions applies to anonymous function implementations of event methods (such as **onClick**).
-
-## Two-Way Binding of Variables
-
-ArkTS supports two-way binding through **$$**, which is usually used for variables whose state values change frequently.
-
-- **$$** supports variables of primitive types and variables decorated by **@State**, **@Link**, or **@Prop**.
-- **$$** supports only the **show** parameter of the **[bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md)** attribute method, the **checked** attribute of the **[\](../reference/arkui-ts/ts-basic-components-radio.md)** component, and the **refreshing** parameter of the **[\](../reference/arkui-ts/ts-container-refresh.md)** component.
-- When the variable bound to **$$** changes, only the current component is rendered, which improves the rendering speed.
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct bindPopupPage {
- @State customPopup: boolean = false
-
- build() {
- Column() {
- Button('Popup')
- .margin(20)
- .onClick(() => {
- this.customPopup = !this.customPopup
- })
- .bindPopup($$this.customPopup, {
- message: "showPopup"
- })
- }
- }
-}
-```
-
-
-
-## Restrictions on Data Type Declarations of State Variables
-
-1. The data types of state variables decorated by state decorators must be explicitly declared. They cannot be declared as **any** or **Date**.
-
- Example:
-
- ```ts
- // xxx.ets
- @Entry
- @Component
- struct DatePickerExample {
- // Incorrect: @State isLunar: any = false
- @State isLunar: boolean = false
- // Incorrect: @State selectedDate: Date = new Date('2021-08-08')
- private selectedDate: Date = new Date('2021-08-08')
-
- build() {
- Column() {
- Button('Switch Calendar')
- .margin({ top: 30 })
- .onClick(() => {
- this.isLunar = !this.isLunar
- })
- DatePicker({
- start: new Date('1970-1-1'),
- end: new Date('2100-1-1'),
- selected: this.selectedDate
- })
- .lunar(this.isLunar)
- .onChange((value: DatePickerResult) => {
- this.selectedDate.setFullYear(value.year, value.month, value.day)
- console.info('select current date is: ' + JSON.stringify(value))
- })
-
- }.width('100%')
- }
- }
- ```
-
- 
-
-2. The data type declaration of the **@State**, **@Provide**, **@Link**, or **@Consume** decorated state variables can consist of only one of the primitive data types or reference data types.
-
- The **Length**, **ResourceStr**, and **ResourceColor** types are combinations of primitive data types or reference data types. Therefore, they cannot be used by the aforementioned types of state variables.
- For details about the definitions of **Length**, **ResourceStr**, and **ResourceColor**, see [Types](../../application-dev/reference/arkui-ts/ts-types.md).
-
- Example:
-
- ```ts
- // xxx.ets
- @Entry
- @Component
- struct IndexPage {
- // Incorrect: @State message: string | Resource = 'Hello World'
- @State message: string = 'Hello World'
- // Incorrect: @State message: ResourceStr = $r('app.string.hello')
- @State resourceStr: Resource = $r('app.string.hello')
-
- build() {
- Row() {
- Column() {
- Text(`${this.message}`)
- .fontSize(50)
- .fontWeight(FontWeight.Bold)
- }
- .width('100%')
- }
- .height('100%')
- }
- }
- ```
-
- 
-
-## Initialization Rules and Restrictions of Custom Components' Member Variables
-
-The member variables of a component can be initialized in either of the following ways:
-
-- Local initialization:
-
- ```ts
- @State counter: Counter = new Counter()
- ```
-- Initialization using constructor parameters:
-
- ```ts
- MyComponent({counter: $myCounter})
- ```
-
-The allowed method depends on the decorator of the state variable, as described in the following table.
-
-| Decorator | Local Initialization| Initialization Using Constructor Parameters|
-| ------------ | ----- | ----------- |
-| @State | Mandatory | Optional |
-| @Prop | Forbidden | Mandatory |
-| @Link | Forbidden | Mandatory |
-| @StorageLink | Mandatory | Forbidden |
-| @StorageProp | Mandatory | Forbidden |
-| @LocalStorageLink | Mandatory | Forbidden |
-| @LocalStorageProp | Mandatory | Forbidden |
-| @Provide | Mandatory | Optional |
-| @Consume | Forbidden | Forbidden |
-| @ObjectLink | Forbidden | Mandatory |
-| Normal member variable | Recommended | Optional |
-
-As indicated by the preceding table:
-
-- The **@State** decorated variables must be initialized locally. Their initial values can be overwritten by the constructor parameters.
-
-- The **@Prop** and **@Link** decorated variables must be initialized only by constructor parameters.
-
-Comply with the following rules when using constructors to initialize member variables:
-
-| **From the Variable in the Parent Component (Right) to the Variable in the Child Component (Below)**| **regular** | **@State** | **@Link** | **@Prop** | **@Provide** | **@Consume** | **@ObjectLink** |
-|---------------------------------|----------------------------|------------|-----------|-----------|--------------|--------------|------------------|
-| **regular** | Supported | Supported | Supported | Supported | Not supported | Not supported | Supported |
-| **@State** | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
-| **@Link** | Not supported | Supported (1) | Supported (1) | Supported (1) | Supported (1) | Supported (1) | Supported (1) |
-| **@Prop** | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
-| **@Provide** | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
-| **@Consume** | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported |
-| **@ObjectLink** | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported |
-
-| **From the Variable in the Parent Component (Right) to the Variable in the Child Component (Below)**| **@StorageLink** | **@StorageProp** | **@LocalStorageLink** | **@LocalStorageProp** |
-|------------------|------------------|------------------|-----------------------|------------------------|
-| **regular** | Supported | Not supported | Not supported | Not supported |
-| **@State** | Supported | Supported | Supported | Supported |
-| **@Link** | Supported (1) | Supported (1) | Supported (1) | Supported (1) |
-| **@Prop** | Supported | Supported | Supported | Supported |
-| **@Provide** | Supported | Supported | Supported | Supported |
-| **@Consume** | Not supported | Not supported | Not supported | Not supported |
-| **@ObjectLink** | Not supported | Not supported | Not supported | Not supported |
-
-> **NOTE**
->
-> **Supported (1)**: The dollar sign ($) must be used, for example, **this.$varA**.
->
-> **regular**: refers to a regular variable that is not decorated by any decorator.
-
-As indicated by the preceding tables:
-
-- The **@ObjectLink** decorated variable cannot be directly initialized from a decorated variable in the parent component. The source of the parent component must be an array item or object attribute decorated by **@State**, **@Link**, **@Provide**, **@Consume**, or **@ObjectLink**.
-
-- The regular variables of the parent component can be used to initialize the **@State** variable of the child component, but cannot be used to initialize the **@Link**, **@Consume**, and **@ObjectLink** variables.
-
-- The **@State** variable of the parent component can be used to initialize the **@Prop**, **@Link** (through **$**), or regular variables of the child component, but cannot be used to initialize the **@Consume** variable.
-
-- The **@Link** variable of the parent component cannot be used to initialize the **@Consume** and **@ObjectLink** variables of the child component.
-
-- The **@Prop** variable of the parent component cannot be used to initialize the **@Consume** and **@ObjectLink** variables of the child component.
-
-- **@StorageLink**, **@StorageProp**, **@LocalStorageLink**, and **@LocalStorageProp** variables cannot be initialized from the parent component.
-
-- In addition to the preceding rules, the TypeScript strong type rules need to be followed.
-
-Example:
-```ts
-@Entry
-@Component
-struct Parent {
- message: string = "Hello World"
- build() {
- Column() {
- Child({
- stateMessage: this.message,
- /* ArkTS:ERROR The regular property 'message' cannot be assigned
- to the @Link property 'linkMessage'.*/
- linkMessage: this.$message
- })
- }
- .width('100%')
- }
-}
-
-@Component
-struct Child {
- @State stateMessage: string = "Hello World"
- @Link linkMessage: string
- build() {
- Column() {
- Text(this.stateMessage)
- .fontSize(50)
- .fontWeight(FontWeight.Bold)
- }
- .width('100%')
- }
-}
-```
-
-## Restrictions on Naming Custom Components, Classes, and Functions
-
-The name of a custom component, class, or function cannot be the same as any system component name.
-
-Example:
-
-```
-// Rect.ets
-export class Rect {
- constructor(){}
-}
-// Index.ets
-// ERROR: The module name 'Rect' can not be the same as the inner component name.
-import { Rect } from './Rect';
-@Entry
-@Component
-struct Index {
- build() {
-
- }
-}
-```
diff --git a/en/application-dev/quick-start/arkts-state-management-overview.md b/en/application-dev/quick-start/arkts-state-management-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..440cceac78c9f5b6d4773e211f790596e5c24ed6
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-state-management-overview.md
@@ -0,0 +1,125 @@
+# State Management Overview
+
+
+In previous examples, most of the pages built are static pages, which are delivered to the end user without having to be processed. If you are building dynamic, interactive pages, you need to master state management.
+
+
+ **Figure 1** State managed UI
+
+
+
+
+In the preceding example, the interaction between the user and the application triggers an update in the text state, which in turn triggers re-rendering of the UI. As a result, the **Hello World** text changes to **Hello ArkUI**.
+
+
+In the declarative UI framework, the UI is the execution result of the application state. You build a UI model in which the state of the application when running is a parameter. When the parameter is changed, the UI as the return result is updated accordingly. This process of UI re-rendering caused by state changes during application running is called the state management mechanism in ArkUI.
+
+
+Custom components have variables. A variable must be decorated by a decorator whenever the re-rendering of the UI depends on this variable. Otherwise, the UI is rendered only at initialization and will not be updated. The following figure shows the relationship between the state and view (UI).
+
+
+
+
+
+- View (UI): UI rendering, which generally refers to the UI description in the **build** method of a custom component and the **\@Builder** decorated method.
+
+- State: data decorated by a decorator. State data is changed by invoking the event method of the component. The change of the state data triggers the re-rendering of the UI.
+
+
+## Basic Concepts
+
+- State variable: a variable decorated by the state decorator. Its change will trigger the re-rendering of the UI.
+
+- Regular variable: a variable that has no state and is usually used for auxiliary calculation. Its change will not trigger the re-rendering of the UI.
+
+- Data source/Synchronization source: original source of a state variable, which can be synchronized to different state data. Generally, it is the data passed from the parent component to the child component.
+
+- Named parameter mechanism: a mechanism where the parent component passes state variables to the child component by specifying parameters. It is the primary means of passing synchronization parameters from the parent component to the child component. Example: CompA: ({ aProp: this.aProp }).
+
+- Initialization from the parent component: a process where the parent component uses the named parameter mechanism to pass specified parameters to the child component. The default value used in local initialization is overwritten by the value passed from the parent component. Example:
+
+ ```ts
+ @Component
+ struct MyComponent {
+ @State count: number = 0;
+ private increaseBy: number = 1;
+
+ build() {
+ }
+ }
+
+ @Component
+ struct Parent {
+ build() {
+ Column() {
+ // Initialization from the parent component: The named parameter specified here will overwrite the default value defined locally.
+ MyComponent({ count: 1, increaseBy: 2 })
+ }
+ }
+ }
+ ```
+
+- Subnode initialization: a capability to pass state variables to the child component to initialize the corresponding state variables therein. The example is the same as above.
+
+- Local initialization: a process where a value is assigned to a variable in its declaration as the default value for initialization. Example: \@State count: number = 0.
+
+
+## Decorator Overview
+
+ArkUI provides a diverse array of decorators. By using these decorators, state variables can not only observe changes within a component, but also pass the changes between different component levels (for example, between parent and child components or grandparent and grandchild components) or globally. According to the scope of the state variable, decorators can be roughly classified into the following types:
+
+
+- Decorators for managing the state owned by a component: implement state management at the component level by allowing for observation of state changes within a component and changes at different component levels. The observation is limited to state changes on the same component tree, that is, on the same page.
+
+- Decorators for managing the state owned by an application: implement state management at the component level by allowing for observation of state changes on different pages or even different UIAbility components.
+
+
+According to the data transfer mode and synchronization type, decorators can also be classified into the following types:
+
+
+- Decorators that allow for one-way (read-only) transfer
+
+- Decorators that allow for two-way (mutable) transfer
+
+
+The following figure illustrates the decorators. For details, see [Component State Management](arkts-state.md) and [Application State Management](arkts-application-state-management-overview.md). You can use these decorators at your disposal to implement linkage between data and the UI.
+
+
+
+
+
+In the preceding figure, the decorators in the Components area are used for state management at the component level, while others are used for state management at the application level. You can use \@StorageLink/\@LocalStorageLink and \@StorageProp/\@LocalStorageProp to implement two-way and one-way synchronization of the application and component state. In the preceding figure, the data synchronization direction is indicated by the arrow direction: single-headed arrow for one-way synchronization and double-headed arrow for two-way sync.
+
+
+Decorators for [managing the state owned by a component](arkts-state.md):
+
+
+- \@State: An \@State decorated variable holds the state owned by the owning component. It can be the source of one- or two-way synchronization with child components. When the variable changes, the dependent component will be updated.
+
+- \@Prop: An \@Prop decorated variable can create one-way synchronization with a variable of its parent component. \@Prop decorated variables are mutable, but changes are not synchronized to the parent component.
+
+- \@Link: An \@Link decorated variable creates two-way synchronization with a variable of its parent component. When the @Link decorated variable has its value changed, its source is updated as well; when the source updates, the @Link decorated variable will do as well.
+
+- \@Provide/\@Consume: Variables decorated by \@Provide/\@Consume are used for data synchronization across component levels. The components can be bound to the variables through aliases or attribute names. Data does not need to be passed through the named parameter mechanism.
+
+- \@Observed: \@Observed is a class decorator. In scenarios involving multiple levels of nested objects or arrays in a class, the class must be decorated with the @Observed decorator. Note that decorating a class with \@Observed alone has no effect. Combined use with \@ObjectLink for two-way synchronization or with \@Prop for one-way synchronization is required.
+
+- \@ObjectLink: An \@ObjectLink decorated variable, when used with an \@Observed decorated class of the parent component, is for two-way data synchronization in scenarios involving multiple levels of nested objects or arrays in the class.
+
+
+Decorators for [managing the state owned by an application](arkts-state.md):
+
+
+- AppStorage: a special LocalStorage singleton instance. It is an application-wide database bound to the application process and can be linked to components through the [@StorageProp](arkts-appstorage.md#storageprop) and [@StorageLink](arkts-appstorage.md#storagelink) decorators.
+
+- AppStorage is the hub for application state. Data that needs to interact with components (UI) is stored in AppStorage, including PersistentStorage and Environment data. The UI accesses the data through the decorators or APIs provided by AppStorage.
+
+- LocalStorage: an in-memory "database" for the application state declared by the application and typically used to share state across pages. It can be linked to the UI through the [@LocalStorageProp](arkts-localstorage.md#localstorageprop) and [@LocalStorageLink](arkts-localstorage.md#localstoragelink) decorators.
+
+
+### Other State Management Features
+
+\@Watch: listens for the changes of the state variables.
+
+
+$$ operator: provides TS variable references for built-in components so that the variables are synchronized with the internal state of built-in components.
diff --git a/en/application-dev/quick-start/arkts-state-mgmt-application-level.md b/en/application-dev/quick-start/arkts-state-mgmt-application-level.md
deleted file mode 100644
index 9a3b22b6e5704978e7d2001d54f367b99debdabb..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-state-mgmt-application-level.md
+++ /dev/null
@@ -1,274 +0,0 @@
-# State Management with Application-level Variables
-
-This topic covers how to manage the application status with application-level variables. For details about the APIs, see [State Management with Application-level Variables](../reference/arkui-ts/ts-state-management.md).
-
-## AppStorage
-
-The [AppStorage](../reference/arkui-ts/ts-state-management.md#appstorage) is a singleton object in an application that provides central storage for changing state attributes of an application. It is created by the UI framework when the application is started and destroyed when the application exits.
-
-The **AppStorage** contains all the state attributes that need to be accessed throughout the application. It retains all attributes and their values as long as the application remains running, and the attribute values can be accessed through unique key values.
-
-Components can synchronize the application state data with the **AppStorage** through decorators. The application service logic can also be implemented by accessing the **AppStorage** through APIs.
-
-The selection state attribute of the **AppStorage** can be synchronized with different data sources or data sinks. These data sources and data sinks can be local or remote devices and provide different functions, such as data persistence. Such data sources and data sinks can be implemented independently of the UI in the service logic.
-
-By default, the attributes in the **AppStorage** are mutable. If needed, **AppStorage** can also use immutable (read-only) attributes.
-
-> **NOTE**
->
-> [Worker](../reference/apis/js-apis-worker.md) can interact with the main thread only through [postMessage](../reference/apis/js-apis-worker.md#postmessage).
-
-### @StorageLink Decorator
-
-Two-way data binding can be established between components and the **AppStorage** through state variables decorated by **@StorageLink(*key*)**. Wherein, **key** is the attribute key value in the **AppStorage**. When a component containing the **@StorageLink** decorated variable is created, the variable is initialized using the value in the **AppStorage**. Changes made to this variable in the component will be first synchronized to the **AppStorage**, and then to other bound instances, such as **PersistentStorage** or other bound UI components.
-
-### @StorageProp Decorator
-
-One-way data binding can be established between components and the **AppStorage** through state variables decorated by **@StorageProp(*key*)**. Wherein, **key** is the attribute key value in the **AppStorage**. When a component containing the **@StorageProp** decorated variable is created, the variable is initialized using the value in the **AppStorage**. Changes made to the value in the **AppStorage** will cause the bound UI component to update the state.
-
-### Example
-
-Each time the user clicks the **Count** button, the value of **this.varA** will increase by 1. This variable is synchronized with **varA** in the **AppStorage**. Each time the user clicks the language button, the value of **languageCode** in the **AppStorage** will be changed, and the change is synchronized to the **this.languageCode** variable.
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct ComponentA {
- @StorageLink('varA') varA: number = 2
- @StorageProp('languageCode') languageCode: string = 'en'
- private label: string = 'count'
-
- aboutToAppear() {
- this.label = (this.languageCode === 'en') ? 'Number' : 'Count'
- }
-
- build() {
- Column() {
- Row({ space: 20 }) {
- Button(`${this.label}: ${this.varA}`)
- .onClick(() => {
- AppStorage.Set('varA', AppStorage.Get('varA') + 1)
- })
- Button(`language: ${this.languageCode}`)
- .onClick(() => {
- if (AppStorage.Get('languageCode') === 'zh') {
- AppStorage.Set('languageCode', 'en')
- } else {
- AppStorage.Set('languageCode', 'zh')
- }
- this.label = (this.languageCode === 'en') ? 'Number' : 'Count'
- })
- }
- .margin({ top: 50, bottom: 50 })
-
- Row() {
- Button (`Change @StorageLink decorated variable: ${this.varA}`).height(40).fontSize(14)
- .onClick(() => {
- this.varA++
- })
- }
- }.width('100%')
- }
-}
-```
-
-
-
-## LocalStorage
-
-> **NOTE**
->
-> This API is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
-
-The **LocalStorage** is a storage unit in an application. Its lifecycle follows its associated ability. In the stage model, the **LocalStorage** provides global data isolation between abilities and applies to where a data sharing scope smaller than that provided by the **AppStorage** is required. The **LocalStorage** also provides storage for application-wide mutable and immutable state attributes, which are used for building part of the application UI, such as an ability UI. The **LocalStorage** resolves the data interference between the application and the abilities and, in multi-instance scenarios, data interference between different **Ability** instances under the same **Ability** class. In distributed migration scenarios, **Ability**, as the minimum unit for the system to schedule applications, allows for easier component data migration when working with the **LocalStorage**.
-
-At the application layer, multiple **LocalStorage** instances can be created for an application, each corresponding to an ability of the application.
-
-An application can have multiple abilities. At most one **LocalStorage** instance can be allocated to the components in an ability. In addition, all components in the ability inherit access to the objects stored in the **LocalStorage** instance.
-
-A component can access a maximum of one **LocalStorage** instance, and one **LocalStorage** instance can be assigned to multiple components.
-
-### @LocalStorageLink Decorator
-
-Two-way data binding can be established between a component and the **LocalStorage** through the component's state variable decorated by **@LocalStorageLink(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**. When a component that contains a **@LocalStorageLink** decorated state variable is created, the state variable is initialized with the initial value in the **LocalStorage**. If no initial value is assigned in the **LocalStorage**, the state variable will use the value defined by **@LocalStorageLink**. Changes made to the **@LocalStorageLink** decorated variable in a component will be first synchronized to the **LocalStorage**, and then to other bound UI components under the same ability.
-
-### @LocalStorageProp Decorator
-
-One-way data binding can be established between a component and the **LocalStorage** through the component's state variable decorated by **@LocalStorageProp(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**. When a component that contains a **@LocalStorageProp** decorated state variable is created, the state variable is initialized with the initial value in the **LocalStorage**. Changes made to the value in the **LocalStorage** will cause all UI components under the current ability to update the state.
-
-> **NOTE**
->
-> If a **LocalStorage** instance does not have an initial value assigned when being created, it can use the initial value defined by **@LocalStorageLink** or **@LocalStorageProp** in the component.
-
-### Example 1: Creating a LocalStorage Instance in an Ability
-
-The **LocalStorage** is loaded through the **loadContent** API. For details, see [loadContent](../reference/apis/js-apis-window.md#loadcontent9-1).
-
-```ts
-// MainAbility.ts
-import Ability from '@ohos.application.Ability'
-
-export default class MainAbility extends Ability {
- storage: LocalStorage
-
- onCreate() {
- this.storage = new LocalStorage()
- this.storage.setOrCreate('storageSimpleProp', 121)
- console.info('[Demo MainAbility onCreate]')
- }
-
- onDestroy() {
- console.info('[Demo MainAbility onDestroy]')
- }
-
- onWindowStageCreate(windowStage) {
- // storage is passed to the loadContent API as a parameter.
- windowStage.loadContent('pages/Index', this.storage)
- }
-
- onWindowStageDestroy() {
- console.info('[Demo] MainAbility onWindowStageDestroy')
- }
-
- onForeground() {
- console.info('[Demo] MainAbility onForeground')
- }
-
- onBackground() {
- console.info('[Demo] MainAbility onBackground')
- }
-}
-```
-
-The **@Component** decorated component obtains data.
-
-```ts
-// Index.ets
-let storage = LocalStorage.GetShared()
-
-@Entry(storage)
-@Component
-struct LocalStorageComponent {
- @LocalStorageLink('storageSimpleProp') simpleVarName: number = 0
-
- build() {
- Column() {
- Button(`LocalStorageLink: ${this.simpleVarName.toString()}`)
- .margin(20)
- .onClick(() => {
- this.simpleVarName += 1
- })
- Text(JSON.stringify(this.simpleVarName))
- .fontSize(50)
- LocalStorageComponentProp()
- }.width('100%')
- }
-}
-
-@Component
-struct LocalStorageComponentProp {
- @LocalStorageProp('storageSimpleProp') simpleVarName: number = 0
-
- build() {
- Column() {
- Button(`LocalStorageProp: ${this.simpleVarName.toString()}`)
- .margin(20)
- .onClick(() => {
- this.simpleVarName += 1
- })
- Text(JSON.stringify(this.simpleVarName))
- .fontSize(50)
- }.width('100%')
- }
-}
-```
-
-
-
-### Example 2: Defining LocalStorage on the Entry Page
-
-```ts
-// xxx.ets
-let storage = new LocalStorage({ "PropA": 47 })
-
-@Entry(storage)
-@Component
-struct ComA {
- @LocalStorageLink("PropA") storageLink: number = 1
-
- build() {
- Column() {
- Text(`Parent from LocalStorage ${this.storageLink}`)
- .fontSize(18)
- .margin(20)
- .onClick(() => this.storageLink += 1)
- Child()
- }
- }
-}
-
-@Component
-struct Child {
- @LocalStorageLink("PropA") storageLink: number = 1
-
- build() {
- Text(`Child from LocalStorage ${this.storageLink}`)
- .fontSize(18)
- .margin(20)
- .onClick(() => this.storageLink += 1)
- }
-}
-```
-
-
-
-## PersistentStorage
-
-[PersistentStorage](../reference/arkui-ts/ts-state-management.md#persistentstorage) provides a set of static methods for managing persistent data of applications. Persistent data with specific tags can be linked to the **AppStorage**, and then the persistent data can be accessed through the **AppStorage** APIs. Alternatively, the **@StorageLink** decorator can be used to access the variable that matches the specific key.
-
-> **NOTE**
->
-> - When using the **PersistProp** API in **PersistentStorage**, ensure that the input key exists in the **AppStorage**.
-> - The **DeleteProp** API in **PersistentStorage** takes effect only for the data that has been linked during the current application startup.
-
-```ts
-// xxx.ets
-PersistentStorage.PersistProp('highScore', '0')
-
-@Entry
-@Component
-struct PersistentComponent {
- @StorageLink('highScore') highScore: string = '0'
- @State currentScore: number = 0
-
- build() {
- Column() {
- if (this.currentScore === Number(this.highScore)) {
- Text(`new highScore : ${this.highScore}`).fontSize(18)
- }
- Button(`goal!, currentScore : ${this.currentScore}`)
- .margin(20)
- .onClick(() => {
- this.currentScore++
- if (this.currentScore > Number(this.highScore)) {
- this.highScore = this.currentScore.toString()
- }
- })
- }.width('100%')
- }
-}
-```
-
-
-
-## Environment
-
-[Environment](../reference/arkui-ts/ts-state-management.md#environment) is a singleton object created by the framework when the application is started. It provides the **AppStorage** with an array of environment state attributes required by the application. These attributes, such as the system language and color mode, describe the device environment where the application runs. **Environment** and its attributes are immutable, and all attribute values are of simple types. The following example shows how to obtain whether accessibility is enabled from **Environment**:
-
-```ts
-Environment.EnvProp('accessibilityEnabled', 'default')
-var enable = AppStorage.Get('accessibilityEnabled')
-```
-
-**accessibilityEnabled** is the default system variable identifier provided by **Environment**. You need to bind the corresponding system attribute to the **AppStorage**. Then, you can use the methods or decorators in the **AppStorage** to access the corresponding system attribute data.
diff --git a/en/application-dev/quick-start/arkts-state-mgmt-concepts.md b/en/application-dev/quick-start/arkts-state-mgmt-concepts.md
deleted file mode 100644
index dd2398a71811e6bbd9b20d0f18ce0659c3bd7acf..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-state-mgmt-concepts.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Basic Concepts
-
-In the multi-dimensional state management mechanism for ArkUI, UI-related data can be used not only within a component, but also be transferred between different component levels (for example, between parent and child components, between grandparent and grandchild components, or globally). In addition, data transfer can be classified as one-way (read-only) or two-way (mutable). You can use these capabilities at your disposal to implement linkage between data and the UI.
-
-
-
-
-
-## State Management with Page-level Variables
-
-| Decorator | Decorates... | Description |
-| ----------- | ------------------------- | ------------------------------------------------------------ |
-| @State | Primitive data types, classes, and arrays | If the decorated state data is modified, the **build** method of the component will be called to update the UI. |
-| @Prop | Primitive data types | This decorator is used to establish one-way data binding between the parent and child components. When the data associated with the parent component is modified, the UI of the current component is re-rendered.|
-| @Link | Primitive data types, classes, and arrays | This decorator is used to establish two-way data binding between the parent and child components. The internal state data of the parent component is used as the data source. Any changes made to one component will be reflected to the other.|
-| @Observed | Class | This decorator is used to indicate that the data changes in the class will be managed by the UI page. |
-| @ObjectLink | Objects of **@Observed** decorated classes| When the decorated state variable is modified, the parent and sibling components that have the state variable will be notified for UI re-rendering.|
-| @Provide | Primitive data types, classes, and arrays | As the data provider, **@Provide** can update the data of child nodes and trigger page re-rendering.|
-| @Consume | Primitive data types, classes, and arrays | When the **@Consume** decorated variable detects the update of the **@Provide** decorated variable, the re-rendering of the current custom component is triggered.|
-
-## State Management with Application-level Variables
-
-**AppStorage** is the central store of the application states in the entire UI. ArkUI creates a singleton **AppStorage** object for the application and provides the corresponding decorators and APIs for the application.
-
-- **@StorageLink**: works in a way similar to that of **@Consume**. The difference is that the target object is obtained from the **AppStorage** based on the given name. **@StorageLink** establishes two-way binding between the decorated UI component and **AppStorage** to synchronize data.
-- **@StorageProp**: synchronizes UI component attributes with the **AppStorage** unidirectionally. That is, the value change in the **AppStorage** will trigger an update of the corresponding UI component, but the change of the UI component will not cause an update of the attribute value in the **AppStorage**.
-- Service logic implementation API: adds, reads, modifies, or deletes the state data of applications. The changes made by this API will be synchronized to the UI component for UI update.
-- **LocalStorage**: provides ability-specific storage.
-- **@LocalStorageLink**: establishes two-way data binding between a component and the **LocalStorage**. Specifically, this is achieved by decorating the component's state variable with **@LocalStorageLink(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**.
-- **@LocalStorageProp**: establishes one-way data binding between a component and the **LocalStorage**. Specifically, this is achieved by decorating the component's state variable with **@LocalStorageProp(*key*)**. Wherein, **key** is the attribute key value in the **LocalStorage**.
-- **PersistentStorage**: provides a set of static methods for managing persistent data of applications. Persistent data with specific tags can be linked to the **AppStorage**, and then the persistent data can be accessed through the **AppStorage** APIs. Alternatively, the **@StorageLink** decorator can be used to access the variable that matches the specific key.
-- **Environment**: provides the **AppStorage** with an array of environment state attributes that are required by the application and describe the device environment where the application runs. It is a singleton object created by the framework when the application is started.
-
-For details about how to use state variables, see [Restrictions on Data Type Declarations of State Variables](arkts-restrictions-and-extensions.md).
diff --git a/en/application-dev/quick-start/arkts-state-mgmt-page-level.md b/en/application-dev/quick-start/arkts-state-mgmt-page-level.md
deleted file mode 100644
index c62e80869644d7993250925efad0efa60d56bd98..0000000000000000000000000000000000000000
--- a/en/application-dev/quick-start/arkts-state-mgmt-page-level.md
+++ /dev/null
@@ -1,521 +0,0 @@
-# State Management with Page-level Variables
-
-This topic covers how to manage the states with page-level variables with the **@State**, **@Prop**, **@Link**, **@Provide**, **@Consume**, **@ObjectLink**, **@Observed**, and **@Watch** decorators.
-
-For details about the constraints of the **@State**, **@Provide**, **@Link**, and **@Consume** decorated state variables, see [Restrictions on Data Type Declarations of State Variables](./arkts-restrictions-and-extensions.md).
-
-## @State
-
-The **@State** decorated variable is the internal state data of the component. When the state data is modified, the **build** method of the component is called to refresh the UI.
-
-The **@State** data has the following features:
-
-- Support for multiple types: The following types are supported: strong types by value and by reference, including **class**, **number**, **boolean**, **string**, as well as arrays of these types, that is, **Array\**, **Array\**, **Array\**, and **Array\**. **object** and **any** are not supported.
-- Support for multiple instances: Multiple instances can coexist in a component. The internal state data of different instances is independent.
-- **Private**: An attribute marked with **@State** can only be accessed within the component.
-- Local initialization required: Initial values must be allocated to all **@State** decorated variables. Uninitialized variables may cause undefined framework exceptions.
-- Support for setting of initial attribute values based on the state variable name: When creating a component instance, you can explicitly specify the initial value of the **@State** decorated attribute based on the variable name.
-
-**Example**
-
-In the following example:
-
-- Two **@State** decorated variables, **count** and **title**, have been defined for **MyComponent**. If the value of **count** or **title** changes, the **build** method of **MyComponent** needs to be called to render the component again.
-
-- The **EntryComponent** has multiple **MyComponent** instances. The internal status change of the first **MyComponent** instance does not affect the second **MyComponent** instance.
-
-- When creating a **MyComponent** instance, initialize the variables in the component based on the variable name. For example:
-
- ```ts
- MyComponent({ title: { value: 'Hello World 2' }, count: 7 })
- ```
-
-```ts
-// xxx.ets
-class Model {
- value: string
-
- constructor(value: string) {
- this.value = value
- }
-}
-
-@Entry
-@Component
-struct EntryComponent {
- build() {
- Column() {
- MyComponent ({ count: 1,increaseBy:2 }) // First MyComponent instance
- MyComponent({ title: { value:'Hello World 2' }, count: 7 }) // Second MyComponent instance
- }
- }
-}
-
-@Component
-struct MyComponent {
- @State title: Model = { value: 'Hello World' }
- @State count: number = 0
- private toggle: string = 'Hello World'
- private increaseBy: number = 1
-
- build() {
- Column() {
- Text(`${this.title.value}`).fontSize(30)
- Button('Click to change title')
- .margin(20)
- .onClick(() => {
- // Change the value of the internal status variable title.
- this.title.value = (this.toggle == this.title.value) ? 'Hello World' : 'Hello ArkUI'
- })
-
- Button(`Click to increase count=${this.count}`)
- .margin(20)
- .onClick(() => {
- // Change the value of the internal status variable count.
- this.count += this.increaseBy
- })
- }
- }
-}
-```
-
-
-## @Prop
-
-**@Prop** and **@State** have the same semantics but different initialization modes. A **@Prop** decorated variable in a component must be initialized using the **@State** decorated variable in its parent component. The **@Prop** decorated variable can be modified in the component, but the modification is not updated to the parent component; the modification to the **@State** decorated variable is synchronized to the **@Prop** decorated variable. That is, **@Prop** establishes one-way data binding.
-
-The **@Prop** decorated state variable has the following features:
-
-- Support for simple types: The number, string, and boolean types are supported.
-- Private: Data is accessed only within the component.
-- Support for multiple instances: A component can have multiple attributes decorated by **@Prop**.
-- Support for initialization with a value passed to the @Prop decorated variable: When a new instance of the component is created, all **@Prop** variables must be initialized. Initialization inside the component is not supported.
-
-**Example**
-
-In the following example, when the user presses **+1** or **-1**, the status of the parent component changes and the **build** method is executed again. In this case, a new **CountDownComponent** instance is created. The **countDownStartValue** attribute of the parent component is used to initialize the **@Prop** decorated variable of the child component. When the **count - costOfOneAttempt** button of the child component is touched, the value of the **@Prop** decorated variable **count** is changed. As a result, the **CountDownComponent** is rendered again. However, the change of the **count** value does not affect the **countDownStartValue** value of the parent component.
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct ParentComponent {
- @State countDownStartValue: number = 10 // Initialize countDownStartValue
-
- build() {
- Column() {
- Text(`Grant ${this.countDownStartValue} nuggets to play.`).fontSize(18)
- Button('+1 - Nuggets in New Game')
- .margin(15)
- .onClick(() => {
- this.countDownStartValue += 1
- })
-
- Button('-1 - Nuggets in New Game')
- .margin(15)
- .onClick(() => {
- this.countDownStartValue -= 1
- })
- // When creating a child component, you must provide the initial value of its @Prop decorated variable count in the constructor parameter and initialize the regular variable costOfOneAttempt (not @Prop decorated).
- CountDownComponent({ count: this.countDownStartValue, costOfOneAttempt: 2 })
- }
- }
-}
-
-@Component
-struct CountDownComponent {
- @Prop count: number
- private costOfOneAttempt: number
-
- build() {
- Column() {
- if (this.count > 0) {
- Text(`You have ${this.count} Nuggets left`).fontSize(18)
- } else {
- Text('Game over!').fontSize(18)
- }
-
- Button('count - costOfOneAttempt')
- .margin(15)
- .onClick(() => {
- this.count -= this.costOfOneAttempt
- })
- }
- }
-}
-```
-
-
-## @Link
-
-Two-way binding can be established between the **@Link** decorated variable and the **@State** decorated variable of the parent component. The **@Link** data has the following features:
-
-- Support for multiple types: The **@Link** decorated variables support the data types the same as the **@State** decorated variables; that is, the value can be of the following types: class, number, string, boolean, or arrays of these types.
-- Private: Data is accessed only within the component.
-- Single data source: The variable used to initialize the **@Link** decorated variable in a component must be a state variable defined in the parent component.
-- **Two-way binding**: When a child component changes the **@Link** decorated variable, the **@State** decorated variable of its parent component is also changed.
-- Support for initialization with the variable reference passed to the @Link decorated variable: When creating an instance of the component, you must use the naming parameter to initialize all **@Link** decorated variables. **@Link** decorated variables can be initialized by using the reference of the **@State** or **@Link** decorated variable. Wherein, the **@State** decorated variables can be referenced using the **'$'** operator.
-
-> **NOTE**
->
-> A **@Link** decorated variable cannot be initialized inside the component.
-
-**Simple Type Example**
-
-The **@Link** semantics are derived from the '**$**' operator. In other words, **$isPlaying** is the two-way binding of the internal state **this.isPlaying**. When the button in the **PlayButton** child component is touched, the value of the **@Link** decorated variable is changed, and **PlayButton** together with the **\** and **\** components of the parent component is refreshed. Similarly, when the button in the parent component is touched, the value of **this.isPlaying** is changed, and **PlayButton** together with the **\** and **\** components of the parent component is refreshed.
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct Player {
- @State isPlaying: boolean = false
-
- build() {
- Column() {
- PlayButton({ buttonPlaying: $isPlaying })
- Text(`Player is ${this.isPlaying ? '' : 'not'} playing`).fontSize(18)
- Button('Parent:' + this.isPlaying)
- .margin(15)
- .onClick(() => {
- this.isPlaying = !this.isPlaying
- })
- }
- }
-}
-
-@Component
-struct PlayButton {
- @Link buttonPlaying: boolean
-
- build() {
- Column() {
- Button(this.buttonPlaying ? 'pause' : 'play')
- .margin(20)
- .onClick(() => {
- this.buttonPlaying = !this.buttonPlaying
- })
- }
- }
-}
-```
-
-**Complex Type Example**
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct Parent {
- @State arr: number[] = [1, 2, 3]
-
- build() {
- Column() {
- Child({ items: $arr })
- Button('Parent Button: splice')
- .margin(10)
- .onClick(() => {
- this.arr.splice(0, 1, 60)
- })
- ForEach(this.arr, item => {
- Text(item.toString()).fontSize(18).margin(10)
- }, item => item.toString())
- }
- }
-}
-
-
-@Component
-struct Child {
- @Link items: number[]
-
- build() {
- Column() {
- Button('Child Button1: push')
- .margin(15)
- .onClick(() => {
- this.items.push(100)
- })
- Button('Child Button2: replace whole item')
- .margin(15)
- .onClick(() => {
- this.items = [100, 200, 300]
- })
- }
- }
-}
-```
-
-**Example of Using @Link, @State, and @Prop Together**
-
-In the following example, **ParentView** contains two child components: **ChildA** and **ChildB**. The **counter** state variable of **ParentView** is used to initialize the **@Prop** decorated variable of **ChildA** and the **@Link** decorated variable of **ChildB**.
-
-- **@Link** establishes two-way binding between **ChildB** and **ParentView**.Value changes of the **counterRef** state variable in **ChildB** will be synchronized to **ParentView** and **ChildA**.
-- **@Prop** establishes one-way binding between **ChildA** and **ParentView**. Value changes of the **counterVal** state variable in **ChildA** will trigger a re-render of **ChildA**, but will not be synchronized to **ParentView** or **ChildB**.
-
-```ts
-// xxx.ets
-@Entry
-@Component
-struct ParentView {
- @State counter: number = 0
-
- build() {
- Column() {
- ChildA({ counterVal: this.counter })
- ChildB({ counterRef: $counter })
- }
- }
-}
-
-@Component
-struct ChildA {
- @Prop counterVal: number
-
- build() {
- Button(`ChildA: (${this.counterVal}) + 1`)
- .margin(15)
- .onClick(() => {
- this.counterVal += 1
- })
- }
-}
-
-@Component
-struct ChildB {
- @Link counterRef: number
-
- build() {
- Button(`ChildB: (${this.counterRef}) + 1`)
- .margin(15)
- .onClick(() => {
- this.counterRef += 1
- })
- }
-}
-```
-
-## @Observed and @ObjectLink
-
-When you need to set up bidirectional synchronization for a parent variable (**parent_a**) between the parent and child components, you can use **@State** to decorate the variable (**parent_a**) in the parent component and use **@Link** to decorate the corresponding variable (**child_a**) in the child component. In this way, data can be synchronized between the parent component and the specific child component, and between the parent component and its other child components. As shown below, bidirectional synchronization is configured for variables of **ClassA** in the parent and child components. If attribute **c** of the variable in child component 1 has its value changed, the parent component will be notified to synchronize the change. If attribute **c** in the parent component has its value changed, all child components will be notified to synchronize the change.
-
-
-
-In the preceding example, full synchronization is performed for a data object. If you want to synchronize partial information of a data object in a parent component, and if the information is a class object, use **@ObjectLink** and **@Observed** instead, as shown below.
-
-
-
-### Configuration Requirements
-
-- **@Observed** applies to classes, and **@ObjectLink** applies to variables.
-
-- The variables decorated by **@ObjectLink** must be of the class type.
- - The classes must be decorated by **@Observed**.
- - Parameters of the simple types are not supported. You can use **@Prop** to perform unidirectional synchronization.
-
-- **@ObjectLink** decorated variables are immutable.
- - Attribute changes are allowed. If an object is referenced by multiple **@ObjectLink** decorated variables, all custom components that have these variables will be notified for re-rendering.
-
-- Default values cannot be set for **@ObjectLink** decorated variables.
- - The parent component must be initialized with a TypeScript expression that involves variables decorated by **@State**, **@Link**, **@StorageLink**, **@Provide**, or **@Consume**.
-
-- **@ObjectLink** decorated variables are private variables and can be accessed only within the component.
-
-
-### Example
-
-```ts
-// xxx.ets
-// Use @ObjectLink and @Observed to set up bidirectional synchronization for the class object ClassA between the parent component ViewB and the child component ViewA. In this way, changes made to ClassA in ViewA will be synchronized to ViewB and other child components bound to ClassA.
-var nextID: number = 0
-
-@Observed
-class ClassA {
- public name: string
- public c: number
- public id: number
-
- constructor(c: number, name: string = 'OK') {
- this.name = name
- this.c = c
- this.id = nextID++
- }
-}
-
-@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
- })
- }.margin({ top: 10 })
- }
-}
-
-@Entry
-@Component
-struct ViewB {
- @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())
- ViewA({ label: `this.arrA[first]`, a: this.arrA[0] })
- ViewA({ label: `this.arrA[last]`, a: this.arrA[this.arrA.length - 1] })
-
- Button(`ViewB: reset array`)
- .margin({ top: 10 })
- .onClick(() => {
- this.arrA = [new ClassA(0), new ClassA(0)]
- })
- Button(`ViewB: push`)
- .margin({ top: 10 })
- .onClick(() => {
- this.arrA.push(new ClassA(0))
- })
- Button(`ViewB: shift`)
- .margin({ top: 10 })
- .onClick(() => {
- this.arrA.shift()
- })
- }.width('100%')
- }
-}
-```
-
-
-## @Provide and @Consume
-
-As the data provider, **@Provide** can update the data of child nodes and trigger page rendering. After **@Consume** detects that the **@Provide** decorated variable is updated, it will initiate re-rendering of the current custom component.
-
-> **NOTE**
->
-> When using **@Provide** and **@Consume**, avoid circular reference that may lead to infinite loops.
-
-### @Provide
-
-| Name | Description |
-| -------------- | ------------------------------------------------------------ |
-| Decorator parameter | A constant of the string type, which is used to set an alias for a decorated variable. If an alias is specified, implement the data update for this alias. If there is no alias, use the variable name as the alias. **@Provide(*'alias'*)** is recommended.|
-| Synchronization mechanism | The **@Provide** decorated variable is similar to the **@State** decorated variable. You can change the value of the variable to trigger a re-render. You can also modify the **@Consume** decorated variable to modify the **@State** decorated variable reversely.|
-| Initial value | The initial value must be set. |
-| Page re-rendering scenarios| Page re-rendering is triggered in the following scenarios: = [7, 12, 47, 3]
- @State totalPurchase: number = 0
- @State addPurchase: number = 0
-
- aboutToAppear() {
- this.updateTotal()
- }
-
- updateTotal(): void {
- let sum = 0;
- this.shopBasket.forEach((i) => {
- sum += i
- })
- // Calculate the total amount of items in the shopping basket. If the amount exceeds 100, the specified discount will be applied.
- this.totalPurchase = (sum < 100) ? sum : 0.9 * sum
- return this.totalPurchase
- }
-
- // This method is triggered when the value of shopBasket is changed.
- onBasketUpdated(propName: string): void {
- this.updateTotal()
- }
-
- build() {
- Column() {
- Button('add to basket ' + this.addPurchase)
- .margin(15)
- .onClick(() => {
- this.addPurchase = Math.round(100 * Math.random())
- this.shopBasket.push(this.addPurchase)
- })
- Text(`${this.totalPurchase}`)
- .fontSize(30)
- }
- }
-}
-```
diff --git a/en/application-dev/quick-start/arkts-state.md b/en/application-dev/quick-start/arkts-state.md
new file mode 100644
index 0000000000000000000000000000000000000000..d9cc3c750e3b2d5ad6a1adb539b177f797c62402
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-state.md
@@ -0,0 +1,261 @@
+# \@State: State Owned by Component
+
+
+An \@State decorated variable, also called a state variable, is a variable that holds the state property and is used to render the owning custom component. When it changes, the UI is re-rendered accordingly.
+
+
+Among the decorators related to state variables, \@State is the most basic decorator, as it is the one that empowers variables to have the state property. It is also the data source of most state variables.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Overview
+
+An @State decorated variable, like all other decorated variables in the declarative paradigm, are private and only accessible from within the component. Its type and its local initialization must be specified. Initialization from the parent component using the named parameter mechanism is accepted.
+
+\@State decorated variables have the following features:
+
+- A one-way and two-way data synchronization relationship can be set up from an \@State decorated variable to an \@Prop, \@Link, or \@ObjectLink decorated variable in a child component.
+
+- The lifecycle of the \@State decorated variable is the same as that of its owning custom component.
+
+
+## Rules of Use
+
+| \@State Decorator| Description |
+| ------------ | ---------------------------------------- |
+| Decorator parameters | None. |
+| Synchronization type | Does not synchronize with any type of variable in the parent component. |
+| Allowed variable types | Object, class, string, number, Boolean, enum, and array of these types. For details about the scenarios of nested types, see [Observed Changes](#observed-changes).** component.
+
+- When the state variable **count** changes, the framework searches for components that depend on this state variable, which include only the **\** component in this example.
+
+- The framework executes the update method of the **\** component to implement on-demand update.
+
+
+```ts
+@Entry
+@Component
+struct MyComponent {
+ @State count: number = 0;
+
+ build() {
+ Button(`click times: ${this.count}`)
+ .onClick(() => {
+ this.count += 1;
+ })
+ }
+}
+```
+
+
+### Decorating Variables of the Class Object Type
+
+- In this example, \@State is used to decorate the variables **count** and **title** in the custom component **MyComponent**. The type of **title** is **Model**, a custom class. If the value of **count** or **title** changes, the framework searches for all **MyComponent** instances that depend on these variables and triggers re-rendering of them.
+
+- The **EntryComponent** has multiple **MyComponent** instances. The internal state change of the first **MyComponent** instance does not affect the second **MyComponent** instance.
+
+
+
+```ts
+class Model {
+ public value: string;
+
+ constructor(value: string) {
+ this.value = value;
+ }
+}
+
+@Entry
+@Component
+struct EntryComponent {
+ build() {
+ Column() {
+ // The parameters specified here will overwrite the default values defined locally during initial render. Not all parameters need to be initialized from the parent component.
+ MyComponent({ count: 1, increaseBy: 2 })
+ MyComponent({ title: new Model('Hello, World 2'), count: 7 })
+ }
+ }
+}
+
+@Component
+struct MyComponent {
+ @State title: Model = new Model('Hello World');
+ @State count: number = 0;
+ private increaseBy: number = 1;
+
+ build() {
+ Column() {
+ Text(`${this.title.value}`)
+ Button(`Click to change title`).onClick(() => {
+ // The update of the @State decorated variable triggers the update of the component.
+ this.title.value = this.title.value === 'Hello ArkUI' ? 'Hello World' : 'HelloArkUI';
+ })
+
+ Button(`Click to increase count=${this.count}`).onClick(() => {
+ // The update of the @State decorated variable triggers the update of the component.
+ this.count += this.increaseBy;
+ })
+ }
+ }
+}
+```
+
+
+From this example, we learn the initialization process of an \@State decorated variable on initial render.
+
+
+1. Apply the locally defined default value.
+
+ ```ts
+ @State title: Model = new Model('Hello World');
+ @State count: number = 0;
+ ```
+
+2. Apply the named parameter value, if one is provided.
+
+ ```ts
+ MyComponent({ count: 1, increaseBy: 2 })
+ ```
diff --git a/en/application-dev/quick-start/arkts-statestyles.md b/en/application-dev/quick-start/arkts-statestyles.md
new file mode 100644
index 0000000000000000000000000000000000000000..fd0ac67bdba9603d82d385658c89ffbc40d931db
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-statestyles.md
@@ -0,0 +1,128 @@
+# stateStyles: Polymorphic Style
+
+
+Unlike \@Styles and \@Extend, which are used to reuse styles only on static pages, stateStyles enables you to set state-specific styles.
+
+
+## Overview
+
+stateStyles is an attribute method that sets the style based on the internal state of a component. It is similar to a CSS pseudo-class, with different syntax. ArkUI provides the following states:
+
+- focused
+
+- normal
+
+- pressed
+
+- disabled
+
+
+## Application Scenarios
+
+
+### Common Scenarios
+
+This example shows the most basic application scenario of stateStyles. The **\** component is the first component and is in the default focused state, where the pink style specified for **focused** takes effect. When the component is pressed, the black style specified for **pressed** takes effect. If you place another component before the **\** component and have it in the normal state, the yellow style specified for **normal** takes effect.
+
+
+```ts
+@Entry
+@Component
+struct StateStylesSample {
+ build() {
+ Column() {
+ Button('Click me')
+ .stateStyles({
+ focused: {
+ .backgroundColor(Color.Pink)
+ },
+ pressed: {
+ .backgroundColor(Color.Black)
+ },
+ normal: {
+ .backgroundColor(Color.Yellow)
+ }
+ })
+ }.margin('30%')
+ }
+}
+```
+
+
+ **Figure 1** Focused and pressed states
+
+
+
+
+### Combined Use of \@Styles and stateStyles
+
+The following example uses \@Styles to specify different states of stateStyles.
+
+
+
+```ts
+@Entry
+@Component
+struct MyComponent {
+ @Styles normalStyle() {
+ .backgroundColor(Color.Gray)
+ }
+
+ @Styles pressedStyle() {
+ .backgroundColor(Color.Red)
+ }
+
+ build() {
+ Column() {
+ Text('Text1')
+ .fontSize(50)
+ .fontColor(Color.White)
+ .stateStyles({
+ normal: this.normalStyle,
+ pressed: this.pressedStyle,
+ })
+ }
+ }
+}
+```
+
+ **Figure 2** Normal and pressed states
+
+
+
+
+### Using Regular Variables and State Variables in stateStyles
+
+stateStyles can use **this** to bind regular variables and state variables in a component.
+
+
+```ts
+@Entry
+@Component
+struct CompWithInlineStateStyles {
+ @State focusedColor: Color = Color.Red;
+ normalColor: Color = Color.Green
+
+ build() {
+ Button('clickMe').height(100).width(100)
+ .stateStyles({
+ normal: {
+ .backgroundColor(this.normalColor)
+ },
+ focused: {
+ .backgroundColor(this.focusedColor)
+ }
+ })
+ .onClick(() => {
+ this.focusedColor = Color.Pink
+ })
+ .margin('30%')
+ }
+}
+```
+
+By default, the **\** component is in red when focused. After a click event is triggered, it turns to pink when focused.
+
+ **Figure 3** Change of the styles in focused state by a click
+
+
diff --git a/en/application-dev/quick-start/arkts-style.md b/en/application-dev/quick-start/arkts-style.md
new file mode 100644
index 0000000000000000000000000000000000000000..64f03c11e337bd4932c5bb7fbece4ac59499364c
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-style.md
@@ -0,0 +1,104 @@
+# \@Styles: Definition of Resusable Styles
+
+
+If the style of each component needs to be set separately, this will result in a large amount of repeated code during development. Though copy and paste is available, it is inefficient and error-prone. To maximize code efficiency and maintainability, the \@Styles decorator is introduced.
+
+
+\@Styles helps avoid repeated style setting, by extracting multiple style settings into one method. When declaring a component, you can invoke this method and use the \@Styles decorator to quickly define and reuse the custom styles of a component.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Rules of Use
+
+- \@Styles supports only [universal attributes](../reference/arkui-ts/ts-universal-attributes-size.md) and [universal events](../reference/arkui-ts/ts-universal-events-click.md).
+
+- An \@Styles decorated method does not support parameters. The following example is invalid:
+
+ ```ts
+ // Invalid: @Styles does not support parameters.
+ @Styles function globalFancy (value: number) {
+ .width(value)
+ }
+ ```
+
+- \@Styles can be defined inside or outside a component declaration. When it is defined outside a component declaration, the component name must be preceded by the keyword **function**.
+
+ ```ts
+ // Global (outside a component declaration)
+ @Styles function functionName() { ... }
+
+ // Inside a component declaration
+ @Component
+ struct FancyUse {
+ @Styles fancy() {
+ .height(100)
+ }
+ }
+ ```
+
+- \@Styles defined inside a component declaration can access constants and state variables of the component through **this**, and mutate the values of state variables through events in \@Styles. The following is an example:
+
+ ```ts
+ @Component
+ struct FancyUse {
+ @State heightVlaue: number = 100
+ @Styles fancy() {
+ .height(this.heightVlaue)
+ .backgroundColor(Color.Yellow)
+ .onClick(() => {
+ this.heightVlaue = 200
+ })
+ }
+ }
+ ```
+
+- The priority of \@Styles defined inside a component declaration is higher than that of \@Styles defined outside a component declaration.
+ The framework preferentially searches for \@Styles within the current component.
+
+
+## Application Scenarios
+
+The following example demonstrates the usage of \@Styles inside and outside a component declaration.
+
+
+
+```ts
+// Define a \@Styles decorated method outside a component declaration.
+@Styles function globalFancy () {
+ .width(150)
+ .height(100)
+ .backgroundColor(Color.Pink)
+}
+
+@Entry
+@Component
+struct FancyUse {
+ @State heightVlaue: number = 100
+ // Define a \@Styles decorated method inside a component declaration.
+ @Styles fancy() {
+ .width(200)
+ .height(this.heightVlaue)
+ .backgroundColor(Color.Yellow)
+ .onClick(() => {
+ this.heightVlaue = 200
+ })
+ }
+
+ build() {
+ Column({ space: 10 }) {
+ // Use the \@Styles decorated method defined outside a component declaration.
+ Text('FancyA')
+ .globalFancy ()
+ .fontSize(30)
+ // Use the \@Styles decorated method defined outside a component declaration.
+ Text('FancyB')
+ .fancy()
+ .fontSize(30)
+ }
+ }
+}
+```
diff --git a/en/application-dev/quick-start/arkts-two-way-sync.md b/en/application-dev/quick-start/arkts-two-way-sync.md
new file mode 100644
index 0000000000000000000000000000000000000000..91be73c3f3ffea335784d26b34f5ab3464743294
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-two-way-sync.md
@@ -0,0 +1,47 @@
+# $$ Syntax: Two-Way Synchronization of Built-in Components
+
+
+The $$ operator provides a TS variable by-reference to a built-in component so that the variable value and the internal state of that component are kept in sync.
+
+
+What the internal state is depends on the component. For example, for the [bindPopup](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md) attribute method, it is the **show** parameter.
+
+
+## Rules of Use
+
+- $$ supports variables of simple types and variables decorated by **\@State**, **\@Link**, or **\@Prop**.
+
+- Currently, $$ supports only the **show** parameter of the [bindPopup](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md) attribute method, the **checked** attribute of the [\](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-basic-components-radio.md) component, and the **refreshing** parameter of the [\](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-container-refresh.md) component.
+
+- When the variable bound to $$ changes, the UI is re-rendered synchronously.
+
+
+## Example
+
+This example uses the **show** parameter of the [bindPopup](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md) attribute method.
+
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct bindPopupPage {
+ @State customPopup: boolean = false;
+
+ build() {
+ Column() {
+ Button('Popup')
+ .margin(20)
+ .onClick(() => {
+ this.customPopup = !this.customPopup
+ })
+ .bindPopup($$this.customPopup, {
+ message: 'showPopup'
+ })
+ }
+ }
+}
+```
+
+
+
diff --git a/en/application-dev/quick-start/arkts-watch.md b/en/application-dev/quick-start/arkts-watch.md
new file mode 100644
index 0000000000000000000000000000000000000000..6a566f0a6ba720ad967bb54c86649edb6e817f77
--- /dev/null
+++ b/en/application-dev/quick-start/arkts-watch.md
@@ -0,0 +1,175 @@
+# \@Watch: Getting Notified of State Variable Changes
+
+
+\@Watch is used to listen for state variables. If your application needs watch for value changes of a state variable, you can decorate the variable with \@Watch.
+
+
+> **NOTE**
+>
+> Since API version 9, this decorator is supported in ArkTS widgets.
+
+
+## Overview
+
+An application can request to be notified whenever the value of the \@Watch decorated variable changes. The \@Watch callback is called when the value change has occurred. \@Watch uses strict equality (===) to determine whether a value is updated in the ArkUI framework. If **false** is returned, the \@Watch callback is triggered.
+
+
+## Decorator Description
+
+| \@Watch Decorator| Description |
+| -------------- | ---------------------------------------- |
+| Decorator parameters | Mandatory. Constant string, which is quoted. Reference to a (string) => void custom component member function.|
+| Custom component variables that can be decorated | All decorated state variables. Regular variables cannot be watched. |
+| Order of decorators | It is recommended that the \@State, \@Prop, \@Link, or other decorators precede the \@Watch decorator.|
+
+
+## Syntax
+
+| Type | Description |
+| ---------------------------------------- | ---------------------------------------- |
+| (changedPropertyName? : string) => void | This function is a member function of the custom component. **changedPropertyName** indicates the name of the watched attribute.): void
-
-Sets the system color mode. This API uses an asynchronous callback to return the result.
-
-**Permission required**: ohos.permission.UPDATE_CONFIGURATION
-
-**System capability**: SystemCapability.ArkUI.UiAppearance
-
-**Parameters**
-| Name| Type| Mandatory| Description|
-| -- | -- | -- | -- |
-| mode | [DarkMode](#darkmode) | Yes| Color mode to set.|
-| callback | AsyncCallback\| Yes| Callback used to return the result.|
-
-**Example**
- ```ts
-uiAppearance.setDarkMode(uiAppearance.DarkMode.ALWAYS_DARK, (err) => {
- console.info(`${err}`);
-})
- ```
-
-
-## uiAppearance.setDarkMode
-
-setDarkMode(mode: DarkMode): Promise\;
-
-Sets the system color mode. This API uses a promise to return the result.
-
-**Permission required**: ohos.permission.UPDATE_CONFIGURATION
-
-**System capability**: SystemCapability.ArkUI.UiAppearance
-
-**Parameters**
-| Name| Type| Mandatory| Description|
-| -- | -- | -- | -- |
-| mode | [DarkMode](#darkmode) | Yes| Color mode to set.|
-
-**Return value**
-
-| Type | Description |
-| ------ | ------------------------------ |
-| Promise\ | Promise that returns no value.|
-
-**Example**
- ```ts
-uiAppearance.setDarkMode(uiAppearance.DarkMode.ALWAYS_DARK).then(() => {
- console.log('Set dark-mode successfully.');
-}).catch((err) => {
- console.log(`Set dark-mode failed, ${err}`);
-});
- ```
-
-
-## uiAppearance.getDarkMode
-
-getDarkMode(): DarkMode;
-
-Obtains the system color mode.
-
-**Permission required**: ohos.permission.UPDATE_CONFIGURATION
-
-**System capability**: SystemCapability.ArkUI.UiAppearance
-
-**Return value**
-| Type| Description|
-| -- | -- |
-|[DarkMode](#darkmode) | Color mode obtained.|
-
-**Example**
- ```ts
-let darkMode = uiAppearance.getDarkMode();
-console.log(`Get dark-mode ${darkMode}`);
- ```
diff --git a/en/application-dev/reference/apis/js-apis-window.md b/en/application-dev/reference/apis/js-apis-window.md
index 9c531d7632c5174adfd8d908c7d648bbb3cca584..3f30f8c0439ea53fb0574a9b062ba4c1cb4492fc 100644
--- a/en/application-dev/reference/apis/js-apis-window.md
+++ b/en/application-dev/reference/apis/js-apis-window.md
@@ -54,7 +54,7 @@ Defines the parameters for creating a subwindow or system window.
| ---------- | -------------------------- | -- | ----------------------------------- |
| name | string | Yes| Name of the window. |
| windowType | [WindowType](#windowtype7) | Yes| Type of the window. |
-| ctx | [BaseContext](js-apis-inner-application-baseContext.md) | No| Current application context. If this parameter is not set, no context is used.9+ | 2 | Gesture area. |
| TYPE_KEYBOARD9+ | 3 | Soft keyboard area. |
@@ -108,10 +108,10 @@ Describes the properties of the status bar and navigation bar.
| Name | Type| Mandatory| Description |
| -------------------------------------- | -------- | ---- | ------------------------------------------------------------ |
-| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or ARGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**. |
+| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**.|
| isStatusBarLightIcon7+ | boolean | No | Whether any icon on the status bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.|
| statusBarContentColor8+ | string | No | Color of the text on the status bar. After this property is set, the setting of **isStatusBarLightIcon** is invalid. The default value is **0xE5FFFFFF**.|
-| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or ARGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**. |
+| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**.|
| isNavigationBarLightIcon7+ | boolean | No | Whether any icon on the navigation bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.|
| navigationBarContentColor8+ | string | No | Color of the text on the navigation bar. After this property is set, the setting of **isNavigationBarLightIcon** is invalid. The default value is **0xE5FFFFFF**.|
@@ -164,7 +164,7 @@ Describes the callback for a single system bar.
| type | [WindowType](#windowtype7) | Yes | No | Type of the system bar whose properties are changed. Only the status bar and navigation bar are supported.|
| isEnable | boolean | Yes | No | Whether the system bar is displayed. The value **true** means that the system bar is displayed, and **false** means the opposite.|
| region | [Rect](#rect7) | Yes | No | Current position and size of the system bar. |
-| backgroundColor | string | Yes | No | Background color of the system bar. The value is a hexadecimal RGB or ARGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. |
+| backgroundColor | string | Yes | No | Background color of the system bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**.|
| contentColor | string | Yes | No | Color of the text on the system bar. |
## SystemBarTintState8+
@@ -2346,7 +2346,7 @@ Loads content from a page associated with a local storage to this window. This A
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the page from which the content will be loaded. |
-| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.|
+| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
@@ -2392,7 +2392,7 @@ Loads content from a page associated with a local storage to this window. This A
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the page from which the content will be loaded. |
-| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.|
+| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.|
**Return value**
@@ -3064,7 +3064,7 @@ Sets the background color for this window. In the stage model, this API must be
| Name| Type| Mandatory| Description|
| ----- | ------ | -- | ----------------------------------------------------------------------- |
-| color | string | Yes| Background color to set. The value is a hexadecimal RGB or ARGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. |
+| color | string | Yes| Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**.|
**Error codes**
@@ -3685,15 +3685,15 @@ Captures this window. This API uses an asynchronous callback to return the resul
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------------------------------------------ | --------- | ----------------------------------- |
-| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| ----------- | ------------------------- | ---- | -------------------- |
+| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
@@ -3720,15 +3720,15 @@ Captures this window. This API uses a promise to return the result.
**Return value**
-| Type | Description |
-| ----------------------------------------------------------- | --------------------------------------------- |
-| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
@@ -3748,7 +3748,7 @@ promise.then((pixelMap)=> {
opacity(opacity: number): void
-Sets the opacity for this window.
+Sets the opacity for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window).
**System API**: This is a system API.
@@ -3756,18 +3756,18 @@ Sets the opacity for this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------- | ------ | --------- | ------------------------------------------------- |
-| opacity | number | Yes | Opacity to set. The value ranges from 0.0 to 1.0. |
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ----------------------------------------------------------- |
+| opacity | number | Yes | Opacity to set. The value ranges from 0.0 to 1.0. The value **0.0** means completely transparent, and **1.0** means completely opaque.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -3783,7 +3783,7 @@ try {
scale(scaleOptions: ScaleOptions): void
-Sets the scale parameters for this window.
+Sets the scale parameters for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window).
**System API**: This is a system API.
@@ -3791,18 +3791,18 @@ Sets the scale parameters for this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------------ | ------------------------------ | --------- | ------------------------ |
-| scaleOptions | [ScaleOptions](#scaleoptions9) | Yes | Scale parameters to set. |
+| Name | Type | Mandatory| Description |
+| ------------ | ------------------------------ | ---- | ---------- |
+| scaleOptions | [ScaleOptions](#scaleoptions9) | Yes | Scale parameters to set.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -3824,7 +3824,7 @@ try {
rotate(rotateOptions: RotateOptions): void
-Sets the rotation parameters for this window.
+Sets the rotation parameters for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window).
**System API**: This is a system API.
@@ -3832,18 +3832,18 @@ Sets the rotation parameters for this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------------- | -------------------------------- | --------- | --------------------------- |
-| rotateOptions | [RotateOptions](#rotateoptions9) | Yes | Rotation parameters to set. |
+| Name | Type | Mandatory| Description |
+| ------------- | -------------------------------- | ---- | ---------- |
+| rotateOptions | [RotateOptions](#rotateoptions9) | Yes | Rotation parameters to set.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -3866,7 +3866,7 @@ try {
translate(translateOptions: TranslateOptions): void
-Sets the translation parameters for this window.
+Sets the translation parameters for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window).
**System API**: This is a system API.
@@ -3874,18 +3874,18 @@ Sets the translation parameters for this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ---------------- | -------------------------------------- | --------- | ------------------------------ |
-| translateOptions | [TranslateOptions](#translateoptions9) | Yes | Translation parameters to set. |
+| Name | Type | Mandatory| Description |
+| ---------------- | -------------------------------------- | ---- | -------------------- |
+| translateOptions | [TranslateOptions](#translateoptions9) | Yes | Translation parameters. The unit is pixels.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -3914,18 +3914,18 @@ Obtains the transition animation controller.
**Return value**
-| Type | Description |
-| ---------------------------------------------- | -------------------------------- |
-| [TransitionController](#transitioncontroller9) | Transition animation controller. |
+| Type | Description |
+| ---------------------------------------------- | ---------------- |
+| [TransitionController](#transitioncontroller9) | Transition animation controller.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -3976,18 +3976,18 @@ Blurs this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------ | ------ | --------- | ------------------------------------------------------------ |
-| radius | number | Yes | Radius of the blur. The value is greater than or equal to 0. The value **0** means that the blur is disabled for the window. |
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| radius | number | Yes | Radius of the blur. The value is greater than or equal to 0. The value **0** means that the blur is disabled for the window.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -4011,18 +4011,18 @@ Blurs the background of this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------ | ------ | --------- | ------------------------------------------------------------ |
-| radius | number | Yes | Radius of the blur. The value is greater than or equal to 0. The value **0** means that the blur is disabled for the background of the window. |
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ------------------------------------------------------------ |
+| radius | number | Yes | Radius of the blur. The value is greater than or equal to 0. The value **0** means that the blur is disabled for the background of the window.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -4046,18 +4046,18 @@ Sets the blur style for the background of this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| --------- | ------------------------ | --------- | --------------------------------------------------- |
-| blurStyle | [BlurStyle](#blurstyle9) | Yes | Blur style to set for the background of the window. |
+| Name | Type | Mandatory| Description |
+| --------- | --------- | ---- | ---------------------- |
+| blurStyle | [BlurStyle](#blurstyle9) | Yes | Blur style to set for the background of the window.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -4081,21 +4081,21 @@ Sets the shadow for the window borders.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------- | ------ | --------- | ------------------------------------------------------------ |
-| radius | number | Yes | Radius of the shadow. The value is greater than or equal to 0. The value **0** means that the shadow is disabled for the window borders. |
-| color | string | No | Color of the shadow. The value is a hexadecimal RGB or ARGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. |
-| offsetX | number | No | Offset of the shadow along the x-axis, in pixels. |
-| offsetY | number | No | Offset of the shadow along the y-axis, in pixels. |
+| Name | Type | Mandatory| Description |
+| ------- | ------ | ---- | ------------------------------------------------------------ |
+| radius | number | Yes | Radius of the shadow. The value is greater than or equal to 0. The value **0** means that the shadow is disabled for the window borders.|
+| color | string | No | Color of the shadow. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**.|
+| offsetX | number | No | Offset of the shadow along the x-axis, in pixels. |
+| offsetY | number | No | Offset of the shadow along the y-axis, in pixels. |
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -4119,18 +4119,18 @@ Sets the radius of the rounded corners for this window.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------ | ------ | --------- | ------------------------------------------------------------ |
-| radius | number | Yes | Radius of the rounded corners. The value is greater than or equal to 0. The value **0** means that the window does not use rounded corners. |
+| Name | Type | Mandatory| Description |
+| ----------- | ------- | ---- | -------------------- |
+| radius | number | Yes | Radius of the rounded corners. The value is greater than or equal to 0. The value **0** means that the window does not use rounded corners.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
-| 1300004 | Unauthorized operation. |
+| 1300004 | Unauthorized operation. |
**Example**
@@ -4149,16 +4149,16 @@ show(callback: AsyncCallback<void>): void
Shows this window. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------- | --------- | ----------------------------------- |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | ---------- |
+| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
**Example**
@@ -4179,16 +4179,16 @@ show(): Promise<void>
Shows this window. This API uses a promise to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4208,16 +4208,16 @@ destroy(callback: AsyncCallback<void>): void
Destroys this window. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------- | --------- | ----------------------------------- |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | ---------- |
+| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
**Example**
@@ -4238,16 +4238,16 @@ destroy(): Promise<void>
Destroys this window. This API uses a promise to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4269,18 +4269,18 @@ Moves this window. This API uses an asynchronous callback to return the result.
This operation is not supported in a window in full-screen mode.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------- | --------- | ------------------------------------------------------------ |
-| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. |
-| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | ------------------------------------------------- |
+| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right.|
+| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
@@ -4303,23 +4303,23 @@ Moves this window. This API uses a promise to return the result.
This operation is not supported in a window in full-screen mode.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ---- | ------ | --------- | ------------------------------------------------------------ |
-| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. |
-| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. |
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ------------------------------------------------- |
+| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right.|
+| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards.|
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4347,18 +4347,18 @@ The new width and height you set must meet the limits.
This operation is not supported in a window in full-screen mode.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------- | --------- | ----------------------------------- |
-| width | number | Yes | New width of the window, in px. |
-| height | number | Yes | New height of the window, in px. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | -------------------------- |
+| width | number | Yes | New width of the window, in px.|
+| height | number | Yes | New height of the window, in px.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
@@ -4387,23 +4387,23 @@ The new width and height you set must meet the limits.
This operation is not supported in a window in full-screen mode.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------ | ------ | --------- | -------------------------------- |
-| width | number | Yes | New width of the window, in px. |
-| height | number | Yes | New height of the window, in px. |
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | -------------------------- |
+| width | number | Yes | New width of the window, in px.|
+| height | number | Yes | New height of the window, in px.|
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4425,17 +4425,17 @@ Sets the type of this window. This API uses an asynchronous callback to return t
**System API**: This is a system API.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | -------------------------- | --------- | ----------------------------------- |
-| type | [WindowType](#windowtype7) | Yes | Window type. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | ---------- |
+| type | [WindowType](#windowtype7) | Yes | Window type.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
**Example**
@@ -4459,22 +4459,22 @@ Sets the type of this window. This API uses a promise to return the result.
**System API**: This is a system API.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ---- | -------------------------- | --------- | ------------ |
-| type | [WindowType](#windowtype7) | Yes | Window type. |
+| Name| Type | Mandatory| Description |
+| ------ | ------------------------- | ---- | ---------- |
+| type | [WindowType](#windowtype7) | Yes | Window type.|
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4495,16 +4495,16 @@ getProperties(callback: AsyncCallback<WindowProperties>): void
Obtains the properties of this window. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ---------------------------------------------------------- | --------- | ---------------------------------------------- |
-| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties. |
+| Name | Type | Mandatory| Description |
+| -------- | ---------------------------------------------------------- | ---- | ---------------------------- |
+| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties.|
**Example**
@@ -4525,16 +4525,16 @@ getProperties(): Promise<WindowProperties>
Obtains the properties of this window. This API uses a promise to return the result.
> **NOTE**
->
+>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
-| Type | Description |
-| ---------------------------------------------------- | --------------------------------------------- |
-| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties. |
+| Type | Description |
+| ---------------------------------------------------- | ------------------------------- |
+| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties.|
**Example**
@@ -4554,17 +4554,17 @@ getAvoidArea(type: [AvoidAreaType](#avoidareatype7), callback: AsyncCallback<
Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | --------------------------------------------- | --------- | --------------------------------- |
-| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. |
-| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. |
+| Name | Type | Mandatory| Description |
+| -------- |-----------------------------------------------| ---- | ------------------------------------------------------------ |
+| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area.|
+| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. |
**Example**
@@ -4586,22 +4586,22 @@ getAvoidArea(type: [AvoidAreaType](#avoidareatype7)): Promise<[AvoidArea](#av
Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. This API uses a promise to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ---- | -------------------------------- | --------- | ----------------- |
-| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. |
+| Name| Type | Mandatory| Description |
+| ------ |----------------------------------| ---- | ------------------------------------------------------------ |
+| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area.|
**Return value**
-| Type | Description |
-| --------------------------------------- | -------------------------------- |
-| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area. |
+| Type | Description |
+|-----------------------------------------| ----------------------------------- |
+| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area.|
**Example**
@@ -4622,17 +4622,17 @@ setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void
Sets whether to enable the full-screen mode for this window. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------------ | ------------------------- | --------- | ------------------------------------------------------------ |
-| isFullScreen | boolean | Yes | Whether to enable the full-screen mode, in which the status bar and navigation bar are hidden. The value **true** means to enable the full-screen mode, and **false** means the opposite. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| ------------ | ------------------------- | ---- | ---------------------------------------------- |
+| isFullScreen | boolean | Yes | Whether to enable the full-screen mode, in which the status bar and navigation bar are hidden. The value **true** means to enable the full-screen mode, and **false** means the opposite.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
@@ -4654,22 +4654,22 @@ setFullScreen(isFullScreen: boolean): Promise<void>
Sets whether to enable the full-screen mode for this window. This API uses a promise to return the result.
> **NOTE**
->
+>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------------ | ------- | --------- | ------------------------------------------------------------ |
-| isFullScreen | boolean | Yes | Whether to enable the full-screen mode, in which the status bar and navigation bar are hidden. The value **true** means to enable the full-screen mode, and **false** means the opposite. |
+| Name | Type | Mandatory| Description |
+| ------------ | ------- | ---- | ---------------------------------------------- |
+| isFullScreen | boolean | Yes | Whether to enable the full-screen mode, in which the status bar and navigation bar are hidden. The value **true** means to enable the full-screen mode, and **false** means the opposite.|
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4690,17 +4690,17 @@ setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void
Sets whether to enable the full-screen mode for the window layout. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ |
-| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| ------------------ | ------------------------- | ---- | ------------------------------------------------------------ |
+| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
@@ -4722,22 +4722,22 @@ setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>
Sets whether to enable the full-screen mode for the window layout. This API uses a promise to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------------------ | ------- | --------- | ------------------------------------------------------------ |
-| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite. |
+| Name | Type | Mandatory| Description |
+| ------------------ | ------- | ---- | ------------------------------------------------------------ |
+| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite.|
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Example**
@@ -4758,17 +4758,17 @@ setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallbac
Sets whether to display the status bar and navigation bar in this window. This API uses an asynchronous callback to return the result.
> **NOTE**
->
+>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ----------------------------- | --------- | ------------------------------------------------------------ |
-| names | Array<'status'\|'navigation'> | Yes | Whether to display the status bar and navigation bar.9+
@@ -5835,15 +5835,15 @@ Obtains the main window of this window stage. This API uses an asynchronous call
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | -------------------------------------- | --------- | ---------------------------------------- |
-| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window. |
+| Name | Type | Mandatory| Description |
+| -------- | -------------------------------------- | ---- | --------------------------------------------- |
+| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -5881,15 +5881,15 @@ Obtains the main window of this window stage. This API uses a promise to return
**Return value**
-| Type | Description |
-| -------------------------------- | --------------------------------------- |
-| Promise<[Window](#window)> | Promise used to return the main window. |
+| Type | Description |
+| -------------------------------- | ------------------------------------------------ |
+| Promise<[Window](#window)> | Promise used to return the main window.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -5926,15 +5926,15 @@ Obtains the main window of this window stage.
**Return value**
-| Type | Description |
-| ----------------- | ----------------------- |
-| [Window](#window) | return the main window. |
+| Type| Description|
+| ----------------- | --------------------------------- |
+| [Window](#window) | return the main window.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -5968,16 +5968,16 @@ Creates a subwindow for this window stage. This API uses an asynchronous callbac
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | -------------------------------------- | --------- | -------------------------------------- |
-| name | string | Yes | Name of the subwindow. |
-| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow. |
+| Name | Type | Mandatory| Description |
+| -------- | -------------------------------------- | ---- | --------------------------------------------- |
+| name | string | Yes | Name of the subwindow. |
+| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6019,21 +6019,21 @@ Creates a subwindow for this window stage. This API uses a promise to return the
**Parameters**
-| Name | Type | Mandatory | Description |
-| ---- | ------ | --------- | ---------------------- |
-| name | string | Yes | Name of the subwindow. |
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | -------------- |
+| name | string | Yes | Name of the subwindow.|
**Return value**
-| Type | Description |
-| -------------------------------- | ------------------------------------- |
-| Promise<[Window](#window)> | Promise used to return the subwindow. |
+| Type | Description |
+| -------------------------------- | ------------------------------------------------ |
+| Promise<[Window](#window)> | Promise used to return the subwindow.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6074,15 +6074,15 @@ Obtains all the subwindows of this window stage. This API uses an asynchronous c
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | --------------------------------------------------- | --------- | ------------------------------------------- |
-| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the subwindows. |
+| Name | Type | Mandatory| Description |
+| -------- | --------------------------------------------------- | ---- | ------------------------------------------------- |
+| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the subwindows.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300005 | This window stage is abnormal. |
@@ -6118,15 +6118,15 @@ Obtains all the subwindows of this window stage. This API uses a promise to retu
**Return value**
-| Type | Description |
-| --------------------------------------------- | ------------------------------------------ |
-| Promise<Array<[Window](#window)>> | Promise used to return all the subwindows. |
+| Type | Description |
+| --------------------------------------------- | ---------------------------------------------------- |
+| Promise<Array<[Window](#window)>> | Promise used to return all the subwindows.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300005 | This window stage is abnormal. |
@@ -6161,17 +6161,17 @@ Loads content from a page associated with a local storage to the main window in
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
-| path | string | Yes | Path of the page from which the content will be loaded. |
-| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
+| path | string | Yes | Path of the page from which the content will be loaded. |
+| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6214,22 +6214,22 @@ Loads content from a page associated with a local storage to the main window in
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
-| path | string | Yes | Path of the page from which the content will be loaded. |
-| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. |
+| Name | Type | Mandatory| Description |
+| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
+| path | string | Yes | Path of the page from which the content will be loaded. |
+| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.|
**Return value**
-| Type | Description |
-| ------------------- | ------------------------------ |
-| Promise<void> | Promise that returns no value. |
+| Type | Description |
+| ------------------- | ------------------------- |
+| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6271,16 +6271,16 @@ Loads content from a page to this window stage. This API uses an asynchronous ca
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------- | --------- | ------------------------------------------------------- |
-| path | string | Yes | Path of the page from which the content will be loaded. |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------- | ---- | -------------------- |
+| path | string | Yes | Path of the page from which the content will be loaded.|
+| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6320,16 +6320,16 @@ Enables listening for window stage lifecycle changes.
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
-| type | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. |
-| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| type | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event.|
+| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. |
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6367,16 +6367,16 @@ Disables listening for window stage lifecycle changes.
**Parameters**
-| Name | Type | Mandatory | Description |
-| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
-| type | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. |
-| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | No | Callback used to return the window stage lifecycle state. |
+| Name | Type | Mandatory| Description |
+| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
+| type | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event.|
+| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | No | Callback used to return the window stage lifecycle state. |
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6415,7 +6415,7 @@ Disables window decorators.
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6447,15 +6447,15 @@ Sets whether to display the window of the application on the lock screen.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ---------------- | ------- | --------- | ------------------------------------------------------------ |
-| showOnLockScreen | boolean | Yes | Whether to display the window on the lock screen. The value **true** means to display the window on the lock screen, and **false** means the opposite. |
+| Name | Type | Mandatory| Description |
+| ---------------- | ------- | ---- | ---------------------------- |
+| showOnLockScreen | boolean | Yes | Whether to display the window on the lock screen. The value **true** means to display the window on the lock screen, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md).
-| ID | Error Message |
+| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
@@ -6486,9 +6486,9 @@ Provides the context for the transition animation.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
-| Name | Type | Readable | Writable | Description |
-| --------------------- | ----------------- | -------- | -------- | --------------------------------------- |
-| toWindow9+ | [Window](#window) | Yes | Yes | Target window to display the animation. |
+| Name | Type | Readable| Writable| Description |
+| --------------------- | ----------------- | ---- | ---- | ---------------- |
+| toWindow9+ | [Window](#window) | Yes | Yes | Target window to display the animation.|
### completeTransition9+
@@ -6502,9 +6502,9 @@ Completes the transition. This API can be called only after [animateTo()](../ark
**Parameters**
-| Name | Type | Mandatory | Description |
-| ----------- | ------- | --------- | ------------------------------------------------------------ |
-| isCompleted | boolean | Yes | Whether the transition is complete. The value **true** means that the transition is complete, and **false** means the opposite. |
+| Name | Type | Mandatory| Description |
+| ----------- | ------- | ---- | ------------------------------------------------------------ |
+| isCompleted | boolean | Yes | Whether the transition is complete. The value **true** means that the transition is complete, and **false** means the opposite.|
**Example**
@@ -6554,9 +6554,9 @@ Customizes the animation for the scenario when the window is shown.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------- | ---------------------------------------- | --------- | ------------------------------------ |
-| context | [TransitionContext](#transitioncontext9) | Yes | Context of the transition animation. |
+| Name | Type | Mandatory| Description |
+| ------- | ---------------------------------------- | ---- | -------------------- |
+| context | [TransitionContext](#transitioncontext9) | Yes | Context of the transition animation.|
**Example**
@@ -6600,9 +6600,9 @@ Customizes the animation for the scenario when the window is hidden.
**Parameters**
-| Name | Type | Mandatory | Description |
-| ------- | ---------------------------------------- | --------- | ------------------------------------ |
-| context | [TransitionContext](#transitioncontext9) | Yes | Context of the transition animation. |
+| Name | Type | Mandatory| Description |
+| ------- | ---------------------------------------- | ---- | -------------------- |
+| context | [TransitionContext](#transitioncontext9) | Yes | Context of the transition animation.|
**Example**
@@ -6632,4 +6632,4 @@ controller.animationForHidden = (context : window.TransitionContext) => {
)
console.info('complete transition end');
};
-```
\ No newline at end of file
+```
diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001511900496.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001511900496.png
new file mode 100644
index 0000000000000000000000000000000000000000..1231a0e0e693e1648c06b25898596bdc8546a3e0
Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001511900496.png differ
diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001563060749.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001563060749.png
new file mode 100644
index 0000000000000000000000000000000000000000..a9b5769ad867f880dbe2b746b15de80cadbf799e
Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001563060749.png differ
diff --git a/en/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md b/en/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md
new file mode 100644
index 0000000000000000000000000000000000000000..0acd1662b6b4e471f085a11539401336186d697a
--- /dev/null
+++ b/en/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md
@@ -0,0 +1,204 @@
+# Custom Component Lifecycle
+
+
+The lifecycle callbacks of a custom component are used to notify users of the lifecycle of the component. These callbacks are private and are invoked by the development framework at a specified time at runtime. They cannot be manually invoked from applications.
+
+
+>**NOTE**
+>
+>Promise and asynchronous callback functions can be used in lifecycle functions, for example, network resource getters and timer setters.
+
+
+## aboutToAppear
+
+aboutToAppear?(): void
+
+Invoked after a new instance of the custom component is created and before its **build** function is executed. You can change state variables in the **aboutToAppear** function. The change will take effect when you execute the **build** function next time.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+## aboutToDisappear
+
+aboutToDisappear?(): void
+
+Invoked before the destructor of the custom component is consumed. Do not change state variables in the **aboutToDisappear** function as doing this can cause unexpected errors. For example, the modification of the **@Link** decorated variable may cause unstable application running.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+## onPageShow
+
+onPageShow?(): void
+
+Invoked when a page is displayed. This callback is used in the routing process or scenarios where the application is switched to the foreground or background. It works only for the custom components decorated by **@Entry**.
+
+
+## onPageHide
+
+onPageHide?(): void
+
+Invoked when a page is hidden. This callback is used in the routing process or scenarios where the application is switched to the foreground or background. It works only for the custom components decorated by **@Entry**.
+
+
+## onBackPress
+
+onBackPress?(): void
+
+Invoked when a user clicks the back button. It works only for the custom components decorated by **@Entry**. The value **true** is returned if the page processes the return logic instead of performing page routing. The value false is returned if the default return logic is used. If the return value is not set, the value **false** is used.
+
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct IndexComponent {
+ @State textColor: Color = Color.Black;
+
+ onPageShow() {
+ this.textColor = Color.Blue;
+ console.info('IndexComponent onPageShow');
+ }
+
+ onPageHide() {
+ this.textColor = Color.Transparent;
+ console.info('IndexComponent onPageHide');
+ }
+
+ onBackPress() {
+ this.textColor = Color.Red;
+ console.info('IndexComponent onBackPress');
+ }
+
+ build() {
+ Column() {
+ Text('Hello World')
+ .fontColor(this.textColor)
+ .fontSize(30)
+ .margin(30)
+ }.width('100%')
+ }
+}
+```
+
+
+
+
+## onLayout9+
+
+onLayout?(children: Array<LayoutChild>, constraint: ConstraintSizeOptions): void
+
+Invoked when the custom component lays out its child components. Through this callback the component receives its child component layout information and size constraint from the framework. The state variable cannot be changed in the **onLayout** callback.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+**Parameters**
+
+| Name | Type | Description |
+| ---------- | ---------------------------------------- | ---------------- |
+| children | Array<[LayoutChild](#layoutchild9)> | Child component layout information. |
+| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Size constraint information of the parent component.|
+
+
+## onMeasure9+
+
+onMeasure?(children: Array<LayoutChild>, constraint: ConstraintSizeOptions): void
+
+Invoked when the custom component lays out its child components. Through this callback the component receives its child component layout information and size constraint from the framework. The state variable cannot be changed in the **onMeasure** callback.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+**Parameters**
+
+| Name | Type | Description |
+| ---------- | ---------------------------------------- | ---------------- |
+| children | Array<[LayoutChild](#layoutchild9)> | Child component layout information. |
+| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Size constraint information of the parent component.|
+
+
+## LayoutChild9+
+
+Provides the child component layout information.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+| Parameter | Type | Description |
+| ---------- | ---------------------------------------- | ------------------- |
+| name | string | Name of the child component. |
+| id | string | ID of the child component. |
+| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Constraint size of the child component. |
+| borderInfo | [LayoutBorderInfo](#layoutborderinfo9) | Provides the border information of the child component. |
+| position | [Position](ts-types.md#position) | Position coordinates of the child component. |
+| measure | (childConstraint:) => void | Method called to apply the size constraint to the child component.|
+| layout | (LayoutInfo: [LayoutInfo](#layoutinfo9)) => void| Method called to apply the layout information to the child component.|
+
+
+## LayoutBorderInfo9+
+
+Provides the border information of the child component.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+| Parameter | Type | Description |
+| ----------- | ------------------------------------ | ----------------------- |
+| borderWidth | [EdgeWidths](ts-types.md#edgewidths) | Edge widths in different directions of the component.|
+| margin | [Margin](ts-types.md#margin) | Margins in different directions of the component. |
+| padding | [Padding](ts-types.md#padding) | Paddings in different directions of the component. |
+
+
+## LayoutInfo9+
+
+Provides the layout information of the child component.
+
+Since API version 9, this API is supported in ArkTS widgets.
+
+| Parameter | Type | Description |
+| ---------- | ---------------------------------------- | -------- |
+| position | [Position](ts-types.md#position) | Position coordinates of the child component.|
+| constraint | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Constraint size of the child component.|
+
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct Index {
+ build() {
+ Column() {
+ CustomLayout() {
+ ForEach([1, 2, 3], (index) => {
+ Text('Sub' + index)
+ .fontSize(30)
+ .borderWidth(2)
+ })
+ }
+ }
+ }
+}
+
+
+@Component
+struct CustomLayout {
+ @BuilderParam builder: () => {};
+
+ onLayout(children: Array, constraint: ConstraintSizeOptions) {
+ let pos = 0;
+ children.forEach((child) => {
+ child.layout({ position: { x: pos, y: pos }, constraint: constraint })
+ pos += 100;
+ })
+ }
+
+ onMeasure(children: Array, constraint: ConstraintSizeOptions) {
+ let size = 100;
+ children.forEach((child) => {
+ child.measure({ minHeight: size, minWidth: size, maxWidth: size, maxHeight: size })
+ size += 50;
+ })
+ }
+
+ build() {
+ this.builder()
+ }
+}
+```
+
+
diff --git a/en/application-dev/ui/Readme-EN.md b/en/application-dev/ui/Readme-EN.md
index afd987b1607c3a489c7d686e848e61330e4f7a1f..2828cf88464c8dcfee6552cdfd232f7dcdf15cd1 100644
--- a/en/application-dev/ui/Readme-EN.md
+++ b/en/application-dev/ui/Readme-EN.md
@@ -1,36 +1,68 @@
# UI Development
- [ArkUI Overview](arkui-overview.md)
-- UI Development with ArkTS-based Declarative Development Paradigm
- - [Overview](ui-ts-overview.md)
- - [Declarative UI Development Guidelines](ui-ts-developing-intro.md)
- - Declarative UI Development Examples
- - [Creating a Simple Page](ui-ts-creating-simple-page.md)
- - Building a Comprehensive Example
- - [Building a Food Data Model](ui-ts-building-data-model.md)
- - [Building a Food Category List Layout](ui-ts-building-category-list-layout.md)
- - [Building a Food Category Grid Layout](ui-ts-building-category-grid-layout.md)
- - [Implementing Page Redirection and Data Transmission](ui-ts-page-redirection-data-transmission.md)
- - Adding a Splash Screen Animation
- - [Using the Drawing Feature](ui-ts-drawing-feature.md)
- - [Using the Animation Feature](ui-ts-animation-feature.md)
- - [Common Components](ui-ts-components-intro.md)
- - Common Layout Development
- - Adaptive Layouts
- - [Linear Layout](ui-ts-layout-linear.md)
- - [Statck Layout](ui-ts-layout-stack.md)
- - [Flex Layout](ui-ts-layout-flex.md)
- - [Grid Layout](ui-ts-layout-grid.md)
- - Responsive Layouts
- - [Grid Layout](ui-ts-layout-grid-container-new.md)
- - [Media Query](ui-ts-layout-mediaquery.md)
- - [Custom Component Lifecycle Callbacks](ui-ts-custom-component-lifecycle-callbacks.md)
- - [Web Component Development](ui-ts-components-web.md)
- - [Recommendations for Improving Performance](ui-ts-performance-improvement-recommendation.md)
-- UI Development with JavaScript-compatible Web-like Development Paradigm
- - [Overview](ui-js-overview.md)
- - Framework Overview
- - [File Organization](js-framework-file.md)
+- UI Development (ArkTS-based Declarative Development Paradigm)
+ - [UI Development (ArkTS-based Declarative Development Paradigm) Overview](arkts-ui-development-overview.md)
+ - Layout Development
+ - [Layout Overview](arkts-layout-development-overview.md)
+ - Building a Layout
+ - [Linear Layout](arkts-layout-development-linear.md)
+ - [Stack Layout](arkts-layout-development-stack-layout.md)
+ - [Flex Layout](arkts-layout-development-flex-layout.md)
+ - [Relative Layout](arkts-layout-development-relative-layout.md)
+ - [Responsive Grid Layout](arkts-layout-development-grid-layout.md)
+ - [Media Query](arkts-layout-development-media-query.md)
+ - [Creating a List](arkts-layout-development-create-list.md)
+ - [Creating a Grid](arkts-layout-development-create-grid.md)
+ - [Creating a Swiper](arkts-layout-development-create-looping.md)
+ - [Improving Layout Performance](arkts-layout-development-performance-boost.md)
+ - Adding a Component
+ - Adding a Common Component
+ - [Button](arkts-common-components-button.md)
+ - [Radio Button](arkts-common-components-radio-button.md)
+ - [Toggle](arkts-common-components-switch.md)
+ - [Progress Indicator](arkts-common-components-progress-indicator.md)
+ - [Text Display](arkts-common-components-text-display.md)
+ - [Text Input](arkts-common-components-text-input.md)
+ - [Custom Dialog Box](arkts-common-components-custom-dialog.md)
+ - [Video Playback](arkts-common-components-video-player.md)
+ - [XComponent](arkts-common-components-xcomponent.md)
+ - Adding a Bubble and Menu
+ - [Bubble](arkts-popup-and-menu-components-popup.md)
+ - [Menu](arkts-popup-and-menu-components-menu.md)
+ - Setting Page Routing and Component Navigation
+ - [Page Routing](arkts-routing.md)
+ - Component Navigation
+ - [Navigation](arkts-navigation-navigation.md)
+ - [Tabs](arkts-navigation-tabs.md)
+ - Using Graphics
+ - [Displaying Images](arkts-graphics-display.md)
+ - [Drawing Geometric Shapes](arkts-geometric-shape-drawing.md)
+ - [Drawing Custom Graphics on the Canvas](arkts-drawing-customization-on-canvas.md)
+ - Using Animation
+ - [Animation Overview](arkts-animation-overview.md)
+ - Animation Within a Page
+ - [Layout Update Animation](arkts-layout-update-animation.md)
+ - [Transition Animation Within a Component](arkts-transition-animation-within-component.md)
+ - [Spring Curve Animation](arkts-spring-animation.md)
+ - Animation Between Pages
+ - [Zoom Animation](arkts-zoom-animation.md)
+ - [Page Transition Animation](arkts-page-transition-animation.md)
+ - Using Interaction Events
+ - [Interaction Event Overview](arkts-event-overview.md)
+ - Universal Events
+ - [Touchscreen Event](arkts-common-events-touch-screen-event.md)
+ - [Keyboard and Mouse Event](arkts-common-events-device-input-event.md)
+ - [Focus Event](arkts-common-events-focus-event.md)
+ - Gesture Events
+ - [Gesture Binding](arkts-gesture-events-binding.md)
+ - [Single Gesture](arkts-gesture-events-single-gesture.md)
+ - [Combined Gestures](arkts-gesture-events-combined-gestures.md)
+ - [Recommendations for Improving Performance](arkts-performance-improvement-recommendation.md)
+- UI Development (JavaScript-compatible Web-like Development Paradigm)
+ - [UI Development (JavaScript-compatible Web-like Development Paradigm) Overview](ui-js-overview.md)
+ - Framework Overview
+ - [File Organization](js-framework-file.md)
- ["js" Tag](js-framework-js-tag.md)
- [app.js](js-framework-js-file.md)
- Syntax
diff --git a/en/application-dev/ui/arkts-animation-overview.md b/en/application-dev/ui/arkts-animation-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..420a573762be5303597b80341e7a17e16ffbb31c
--- /dev/null
+++ b/en/application-dev/ui/arkts-animation-overview.md
@@ -0,0 +1,27 @@
+# Animation Overview
+
+
+The principle of animation is that the UI appearance is changed for multiple times within a period of time. Because human eyes generate visual persistence, what you finally see is a continuous animation. A change of the UI is called an animation frame, which corresponds to a screen refresh. An important indicator that determines the animation smoothness is the frame rate (FPS), that is, the number of animation frames per second. The higher the frame rate, the smoother the animation.
+
+
+In ArkUI, an animation is generated by changing the attribute value and specifying the animation parameters. Animation parameters include parameters such as animation duration and change rule (that is, curve). After the attribute value changes, the original state is transited to the new state according to the animation parameter, that is, an animation is formed.
+
+
+The animation capability provided by the ArkUI can be classified into intra-page animation and inter-page animation based on the page classification mode. As shown in the following figure, an animation on a page refers to an animation that can occur on a page, and an animation between pages refers to an animation that occurs only when two pages jump.
+
+
+ Figure 1 Animation by page
+
+
+
+
+Based on the basic capability, the animation can be divided into three parts: attribute animation, explicit animation, and transition animation. as shown in the following figure.
+
+
+ Figure 2 Animation classified by basic capability
+
+
+
+
+
+Based on the page classification mode and application scenarios, this document provides the usage methods and precautions of various animations for developers to quickly learn animations.
diff --git a/en/application-dev/ui/arkts-common-components-button.md b/en/application-dev/ui/arkts-common-components-button.md
new file mode 100644
index 0000000000000000000000000000000000000000..82c893d33aa0049e5b2e815ae6a31b7d13a1775a
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-button.md
@@ -0,0 +1,261 @@
+# Button
+
+
+The **\** component is usually activated by user clicks to perform a specific action. Buttons are classified as capsule, circle, or normal buttons. When used as a container, the **\** component accepts child components such as text and images. For details, see [Button](../reference/arkui-ts/ts-basic-components-button.md).
+
+
+## Creating a Button
+
+You can create a button that contains or does not contain child components.
+
+
+- Create a button that does not contain child components.
+
+ ```ts
+ Button(label?: string, options?: { type?: ButtonType, stateEffect?: boolean })
+ ```
+
+ Creates a button that does not contain child components. In this API, **label** indicates the button text, **type** indicates the button type, and **stateEffect** specifies whether to set pressed effect on the click of the button.
+
+ ```ts
+ Button('Ok', { type: ButtonType.Normal, stateEffect: true })
+ .borderRadius(8)
+ .backgroundColor(0x317aff)
+ .width(90)
+ .height(40)
+ ```
+
+ 
+
+
+- Create a button that contains child components.
+
+ ```ts
+ Button(options?: {type?: ButtonType, stateEffect?: boolean})
+ ```
+
+ Creates a button that contains a single child component, which can either be a [basic component](../reference/arkui-ts/ts-basic-components-blank.md) or a [container component](../reference/arkui-ts/ts-container-ability-component.md).
+
+ ```ts
+ Button({ type: ButtonType.Normal, stateEffect: true }) {
+ Row() {
+ Image($r('app.media.loading')).width(20).height(40).margin({ left: 12 })
+ Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 })
+ }.alignItems(VerticalAlign.Center)
+ }.borderRadius(8).backgroundColor(0x317aff).width(90).height(40)
+ ```
+
+ 
+
+
+## Setting the Button Type
+
+Use the **type** parameter to set the button type to **Capsule**, **Circle**, or **Normal**.
+
+
+- Capsule button (default type)
+ Buttons of this type have rounded corners whose radius is automatically set to half of the button height. The rounded corners cannot be reset through the **borderRadius** attribute.
+
+ ```ts
+ Button('Disable', { type: ButtonType.Capsule, stateEffect: false })
+ .backgroundColor(0x317aff)
+ .width(90)
+ .height(40)
+ ```
+
+ 
+
+
+- Circle button
+ Buttons of this type are round. The rounded corners cannot be reset through the **borderRadius** attribute.
+
+ ```ts
+ Button('Circle', { type: ButtonType.Circle, stateEffect: false })
+ .backgroundColor(0x317aff)
+ .width(90)
+ .height(90)
+ ```
+
+ 
+
+- Normal button
+ Buttons of this type have rounded corners set to 0. The rounded corners can be reset through the **borderRadius** attribute.
+
+ ```ts
+ Button('Ok', { type: ButtonType.Normal, stateEffect: true })
+ .borderRadius(8)
+ .backgroundColor(0x317aff)
+ .width(90)
+ .height(40)
+ ```
+
+ 
+
+
+## Setting Styles
+
+- Set the border radius:
+ In general cases, you can use universal attributes to define the button styles. For example, you can use the **borderRadius** attribute to set the border radius.
+
+ ```ts
+ Button('circle border', { type: ButtonType.Normal })
+ .borderRadius(20)
+ .height(40)
+ ```
+
+ 
+
+
+- The **Font** type is used to set the text style.
+ Add a font style for text displayed on the button.
+
+ ```ts
+ Button('font style', { type: ButtonType.Normal })
+ .fontSize(20)
+ .fontColor(Color.Pink)
+ .fontWeight(800)
+ ```
+
+ 
+
+
+- Set the background color:
+ You can do so by adding the **backgroundColor** attribute.
+
+ ```ts
+ Button('background color').backgroundColor(0xF55A42)
+ ```
+
+ 
+
+
+- Assign a function to the button:
+ In this example, the delete function is assigned to the button.
+
+ ```ts
+ Button({ type: ButtonType.Circle, stateEffect: true }) {
+ Image($r('app.media.ic_public_delete_filled')).width(30).height(30)
+ }.width(55).height(55).margin({ left: 20 }).backgroundColor(0xF55A42)
+ ```
+
+ 
+
+
+## Adding Events
+
+The **\** component is usually used to trigger actions. You can bind the **onClick** event to the button to have it respond with custom behavior after being clicked.
+
+```ts
+Button('Ok', { type: ButtonType.Normal, stateEffect: true })
+ .onClick(()=>{
+ console.info('Button onClick')
+ })
+```
+
+
+## Example Scenario
+
+- Using the Button for Startup
+ You can use the button for any UI element that involves the startup operation. The button triggers the predefined event based on the user's operation. For example, you can use a button in the **\** container to redirect the user to another page.
+
+ ```ts
+ // xxx.ets
+ import router from '@ohos.router';
+ @Entry
+ @Component
+ struct ButtonCase1 {
+ build() {
+ List({ space: 4 }) {
+ ListItem() {
+ Button("First").onClick(() => {
+ router.pushUrl({ url: 'pages/first_page' })
+ })
+ .width('100%')
+ }
+ ListItem() {
+ Button("Second").onClick(() => {
+ router.pushUrl({ url: 'pages/second_page' })
+ })
+ .width('100%')
+ }
+ ListItem() {
+ Button("Third").onClick(() => {
+ router.pushUrl({ url: 'pages/third_page' })
+ })
+ .width('100%')
+ }
+ }
+ .listDirection(Axis.Vertical)
+ .backgroundColor(0xDCDCDC).padding(20)
+ }
+ }
+ ```
+
+ 
+
+
+- Use the button for submitting forms:
+ On the user login/registration page, you can use a button to submit a login or registration request.
+
+ ```ts
+ // xxx.ets
+ @Entry
+ @Component
+ struct ButtonCase2 {
+ build() {
+ Column() {
+ TextInput({ placeholder: 'input your username' }).margin({ top: 20 })
+ TextInput({ placeholder: 'input your password' }).type(InputType.Password).margin({ top: 20 })
+ Button('Register').width(300).margin({ top: 20 })
+ .onClick(() => {
+ // Operation
+ })
+ }.padding(20)
+ }
+ }
+ ```
+
+ 
+
+- Configure the button to float:
+ The button can remain floating when the user swipes on the screen.
+
+ ```ts
+ // xxx.ets
+ @Entry
+ @Component
+ struct HoverButtonExample {
+ private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ build() {
+ Stack() {
+ List({ space: 20, initialIndex: 0 }) {
+ ForEach(this.arr, (item) => {
+ ListItem() {
+ Text('' + item)
+ .width('100%').height(100).fontSize(16)
+ .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
+ }
+ }, item => item)
+ }.width('90%')
+ Button() {
+ Image($r('app.media.ic_public_add'))
+ .width(50)
+ .height(50)
+ }
+ .width(60)
+ .height(60)
+ .position({x: '80%', y: 600})
+ .shadow({radius: 10})
+ .onClick(() => {
+ // Operation
+ })
+ }
+ .width('100%')
+ .height('100%')
+ .backgroundColor(0xDCDCDC)
+ .padding({ top: 5 })
+ }
+ }
+ ```
+
+ 
diff --git a/en/application-dev/ui/arkts-common-components-custom-dialog.md b/en/application-dev/ui/arkts-common-components-custom-dialog.md
new file mode 100644
index 0000000000000000000000000000000000000000..bf36a7bdee51a4808c06687d8c90f90bdc5b62ae
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-custom-dialog.md
@@ -0,0 +1,100 @@
+# Custom Dialog Box
+
+
+A custom dialog box is a dialog box you customize by using APIs of the **CustomDialogController** class. It can be used for user interactions, showing an ad, prize, alert, software update message, and more. For details, see [Custom Dialog Box](../reference/arkui-ts/ts-methods-custom-dialog-box.md).
+
+
+## Creating a Custom Dialog Box
+
+1. Use the \@CustomDialog decorator to create a custom dialog box.
+
+2. Set the content for the \@CustomDialog decorated dialog box.
+
+ ```ts
+ @CustomDialog
+ struct CustomDialogExample {
+ controller: CustomDialogController
+ build() {
+ Column() {
+ Text ('I am content')
+ .fontSize(20)
+ .margin({ top: 10, bottom: 10 })
+ }
+ }
+ }
+ ```
+
+3. Create a builder that is bound to the decorator.
+
+ ```ts
+ dialogController: CustomDialogController = new CustomDialogController({
+ builder: CustomDialogExample({}),
+ })
+ ```
+
+4. Click the component bound to the **onClick** event to display the dialog box.
+
+ ```ts
+ Flex({justifyContent:FlexAlign.Center}){
+ Button('click me')
+ .onClick(() => {
+ this.dialogController.open()
+ })
+ }.width('100%')
+ ```
+
+ 
+
+
+## Interaction with Custom Dialog Box
+
+Custom dialog boxes can be used for data interactions to complete a series of response operations.
+
+
+1. Add button operations to the \@CustomDialog decorator and add the creation of data functions.
+
+ ```ts
+ @CustomDialog
+ struct CustomDialogExample {
+ controller: CustomDialogController
+ cancel: () => void
+ confirm: () => void
+ build() {
+ Column() {
+ Text('I am content') .fontSize(20).margin({ top: 10, bottom: 10 })
+ Flex({ justifyContent: FlexAlign.SpaceAround }) {
+ Button('cancel')
+ .onClick(() => {
+ this.controller.close()
+ this.cancel()
+ }).backgroundColor(0xffffff).fontColor(Color.Black)
+ Button('confirm')
+ .onClick(() => {
+ this.controller.close()
+ this.confirm()
+ }).backgroundColor(0xffffff).fontColor(Color.Red)
+ }.margin({ bottom: 10 })
+ }
+ }
+ }
+ ```
+
+2. Receive the page in the builder and create corresponding function operations.
+
+ ```ts
+ dialogController: CustomDialogController = new CustomDialogController({
+ builder: CustomDialogExample({
+ cancel: this.onCancel,
+ confirm: this.onAccept,
+ }),
+ alignment: DialogAlignment.Default, // Set the alignment mode of the dialog box. By default, the dialog box is displayed at the bottom.
+ })
+ onCancel() {
+ console.info('Callback when the first button is clicked')
+ }
+ onAccept() {
+ console.info('Callback when the second button is clicked')
+ }
+ ```
+
+ 
diff --git a/en/application-dev/ui/arkts-common-components-progress-indicator.md b/en/application-dev/ui/arkts-common-components-progress-indicator.md
new file mode 100644
index 0000000000000000000000000000000000000000..6be5721def291240c6a3a984bd41032c801d91f0
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-progress-indicator.md
@@ -0,0 +1,135 @@
+# Progress Indicator
+
+
+The **\** component is used to provide a progress indicator that displays the progress of an operation. For details, see [Progress](../reference/arkui-ts/ts-basic-components-progress.md).
+
+
+## Creating a Progress Indicator
+
+You can create a progress indicator by calling the following API:
+
+
+
+```ts
+Progress(options: {value: number, total?: number, type?: ProgressType})
+```
+
+
+Creates a progress bar indicator. In this API, **value** indicates the initial progress, **total** indicates the total progress, and **type** indicates the style of the progress indicator.
+
+
+
+```ts
+Progress({ value: 24, total: 100, type: ProgressType.Linear }) // Create a linear progress indicator whose total progress is 100 and initial progress is 24.
+```
+
+
+
+
+
+## Setting the Progress Indicator Style
+
+Progress indicators come in five styles. When creating a progress indicator, you can specify its style by setting the **ProgressType** parameter to any of the following: **ProgressType.Linear** (linear style), **ProgressType.Ring** (indeterminate ring style), **ProgressType.ScaleRing** (determinate ring style), **ProgressType.Eclipse** (eclipse style), and **ProgressType.Capsule** (capsule style).
+
+
+- Linear style (default style)
+ >**NOTE**
+ >
+ > Since API version 9, the progress indicator adaptively switches to the vertical layout if the height is greater than the width and remains the horizontal layout if the height is equal to the width.
+
+
+ ```ts
+ Progress({ value: 20, total: 100, type: ProgressType.Linear }).width(200).height(50)
+ Progress({ value: 20, total: 100, type: ProgressType.Linear }).width(50).height(200)
+ ```
+
+ 
+
+- Indeterminate ring style
+
+ ```ts
+ // The progress indicator in the indeterminate ring style on the left: Retain its default settings for the foreground color (blue) and stroke width (2.0 vp).
+ Progress({ value: 40, total: 150, type: ProgressType.Ring }).width(100).height(100)
+ // The right progress indicator in the indeterminate ring style on the right.
+ Progress({ value: 40, total: 150, type: ProgressType.Ring }).width(100).height(100)
+ .color(Color.Grey) // Set the foreground color to gray.
+ .style({ strokeWidth: 15}) // Set the stroke width to 15.0 vp.
+ ```
+
+ 
+
+- Determinate ring style
+
+ ```ts
+ Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
+ .backgroundColor(Color.Black)
+ .style({ scaleCount: 20, scaleWidth: 5 }) // Set the total number of scales to 20 and the scale width to 5 vp.
+ Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
+ .backgroundColor(Color.Black)
+ .style({ strokeWidth: 15, scaleCount: 20, scaleWidth: 5 }) // Set the stroke width to 15, the total number of scales to 20, and the scale width to 5 vp.
+ Progress({ value: 20, total: 150, type: ProgressType.ScaleRing }).width(100).height(100)
+ .backgroundColor(Color.Black)
+ .style({ strokeWidth: 15, scaleCount: 20, scaleWidth: 3 }) // Set the stroke width to 15, the total number of scales to 20, and the scale width to 3 vp.
+ ```
+
+ 
+
+- Eclipse style
+
+ ```ts
+ // The progress indicator in the eclipse style on the left: Retain its default settings for the foreground color (blue).
+ Progress({ value: 10, total: 150, type: ProgressType.Eclipse }).width(100).height(100)
+ // The progress indicator in the eclipse style on the right: Set its foreground color to gray.
+ Progress({ value: 20, total: 150, type: ProgressType.Eclipse }).color(Color.Grey).width(100).height(100)
+ ```
+
+ 
+
+- Capsule style
+ >**NOTE**
+ >
+ >- At both ends, the progress indicator in the capsule style works in a same manner as that in the eclipse style.
+ >- In the middle part of the capsule, the progress indicator works in a same manner as the linear style.
+ >
+ >- If the height is greater than the width, the progress indicator adaptively switches to the vertical layout.
+
+
+ ```ts
+ Progress({ value: 10, total: 150, type: ProgressType.Capsule }).width(100).height(50)
+ Progress({ value: 20, total: 150, type: ProgressType.Capsule }).width(50).height(100).color(Color.Grey)
+ Progress({ value: 50, total: 150, type: ProgressType.Capsule }).width(50).height(100).backgroundColor(Color.Black)
+ ```
+
+ 
+
+
+## Example Scenario
+
+In this example, the progress of the **\** component is updated by clicking the button. After the button is clicked, the value of **progressValue** is incremented and passed to the **\** component, which is then updated accordingly.
+
+```ts
+@Entry
+@Component
+struct ProgressCase1 {
+ @State progressValue: number = 0 // Set the initial progress of the progress indicator to 0.
+ build() {
+ Column() {
+ Column() {
+ Progress({value:0, total:100, type:ProgressType.Capsule}).width(200).height(50)
+ .style({strokeWidth:50}).value(this.progressValue)
+ Row().width('100%').height(5)
+ Button ("Progress + 5")
+ .onClick(()=>{
+ this.progressValue += 5
+ if (this.progressValue > 100){
+ this.progressValue = 0
+ }
+ })
+ }
+ }.width('100%').height('100%')
+ }
+}
+```
+
+
+
diff --git a/en/application-dev/ui/arkts-common-components-radio-button.md b/en/application-dev/ui/arkts-common-components-radio-button.md
new file mode 100644
index 0000000000000000000000000000000000000000..92f5105642e0200b6852962d030d13c9cdbd58e8
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-radio-button.md
@@ -0,0 +1,106 @@
+# Radio Button
+
+
+The **\** component allows users to select from a set of mutually exclusive options. Only one radio button in a given group can be selected at the same time. For details, see [Radio](../reference/arkui-ts/ts-basic-components-radio.md).
+
+
+## Creating a Radio Button
+
+You can create a radio button by calling the following API:
+
+
+```ts
+Radio(options: {value: string, group: string})
+```
+
+ Creates a radio button. In this API, **value** indicates the name of the radio button, and **group** indicates the name of the group to which the radio button belongs. You can use the **checked** attribute of the radio button to specify whether it is selected. The value **true** means that the radio button is selected. The color and shape cannot be customized for the radio button.
+
+```ts
+Radio({ value: 'Radio1', group: 'radioGroup' })
+ .checked(false)
+Radio({ value: 'Radio2', group: 'radioGroup' })
+ .checked(true)
+```
+
+
+
+
+
+## Adding Events
+
+The **\** component supports the [universal events](../reference/arkui-ts/ts-universal-events-click.md). In addition, it can be bound to the **onChange** event so that it responds with custom behavior after being selected.
+
+
+
+```ts
+ Radio({ value: 'Radio1', group: 'radioGroup' })
+ .onChange((isChecked: boolean) => {
+ if(isChecked) {
+ // Operation
+ }
+ })
+ Radio({ value: 'Radio2', group: 'radioGroup' })
+ .onChange((isChecked: boolean) => {
+ if(isChecked) {
+ // Operation
+ }
+ })
+```
+
+
+## Example Scenario
+
+In this example, the **\** components are used to switch between sound modes.
+
+
+```ts
+// xxx.ets
+import promptAction from '@ohos.promptAction';
+@Entry
+@Component
+struct RadioExample {
+ build() {
+ Row() {
+ Column() {
+ Radio({ value: 'Radio1', group: 'radioGroup' }).checked(true)
+ .height(50)
+ .width(50)
+ .onChange((isChecked: boolean) => {
+ if(isChecked) {
+ // Switch to the ringing mode.
+ promptAction.showToast({ message: 'Ringing mode.' })
+ }
+ })
+ Text('Ringing')
+ }
+ Column() {
+ Radio({ value: 'Radio2', group: 'radioGroup' })
+ .height(50)
+ .width(50)
+ .onChange((isChecked: boolean) => {
+ if(isChecked) {
+ // Switch to the vibration mode.
+ promptAction.showToast({ message: 'Vibration mode.' })
+ }
+ })
+ Text('Vibration')
+ }
+ Column() {
+ Radio({ value: 'Radio3', group: 'radioGroup' })
+ .height(50)
+ .width(50)
+ .onChange((isChecked: boolean) => {
+ if(isChecked) {
+ // Switch to the silent mode.
+ promptAction.showToast({ message: 'Silent mode.' })
+ }
+ })
+ Text('Silent')
+ }
+ }.height('100%').width('100%').justifyContent(FlexAlign.Center)
+ }
+}
+```
+
+
+
diff --git a/en/application-dev/ui/arkts-common-components-switch.md b/en/application-dev/ui/arkts-common-components-switch.md
new file mode 100644
index 0000000000000000000000000000000000000000..9a0b8592315f876c7171b97eff95ae805fe9fdd9
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-switch.md
@@ -0,0 +1,153 @@
+# Toggle
+
+
+The **\** component provides a clickable element in the check box, button, or switch type, typically used to switch between two states. For details, see [Toggle](../reference/arkui-ts/ts-basic-components-toggle.md).
+
+
+## Creating a Toggle
+
+You can create a toggle by calling the following API:
+
+
+
+```ts
+Toggle(options: { type: ToggleType, isOn?: boolean })
+```
+
+
+Creates a toggle. In this API, **ToggleType** indicates the toggle type, which can be **Button**, **Checkbox**, or **Switch**, and **isOn** specifies whether the toggle is turned on. The API can be called in either of the following ways:
+
+
+- Create a toggle that does not contain child components.
+ This can be achieved by calling the API with **ToggleType** set to **Checkbox** or **Switch**.
+
+
+ ```ts
+ Toggle({ type: ToggleType.Checkbox, isOn: false })
+ Toggle({ type: ToggleType.Checkbox, isOn: true })
+ ```
+
+ 
+
+
+ ```ts
+ Toggle({ type: ToggleType.Switch, isOn: false })
+ Toggle({ type: ToggleType.Switch, isOn: true })
+ ```
+
+ 
+
+
+- Create a toggle that contains child components.
+ This can be achieved by calling the API with **ToggleType** set to **Button**. If the child component has text set, the text content is displayed inside the button.
+
+
+ ```ts
+ Toggle({ type: ToggleType.Button, isOn: false }) {
+ Text('status button')
+ .fontColor('#182431')
+ .fontSize(12)
+ }.width(100)
+ Toggle({ type: ToggleType.Button, isOn: true }) {
+ Text('status button')
+ .fontColor('#182431')
+ .fontSize(12)
+ }.width(100)
+ ```
+
+ 
+
+
+## Setting Styles
+
+- Use the **selectedColor** attribute to set the background color of the toggle for when it is turned on.
+
+ ```ts
+ Toggle({ type: ToggleType.Button, isOn: true }) {
+ Text('status button')
+ .fontColor('#182431')
+ .fontSize(12)
+ }.width(100).selectedColor(Color.Pink)
+ Toggle({ type: ToggleType.Checkbox, isOn: true })
+ .selectedColor(Color.Pink)
+ Toggle({ type: ToggleType.Switch, isOn: true })
+ .selectedColor(Color.Pink)
+ ```
+
+ 
+
+- Use the **switchPointColor** attribute to set the color of the circular slider. This attribute is valid only when **type** of the toggle is set to **ToggleType.Switch**.
+
+ ```ts
+ Toggle({ type: ToggleType.Switch, isOn: false })
+ .switchPointColor(Color.Pink)
+ Toggle({ type: ToggleType.Switch, isOn: true })
+ .switchPointColor(Color.Pink)
+ ```
+
+ 
+
+
+## Adding Events
+
+The **\** component supports the [universal events](../reference/arkui-ts/ts-universal-events-click.md). In addition, it can be bound to the **onChange** event so that it responds with custom behavior after being turned on or off.
+
+
+```ts
+Toggle({ type: ToggleType.Switch, isOn: false })
+ .onChange((isOn: boolean) => {
+ if(isOn) {
+ // Operation
+ }
+ })
+```
+
+
+## Example Scenario
+
+In this example, the **\** component is used to enable or disable Bluetooth.
+
+
+
+```ts
+// xxx.ets
+import prompt from '@ohos.promptAction';
+@Entry
+@Component
+struct ToggleExample {
+ build() {
+ Column() {
+ Row() {
+ Text("Bluetooth Mode")
+ .height(50)
+ .fontSize(16)
+ }
+ Row() {
+ Text("Bluetooth")
+ .height(50)
+ .padding({left: 10})
+ .fontSize(16)
+ .textAlign(TextAlign.Start)
+ .backgroundColor(0xFFFFFF)
+ Toggle({ type: ToggleType.Switch })
+ .margin({left: 200, right: 10})
+ .onChange((isOn: boolean) => {
+ if(isOn) {
+ promptAction.showToast({ message: 'Bluetooth is on.' })
+ } else {
+ promptAction.showToast({ message: 'Bluetooth is off.' })
+ }
+ })
+ }
+ .backgroundColor(0xFFFFFF)
+ }
+ .padding(10)
+ .backgroundColor(0xDCDCDC)
+ .width('100%')
+ .height('100%')
+ }
+}
+```
+
+
+
diff --git a/en/application-dev/ui/arkts-common-components-text-display.md b/en/application-dev/ui/arkts-common-components-text-display.md
new file mode 100644
index 0000000000000000000000000000000000000000..f630b0caf6e6e2e98d4557c1dbf58bd5984ca06e
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-text-display.md
@@ -0,0 +1,421 @@
+# Text Display
+
+
+The **\** component is used to display a piece of textual information. For details, see [Text](../reference/arkui-ts/ts-basic-components-text.md).
+
+
+## Creating Text
+
+You can create text in either of the following ways:
+
+
+- Entering strings
+
+ ```ts
+ Text ('I am a piece of text')
+ ```
+
+
+
+
+
+- Referencing Resource objects
+ You can use **$r** to create a **Resource** object to reference resources in **/resources/base/element/string.json**.
+
+
+ ```ts
+ Text($r('app.string.module_desc'))
+ .baselineOffset(0)
+ .fontSize(30)
+ .border({ width: 1 })
+ .padding(10)
+ .width(300)
+ ```
+
+ 
+
+
+## Adding Child Components
+
+The **\** component accepts \<[Span](../reference/arkui-ts/ts-basic-components-span.md)> as its child component. You can add one or more **\** child components to a **\** component to display a piece of information, such as the product description and statement of commitment.
+
+- Creating a \ Component
+ The **\** component works only when included in a **\** component. If both the **\** and **\** components have text configured, the text of the **\** overwrites that of the **\** component.
+
+
+ ```ts
+ Text (' I'm Text') {
+ Span (' I'm Span')
+ }
+ .padding(10)
+ .borderWidth(1)
+ ```
+
+ 
+
+- Set the text decorative line.
+ Use the **decoration** attribute to set the style and color of the text decorative line.
+
+
+ ```ts
+ Text() {
+ Span('I'm Span1,') .fontSize (16).fontColor (Color.Grey)
+ .decoration({ type: TextDecorationType.LineThrough, color: Color.Red })
+ Span('I'm Span2').fontColor (Color.Blue).fontSize (16)
+ .fontStyle(FontStyle.Italic)
+ .decoration({ type: TextDecorationType.Underline, color: Color.Black })
+ Span('I'm Span3').fontSize(16).fontColor(Color.Grey)
+ .decoration({ type: TextDecorationType.Overline, color: Color.Green })
+ }
+ .borderWidth(1)
+ .padding(10)
+ ```
+
+ 
+
+- Use the **textCase** attribute to set the text case.
+
+ ```ts
+ Text() {
+ Span('I am Upper-span').fontSize(12)
+ .textCase(TextCase.UpperCase)
+ }
+ .borderWidth(1)
+ .padding(10)
+ ```
+
+ 
+
+- Adding Events
+ The **\** component does not have size information. Therefore, only the **onClick** event is supported.
+
+
+ ```ts
+ Text() {
+ Span('I am Upper-span').fontSize(12)
+ .textCase(TextCase.UpperCase)
+ .onClick(()=>{
+ console.info (' I'm Span - onClick')
+ })
+ }
+ ```
+
+
+## Setting Styles
+
+- Use the **textAlign** attribute to set the alignment mode of text.
+
+ ```ts
+ Text('Left aligned')
+ .width(300)
+ .textAlign(TextAlign.Start)
+ .border({ width: 1 })
+ .padding(10)
+ Text ('Center aligned')
+ .width(300)
+ .textAlign(TextAlign.Center)
+ .border({ width: 1 })
+ .padding(10)
+ Text('Right aligned')
+ .width(300)
+ .textAlign(TextAlign.End)
+ .border({ width: 1 })
+ .padding(10)
+ ```
+
+ 
+
+- Use the **textOverflow** attribute to set the display mode for when the text is too long. This attribute must be used together with **maxLines**. By default, the text is automatically folded.
+
+ ```ts
+ Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content. This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content.')
+ .width(250)
+ .textOverflow({ overflow: TextOverflow.None })
+ .maxLines(1)
+ .fontSize(12)
+ .border({ width: 1 }).padding(10)
+ Text('I am extra long text, with an ellipse displayed for any excess.')
+ .width(250)
+ .textOverflow({ overflow: TextOverflow.Ellipsis })
+ .maxLines(1)
+ .fontSize(12)
+ .border({ width: 1 }).padding(10)
+ ```
+
+ 
+
+ 
+
+- Use the **lineHeight** attribute to set the text line height.
+
+ ```ts
+ Text('This is the text with the line height set. This is the text with the line height set.')
+ .width(300).fontSize(12).border({ width: 1 }).padding(10)
+ Text('This is the text with the line height set. This is the text with the line height set.')
+ .width(300).fontSize(12).border({ width: 1 }).padding(10)
+ .lineHeight(20)
+ ```
+
+ 
+
+- Use the **decoration** attribute to set the style and color of the text decorative line.
+
+ ```ts
+ Text('This is the text')
+ .decoration({
+ type: TextDecorationType.LineThrough,
+ color: Color.Red
+ })
+ .borderWidth(1).padding(10).margin(5)
+ Text('This is the text')
+ .decoration({
+ type: TextDecorationType.Overline,
+ color: Color.Red
+ })
+ .borderWidth(1).padding(10).margin(5)
+ Text('This is the text')
+ .decoration({
+ type: TextDecorationType.Underline,
+ color: Color.Red
+ })
+ .borderWidth(1).padding(10).margin(5)
+ ```
+
+ 
+
+- Use the **baselineOffset** attribute to set the baseline offset of the text.
+
+ ```ts
+ Text('This is the text content with baselineOffset 0.')
+ .baselineOffset(0)
+ .fontSize(12)
+ .border({ width: 1 })
+ .padding(10)
+ .width('100%')
+ .margin(5)
+ Text('This is the text content with baselineOffset 30.')
+ .baselineOffset(30)
+ .fontSize(12)
+ .border({ width: 1 })
+ .padding(10)
+ .width('100%')
+ .margin(5)
+
+ Text('This is the text content with baselineOffset -20.')
+ .baselineOffset(-20)
+ .fontSize(12)
+ .border({ width: 1 })
+ .padding(10)
+ .width('100%')
+ .margin(5)
+ ```
+
+ 
+
+- Use the **letterSpacing** attribute to set the letter spacing.
+
+ ```ts
+ Text('This is the text content with letterSpacing 0.')
+ .letterSpacing(0)
+ .fontSize(12)
+ .border({ width: 1 })
+ .padding(10)
+ .width('100%')
+ .margin(5)
+ Text('This is the text content with letterSpacing 3.')
+ .letterSpacing(3)
+ .fontSize(12)
+ .border({ width: 1 })
+ .padding(10)
+ .width('100%')
+ .margin(5)
+ Text('This is the text content with letterSpacing -1.')
+ .letterSpacing(-1)
+ .fontSize(12)
+ .border({ width: 1 })
+ .padding(10)
+ .width('100%')
+ .margin(5)
+ ```
+
+ 
+
+- Use the **minFontSize** and **maxFontSize** attributes to set the minimum and maximum font size, respectively. For the settings to take effect, these attributes must be used together with **maxLines** or layout constraint settings.
+
+ ```ts
+ Text('My maximum font size is 30, minimum font size is 5, width is 250, and maximum number of lines is 1')
+ .width(250)
+ .maxLines(1)
+ .maxFontSize(30)
+ .minFontSize(5)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+ Text('My maximum font size is 30, minimum font size is 5, width is 250, and maximum number of lines is 2')
+ .width(250)
+ .maxLines(2)
+ .maxFontSize(30)
+ .minFontSize(5)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+ Text('My maximum font size is 30, minimum font size is 15, width is 250, and line height is 50')
+ .width(250)
+ .height(50)
+ .maxFontSize(30)
+ .minFontSize(15)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+ Text('My maximum font size is 30, minimum font size is 15, width is 250, and line height is 100')
+ .width(250)
+ .height(100)
+ .maxFontSize(30)
+ .minFontSize(15)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+ ```
+
+ 
+
+- Use the **textCase** attribute to set the text case.
+
+ ```ts
+ Text('This is the text content with textCase set to Normal.')
+ .textCase(TextCase.Normal)
+ .padding(10)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+
+ // The text is displayed in lowercase.
+ Text('This is the text content with textCase set to LowerCase.')
+ .textCase(TextCase.LowerCase)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+
+ // The text is displayed in uppercase.
+ Text('This is the text content with textCase set to UpperCase.')
+ .textCase(TextCase.UpperCase)
+ .border({ width: 1 })
+ .padding(10)
+ .margin(5)
+ ```
+
+ 
+
+- Use the **copyOption** attribute to set whether copy and paste is allowed.
+
+ ```ts
+ Text("This text is copyable")
+ .fontSize(30)
+ .copyOption(CopyOptions.InApp)
+ ```
+
+ 
+
+
+## Adding Events
+
+The **\** component supports the [universal events](../reference/arkui-ts/ts-universal-events-click.md). It can be bound to the **onClick**, **onTouch**, or other events to respond to user operations.
+
+
+```ts
+Text ('Click Me')
+ .onClick(()=>{
+ console.info('I am the response to the click event');
+ })
+```
+
+
+## Example Scenario
+
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct TextExample {
+ build() {
+ Column() {
+ Row() {
+ Text("1").fontSize(14).fontColor(Color.Red).margin({ left: 10, right: 10 })
+ Text("I am entry 1")
+ .fontSize(12)
+ .fontColor(Color.Blue)
+ .maxLines(1)
+ .textOverflow({ overflow: TextOverflow.Ellipsis })
+ .fontWeight(300)
+ Text ("Top Hit")
+ .margin({ left: 6 })
+ .textAlign(TextAlign.Center)
+ .fontSize(10)
+ .fontColor(Color.White)
+ .fontWeight(600)
+ .backgroundColor(0x770100)
+ .borderRadius(5)
+ .width(15)
+ .height(14)
+ }.width('100%').margin(5)
+
+ Row() {
+ Text("2").fontSize(14).fontColor(Color.Red).margin({ left: 10, right: 10 })
+ Text("I am entry 2")
+ .fontSize(12)
+ .fontColor(Color.Blue)
+ .fontWeight(300)
+ .constraintSize({ maxWidth: 200 })
+ .maxLines(1)
+ .textOverflow({ overflow: TextOverflow.Ellipsis })
+ Text ("Hot")
+ .margin({ left: 6 })
+ .textAlign(TextAlign.Center)
+ .fontSize(10)
+ .fontColor(Color.White)
+ .fontWeight(600)
+ .backgroundColor(0xCC5500)
+ .borderRadius(5)
+ .width(15)
+ .height(14)
+ }.width('100%').margin(5)
+
+ Row() {
+ Text("3").fontSize(14).fontColor(Color.Orange).margin({ left: 10, right: 10 })
+ Text("I am entry 3")
+ .fontSize(12)
+ .fontColor(Color.Blue)
+ .fontWeight(300)
+ .maxLines(1)
+ .constraintSize({ maxWidth: 200 })
+ .textOverflow({ overflow: TextOverflow.Ellipsis })
+ Text ("Hot")
+ .margin({ left: 6 })
+ .textAlign(TextAlign.Center)
+ .fontSize(10)
+ .fontColor(Color.White)
+ .fontWeight(600)
+ .backgroundColor(0xCC5500)
+ .borderRadius(5)
+ .width(15)
+ .height(14)
+ }.width('100%').margin(5)
+
+ Row() {
+ Text("4").fontSize(14).fontColor(Color.Grey).margin({ left: 10, right: 10 })
+ Text("I am entry 4")
+ .fontSize(12)
+ .fontColor(Color.Blue)
+ .fontWeight(300)
+ .constraintSize({ maxWidth: 200 })
+ .maxLines(1)
+ .textOverflow({ overflow: TextOverflow.Ellipsis })
+ }.width('100%').margin(5)
+ }.width('100%')
+ }
+}
+
+```
+
+
diff --git a/en/application-dev/ui/arkts-common-components-text-input.md b/en/application-dev/ui/arkts-common-components-text-input.md
new file mode 100644
index 0000000000000000000000000000000000000000..0d7f8ec2f431bc5d171a40903fd752b3da2ab139
--- /dev/null
+++ b/en/application-dev/ui/arkts-common-components-text-input.md
@@ -0,0 +1,151 @@
+# Text Input
+
+
+The **\** and **\