diff --git a/en/application-dev/application-models/arkts-ui-widget-configuration.md b/en/application-dev/application-models/arkts-ui-widget-configuration.md index ea9832f92d32dfe0c2a4160f3ac6f8e904d323fa..d86c3b6991460a25c0ea6a177a8aec8c4607364c 100644 --- a/en/application-dev/application-models/arkts-ui-widget-configuration.md +++ b/en/application-dev/application-models/arkts-ui-widget-configuration.md @@ -54,7 +54,7 @@ Widget-related configuration includes **FormExtensionAbility** configuration and | formVisibleNotify | Whether the widget is allowed to use the widget visibility notification.| String| Yes (initial value: left empty)| | metadata | Metadata of the widget. This field contains the array of the **customizeData** field.| Object| Yes (initial value: left empty)| | dataProxyEnabled | Whether the widget supports the [update-through-proxy](./arkts-ui-widget-update-by-proxy.md) feature.
- **true**: The widget supports the update-through-proxy feature.
- **false**: The widget does not support the update-through-proxy feature.
If this tag is set to **true**, the settings for the scheduled update time will still take effect, but the settings for the update interval and next update time will not.| Boolean| Yes (initial value: **false**)| - | isDynamic | Whether the widget is a dynamic widget. This tag only applies to ArkTS widgets.
- **true**: The widget is a dynamic widget.
- **false**: The widget is a static widget. In this case, the widget is displayed as a static image after being added.| Boolean| Yes (initial value: **true**)| + | isDynamic | Whether the widget is a dynamic widget. This tag applies only to ArkTS widgets.
- **true**: The widget is a dynamic widget.
- **false**: The widget is a static widget. In this case, the widget is displayed as a static image after being added.| Boolean| Yes (initial value: **true**)| **Table 2** Internal structure of the window object diff --git a/en/application-dev/quick-start/arkts-environment.md b/en/application-dev/quick-start/arkts-environment.md index 2f0718290460508c4510acc298fa85c855bbec26..ac80bd54590b0dffdfa6b3bf82351d27f09917a1 100644 --- a/en/application-dev/quick-start/arkts-environment.md +++ b/en/application-dev/quick-start/arkts-environment.md @@ -15,12 +15,11 @@ Environment is a singleton object created by the ArkUI framework at application - Use **Environment.EnvProp** to save the environment variables of the device to AppStorage. ```ts - // Save the language code of the device to AppStorage. The default value is en. - // Whenever its value changes in the device environment, it will update its value in AppStorage. + // Save languageCode to AppStorage. The default value is en. Environment.EnvProp('languageCode', 'en'); ``` -- To keep a component variable updated with changes in the device environment, this variable should be decorated with \@StorageProp. +- Decorate the variables with \@StorageProp to link them with components. ```ts @StorageProp('languageCode') lang : string = 'en'; @@ -29,6 +28,7 @@ Environment is a singleton object created by the ArkUI framework at application The chain of updates is as follows: Environment > AppStorage > Component. > **NOTE** +> > An \@StorageProp decorated variable can be locally modified, but the change will not be updated to AppStorage. This is because the environment variable parameters are read-only to the application. @@ -69,3 +69,29 @@ if (lang.get() === 'en') { console.info('Hello!'); } ``` + + +## Restrictions + + +Environment can be called only when the [UIContext](../reference/apis/js-apis-arkui-UIContext.md#uicontext), which can be obtained through [runScopedTask](../reference/apis/js-apis-arkui-UIContext.md#runscopedtask), is specified. If Environment is called otherwise, no device environment data can be obtained. + + +```ts +// EntryAbility.ts +import UIAbility from '@ohos.app.ability.UIAbility'; +import window from '@ohos.window'; + +export default class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage: window.WindowStage) { + windowStage.loadContent('pages/Index'); + let window = windowStage.getMainWindow() + window.then(window => { + let uicontext = window.getUIContext() + uicontext.runScopedTask(() => { + Environment.EnvProp('languageCode', 'en'); + }) + }) + } +} +``` diff --git a/en/application-dev/quick-start/arkts-observed-and-objectlink.md b/en/application-dev/quick-start/arkts-observed-and-objectlink.md index 61f1bd8ae476f5984405eed97fb127161bb131e2..a7e47fb63e57896158a6a03aaa6896bea7ac644f 100644 --- a/en/application-dev/quick-start/arkts-observed-and-objectlink.md +++ b/en/application-dev/quick-start/arkts-observed-and-objectlink.md @@ -162,6 +162,26 @@ class ClassB { this.a = a; } } + +@Observed +class ClassD { + public c: ClassC; + + constructor(c: ClassC) { + this.c = c; + } +} + +@Observed +class ClassC extends ClassA { + public k: number; + + constructor(k: number) { + // Invoke the parent class method to process k. + super(k); + this.k = k; + } +} ``` @@ -169,60 +189,64 @@ class ClassB { ```ts @Component -struct ViewA { - label: string = 'ViewA1'; - @ObjectLink a: ClassA; +struct ViewC { + label: string = 'ViewC1'; + @ObjectLink c: ClassC; build() { Row() { - Button(`ViewA [${this.label}] this.a.c=${this.a.c} +1`) - .onClick(() => { - this.a.c += 1; - }) - } + Column() { + Text(`ViewC [${this.label}] this.a.c = ${this.c.c}`) + .fontColor('#ffffffff') + .backgroundColor('#ff3fc4c4') + .height(50) + .borderRadius(25) + Button(`ViewC: this.c.c add 1`) + .backgroundColor('#ff7fcf58') + .onClick(() => { + this.c.c += 1; + console.log('this.c.c:' + this.c.c) + }) + } + .width(300) } } +} @Entry @Component struct ViewB { @State b: ClassB = new ClassB(new ClassA(0)); - + @State child : ClassD = new ClassD(new ClassC(0)); build() { Column() { - ViewA({ label: 'ViewA #1', a: this.b.a }) - ViewA({ label: 'ViewA #2', a: this.b.a }) - - Button(`ViewB: this.b.a.c+= 1`) - .onClick(() => { - this.b.a.c += 1; - }) - Button(`ViewB: this.b.a = new ClassA(0)`) + ViewC({ label: 'ViewC #3', c: this.child.c}) + Button(`ViewC: this.child.c.c add 10`) + .backgroundColor('#ff7fcf58') .onClick(() => { - this.b.a = new ClassA(0); - }) - Button(`ViewB: this.b = new ClassB(ClassA(0))`) - .onClick(() => { - this.b = new ClassB(new ClassA(0)); + this.child.c.c += 10 + console.log('this.child.c.c:' + this.child.c.c) }) } } } ``` +The @Observed decorated **ClassC** class can observe changes in attributes inherited from the base class. + Event handlers in **ViewB**: -- this.b.a = new ClassA(0) and this.b = new ClassB(new ClassA(0)): Change to the \@State decorated variable **b** and its attributes. +- this.child.c = new ClassA(0) and this.b = new ClassB(new ClassA(0)): Change to the \@State decorated variable **b** and its attributes. -- this.b.a.c = ... : Change at the second layer. Though [@State](arkts-state.md#observed-changes) cannot observe the change at the second layer, the change of an attribute of \@Observed decorated ClassA, which is attribute **c** in this example, can be observed by \@ObjectLink. +- this.child.c.c = ... : Change at the second layer. Though [@State](arkts-state.md#observed-changes) cannot observe the change at the second layer, the change of an attribute of \@Observed decorated ClassA, which is attribute **c** in this example, can be observed by \@ObjectLink. -Event handlers in **ViewA**: +Event handle in **ViewC**: -- this.a.c += 1: Changes to the \@ObjectLink decorated variable cause the button label to be updated. Unlike \@Prop, \@ObjectLink does not have a copy of its source. Instead, \@ObjectLink creates a reference to its source. +- this.c.c += 1: Changes to the \@ObjectLink decorated variable **a** cause the button label to be updated. Unlike \@Prop, \@ObjectLink does not have a copy of its source. Instead, \@ObjectLink creates a reference to its source. - The \@ObjectLink decorated variable is read-only. Assigning **this.a = new ClassA(...)** is not allowed. Once value assignment occurs, the reference to the data source is reset and the synchronization is interrupted. @@ -297,7 +321,7 @@ struct ViewB { 2. ViewA({ label: ViewA this.arrA[first], a: this.arrA[0] }): The preceding update changes the first element in the array. Therefore, the **ViewA** component instance bound to **this.arrA[0]** is updated. - this.arrA.push(new ClassA(0)): The change of this state variable triggers two updates with different effects. - 1. ForEach: The newly added Class A object is unknown to the **ForEach** [itemGenerator](arkts-rendering-control-foreach.md#api-description). The item builder of **ForEach** will be executed to create a **View A** component instance. + 1. ForEach: The newly added **ClassA** object is unknown to the **ForEach** [itemGenerator](arkts-rendering-control-foreach.md#api-description). The item builder of **ForEach** will be executed to create a **ViewA** component instance. 2. ViewA({ label: ViewA this.arrA[last], a: this.arrA[this.arrA.length-1] }): The last item of the array is changed. As a result, the second **View A** component instance is changed. For **ViewA({ label: ViewA this.arrA[first], a: this.arrA[0] })**, a change to the array does not trigger a change to the array item, so the first **View A** component instance is not refreshed. - this.arrA[Math.floor (this.arrA.length/2)].c: [@State](arkts-state.md#observed-changes) cannot observe changes at the second layer. However, as **ClassA** is decorated by \@Observed, the change of its attributes will be observed by \@ObjectLink. diff --git a/en/application-dev/quick-start/arkts-persiststorage.md b/en/application-dev/quick-start/arkts-persiststorage.md index fdbacd4235dcd50ea2777e8e3695227ff02be70c..21c854c26557e5fcd5027623b0429b625d6c9c91 100644 --- a/en/application-dev/quick-start/arkts-persiststorage.md +++ b/en/application-dev/quick-start/arkts-persiststorage.md @@ -24,7 +24,7 @@ Persistence of data is a relatively slow operation. Applications should avoid th The preceding situations may overload the change process of persisted data. As a result, the PersistentStorage implementation may limit the change frequency of persisted attributes. -PersistentStorage is associated with UIContext and can be called to persist data only when [UIContext](../reference/apis/js-apis-arkui-UIContext.md#uicontext) is specified. The context can be identified in [runScopedTask](../reference/apis/js-apis-arkui-UIContext.md#runscopedtask). +PersistentStorage can be called to persist data only when the [UIContext](../reference/apis/js-apis-arkui-UIContext.md#uicontext), which can be obtained through [runScopedTask](../reference/apis/js-apis-arkui-UIContext.md#runscopedtask), is specified. ## Application Scenarios diff --git a/en/application-dev/quick-start/arkts-rendering-control-foreach.md b/en/application-dev/quick-start/arkts-rendering-control-foreach.md index 4c916bec86f9c9d22b9bdb60ca476f9cbdcd4846..dc6ae173f51df82fbc48f26df56368450fa6fa79 100644 --- a/en/application-dev/quick-start/arkts-rendering-control-foreach.md +++ b/en/application-dev/quick-start/arkts-rendering-control-foreach.md @@ -3,6 +3,9 @@ **ForEach** enables repeated content based on array-type data. +> **NOTE** +> +> Since API version 9, this API is supported in ArkTS widgets. ## API Description @@ -19,15 +22,15 @@ ForEach( | Name | Type | Mandatory | Description | | ------------- | ---------------------------------------- | ---- | ---------------------------------------- | | arr | Array | Yes | An array, which can be empty, in which case no child component is created. The functions that return array-type values are also allowed, for example, **arr.slice (1, 3)**. The set functions cannot change any state variables including the array itself, such as **Array.splice**, **Array.sort**, and **Array.reverse**.| -| itemGenerator | (item: any, index?: number) => void | Yes | A lambda function used to generate one or more child components for each data item in an array. Each component and its child component list must be contained in parentheses.
**NOTE**
- The type of the child component must be the one allowed inside the parent container component of **ForEach**. For example, a **\** child component is allowed only when the parent container component of **ForEach** is **\**.
- The child build function is allowed to return an **if** or another **ForEach**. **ForEach** can be placed inside **if**.
- The optional **index** parameter should only be specified in the function signature if used in its body.| -| keyGenerator | (item: any, index?: number) => string | No | An anonymous function used to generate a unique and fixed key value for each data item in an array. This key-value generator is optional. However, for performance reasons, it is strongly recommended that the key-value generator be provided, so that the development framework can better identify array changes. For example, if no key-value generator is provided, a reverse of an array will result in rebuilding of all nodes in **ForEach**.
**NOTE**
- Two items inside the same array must never work out the same ID.
- If **index** is not used, an item's ID must not change when the item's position within the array changes. However, if **index** is used, then the ID must change when the item is moved within the array.
- When an item is replaced by a new one (with a different value), the ID of the replaced and the ID of the new item must be different.
- When **index** is used in the build function, it should also be used in the ID generation function.
- The ID generation function is not allowed to mutate any component state.| +| itemGenerator | (item: any, index?: number) => void | Yes | A lambda function used to generate one or more child components for each data item in an array. Each component and its child component list must be contained in parentheses.
**NOTE**
- The type of the child component must be the one allowed inside the parent container component of **ForEach**. For example, a **\** child component is allowed only when the parent container component of **ForEach** is **\**.
- The child build function is allowed to return an **if** or another **ForEach**. **ForEach** can be placed inside **if**.
- The optional **index** parameter should only be specified in the function signature if used in its body.| +| keyGenerator | (item: any, index?: number) => string | No | An anonymous function used to generate a unique and fixed key value for each data item in an array. This key-value generator is optional. However, for performance reasons, it is strongly recommended that the key-value generator be provided, so that the development framework can better identify array changes. For example, if no key-value generator is provided, a reverse of an array will result in rebuilding of all nodes in **ForEach**.
**NOTE**
- Two items inside the same array must never work out the same ID.
- If **index** is not used, an item's ID must not change when the item's position within the array changes. However, if **index** is used, then the ID must change when the item is moved within the array.
- When an item is replaced by a new one (with a different value), the ID of the replaced and the ID of the new item must be different.
- When **index** is used in the build function, it should also be used in the ID generation function.
- The ID generation function is not allowed to mutate any component state.| ## Restrictions - **ForEach** must be used in container components. -- The type of the child component must be the one allowed inside the parent container component of **ForEach**. +- The type of the child component must be the one allowed inside the parent container component of **ForEach**. - The **itemGenerator** function can contain an **if/else** statement, and an **if/else** statement can contain **ForEach**. diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md b/en/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md index 07b043411ed7ce7658cb575490e559e0dbd3aab0..daf26e98a24a303138f9f79c88c4340c73ba629a 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md @@ -26,6 +26,11 @@ StepperItem() | nextLabel | string | Text label of the button on the right. The default value is **Start** for the last page and **Next** for the other pages.| | status | [ItemState](#itemstate) | Display status of **nextLabel** in the stepper. Optional.
Default value: **ItemState.Normal**| +> **NOTE** +> +> - The **\** component does not support setting of the universal width attribute. By default, its width is the same as that of the parent **\** component. +> - The **\** component does not support setting of the universal height attribute. Its height is the height of the parent **\** component minus the height of the label button. +> - The **\** component does not support setting of the **aspectRadio** or **constrainSize** attribute, which may affect the length and width. ## ItemState | Name | Description|