diff --git a/en/application-dev/quick-start/arkts-restrictions-and-extensions.md b/en/application-dev/quick-start/arkts-restrictions-and-extensions.md index a03b839c3b1cdc06017c897cdd20be8a0dc02210..fa62ed392100f7ff0b60dcc6e8ee66ef465fbb3a 100644 --- a/en/application-dev/quick-start/arkts-restrictions-and-extensions.md +++ b/en/application-dev/quick-start/arkts-restrictions-and-extensions.md @@ -118,7 +118,7 @@ struct bindPopupPage { ![hello](figures/hello.PNG) -## Initialization and Restrictions of Custom Components' Member Variables +## Initialization Rules and Restrictions of Custom Components' Member Variables The member variables of a component can be initialized in either of the following ways: @@ -133,7 +133,7 @@ The member variables of a component can be initialized in either of the followin MyComponent({counter: $myCounter}) ``` -The allowed method depends on the decorator of the state variable, as shown in the following table. +The allowed method depends on the decorator of the state variable, as described in the following table. | Decorator | Local Initialization| Initialization Using Constructor Parameters| | ------------ | ----- | ----------- | diff --git a/en/release-notes/changelogs/OpenHarmony_3.2.10.5/changelogs-arkui.md b/en/release-notes/changelogs/OpenHarmony_3.2.10.5/changelogs-arkui.md new file mode 100644 index 0000000000000000000000000000000000000000..3e4d9a57601c4d8b930451927c91bb209c4954b9 --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_3.2.10.5/changelogs-arkui.md @@ -0,0 +1,217 @@ +# ArkUI Subsystem ChangeLog + +## cl.arkui.1 Restrictions on Data Type Declarations of State Variables + +1. The data types of state variables decorated by state decorators must be explicitly declared. They cannot be declared as **any** or **Date**. + + Example: + + ```ts + // xxx.ets + @Entry + @Component + struct DatePickerExample { + // Incorrect: @State isLunar: any = false + @State isLunar: boolean = false + // Incorrect: @State selectedDate: Date = new Date('2021-08-08') + private selectedDate: Date = new Date('2021-08-08') + + build() { + Column() { + Button('Switch Calendar') + .margin({ top: 30 }) + .onClick(() => { + this.isLunar = !this.isLunar + }) + DatePicker({ + start: new Date('1970-1-1'), + end: new Date('2100-1-1'), + selected: this.selectedDate + }) + .lunar(this.isLunar) + .onChange((value: DatePickerResult) => { + this.selectedDate.setFullYear(value.year, value.month, value.day) + console.info('select current date is: ' + JSON.stringify(value)) + }) + + }.width('100%') + } + } + ``` + + ![datePicker](../../../application-dev/reference/arkui-ts/figures/datePicker.gif) + +2. The data type declaration of the **@State**, **@Provide**, **@Link**, or **@Consume** decorated state variables can consist of only one of the primitive data types or reference data types. + + The **Length**, **ResourceStr**, and **ResourceColor** types are combinations of primitive data types or reference data types. Therefore, they cannot be used by the aforementioned types of state variables. + For details about the definitions of **Length**, **ResourceStr**, and **ResourceColor**, see [Types](../../../application-dev/reference/arkui-ts/ts-types.md). + + Example: + + ```ts + // xxx.ets + @Entry + @Component + struct IndexPage { + // Incorrect: @State message: string | Resource = 'Hello World' + @State message: string = 'Hello World' + // Incorrect: @State message: ResourceStr = $r('app.string.hello') + @State resourceStr: Resource = $r('app.string.hello') + + build() { + Row() { + Column() { + Text(`${this.message}`) + .fontSize(50) + .fontWeight(FontWeight.Bold) + } + .width('100%') + } + .height('100%') + } + } + ``` + + ![hello](../../../application-dev/quick-start/figures/hello.PNG) + +**Change Impacts** + +1. If the data type of a state variable decorated by a state decorator is declared as **any**, a build error will occur. + ```ts + // ArkTS:ERROR Please define an explicit type, not any. + @State isLunar: any = false + ``` +2. If the data type of a state variable decorated by a state decorator is declared as **Date**, a build error will occur. + ```ts + // ArkTS:ERROR The @State property 'selectedDate' cannot be a 'Date' object. + @State selectedDate: Date = new Date('2021-08-08') + ``` +3. If the data type of a **@State**, **@Provide**, **@Link**, and or **@Consume** decorated state variable is Length, **ResourceStr**, or **ResourceColor**, a build error will occur. + ```ts + /* ArkTS:ERROR The state variable type here is 'ResourceStr', it contains both a simple type and an object type, + which are not allowed to be defined for state variable of a struct.*/ + @State message: ResourceStr = $r('app.string.hello') + ``` + +**Key API/Component Changes** + +N/A + +**Adaptation Guide** + +1. Explicitly declare the data type for state variables decorated by state decorators. +2. If a state variable decorated by a state decorator uses the **Date** object, change it to a regular variable – a variable not decorated by any decorator. +3. Adapt the **@State**, **@Provide**, **@Link**, and **@Consume** decorated variables based on the following code snippet so that they do not use the **Length(string|number|Resource)**, **ResourceStr(string|Resource)**, and **ResourceColor(string|number|Color|Resource)** types: + + ```ts + // Incorrect: + @State message: ResourceStr = $r('app.string.hello') + // Corrected: + @State resourceStr: Resource = $r('app.string.hello') + ``` + +## cl.arkui.2 Initialization Rules and Restrictions of Custom Components' Member Variables + +Comply with the following rules when using constructors to initialize member variables: + +| **From the Variable in the Parent Component (Right) to the Variable in the Child Component (Below)**| **regular** | **@State** | **@Link** | **@Prop** | **@Provide** | **@Consume** | **@ObjectLink** | +|---------------------------------|----------------------------|------------|-----------|-----------|--------------|--------------|------------------| +| **regular** | Supported | Supported | Supported | Supported | Not supported | Not supported | Supported | +| **@State** | Supported | Supported | Supported | Supported | Supported | Supported | Supported | +| **@Link** | Not supported | Supported (1) | Supported (1) | Supported (1) | Supported (1) | Supported (1) | Supported (1) | +| **@Prop** | Supported | Supported | Supported | Supported | Supported | Supported | Supported | +| **@Provide** | Supported | Supported | Supported | Supported | Supported | Supported | Supported | +| **@Consume** | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | +| **@ObjectLink** | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | + +| **From the Variable in the Parent Component (Right) to the Variable in the Child Component (Below)**| **@StorageLink** | **@StorageProp** | **@LocalStorageLink** | **@LocalStorageProp** | +|------------------|------------------|------------------|-----------------------|------------------------| +| **regular** | Supported | Not supported | Not supported | Not supported | +| **@State** | Supported | Supported | Supported | Supported | +| **@Link** | Supported (1) | Supported (1) | Supported (1) | Supported (1) | +| **@Prop** | Supported | Supported | Supported | Supported | +| **@Provide** | Supported | Supported | Supported | Supported | +| **@Consume** | Not supported | Not supported | Not supported | Not supported | +| **@ObjectLink** | Not supported | Not supported | Not supported | Not supported | + +> **NOTE** +> +> **Supported (1)**: The dollar sign ($) must be used, for example, **this.$varA**. +> +> **regular**: refers to a regular variable that is not decorated by any decorator. + +**@StorageLink**, **@StorageProp**, **@LocalStorageLink**, and **@LocalStorageProp** variables cannot be initialized from the parent component. + +**Change Impacts** + +1. Variables decorated by **@LocalStorageLink** and **@LocalStorageProp** cannot be initialized from the parent component. + ```ts + @Entry + @Component + struct LocalStorageComponent { + build() { + Column() { + Child({ + /* ArkTS:ERROR Property 'simpleVarName' in the custom component 'Child' cannot + initialize here (forbidden to specify). */ + simpleVarName: 1, + /* ArkTS:ERROR Property 'objectName' in the custom component 'Child' cannot + initialize here (forbidden to specify). */ + objectName: new ClassA("x") + }) + } + } + } + @Component + struct Child { + @LocalStorageLink("storageSimpleProp") simpleVarName: number = 0; + @LocalStorageProp("storageObjectProp") objectName: ClassA = new ClassA("x"); + build() {} + } + ``` +2. The **@ObjectLink** decorated variable cannot be directly initialized from a decorated variable in the parent component. The source of the parent component must be an array item or object attribute decorated by **@State**, **@Link**, **@Provide**, **@Consume**, or **@ObjectLink**. + ```ts + let NextID : number = 0; + + @Observed class ClassA { + public id : number; + public c: number; + constructor(c: number) { + this.id = NextID++; + this.c = c; + } + } + + @Component + struct Child { + @ObjectLink varA : ClassA; + build() { + Row() { + Text('ViewA-' + this.varA.id) + } + } + } + + @Component + struct Parent { + @Link linkValue: ClassA + build() { + Column() { + /* ArkTS:ERROR The @Link property 'linkValue' cannot be assigned to + the @ObjectLink property 'varA'.*/ + Child({ varA: this.linkValue }) + } + } + } + ``` + +**Key API/Component Changes** + +N/A + +**Adaptation Guide** +1. When building a child component, do not perform the build on the variables decorated by **@LocalStorageLink** and **@LocalStorageProp** in the child component. + + To change these variables from the parent component, use the API provided by the **LocalStorage** (such as the **set** API) to assign values to them. + +2. For details about how to use **@ObjectLink**, see [@Observed and @ObjectLink](../../../application-dev/quick-start/arkts-state-mgmt-page-level.md).