diff --git a/en/application-dev/reference/apis/development-intro.md b/en/application-dev/reference/apis/development-intro.md index 565bb231015c61926de2c4ddc868d473527ac4c6..c943b08d302ab654a8f7b5b2108212c99a30c1ad 100644 --- a/en/application-dev/reference/apis/development-intro.md +++ b/en/application-dev/reference/apis/development-intro.md @@ -29,19 +29,19 @@ A description regarding system APIs will be provided in the document. A common application is an application whose application type is **hos_normal_app** in the HarmonyAppProvision configuration file. **hos_normal_app** is the default value for project creation. The public SDK, which does not include system APIs, is provided as standard in DevEco Studio. To use the system APIs, you must: -- Switch the public SDK to the full SDK by following the instructions provided in [Guide to Switching to Full SDK] (../../quick-start/full-sdk-switch-guide.md). +- Switch the public SDK to the full SDK by following the instructions provided in [Guide to Switching to Full SDK](../../quick-start/full-sdk-switch-guide.md). - Change the value of **app-feature** in the HarmonyAppProvision configuration file to **hos_system_app**. For details, see [HarmonyAppProvision Configuration File](../../security/app-provision-structure.md). ## Permission Description -By default, applications can access limited system resources. However, in some cases, an application needs to access excess data (including personal data) and functions of the system or another application to implement extended functions. For details, see [Access Control Overview](../../security/accesstoken-overview.md). +By default, applications can access limited system resources. However, in some cases, an application needs to access excess data (including personal data) and functions of the system or another application to implement extended functions. For details, see [Access Control (Permission) Overview](../../security/accesstoken-overview.md). -To call APIs to access these resources, you must apply for the corresponding permissions by following the instructions provided in [Access Control Development](../../security/accesstoken-guidelines.md). +To call APIs to access these resources, you must apply for the corresponding permissions by following the instructions provided in [Applying for Permissions](../../security/accesstoken-guidelines.md). - If an application can call an API only after it has obtained a specific permission, the following description is provided for the API: "**Required permissions**: ohos.permission.xxxx" - If an application can call an API without any permission, no special description is provided. -To determine whether an application can request a specific permission, see [Permission Application and Use](../../security/accesstoken-overview.md#applying-for-and-using-a-permission). +To determine whether an application can request a specific permission, see [Applying for and Using a Permission](../../security/accesstoken-overview.md#applying-for-and-using-a-permission). ## System Capability Description diff --git a/en/application-dev/reference/arkui-ts/ts-appendix-enums.md b/en/application-dev/reference/arkui-ts/ts-appendix-enums.md index 02df27c18b45a96f6f409cf498a8b91b93c4641e..efbb568aca75ad50f8d51dd9baffda38199538d6 100644 --- a/en/application-dev/reference/arkui-ts/ts-appendix-enums.md +++ b/en/application-dev/reference/arkui-ts/ts-appendix-enums.md @@ -54,8 +54,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## TouchType -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | ------ | ------------------------------ | | Down | A finger is pressed. | @@ -65,8 +63,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## MouseButton -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | ------- | ---------------- | | Left | Left button on the mouse. | @@ -78,8 +74,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## MouseAction -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | ------- | -------------- | | Press | The mouse button is pressed.| @@ -109,9 +103,7 @@ Since API version 9, this API is supported in ArkTS widgets. ## AnimationStatus -Since API version 9, this API is supported in ArkTS widgets. - -| Name | Description | +| Name | Description | | ------- | ------------------ | | Initial | The animation is in the initial state. | | Running | The animation is being played.| @@ -120,9 +112,7 @@ Since API version 9, this API is supported in ArkTS widgets. ## FillMode -Since API version 9, this API is supported in ArkTS widgets. - -| Name | Description | +| Name | Description | | --------- | ------------------------------------------------------------ | | None | Before execution, the animation does not apply any styles to the target component. After execution, the animation restores the target component to its default state.| | Forwards | The target component retains the state set by the last keyframe encountered during execution of the animation. | @@ -142,8 +132,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## KeyType -Since API version 9, this API is supported in ArkTS widgets. - | Name| Description | | ---- | ---------- | | Down | The key is pressed.| @@ -151,8 +139,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## KeySource -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | -------- | -------------------- | | Unknown | Unknown input device. | @@ -172,8 +158,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## Week -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | -------- | ---------------------- | | Mon | Monday. | @@ -242,8 +226,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## RelateType -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | ------ | ------------------------------- | | FILL | The current child component is scaled to fill the parent component. | @@ -384,8 +366,6 @@ Since API version 9, this API is supported in ArkTS widgets. ## SharedTransitionEffectType -Since API version 9, this API is supported in ArkTS widgets. - | Name | Description | | ----------- | ---------- | | Static | The element position remains unchanged on the target page, and transition opacity can be configured. Currently, this effect is only valid in redirecting to the target page.| @@ -456,18 +436,14 @@ Since API version 9, this API is supported in ArkTS widgets. ## ResponseType8+ -Since API version 9, this API is supported in ArkTS widgets. - -| Name | Description | +| Name | Description | | ---------- | -------------------------- | | LongPress | The menu is displayed when the component is long-pressed. | | RightClick | The menu is displayed when the component is right-clicked.| ## HoverEffect8+ -Since API version 9, this API is supported in ArkTS widgets. - -| Name | Description | +| Name | Description | | --------- | ---------------------------- | | Auto | Default hover effect.| | Scale | Scale effect. | @@ -476,9 +452,7 @@ Since API version 9, this API is supported in ArkTS widgets. ## Placement8+ -Since API version 9, this API is supported in ArkTS widgets. - -| Name | Description | +| Name | Description | | ------------- | ------------------------------------------------------------ | | Left | The popup is on the left of the component, vertically aligned with the component on the left. | | Right | The popup is on the right of the component, vertically aligned with the component on the right. | @@ -505,9 +479,7 @@ Since API version 9, this API is supported in ArkTS widgets. ## HitTestMode9+ -Since API version 9, this API is supported in ArkTS widgets. - -| Name | Description | +| Name | Description | | ----------- | -------------------- | | Default | Both the node and its child node respond to the hit test of a touch event, but its sibling node is blocked from the hit test. | | Block | The node responds to the hit test of a touch event, but its child node and sibling node are blocked from the hit test. | 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 index 8ce1ba21e0a1d87817ff557e3544a799668b2565..8c0149ffd66fd3269d0bd28189a25e70f96cf89e 100644 --- a/en/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md +++ b/en/application-dev/reference/arkui-ts/ts-custom-component-lifecycle.md @@ -43,7 +43,7 @@ Invoked when a page is hidden. This callback is used in the routing process or s 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. +Invoked when a user clicks the back button. It works only for the custom components decorated by **@Entry**. ```ts diff --git a/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md b/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md index 5ee06b1002d15dbb13cc32181364e505f716ecb6..4c164070999d363b634dc618fa6660b33fbfe1ba 100644 --- a/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md +++ b/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md @@ -2268,7 +2268,7 @@ Draws the input [PixelMap](../apis/js-apis-image.md#pixelmap7) object on the can **Parameters** -| Parameters | Type | Mandatory | Default Value | Description | +| Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | --------------- | | sx | number | Yes | 0 | X-coordinate of the upper left corner of the output area.| | sy | number | Yes | 0 | Y-coordinate of the upper left corner of the output area.| diff --git a/en/application-dev/reference/arkui-ts/ts-state-management.md b/en/application-dev/reference/arkui-ts/ts-state-management.md index b5bbf02f094b27083e61c6d2fdcfed14da7f1b88..ea05b3c0f5f7b71cd3626d5317d3926159d55b91 100644 --- a/en/application-dev/reference/arkui-ts/ts-state-management.md +++ b/en/application-dev/reference/arkui-ts/ts-state-management.md @@ -1,238 +1,294 @@ # State Management with Application-level Variables -The state management module provides APIs for data storage, persistent data management, **Ability** data storage, and environment status required by applications. The APIs for **Ability** data storage are supported since API version 9. -> **NOTE** +The state management module provides data storage, persistent data management, UIAbility data storage, and environment state required by applications. + + +>**NOTE** > -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +>The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +The meanings of T and S in this topic are as follows: + + +| Type | Description | +| ---- | -------------------------------------- | +| T | Class, number, boolean, string, and arras of these types.| +| S | number, boolean, string. | + ## AppStorage + ### Link -Link(propName: string): any +static Link(propName: string): any + +Establishes two-way data binding with the given attribute (specified by **propName**) in AppStorage. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. -Establishes two-way data binding between an attribute and this **LocalStorage** instance. +Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the attribute. + +If the given attribute does not exist in AppStorage, **undefined** is returned. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Name of the target attribute.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------- | +| propName | string | Yes | Attribute name in AppStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Link | Returns two-way binding to this attribute if there is data with a given key. This means that attribute changes made by a variable or component will be synchronized to the **AppStorage**, and attribute changes made through the **AppStorage** will be synchronized to the variable or component.| +| Type | Description | +| ---- | ---------------------------------------- | +| any | Returns two-way bound data if specified attribute exists in AppStorage; returns **undefined** otherwise.| + ```ts -let simple = AppStorage.Link('simpleProp') +AppStorage.SetOrCreate('PropA', 47); +let linkToPropA1 = AppStorage.Link('PropA'); +let linkToPropA2 = AppStorage.Link('PropA'); // linkToPropA2.get() == 47 +linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 ``` + ### SetAndLink -SetAndLink\(propName: string, defaultValue: T): SubscribedAbstractProperty\ +static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> -Works in a way similar to the **Link** API. If the current key is stored in the **AppStorage**, the value corresponding to the key is returned. If the key has not been created, a **Link** instance corresponding to the default value is created and returned. +Works in a way similar to the **Link** API. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in AppStorage, and two-way bound data is returned. **Parameters** -| Name | Type | Mandatory | Description | -| ------------ | ------ | ---- | ----------- | -| propName | string | Yes | Target key.| -| defaultValue | T | Yes | Default value to set. | +| Name | Type | Mandatory | Description | +| ------------ | ------ | ---- | ---------------------------------------- | +| propName | string | Yes | Attribute name in AppStorage. | +| defaultValue | T | Yes | Default value used to initialize the attribute with the specified attribute name in AppStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Link | Returns the value corresponding to the key if the current key is stored in the **AppStorage**; creates and returns a **Link** instance corresponding to the default value if the key has not been created.| +| Type | Description | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<T> | Instance of **SubscribedAbstractProperty<T>** and two-way bound data of the given attribute in AppStorage| + ```ts -let simple = AppStorage.SetAndLink('simpleProp', 121) +AppStorage.SetOrCreate('PropA', 47); +let link1: SubscribedAbstractProperty = AppStorage.SetAndLink('PropB', 49); // Create PropB 49 +let link2: SubscribedAbstractProperty = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47 ``` + ### Prop -Prop(propName: string): any +static Prop(propName: string): any + +Establishes one-way data binding with the given attribute (specified by **propName**) in AppStorage. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist in AppStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to AppStorage. -Establishes one-way data binding with an attribute to update its status. +>**NOTE** +> Prop supports only simple types. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Target key.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------- | +| propName | string | Yes | Attribute name in AppStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Prop | Returns one-way binding to an attribute with a given key if the attribute exists; returns **undefined** otherwise. One-way binding means that attribute changes made through the **AppStorage** will be synchronized to the variable or component, but attribute changes made by the variable or component will not be synchronized to the **AppStorage**. This API returns immutable variables and is applicable to mutable and immutable state variables alike.| +| Type | Description | +| ---- | ---------------------------------------- | +| any | Returns one-way bound data if specified attribute exists in AppStorage; returns **undefined** otherwise.| + ```ts -let simple = AppStorage.Prop('simpleProp') +AppStorage.SetOrCreate('PropA', 47); +let prop1 = AppStorage.Prop('PropA'); +let prop2 = AppStorage.Prop('PropA'); +prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 ``` + ### SetAndProp -SetAndProp\(propName: string, defaultValue: S): SubscribedAbstractProperty\ +static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> -Works in a way similar to the **Prop** API. If the current key is stored in the **AppStorage**, the value corresponding to the key is returned. If the key has not been created, a **Prop** instance corresponding to the default value is created and returned. +Works in a way similar to the **Prop** API. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in AppStorage, and one-way bound data is returned. **Parameters** -| Name | Type | Mandatory | Description | -| ------------ | ------ | ---- | --------------- | -| propName | string | Yes | Key of the target key-value pair.| -| defaultValue | S | Yes | Default value to set. | +| Name | Type | Mandatory | Description | +| ------------ | ------ | ---- | ---------------------------------------- | +| propName | string | Yes | Attribute name in AppStorage. | +| defaultValue | S | Yes | Default value used to initialize the attribute with the specified attribute name in AppStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Prop | Returns the value corresponding to the key if the current key is stored in the **AppStorage**; creates and returns a **Prop** instance corresponding to the default value otherwise.| +| Type | Description | +| ----------------------------------- | --------------------------------------- | +| SubscribedAbstractProperty<S> | Instance of **SubscribedAbstractProperty<S>**.| + ```ts -let simple = AppStorage.SetAndProp('simpleProp', 121) +AppStorage.SetOrCreate('PropA', 47); +let prop: SubscribedAbstractProperty = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49 ``` + ### Has -Has(propName: string): boolean +static Has(propName: string): boolean -Checks whether the attribute corresponding to the specified key exists. +Checks whether the attribute with the specified attribute name exists in AppStorage. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ------- | -| propName | string | Yes | Key of the attribute.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------- | +| propName | string | Yes | Attribute name in AppStorage.| **Return value** -| Type | Description | -| ------- | ------------- | -| boolean | Returns whether the attribute exists.| +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **true** if the attribute with the specified attribute name exists in AppStorage; returns **false** otherwise.| + ```ts -let simple = AppStorage.Has('simpleProp') +AppStorage.Has('simpleProp'); ``` + ### Get -Get\(propName: string): T | undefined +static Get<T>(propName: string): T | undefined -Obtains the value of the specified key. +Obtains the attribute with the specified attribute name in AppStorage. If the attribute does not exist, **undefined** is returned. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Key of the value to obtain.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------- | +| propName | string | Yes | Attribute name in AppStorage.| **Return value** -| Type | Description | -| ----------------- | ------------- | -| T or undefined| Returns the attribute value if the attribute exists; returns **undefined** otherwise.| +| Type | Description | +| ------------------------ | ---------------------------------------- | +| T \| undefined | Returns the attribute with the specified attribute name in AppStorage; returns **undefined** if the attribute does not exist.| + ```ts -let simple = AppStorage.Get('simpleProp') +AppStorage.SetOrCreate('PropA', 47); +let value: number = AppStorage.Get('PropA'); // 47 ``` + ### Set -Set\(propName: string, newValue: T): boolean +static Set<T>(propName: string, newValue: T): boolean -Replaces the value of a saved key. +Sets the value for the attribute with the specified attribute name in AppStorage. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Key to set. | -| newValue | T | Yes | Value to set.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------------- | +| propName | string | Yes | Attribute name in AppStorage. | +| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| **Return value** -| Type | Description | -| ------- | ----------------------------------- | -| boolean | Returns **true** and the value if the key exists; returns **false** otherwise.| +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **true** if the operation is successful; return **false** if the attribute with the specified attribute name does not exist in AppStorage, or the value to set is **undefined** or **null**. | + ```ts -let simple = AppStorage.Set('simpleProp', 121) +AppStorage.SetOrCreate('PropA', 48); +let res: boolean = AppStorage.Set('PropA', 47) // true +let res1: boolean = AppStorage.Set('PropB', 47) // false ``` + ### SetOrCreate -SetOrCreate\(propName: string, newValue: T): void +static SetOrCreate<T>(propName: string, newValue: T): void -Creates or updates the value of the specified key. +Sets a new value for the attribute with the specified attribute name in AppStorage or, if the attribute does not exist, creates one with the specified attribute name and default value. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | --------------- | -| propName | string | Yes | Key to set. | -| newValue | T | Yes | Value to be updated or created.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------------- | +| propName | string | Yes | Attribute name in AppStorage. | +| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| -**Return value** - -| Type | Description | -| ------- | ---------------------------------------- | -| boolean | Updates the value of the attribute and returns **true** if an attribute that has the same name as the specified key exists; creates an attribute with the specified value as its default value and returns **false** otherwise. **undefined** and **null** are not allowed to return **true**.| ```ts -let simple = AppStorage.SetOrCreate('simpleProp', 121) +AppStorage.SetOrCreate('simpleProp', 121); ``` + ### Delete -Delete(propName: string): boolean +static Delete(propName: string): boolean + +Deletes the attribute with the specified attribute name from AppStorage -Deletes the key-value pair that matches the specified key. +under the prerequisite that the attribute does not have a subscriber. If there is a subscriber, **false** is returned. If the deletion is successful, **true** is returned. + +The subscribers of the attribute are attributes with the same name bound to APIs such as **Link** and **Prop**, **\@StorageLink('propName')**, and **\@StorageProp('propName')**. This means that if **\@StorageLink('propName')** and **\@StorageProp('propName')** are used in a custom component or if there is still a **SubscribedAbstractProperty** instance in sync with the attribute, the attribute cannot be deleted from AppStorage. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ------------ | -| propName | string | Yes | Key of the target key-value pair.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------- | +| propName | string | Yes | Attribute name in AppStorage.| **Return value** | Type | Description | | ------- | ---------------------------------------- | -| boolean | Returns **true** if the key-value pair exists and is successfully deleted; returns **false** otherwise.| +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + ```ts -let simple = AppStorage.Delete('simpleProp') +AppStorage.SetOrCreate('PropA', 47); +AppStorage.Link('PropA'); +let res: boolean = AppStorage.Delete('PropA'); // false, PropA still has a subscriber + +AppStorage.SetOrCreate('PropB', 48); +let res1: boolean = AppStorage.Delete('PropB'); // true, PropB is deleted from AppStorage successfully ``` -### keys -keys(): IterableIterator\ +### Keys + +static Keys(): IterableIterator<string> -Searches for all keys. +Obtains all attribute names in AppStorage. **Return value** -| Type | Description | -| -------------- | -------------- | -| array\ | Returns an array of strings containing all keys.| +| Type | Description | +| ------------------------------ | ------------------ | +| IterableIterator<string> | All attribute names in AppStorage.| + ```ts -let simple = AppStorage.Keys() +AppStorage.SetOrCreate('PropB', 48); +let keys: IterableIterator = AppStorage.Keys(); ``` + ### staticClear -staticClear(): boolean +static staticClear(): boolean Deletes all attributes. -This API is deprecated since API version 9. You are advised to use [Clear](#clear) instead. +This API is deprecated since API version 9. You are advised to use [Clear9+](#clear9) instead. **Return value** @@ -240,482 +296,627 @@ This API is deprecated since API version 9. You are advised to use [Clear](#clea | ------- | --------------------------------- | | boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| + ```ts -let simple = AppStorage.staticClear() +let simple = AppStorage.staticClear(); ``` + ### Clear9+ -Clear(): boolean +static Clear(): boolean -Deletes all attributes. +Deletes all attributes from AppStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, **false** is returned. If the deletion is successful, **true** is returned. + +For details about the subscriber, see [Delete](#delete). **Return value** -| Type | Description | -| ------- | --------------------------------- | -| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + ```typescript -let simple = AppStorage.Clear() +AppStorage.SetOrCreate('PropA', 47); +let res: boolean = AppStorage.Clear(); // true, there are no subscribers ``` + ### IsMutable -IsMutable(propName: string): boolean +static IsMutable(propName: string): boolean -Checks whether an attribute exists and can be changed. +Checks whether the given attribute in AppStorage name is mutable. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | :--- | ------------ | -| propName | string | Yes | Key of the target attribute.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ---------------- | +| propName | string | Yes | Attribute name in AppStorage.| **Return value** -| Type | Description | -| ------- | ------------------ | -| boolean | Returns whether the attribute exists and can be changed.| +| Type | Description | +| ------- | -------------------------------- | +| boolean | Whether the given attribute in AppStorage name is mutable.| + ```ts -let simple = AppStorage.IsMutable('simpleProp') +AppStorage.SetOrCreate('PropA', 47); +let res: boolean = AppStorage.IsMutable('simpleProp'); ``` + ### Size -Size(): number +static Size(): number -Obtains the number of existing key-value pairs. +Obtains the number of attributes in AppStorage. **Return value** -| Type | Description | -| ------ | --------- | -| number | Returns the number of key-value pairs.| +| Type | Description | +| ------ | ------------------- | +| number | Number of attributes in AppStorage.| + ```ts -let simple = AppStorage.Size() +AppStorage.SetOrCreate('PropB', 48); +let res: number = AppStorage.Size(); // 1 ``` + ## LocalStorage9+ + ### constructor9+ constructor(initializingProperties?: Object) -Creates and initializes a **LocalStorage** object. +Creates a **LocalStorage** instance and initializes it using the attributes and values returned by **Object.keys(initializingProperties)**. + +Since API version 9, this API is supported in ArkTS widgets. **Parameters** | Name | Type | Mandatory | Description | | ---------------------- | ------ | ---- | ---------------------------------------- | -| initializingProperties | Object | No | All object attributes and their values returned by **object.keys(obj)**.| +| initializingProperties | Object | No | Attributes and values used to initialize the **LocalStorage** instance. The value cannot be **undefined**.| + ```ts -let storage = new LocalStorage() +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); ``` + ### GetShared9+ static GetShared(): LocalStorage -Obtains the **LocalStorage** object being shared. +Obtains the **LocalStorage** instance shared by the current stage. + +Since API version 9, this API is supported in ArkTS widgets. -This API can be used only in the stage model. +**Model restriction**: This API can be used only in the stage model. **Return value** -| Type | Description | -| ----------------------------- | ----------------- | -| [LocalStorage](#localstorage) | **LocalStorage** object.| +| Type | Description | +| ------------------------------ | ----------------- | +| [LocalStorage](#localstorage9) | **LocalStorage** instance.| + ```ts -let storage = LocalStorage.GetShared() +let storage: LocalStorage = LocalStorage.GetShared(); ``` + ### has9+ has(propName: string): boolean -Checks whether the **LocalStorage** contains the specified attribute. +Checks whether the attribute with the specified attribute name exists in LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ------- | -| propName | string | Yes | Key of the attribute.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ------------------ | +| propName | string | Yes | Attribute name in LocalStorage.| **Return value** -| Type | Description | -| ------- | ------------- | -| boolean | Returns whether the attribute exists.| +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **true** if the target attribute exists in AppStorage; returns **false** otherwise.| -```ts -let storage = new LocalStorage() -storage.has('storageSimpleProp') + +``` +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +storage.has('PropA'); // true ``` + ### get9+ -get\(propName: string): T +get<T>(propName: string): T | undefined -Obtains the value of the specified key. +Obtains the attribute with the specified attribute name in LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Key of the value to obtain.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ------------------ | +| propName | string | Yes | Attribute name in LocalStorage.| **Return value** -| Type | Description | -| -------------- | ---------------------------------------- | -| T \| undefined | Returns the value of the specified key if it exists; returns **undefined** otherwise.| +| Type | Description | +| ------------------------ | ---------------------------------------- | +| T \| undefined | Returns the attribute with the specified attribute name in LocalStorage; returns **undefined** if the attribute does not exist.| + ```ts -let storage = new LocalStorage() -let simpleValue = storage.get('storageSimpleProp') +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let value: number = storage.get('PropA'); // 47 ``` + ### set9+ -set\(propName: string, newValue: T): boolean +set<T>(propName: string, newValue: T): boolean -Sets a new value for the specified key. +Sets the value for the attribute with the specified attribute name in LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Key to set. | -| newValue | T | Yes | Value to set.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ----------------------- | +| propName | string | Yes | Attribute name in LocalStorage. | +| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| **Return value** -| Type | Description | -| ------- | ----------------------------------- | -| boolean | Returns **true** and the value if the key exists; returns **false** otherwise.| +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **true** if the operation is successful; return **false** if the attribute with the specified attribute name does not exist in LocalStorage, or the value to set is **undefined** or **null**. | + ```ts -let storage = new LocalStorage() -storage.set('storageSimpleProp', 121) +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let res: boolean = storage.set('PropA', 47); // true +let res1: boolean = storage.set('PropB', 47); // false ``` + ### setOrCreate9+ -setOrCreate\(propName: string, newValue: T): boolean +setOrCreate<T>(propName: string, newValue: T): boolean + +Sets a new value for the attribute with the specified attribute name in LocalStorage or, if the attribute does not exist, creates one with the specified attribute name and default value. -Creates or updates the value of the specified key. +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | :--- | -------------- | -| propName | string | Yes | Key of the value to create or update. | -| newValue | T | Yes | Value to be updated or created.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ----------------------- | +| propName | string | Yes | Attribute name in LocalStorage. | +| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| **Return value** | Type | Description | | ------- | ---------------------------------------- | -| boolean | Updates the value of the attribute and returns **true** if an attribute that has the same name as the specified key exists; creates an attribute with the specified value as its default value and returns false otherwise. **undefined** and **null** are not allowed.| +| boolean | Returns **false** if **newValue** is set to **undefined** or **null**.
Updates the target attribute with the new value and returns **true** if the attribute exists in LocalStorage.
Creates an attribute with the specified attribute name and default value if the attribute does not exist in LocalStorage.| + ```ts -let storage = new LocalStorage() -storage.setOrCreate('storageSimpleProp', 121) +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let res: boolean =storage.setOrCreate('PropA', 121); // true +let res1: boolean =storage.setOrCreate('PropB', 111); // true +let res2: boolean =storage.setOrCreate('PropB', undefined); // false ``` + ### link9+ -link\(propName: string): T +link<T>(propName: string): SubscribedAbstractProperty<T> + +Establishes two-way data binding with the given attribute in this **LocalStorage** instance. If the given attribute exists, the two-way bound data of the attribute in LocalStorage is returned. -Establishes two-way data binding between an attribute and this **LocalStorage** instance. +Any update of the data is synchronized back to LocalStorage, which then synchronizes the update to all data and custom components bound to the attribute. + +If the given attribute does not exist in LocalStorage, **undefined** is returned. + +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ----------- | -| propName | string | Yes | Name of the target attribute.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ------------------ | +| propName | string | Yes | Attribute name in LocalStorage.| **Return value** -| Type | Description | -| ---- | ---------------------------------------- | -| T | Returns two-way binding to this attribute if there is data with a given key. This means that attribute changes made by a variable or component will be synchronized to the **LocalStorage**, and attribute changes made through the **LocalStorage** will be synchronized to the variable or component. returns **undefined** if the attribute with the given key does not exist.| +| Type | Description | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<T> | Returns the **SubscribedAbstractProperty** instance if the given attribute exists in AppStorage; returns **undefined** otherwise.| + ```ts -let storage = new LocalStorage() -let localStorage = storage.link('storageSimpleProp') +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let linkToPropA1: SubscribedAbstractProperty = storage.link('PropA'); +let linkToPropA2: SubscribedAbstractProperty = storage.link('PropA'); // linkToPropA2.get() == 47 +linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 ``` + ### setAndLink9+ -setAndLink\(propName: string, defaultValue: T): T +setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> + +Works in a way similar to the **Link** API. If the given attribute exists in LocalStorage, the two-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in LocalStorage, and two-way bound data is returned. -Works in a way similar to the **Link** API. +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| ------------ | ------ | ---- | ----------- | -| propName | string | Yes | Target key.| -| defaultValue | T | Yes | Default value to set. | +| Name | Type | Mandatory | Description | +| ------------ | ------ | ---- | ---------------------------------------- | +| propName | string | Yes | Attribute name in LocalStorage. | +| defaultValue | T | Yes | Default value used to initialize the attribute with the specified attribute name in LocalStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Link | Returns the value corresponding to the key if the current key is stored in the **LocalStorage**; creates and returns a **Link** instance corresponding to the default value if the key has not been created.| +| Type | Description | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<T> | Returns the **SubscribedAbstractProperty<T>** instance if the given attribute exists in LocalStorage; returns **undefined** otherwise.| + ```ts -let storage = new LocalStorage() -let localStorage = storage.setAndLink('storageSimpleProp', 121) +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let link1: SubscribedAbstractProperty = storage.setAndLink('PropB', 49); // Create PropB 49 +var link2: SubscribedAbstractProperty = storage.setAndLink('PropA', 50); // PropA exists, remains 47 ``` + ### prop9+ -prop\(propName: string): T +prop<S>(propName: string): SubscribedAbstractProperty<S> + +Establishes one-way data binding with the given attribute in this **LocalStorage** instance. If the given attribute exists, the one-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist in LocalStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to LocalStorage. -Establishes one-way data binding with an attribute to update its status. +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | ---- | ------------- | -| propName | string | Yes | Key of the attribute.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ------------------ | +| propName | string | Yes | Attribute name in LocalStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Prop | Returns one-way binding to an attribute with a given key if the attribute exists; returns **undefined** otherwise. One-way binding means that attribute changes made through the **LocalStorage** will be synchronized to the variable or component, but attribute changes made by the variable or component will not be synchronized to the **LocalStorage**. This API returns immutable variables and is applicable to mutable and immutable state variables alike. | +| Type | Description | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<S> | Returns the **SubscribedAbstractProperty<S>** instance if the given attribute exists in LocalStorage; returns **undefined** otherwise.| + ```ts -let storage = new LocalStorage() -let localStorage = storage.prop('storageSimpleProp') +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let prop1: SubscribedAbstractProperty = storage.prop('PropA'); +let prop2: SubscribedAbstractProperty = storage.prop('PropA'); +prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 ``` + ### setAndProp9+ -setAndProp\(propName: string, defaultValue: T): T +setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> + +Establishes one-way data binding with the given attribute in this **LocalStorage** instance. If the given attribute exists, the one-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in LocalStorage, and one-way bound data is returned. -Works in a way similar to the **Prop** API. +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| ------------ | ------ | ---- | -------------- | -| propName | string | Yes | Key of the target key-value pair.| -| defaultValue | T | Yes | Default value to set. | +| Name | Type | Mandatory | Description | +| ------------ | ------ | ---- | ---------------------------------------- | +| propName | string | Yes | Attribute name in LocalStorage. | +| defaultValue | S | Yes | Default value used to initialize the attribute with the specified attribute name in LocalStorage.| **Return value** -| Type | Description | -| ----- | ---------------------------------------- | -| @Prop | Returns the value corresponding to the given key if the key is stored in the **LocalStorage**; creates and returns a **Prop** instance corresponding to the default value if the key has not been created.| +| Type | Description | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<S> | Instance of **SubscribedAbstractProperty<T>** and one-way bound data of the given attribute in LocalStorage.| + ```ts -let storage = new LocalStorage() -let localStorage = storage.setAndProp('storageSimpleProp', 121) +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let prop: SubscribedAbstractProperty = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 ``` + ### delete9+ delete(propName: string): boolean -Deletes the key-value pair that matches the specified key. +Deletes the attribute with the specified attribute name from LocalStorage under the prerequisite that the attribute does not have a subscriber. If the deletion is successful, **true** is returned. + +The subscribers of the attribute are attributes with the same name bound to the **Link** and **Prop** APIs, **\@LocalStorageLink('propName')**, and **\@LocalStorageProp('propName')**. This means that if **\@LocalStorageLink('propName')** and **\@LocalStorageProp('propName')** are used in a custom component or if there is still a **SubscribedAbstractProperty** instance (return type of the **link** and **prop** APIs) in sync with the attribute, the attribute cannot be deleted from LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------ | :--- | ------------ | -| propName | string | Yes | Key of the target key-value pair.| +| Name | Type | Mandatory | Description | +| -------- | ------ | ---- | ------------------ | +| propName | string | Yes | Attribute name in LocalStorage.| **Return value** | Type | Description | | ------- | ---------------------------------------- | -| boolean | Returns **true** if the key-value pair exists and is successfully deleted; returns **false** otherwise.| +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + ```ts -let storage = new LocalStorage() -storage.delete('storageSimpleProp') +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +storage.link('PropA'); +let res: boolean = storage.delete('PropA'); // false, PropA still has a subscriber +let res1: boolean = storage.delete('PropB'); // false, PropB is not in storage +storage.setOrCreate('PropB', 48); +let res2: boolean = storage.delete('PropB'); // true, PropB is deleted from storage successfully ``` + ### keys9+ -keys(): IterableIterator\ +keys(): IterableIterator<string> + +Obtains all attribute names in LocalStorage. -Searches for all keys. +Since API version 9, this API is supported in ArkTS widgets. **Return value** -| Type | Description | -| -------------- | ------------------- | -| array\ | Returns an array of strings containing all keys that are not serializable.| +| Type | Description | +| ------------------------------ | -------------------- | +| IterableIterator<string> | All attribute names in LocalStorage.| + ```ts -let storage = new LocalStorage() -let simple = storage.keys() +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let keys: IterableIterator = storage.keys(); ``` + ### size9+ size(): number -Obtains the number of existing key-value pairs. +Obtains the number of attributes in LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. **Return value** | Type | Description | | ------ | --------- | -| number | Returns the number of key-value pairs.| +| number | Number of attributes in LocalStorage.| + ```ts -let storage = new LocalStorage() -let simple = storage.size() +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let res: number = storage.size(); // 1 ``` -### Clear9+ + +### clear9+ clear(): boolean -Deletes all attributes. + +Deletes all attributes from LocalStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, **false** is returned. If the deletion is successful, **true** is returned. + +Since API version 9, this API is supported in ArkTS widgets. **Return value** -| Type | Description | -| ------- | --------------------------------- | -| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| + +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + ```ts -let storage = new LocalStorage() -let simple = storage.clear() +let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); +let res: boolean = storage.clear(); // true, there are no subscribers ``` -## PersistentStorage -### constructor +## SubscribedAbstractProperty -constructor(appStorage: AppStorage, storage: Storage) -Creates a **persistentstorage** object. +### get9+ -**Parameters** +abstract get(): T + +Obtains attribute data synchronized from AppStorage or LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. + +**Return value** + +| Type | Description | +| ---- | ------------------------------- | +| T | Attribute data synchronized from AppStorage or LocalStorage.| -| Name | Type | Mandatory | Description | -| ---------- | ---------- | ---- | ---------------- | -| appStorage | AppStorage | Yes | Singleton object that saves all attributes and attribute values.| -| storage | Storage | Yes | **Storage** object. | ```ts -let persistentstorage = new PersistentStorage(AppStorage,Storage) +AppStorage.SetOrCreate('PropA', 47); +let prop1 = AppStorage.Prop('PropA'); +prop1.get(); // prop1.get()=47 +``` + + +### set9+ + +abstract set(newValue: T): void + +Sets the attribute data synchronized from AppStorage or LocalStorage. + +Since API version 9, this API is supported in ArkTS widgets. + + +**Parameters** + + +| Name | Type | Mandatory | Description | +| -------- | ---- | ---- | ------- | +| newValue | T | Yes | Data to set.| + + + +``` +AppStorage.SetOrCreate('PropA', 47); +let prop1 = AppStorage.Prop('PropA'); +prop1.set(1); // prop1.get()=1 ``` +## PersistentStorage + + ### PersistProp -PersistProp(key:string,defaultValue:T): void +static PersistProp<T>(key: string, defaultValue: T): void -Changes the attribute that matches the specified key to persistent data in the **AppStorage**. +Persists the attribute with the specified key in AppStorage to a file. This API is usually called before access to AppStorage. + +The sequence of determining the type and value of an attribute is as follows: + +1. If the PersistentStorage file contains the attribute with the specified key, an attribute with the key as the name is created in AppStorage and initialized with the attribute of the key found in PersistentStorage. + +2. If the attribute with the specified key is not found in the PersistentStorage file, AppStorage is searched for the attribute corresponding to the key. If the matching attribute is found, it is persisted. + +3. If no matching attribute is found in AppStorage, it is created in AppStorage, initialized with the value of **defaultValue**, and persisted. + +According to the preceding initialization process, if AppStorage contains the matching attribute, the value of this attribute is used to overwrite the value in the PersistentStorage file. Because AppStorage stores data in the memory, the attribute value becomes impersistent. **Parameters** -| Name | Type | Mandatory | Description | -| ------------ | ------ | ---- | -------------- | -| key | string | Yes | Key of the target attribute. | -| defaultValue | T | Yes | Value of the target attribute.| +| Name | Type | Mandatory | Description | +| ------------ | ------ | ---- | ---------------------------------------- | +| key | string | Yes | Attribute name. | +| defaultValue | T | Yes | Default value used to initialize the created attribute. The value cannot be **undefined** or **null**.| + + +**Example:** + + ```ts -PersistentStorage.PersistProp('highScore', '0') +PersistentStorage.PersistProp('highScore', '0'); ``` + ### DeleteProp -DeleteProp(key: string): void +static DeleteProp(key: string): void -Cancels two-way binding. The value of this attribute will be deleted from the persistent storage. +Performs the reverse operation of **PersistProp**. Specifically, this API deletes the attribute corresponding to the key from PersistentStorage. Subsequent AppStorage operations do not affect data in PersistentStorage. **Parameters** -| Name | Type | Mandatory | Description | -| ---- | ------ | ---- | ------------ | -| key | string | Yes | Key of the target attribute.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ----------------------- | +| key | string | Yes | Attribute name in PersistentStorage.| + ```ts -PersistentStorage.DeleteProp('highScore') +PersistentStorage.DeleteProp('highScore'); ``` + ### PersistProps -PersistProps(properties: {key: string, defaultValue: any}[]): void +static PersistProps(properties: {key: string, defaultValue: any;}[]): void -Changes the attributes that match the specified keys to persistent data in the **AppStorage**. +Works in a way similar to the **PersistProp** API, with the difference that it allows for persistence in batches and is therefore ideal for initialization during application startup. **Parameters** -| Name | Type | Mandatory | Description | -| ---- | ---------------------------------- | ---- | --------- | -| key | {key: string, defaultValue: any}[] | Yes | Keys of the target attributes.| +| Name | Type | Mandatory | Description | +| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | +| properties | {key: string, defaultValue: any}[] | Yes | Array of attributes to persist.
**key**: attribute name.
**defaultValue**: default value. The rules are the same as those of **PersistProp**.| + ```ts -PersistentStorage.PersistProps([{key: 'highScore', defaultValue: '0'},{key: 'wightScore',defaultValue: '1'}]) +PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); ``` + ### Keys -Keys(): Array\ +static Keys(): Array<string> -Returns the flags of all persistent attributes. +Obtains an array of keys for all persistent attributes. **Return value** -| Type | Description | -| -------------- | ------------- | -| Array\ | Returns the flags of all persistent attributes.| +| Type | Description | +| ------------------- | ----------------- | +| Array<string> | Array of keys of all persistent attributes.| + ```ts -let simple = PersistentStorage.Keys() +let keys: Array = PersistentStorage.Keys(); ``` -> **NOTE** -> -> - When using **PersistProp**, ensure that the input key exists in the **AppStorage**. -> -> - **DeleteProp** takes effect only for the data that has been linked during the current startup. ## Environment -### constructor -Creates an **Environment** object. +### EnvProp -```ts -let simple = new Environment() -``` +static EnvProp<S>(key: string, value: S): boolean -### EnvProp +Saves the built-in environment variable key in environment to AppStorage. If the value of the environment variable key is not found in AppStorage, the default value is used. If the value is successfully saved, **true** is returned. If the value of the environment variable key is found in AppStorage, **false** is returned. -EnvProp\(key: string, value: S): boolean +You are advised to call this API when the application is started. -Binds this system attribute to the **AppStorage**. You are advised to use this API during application startup. If the attribute already exists in the **AppStorage**, **false** is returned. Do not use the variables in the **AppStorage**. Instead, call this API to bind environment variables. +It is incorrect to use AppStorage to read environment variables without invoking **EnvProp**. **Parameters** -| Name | Type | Mandatory | Description | Description | -| ----- | ------ | ---- | ---------- | ------------------------- | -| key | string | Yes | Key of the target attribute. | For details, see **Built-in environment variables**.| -| value | S | Yes | Value of the target attribute.| Value of the target attribute. | +| Name | Type | Mandatory | Description | +| ----- | ------ | ---- | --------------------------------------- | +| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables). | +| value | S | Yes | Default value used if the value of the environment variable key is not found in AppStorage.| **Return value** -| Type | Description | -| ------- | ---------------------- | -| boolean | Returns whether the attribute exists in the **AppStorage**.| +| Type | Description | +| ------- | ---------------------------------------- | +| boolean | Returns **false** if the attribute corresponding to the key exists in AppStorage; returns **false** otherwise.| + +**Example:** -**Built-in environment variables** + +```ts +Environment.EnvProp('accessibilityEnabled', 'default'); +``` + + +### Built-in Environment Variables | key | Type | Description | | -------------------- | --------------- | ---------------------------------------- | @@ -723,41 +924,49 @@ Binds this system attribute to the **AppStorage**. You are advised to use this A | colorMode | ColorMode | Color mode. The options are as follows:
- **ColorMode.LIGHT**: light mode.
- **ColorMode.DARK**: dark mode.| | fontScale | number | Font scale. | | fontWeightScale | number | Font weight scale. | -| layoutDirection | LayoutDirection | Layout direction. The options are as follows:
- **LayoutDirection.LTR**: The direction is from left to right.
- **LayoutDirection.RTL**: The direction is from right to left.| +| layoutDirection | LayoutDirection | Layout direction. The options are as follows:
- **LayoutDirection.LTR**: from left to right.
- **LayoutDirection.RTL**: from right to left.| | languageCode | string | Current system language. The value is in lowercase, for example, **zh**. | -```ts -Environment.EnvProp('accessibilityEnabled', 'default') -``` ### EnvProps -EnvProps(props: {key: string, defaultValue: any}[]): void +static EnvProps(props: {key: string; defaultValue: any;}[]): void -Associates this system item array with the **AppStorage**. +Works in a way similar to the **EnvProp** API, with the difference that it allows for initialization of multiple attributes in batches. You are advised to call this API during application startup to save system environment variables to AppStorage in batches. **Parameters** -| Name | Type | Mandatory | Description | Description | -| ---- | ---------------------------------- | ---- | --------- | --------- | -| key | {key: string, defaultValue: any}[] | Yes | Keys of the target attributes.| Keys of the target attributes.| +| Name | Type | Mandatory | Description | +| ----- | ---------------------------------------- | ---- | ------------------ | +| props | {key: string, defaultValue: any}[] | Yes | Array of key-value pairs consisting of system environment variables and default values.| + ```ts -Environment.EnvProps([{key: 'accessibilityEnabled', defaultValue: 'default'},{key: 'accessibilityUnEnabled', defaultValue: 'undefault'}]) +Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { + key: 'languageCode', + defaultValue: 'en' +}, { key: 'prop', defaultValue: 'hhhh' }]); ``` + ### Keys -Keys(): Array\ +static Keys(): Array<string> -Returns an array of associated system attributes. +Array of keys of environment variables. **Return value** -| Type | Description | -| -------------- | ----------- | -| Array\ | Returns an array of associated system attributes.| +| Type | Description | +| ------------------- | ----------- | +| Array<string> | Returns an array of associated system attributes.| + ```ts -let simple = Environment.Keys() +Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { + key: 'languageCode', + defaultValue: 'en' +}, { key: 'prop', defaultValue: 'hhhh' }]); + +let keys: Array = Environment.Keys(); // accessibilityEnabled, languageCode, prop ``` diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md index 19fb0da84c1cafd88ea971c93db167934313de3f..9c31eb0275e5ca765453580377f1f72bb375ea8a 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md @@ -13,13 +13,13 @@ The text style attributes set the style for text in a component. | Name | Type | Description | | -----------| ---------------------------------------- | ------------------------------------ | -| fontColor | [ResourceColor](ts-types.md#resourcecolor) | Font color. | -| fontSize | [Length](ts-types.md#length) | Font size. If the value is of the number type, the unit fp is used. The default font size is 16. This attribute cannot be set in percentage. | -| fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | Font style.
Default value: **FontStyle.Normal** | -| fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight. The string type supports only the string of the number type, for example, **400**, **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**, which correspond to the enumerated values in **FontWeight**.
Default value: **FontWeight.Normal** | -| fontFamily | string \| [Resource](ts-types.md#resource) | Font family.
Default value: **'HarmonyOS Sans'**
Currently, only the default font is supported. | -| lineHeight | string \| number \| [Resource](ts-types.md#resource) | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used.| -| decoration | {
type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),
color?: [ResourceColor](ts-types.md#resourcecolor)
} | Style and color of the text decorative line.
Default value: {
type: TextDecorationType.None,
color: Color.Black
} | +| fontColor | [ResourceColor](ts-types.md#resourcecolor) | Font color.
Since API version 9, this API is supported in ArkTS widgets.| +| fontSize | [Length](ts-types.md#length) | Font size. If the value is of the number type, the unit fp is used. The default font size is 16. This attribute cannot be set in percentage.
Since API version 9, this API is supported in ArkTS widgets.| +| fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | Font style.
Default value: **FontStyle.Normal**
Since API version 9, this API is supported in ArkTS widgets.| +| fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | Font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight. The string type supports only the string of the number type, for example, **400**, **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**, which correspond to the enumerated values in **FontWeight**.
Default value: **FontWeight.Normal**
Since API version 9, this API is supported in ArkTS widgets.| +| fontFamily | string \| [Resource](ts-types.md#resource) | Font family.
Default value: **'HarmonyOS Sans'**. Currently, only the default font is supported.
Since API version 9, this API is supported in ArkTS widgets.| +| lineHeight | string \| number \| [Resource](ts-types.md#resource) | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used.
Since API version 9, this API is supported in ArkTS widgets.| +| decoration | {
type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),
color?: [ResourceColor](ts-types.md#resourcecolor)
} | Style and color of the text decorative line.
Default value: {
type: TextDecorationType.None,
color: Color.Black
}
Since API version 9, this API is supported in ArkTS widgets.| ## Example diff --git a/en/application-dev/ui/arkts-layout-development-create-looping.md b/en/application-dev/ui/arkts-layout-development-create-looping.md index ac1b89ef014cd38b97b6ecaf98a7d55de1b19ae9..4845c9dc535a89a990eea9117271d1655d41476b 100644 --- a/en/application-dev/ui/arkts-layout-development-create-looping.md +++ b/en/application-dev/ui/arkts-layout-development-create-looping.md @@ -280,7 +280,7 @@ Swiper(this.swiperController) { ## Child Components Per Page -You can set the number of child components per page for the \ component through its [displayCount](../reference/arkui-ts/ts-container-swiper.md#attributes) attribute. +You can set the number of child components per page for the **\** component through its [displayCount](../reference/arkui-ts/ts-container-swiper.md#attributes) attribute. To display two child components per page: diff --git a/en/application-dev/ui/arkts-popup-and-menu-components-popup.md b/en/application-dev/ui/arkts-popup-and-menu-components-popup.md index 5f2516da41bcb61d0d35deddb38466462e1138c3..2176e02b39dfaf3b7bc59141835578f1ff0c55d9 100644 --- a/en/application-dev/ui/arkts-popup-and-menu-components-popup.md +++ b/en/application-dev/ui/arkts-popup-and-menu-components-popup.md @@ -1,17 +1,17 @@ -# Bubble +# Popup -You can bind the **Popup** attribute to a component, specifying its content, interaction logic, and display status. It is mainly used for screen recording and message pop-up notification. +You can bind the **Popup** attribute to a component to create a popup, specifying its content and interaction logic, and display state. It is mainly used for screen recording and message notification. -Bubbles are classified into two types: built-in bubbles with [PopupOptions](../reference/arkui-ts/ts-universal-attributes-popup.md#popupoptions) and custom bubbles with [CustomPopupOptions](../reference/arkui-ts/ts-universal-attributes-popup.md#custompopupoptions8). For PopupOptions, you can set primaryButton and secondaryButton to set bubbles with buttons. CustomPopupOptions sets the customized bubble by configuring the [builder](../quick-start/arkts-builder.md) parameter. +Popups can be defined with [PopupOptions](../reference/arkui-ts/ts-universal-attributes-popup.md#popupoptions) or [CustomPopupOptions](../reference/arkui-ts/ts-universal-attributes-popup.md#custompopupoptions8). In **PopupOptions**, you can set **primaryButton** and **secondaryButton** to include buttons in the popup. In **CustomPopupOptions**, you can create a custom popup through the [builder](../quick-start/arkts-builder.md) parameter. -## Text prompt bubble +## Text Popup -Text pop-up messages are usually used to display only text messages without any interaction. The Popup attribute needs to be bound to a component. When the show parameter in the bindPopup attribute is set to true, a pop-up message is displayed. +Text popups are usually used to display text only and do not allow for user interactions. Bind the **Popup** attribute to a component. When the **show** parameter in the **bindPopup** attribute is set to **true**, a popup is displayed. -Bind the Popup attribute to the Button component. Each time the Button button is clicked, handlePopup switches the Boolean value. When handlePopup is set to true, bindPopup pops up. +If you bind the **Popup** attribute to a **\