From c616179ed9a803a90494db6248170c3a7e6b57ed Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Sat, 6 May 2023 16:53:18 +0800 Subject: [PATCH] Update docs (17050) Signed-off-by: ester.zhou --- en/application-dev/quick-start/Readme-EN.md | 48 +- ...s-application-state-management-overview.md | 13 + .../quick-start/arkts-appstorage.md | 203 ++++ .../arkts-basic-syntax-overview.md | 40 + .../quick-start/arkts-basic-ui-description.md | 205 ---- .../quick-start/arkts-builder.md | 130 ++ .../quick-start/arkts-builderparam.md | 210 ++++ .../arkts-create-custom-components.md | 380 ++++++ .../arkts-declarative-ui-description.md | 172 +++ .../arkts-dynamic-ui-elememt-building.md | 385 ------ .../quick-start/arkts-environment.md | 72 ++ .../quick-start/arkts-extend.md | 177 +++ .../quick-start/arkts-get-started.md | 25 +- en/application-dev/quick-start/arkts-link.md | 186 +++ .../quick-start/arkts-localstorage.md | 425 +++++++ .../arkts-observed-and-objectlink.md | 383 ++++++ ...kts-other-state-mgmt-functions-overview.md | 9 + .../arkts-page-custom-components-lifecycle.md | 186 +++ .../quick-start/arkts-persiststorage.md | 114 ++ en/application-dev/quick-start/arkts-prop.md | 367 ++++++ .../quick-start/arkts-provide-and-consume.md | 172 +++ .../arkts-rendering-control-foreach.md | 344 ++++++ .../arkts-rendering-control-ifelse.md | 229 ++++ .../arkts-rendering-control-lazyforeach.md | 220 ++++ .../arkts-rendering-control-overview.md | 4 + .../quick-start/arkts-rendering-control.md | 284 ----- .../arkts-restrictions-and-extensions.md | 257 ---- .../arkts-state-management-overview.md | 125 ++ .../arkts-state-mgmt-application-level.md | 274 ----- .../quick-start/arkts-state-mgmt-concepts.md | 34 - .../arkts-state-mgmt-page-level.md | 521 -------- en/application-dev/quick-start/arkts-state.md | 261 ++++ .../quick-start/arkts-statestyles.md | 128 ++ en/application-dev/quick-start/arkts-style.md | 104 ++ .../quick-start/arkts-two-way-sync.md | 47 + en/application-dev/quick-start/arkts-watch.md | 175 +++ .../figures/Video_2023-03-06_152548.gif | Bin 0 -> 128074 bytes .../figures/Video_2023-03-17_120758.gif | Bin 0 -> 38726 bytes .../figures/Video_2023-03-17_144605.gif | Bin 0 -> 164609 bytes .../figures/Video_2023-03-17_144824.gif | Bin 0 -> 66965 bytes .../figures/arkts-basic-grammar.png | Bin 0 -> 79771 bytes .../figures/en-us_image_0000001501936014.png | Bin 0 -> 18226 bytes .../figures/en-us_image_0000001501938718.png | Bin 0 -> 18097 bytes .../figures/en-us_image_0000001502091796.png | Bin 0 -> 17253 bytes .../figures/en-us_image_0000001502092556.png | Bin 0 -> 16433 bytes .../figures/en-us_image_0000001502094666.png | Bin 0 -> 3712 bytes .../figures/en-us_image_0000001502255262.png | Bin 0 -> 15254 bytes .../figures/en-us_image_0000001502372786.png | Bin 0 -> 27033 bytes .../figures/en-us_image_0000001502704640.png | Bin 0 -> 59942 bytes .../figures/en-us_image_0000001552614217.png | Bin 0 -> 10079 bytes .../figures/en-us_image_0000001552855957.png | Bin 0 -> 18247 bytes .../figures/en-us_image_0000001552972029.png | Bin 0 -> 10481 bytes .../figures/en-us_image_0000001552978157.png | Bin 0 -> 18377 bytes .../figures/en-us_image_0000001553348833.png | Bin 0 -> 34983 bytes .../figures/en-us_image_0000001562352677.png | Bin 0 -> 3768 bytes .../resource-categories-and-access.md | 6 +- .../figures/en-us_image_0000001511900496.png | Bin 0 -> 6120 bytes .../figures/en-us_image_0000001563060749.png | Bin 0 -> 3774 bytes .../arkui-ts/ts-custom-component-lifecycle.md | 204 ++++ en/application-dev/ui/Readme-EN.md | 92 +- .../ui/arkts-animation-overview.md | 27 + .../ui/arkts-common-components-button.md | 261 ++++ .../arkts-common-components-custom-dialog.md | 100 ++ ...ts-common-components-progress-indicator.md | 135 +++ .../arkts-common-components-radio-button.md | 106 ++ .../ui/arkts-common-components-switch.md | 153 +++ .../arkts-common-components-text-display.md | 421 +++++++ .../ui/arkts-common-components-text-input.md | 151 +++ .../arkts-common-components-video-player.md | 244 ++++ .../ui/arkts-common-components-xcomponent.md | 299 +++++ .../arkts-common-events-device-input-event.md | 375 ++++++ .../ui/arkts-common-events-focus-event.md | 1061 +++++++++++++++++ .../arkts-common-events-touch-screen-event.md | 315 +++++ .../arkts-drawing-customization-on-canvas.md | 346 ++++++ en/application-dev/ui/arkts-event-overview.md | 23 + .../ui/arkts-geometric-shape-drawing.md | 288 +++++ .../ui/arkts-gesture-events-binding.md | 125 ++ .../arkts-gesture-events-combined-gestures.md | 202 ++++ .../ui/arkts-gesture-events-single-gesture.md | 377 ++++++ .../ui/arkts-graphics-display.md | 327 +++++ .../arkts-layout-development-create-grid.md | 339 ++++++ .../arkts-layout-development-create-list.md | 841 +++++++++++++ ...arkts-layout-development-create-looping.md | 318 +++++ .../arkts-layout-development-flex-layout.md | 626 ++++++++++ .../arkts-layout-development-grid-layout.md | 481 ++++++++ .../ui/arkts-layout-development-linear.md | 629 ++++++++++ .../arkts-layout-development-media-query.md | 263 ++++ .../ui/arkts-layout-development-overview.md | 79 ++ ...ts-layout-development-performance-boost.md | 62 + ...rkts-layout-development-relative-layout.md | 158 +++ .../arkts-layout-development-stack-layout.md | 135 +++ .../ui/arkts-layout-update-animation.md | 270 +++++ .../ui/arkts-navigation-navigation.md | 202 ++++ .../ui/arkts-navigation-tabs.md | 378 ++++++ .../ui/arkts-page-transition-animation.md | 361 ++++++ ...-performance-improvement-recommendation.md | 318 +++++ .../arkts-popup-and-menu-components-menu.md | 111 ++ .../arkts-popup-and-menu-components-popup.md | 158 +++ en/application-dev/ui/arkts-routing.md | 326 +++++ .../ui/arkts-spring-animation.md | 166 +++ ...s-transition-animation-within-component.md | 256 ++++ .../ui/arkts-ui-development-overview.md | 95 ++ en/application-dev/ui/arkts-zoom-animation.md | 98 ++ en/application-dev/ui/figures/Picture 1.png | Bin 0 -> 40406 bytes .../ui/figures/arkts-basic-grammar.png | Bin 0 -> 79771 bytes en/application-dev/ui/figures/creation-2.jpg | Bin 0 -> 2723 bytes .../figures/en-us_image_0000001511580836.png | Bin 0 -> 10763 bytes .../figures/en-us_image_0000001511740444.png | Bin 0 -> 14891 bytes .../figures/en-us_image_0000001511900400.png | Bin 0 -> 7066 bytes .../figures/en-us_image_0000001511900428.png | Bin 0 -> 28059 bytes .../figures/en-us_image_0000001562700385.png | Bin 0 -> 25824 bytes .../figures/en-us_image_0000001562820753.png | Bin 0 -> 20380 bytes .../figures/en-us_image_0000001562820761.png | Bin 0 -> 5583 bytes .../figures/en-us_image_0000001563060653.png | Bin 0 -> 23596 bytes .../ui/figures/horizontal-swiping.PNG | Bin 0 -> 35361 bytes en/application-dev/ui/figures/onDestroy.png | Bin 0 -> 25366 bytes en/application-dev/ui/figures/onLoad.png | Bin 0 -> 26121 bytes en/application-dev/ui/figures/scenario-1.jpg | Bin 0 -> 3977 bytes en/application-dev/ui/figures/scenario-2.jpg | Bin 0 -> 3432 bytes .../ui/figures/screenshot_20230223_141141.png | Bin 0 -> 2178 bytes en/application-dev/ui/figures/untitled.png | Bin 0 -> 14976 bytes .../ui/figures/vertical-swiping.PNG | Bin 0 -> 34905 bytes .../ui/figures/viewport (2).jpg | Bin 0 -> 4175 bytes .../ui/figures/viewport (3).jpg | Bin 0 -> 4259 bytes .../ui/js-framework-multiple-languages.md | 2 +- en/application-dev/ui/ui-js-overview.md | 2 +- en/application-dev/ui/ui-ts-layout-flex.md | 4 +- 127 files changed, 17195 insertions(+), 2030 deletions(-) create mode 100644 en/application-dev/quick-start/arkts-application-state-management-overview.md create mode 100644 en/application-dev/quick-start/arkts-appstorage.md create mode 100644 en/application-dev/quick-start/arkts-basic-syntax-overview.md delete mode 100644 en/application-dev/quick-start/arkts-basic-ui-description.md create mode 100644 en/application-dev/quick-start/arkts-builder.md create mode 100644 en/application-dev/quick-start/arkts-builderparam.md create mode 100644 en/application-dev/quick-start/arkts-create-custom-components.md create mode 100644 en/application-dev/quick-start/arkts-declarative-ui-description.md delete mode 100644 en/application-dev/quick-start/arkts-dynamic-ui-elememt-building.md create mode 100644 en/application-dev/quick-start/arkts-environment.md create mode 100644 en/application-dev/quick-start/arkts-extend.md create mode 100644 en/application-dev/quick-start/arkts-link.md create mode 100644 en/application-dev/quick-start/arkts-localstorage.md create mode 100644 en/application-dev/quick-start/arkts-observed-and-objectlink.md create mode 100644 en/application-dev/quick-start/arkts-other-state-mgmt-functions-overview.md create mode 100644 en/application-dev/quick-start/arkts-page-custom-components-lifecycle.md create mode 100644 en/application-dev/quick-start/arkts-persiststorage.md create mode 100644 en/application-dev/quick-start/arkts-prop.md create mode 100644 en/application-dev/quick-start/arkts-provide-and-consume.md create mode 100644 en/application-dev/quick-start/arkts-rendering-control-foreach.md create mode 100644 en/application-dev/quick-start/arkts-rendering-control-ifelse.md create mode 100644 en/application-dev/quick-start/arkts-rendering-control-lazyforeach.md create mode 100644 en/application-dev/quick-start/arkts-rendering-control-overview.md delete mode 100644 en/application-dev/quick-start/arkts-rendering-control.md delete mode 100644 en/application-dev/quick-start/arkts-restrictions-and-extensions.md create mode 100644 en/application-dev/quick-start/arkts-state-management-overview.md delete mode 100644 en/application-dev/quick-start/arkts-state-mgmt-application-level.md delete mode 100644 en/application-dev/quick-start/arkts-state-mgmt-concepts.md delete mode 100644 en/application-dev/quick-start/arkts-state-mgmt-page-level.md create mode 100644 en/application-dev/quick-start/arkts-state.md create mode 100644 en/application-dev/quick-start/arkts-statestyles.md create mode 100644 en/application-dev/quick-start/arkts-style.md create mode 100644 en/application-dev/quick-start/arkts-two-way-sync.md create mode 100644 en/application-dev/quick-start/arkts-watch.md create mode 100644 en/application-dev/quick-start/figures/Video_2023-03-06_152548.gif create mode 100644 en/application-dev/quick-start/figures/Video_2023-03-17_120758.gif create mode 100644 en/application-dev/quick-start/figures/Video_2023-03-17_144605.gif create mode 100644 en/application-dev/quick-start/figures/Video_2023-03-17_144824.gif create mode 100644 en/application-dev/quick-start/figures/arkts-basic-grammar.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001501936014.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001501938718.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001502091796.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001502092556.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001502094666.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001502255262.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001502372786.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001502704640.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001552614217.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001552855957.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001552972029.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001552978157.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001553348833.png create mode 100644 en/application-dev/quick-start/figures/en-us_image_0000001562352677.png create mode 100644 en/application-dev/reference/arkui-ts/figures/en-us_image_0000001511900496.png create mode 100644 en/application-dev/reference/arkui-ts/figures/en-us_image_0000001563060749.png create mode 100644 en/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md create mode 100644 en/application-dev/ui/arkts-animation-overview.md create mode 100644 en/application-dev/ui/arkts-common-components-button.md create mode 100644 en/application-dev/ui/arkts-common-components-custom-dialog.md create mode 100644 en/application-dev/ui/arkts-common-components-progress-indicator.md create mode 100644 en/application-dev/ui/arkts-common-components-radio-button.md create mode 100644 en/application-dev/ui/arkts-common-components-switch.md create mode 100644 en/application-dev/ui/arkts-common-components-text-display.md create mode 100644 en/application-dev/ui/arkts-common-components-text-input.md create mode 100644 en/application-dev/ui/arkts-common-components-video-player.md create mode 100644 en/application-dev/ui/arkts-common-components-xcomponent.md create mode 100644 en/application-dev/ui/arkts-common-events-device-input-event.md create mode 100644 en/application-dev/ui/arkts-common-events-focus-event.md create mode 100644 en/application-dev/ui/arkts-common-events-touch-screen-event.md create mode 100644 en/application-dev/ui/arkts-drawing-customization-on-canvas.md create mode 100644 en/application-dev/ui/arkts-event-overview.md create mode 100644 en/application-dev/ui/arkts-geometric-shape-drawing.md create mode 100644 en/application-dev/ui/arkts-gesture-events-binding.md create mode 100644 en/application-dev/ui/arkts-gesture-events-combined-gestures.md create mode 100644 en/application-dev/ui/arkts-gesture-events-single-gesture.md create mode 100644 en/application-dev/ui/arkts-graphics-display.md create mode 100644 en/application-dev/ui/arkts-layout-development-create-grid.md create mode 100644 en/application-dev/ui/arkts-layout-development-create-list.md create mode 100644 en/application-dev/ui/arkts-layout-development-create-looping.md create mode 100644 en/application-dev/ui/arkts-layout-development-flex-layout.md create mode 100644 en/application-dev/ui/arkts-layout-development-grid-layout.md create mode 100644 en/application-dev/ui/arkts-layout-development-linear.md create mode 100644 en/application-dev/ui/arkts-layout-development-media-query.md create mode 100644 en/application-dev/ui/arkts-layout-development-overview.md create mode 100644 en/application-dev/ui/arkts-layout-development-performance-boost.md create mode 100644 en/application-dev/ui/arkts-layout-development-relative-layout.md create mode 100644 en/application-dev/ui/arkts-layout-development-stack-layout.md create mode 100644 en/application-dev/ui/arkts-layout-update-animation.md create mode 100644 en/application-dev/ui/arkts-navigation-navigation.md create mode 100644 en/application-dev/ui/arkts-navigation-tabs.md create mode 100644 en/application-dev/ui/arkts-page-transition-animation.md create mode 100644 en/application-dev/ui/arkts-performance-improvement-recommendation.md create mode 100644 en/application-dev/ui/arkts-popup-and-menu-components-menu.md create mode 100644 en/application-dev/ui/arkts-popup-and-menu-components-popup.md create mode 100644 en/application-dev/ui/arkts-routing.md create mode 100644 en/application-dev/ui/arkts-spring-animation.md create mode 100644 en/application-dev/ui/arkts-transition-animation-within-component.md create mode 100644 en/application-dev/ui/arkts-ui-development-overview.md create mode 100644 en/application-dev/ui/arkts-zoom-animation.md create mode 100644 en/application-dev/ui/figures/Picture 1.png create mode 100644 en/application-dev/ui/figures/arkts-basic-grammar.png create mode 100644 en/application-dev/ui/figures/creation-2.jpg create mode 100644 en/application-dev/ui/figures/en-us_image_0000001511580836.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001511740444.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001511900400.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001511900428.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001562700385.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001562820753.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001562820761.png create mode 100644 en/application-dev/ui/figures/en-us_image_0000001563060653.png create mode 100644 en/application-dev/ui/figures/horizontal-swiping.PNG create mode 100644 en/application-dev/ui/figures/onDestroy.png create mode 100644 en/application-dev/ui/figures/onLoad.png create mode 100644 en/application-dev/ui/figures/scenario-1.jpg create mode 100644 en/application-dev/ui/figures/scenario-2.jpg create mode 100644 en/application-dev/ui/figures/screenshot_20230223_141141.png create mode 100644 en/application-dev/ui/figures/untitled.png create mode 100644 en/application-dev/ui/figures/vertical-swiping.PNG create mode 100644 en/application-dev/ui/figures/viewport (2).jpg create mode 100644 en/application-dev/ui/figures/viewport (3).jpg diff --git a/en/application-dev/quick-start/Readme-EN.md b/en/application-dev/quick-start/Readme-EN.md index a60e0f7ef7..b7d98534c9 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 0000000000..b481f79298 --- /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 0000000000..c5f6196fc6 --- /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).
The type must be specified and must be the same as the corresponding attribute in LocalStorage. **any** is not supported. The **undefined** and **null** values are not allowed.| +| Synchronization type | One-way: from the attribute in AppStorage to the component variable.
The component variable can be changed locally, but an update from AppStorage will overwrite local changes.| +| Initial value for the decorated variable | Mandatory. It is used as the default value for initialization if the attribute does not exist in AppStorage.| + + +### Variable Transfer/Access Rules + +| Transfer/Access | Description | +| ---------- | ---------------------------------------- | +| Initialization and update from the parent component| Forbidden.| +| Subnode initialization | Supported; can be used to initialize a n \@State, \@Link, \@Prop, or \@Provide decorated variable in the child component.| +| Access | None. | + + + **Figure 1** \@StorageProp initialization rule + + +![en-us_image_0000001552978157](figures/en-us_image_0000001552978157.png) + + +### Observed Changes and Behavior + +**Observed Changes** + + +- When the decorated variable is of the Boolean, string, or number type, its value change can be observed. + +- When the decorated variable is of the class or Object type, its value change and value changes of all its attributes, that is, the attributes that **Object.keys(observedObject)** returns. + +- When the decorated variable is of the array type, the addition, deletion, and updates of array items can be observed. + + +**Framework Behavior** + + +- When the value change of the \@StorageProp(key) decorated variable is observed, the change is not synchronized to the attribute with the give key value in AppStorage. + +- The value change of the \@StorageProp(key) decorated variable only applies to the private member variables of the current component, but not other variables bound to the key. + +- When the data decorated by \@StorageProp(key) is a state variable, the change of the data is not synchronized to AppStorage, but the owning custom component is re-rendered. + +- When the attribute with the given key in AppStorage is updated, the change is synchronized to all the \@StorageProp(key) decorated data, and the local changes of the data are overwritten. + + +## \@StorageLink + +\@StorageLink(key) creates a two-way data synchronization with the attribute with the given key in AppStorage. + +1. If a local change occurs, it is synchronized to AppStorage. + +2. Changes in AppStorage are synchronized to all attributes with the given key, including one-way bound variables (\@StorageProp decorated variables and one-way bound variables created through \@Prop), two-way bound variables (\@StorageLink decorated variables and two-way bound variables created through \@Link), and other instances (such as PersistentStorage). + + +### Rules of Use + +| \@StorageLink 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).
The type must be specified and must be the same as the corresponding attribute in AppStorage. **any** is not supported. The **undefined** and **null** values are not allowed.| +| Synchronization type | Two-way: from the attribute in AppStorage to the custom component variable and back| +| Initial value for the decorated variable | Mandatory. It is used as the default value for initialization if the attribute does not exist in AppStorage.| + + +### Variable Transfer/Access Rules + +| Transfer/Access | Description | +| ---------- | ---------------------------------------- | +| Initialization and update from the parent component| Forbidden. | +| Subnode initialization | Supported; can be used to initialize a regular variable or \@State, \@Link, \@Prop, or \@Provide decorated variable in the child component.| +| Access | None. | + + + **Figure 2** \@StorageLink initialization rule + + +![en-us_image_0000001501938718](figures/en-us_image_0000001501938718.png) + + +### Observed Changes and Behavior + +**Observed Changes** + + +- When the decorated variable is of the Boolean, string, or number type, its value change can be observed. + +- When the decorated variable is of the class or Object type, its value change and value changes of all its attributes, that is, the attributes that **Object.keys(observedObject)** returns. + +- When the decorated variable is of the array type, the addition, deletion, and updates of array items can be observed. + + +**Framework Behavior** + + +1. When the value change of the \@StorageLink(key) decorated variable is observed, the change is synchronized to the attribute with the give key value in AppStorage. + +2. Once the attribute with the given key in AppStorage is updated, all the data (including \@StorageLink and \@StorageProp decorated variables) bound to the attribute key is changed synchronously. + +3. When the data decorated by \@StorageLink(key) is a state variable, the change of the data is synchronized to AppStorage, and the owning custom component is re-rendered. + + +## Application Scenarios + + +### Example of Using AppStorage and LocalStorage from Application Logic + +Since AppStorage is a singleton, its APIs are all static ones. How these APIs work resembles the non-static APIs of LocalStorage. + + +```ts +AppStorage.SetOrCreate('PropA', 47); + +let storage: LocalStorage = new LocalStorage({ 'PropA': 17 }); +let propA: number = AppStorage.Get('PropA') // propA in AppStorage == 47, propA in LocalStorage == 17 +var link1: SubscribedAbstractProperty = 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 0000000000..59dd8e9e0e --- /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 + +![Video_2023-03-06_152548](figures/Video_2023-03-06_152548.gif) + + +In this example, the basic composition of ArkTS is as follows. + + + **Figure 2** Basic composition of ArkTS + +![arkts-basic-grammar](figures/arkts-basic-grammar.png) + + +- 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 **\