android2harmony 0.1.2 → 0.1.3

package/skills/hmos-incremental-ui-align/references/MVVM/345/274/200/345/217/221/346/226/207/346/241/243V2/@Computed/350/243/205/351/245/260/345/231/250/357/274/232/350/256/241/347/256/227/345/261/236/346/200/247.md

@@ -0,0 +1,373 @@
+# @Computed装饰器：计算属性
+
+当开发者使用相同的计算逻辑重复绑定在UI上时，为了防止重复计算，可以使用@Computed计算属性。计算属性中依赖的状态变量变化时，只会计算一次。这解决了UI多次重用该属性导致的重复计算和性能问题。
+
+```arkts
+@Computed
+get sum() {
+  return this.count1 + this.count2 + this.count3;
+}
+```
+
+```arkts
+Text(`${this.count1 + this.count2 + this.count3}`) // 计算this.count1 + this.count2 + this.count3
+Text(`${this.count1 + this.count2 + this.count3}`) // 重复计算this.count1 + this.count2 + this.count3
+Text(`${this.sum}`) // 读取@Computed sum的缓存值，节省上述重复计算
+Text(`${this.sum}`) // 读取@Computed sum的缓存值，节省上述重复计算
+```
+
+在阅读本文档前，建议提前阅读：
+- [@ComponentV2](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-custom-components)
+- [@ObservedV2和@Trace](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-observedv2-and-trace)
+- [@Local](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-local)
+
+@Computed装饰器从API version 12开始支持。
+从API version 12开始，该装饰器支持在元服务中使用。
+从API version 23开始，该装饰器支持在ArkTS卡片中使用。
+
+## 概述
+
+@Computed为方法装饰器，装饰getter方法。@Computed会检测被计算的属性变化，当被计算的属性变化时，@Computed只会被求解一次。不建议在@Computed中修改变量，错误的使用会导致数据无法被追踪或appfreeze等问题。
+
+但需要注意，对于简单计算，不建议使用计算属性，因为计算属性本身也有开销。对于复杂的计算，@Computed能带来性能收益。
+
+## 装饰器说明
+
+@Computed语法：
+```arkts
+@Computed
+get varName(): T {
+    return value;
+}
+```
+
+| @Computed方法装饰器 | 说明 |
+| --- | --- |
+| 支持类型 | getter访问器。 |
+| 从父组件初始化 | 禁止。 |
+| 可初始化子组件 | [@Param](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-param)。 |
+| 被执行的时机 | @ComponentV2中的@Computed会在自定义组件创建的时候初始化，触发@Computed计算。@ObservedV2装饰的类中的@Computed，会在@ObservedV2装饰的类实例创建后，异步初始化，触发@Computed计算。在@Computed中计算的状态变量被改变时，计算属性会重新计算。 |
+| 是否允许赋值 | @Computed装饰的属性是只读的，不允许赋值。 |
+
+## 使用限制
+
+1. @Computed为方法装饰器，仅能装饰getter方法。
+```arkts
+@Computed
+get fullName() { // 正确用法
+  return this.firstName + ' ' + this.lastName;
+}
+@Computed val: number = 0; // 错误用法，编译时报错
+@Computed
+func() { // 错误用法，编译时报错
+}
+```
+
+2. @Computed装饰的方法只有在初始化，或者其被计算的状态变量改变时，才会发生重新计算。不建议开发者在@Computed装饰的getter方法中做除获取数据外其余的逻辑操作。
+```arkts
+@Entry
+@ComponentV2
+struct Page {
+  @Local firstName: string = 'Hua';
+  @Local lastName: string = 'Li';
+  @Local showFullNameRequestCount: number = 0;
+  private fullNameRequestCount: number = 0;
+  @Computed
+  get fullName() {
+    console.info('fullName');
+    // 不建议在@Computed的计算中做赋值逻辑
+    this.fullNameRequestCount++;
+    return this.firstName + ' ' + this.lastName;
+  }
+  build() {
+    Column() {
+      Text(`${this.fullName}`)
+      Text(`${this.fullName}`)
+      Text(`count ${this.showFullNameRequestCount}`)
+      Button('get fullName').onClick(() => {
+        this.showFullNameRequestCount = this.fullNameRequestCount;
+      })
+    }
+  }
+}
+```
+
+3. 在@Computed装饰的getter方法中，不能改变参与计算的属性，以防止重复执行计算属性导致的appfreeze。
+```arkts
+@Entry
+@ComponentV2
+struct Page {
+  @Local firstName: string = 'Hua';
+  @Local lastName: string = 'Li';
+  @Computed
+  get fullName1() {
+    console.info('fullName1');
+    this.lastName += 'a'; // 错误，不能改变参与计算的属性
+    return this.firstName + ' ' + this.lastName;
+  }
+  @Computed
+  get fullName2() {
+    console.info('fullName2');
+    this.firstName += 'a'; // 错误，不能改变参与计算的属性
+    return this.firstName + ' ' + this.lastName;
+  }
+  build() {
+    Column() {
+      Text(`${this.fullName1}`)
+      Text(`${this.fullName2}`)
+    }
+  }
+}
+```
+
+4. @Computed不能和双向绑定!!连用，@Computed装饰的是getter访问器，不会被子组件同步，也不能被赋值。
+```arkts
+@ComponentV2
+struct Child {
+  @Param double: number = 100;
+  @Event $double: (val: number) => void;
+  build() {
+    Button('ChildChange')
+      .onClick(() => {
+        this.$double(200);
+      })
+  }
+}
+@Entry
+@ComponentV2
+struct Index {
+  @Local count: number = 100;
+  @Computed
+  get double() {
+    return this.count * 2;
+  }
+  set double(newValue : number) {
+    this.count = newValue / 2;
+  }
+  build() {
+    Scroll() {
+      Column({ space: 3 }) {
+        Text(`${this.count}`)
+        Child({ double: this.double!! }) // 错误写法
+      }
+    }
+  }
+}
+```
+
+5. @Computed为状态管理V2提供的能力，只能在@ComponentV2和@ObservedV2中使用。
+
+6. 多个@Computed一起使用时，警惕循环求解，以防止计算过程中的死循环。
+```arkts
+@Local a : number = 1;
+@Computed
+get b() {
+  return this.a + ' ' + this.c;  // 错误写法，存在循环
+}
+@Computed
+get c() {
+  return this.a + ' ' + this.b; // 错误写法，存在循环
+}
+```
+
+## 使用场景
+
+### 当被计算的属性变化时，@Computed装饰的getter访问器只会被求解一次
+
+**1. 在自定义组件中使用计算属性**
+
+点击第一个Button改变lastName，触发@Computed fullName重新计算。this.fullName被绑定在两个Text组件上，计算只发生了一次。
+
+```arkts
+import { hilog } from '@kit.PerformanceAnalysisKit';
+const TAG = '[Sample_Textcomponent]';
+const DOMAIN = 0xF811;
+const BUNDLE = 'Textcomponent_';
+
+@Entry
+@ComponentV2
+struct CustomComponentUse {
+  @Local firstName: string = 'Li';
+  @Local lastName: string = 'Hua';
+  age: number = 20;
+  @Computed
+  get fullName() {
+    hilog.info(DOMAIN, TAG, BUNDLE + '---------Computed----------');
+    return this.firstName + ' ' + this.lastName + this.age;
+  }
+  build() {
+    Column() {
+      Text(this.lastName + ' ' + this.firstName)
+      Text(this.lastName + ' ' + this.firstName)
+      Divider()
+      Text(this.fullName)
+      Text(this.fullName)
+      Button('changed lastName')
+        .onClick(() => {
+          this.lastName += 'a';
+        })
+      Button('changed age')
+        .onClick(() => {
+          this.age++;  // 无法触发Computed
+        })
+    }
+  }
+}
+```
+
+计算属性本身会带来性能开销，在实际应用开发中需要注意：
+- 对于简单的计算逻辑，可以不使用计算属性。
+- 如果计算逻辑在视图中仅使用一次，则不使用计算属性，直接求解。
+
+**2. 在@ObservedV2装饰的类中使用计算属性**
+
+点击Button改变lastName，触发@Computed fullName重新计算，且只被计算一次。
+
+```arkts
+import { hilog } from '@kit.PerformanceAnalysisKit';
+const TAG = '[Sample_Textcomponent]';
+const DOMAIN = 0xF811;
+const BUNDLE = 'Textcomponent_';
+
+@ObservedV2
+class Name {
+  @Trace public firstName: string = 'Hua';
+  @Trace public lastName: string = 'Li';
+  @Computed
+  get fullName() {
+    hilog.info(DOMAIN, TAG, BUNDLE + '---------Computed----------');
+    return this.firstName + ' ' + this.lastName;
+  }
+}
+
+const name: Name = new Name();
+@Entry
+@ComponentV2
+struct ObservedV2ClassUser {
+  name1: Name = name;
+  build() {
+    Column() {
+      Text(this.name1.fullName)
+      Text(this.name1.fullName)
+      Button('changed lastName').onClick(() => {
+        this.name1.lastName += 'a';
+      })
+    }
+  }
+}
+```
+
+### @Computed装饰的属性可以被@Monitor监听变化
+
+使用计算属性求解fahrenheit和kelvin：
+
+```arkts
+import { hilog } from '@kit.PerformanceAnalysisKit';
+const TAG = '[Sample_Textcomponent]';
+const DOMAIN = 0xF811;
+const BUNDLE = 'Textcomponent_';
+
+@Entry
+@ComponentV2
+struct ComputedPropertyResolution {
+  @Local celsius: number = 20;
+  @Computed
+  get fahrenheit(): number {
+    return this.celsius * 9 / 5 + 32;
+  }
+  @Computed
+  get kelvin(): number {
+    return (this.fahrenheit - 32) * 5 / 9 + 273.15;
+  }
+  @Monitor('kelvin')
+  onKelvinMonitor(mon: IMonitor) {
+    hilog.info(DOMAIN, TAG, BUNDLE + 'kelvin changed from' + mon.value()?.before + ' to ' + mon.value()?.now);
+  }
+  build() {
+    Column({ space: 20 }) {
+      Row({ space: 20 }) {
+        Button('-')
+          .onClick(() => {
+            this.celsius--;
+          })
+        Text(`Celsius ${this.celsius.toFixed(1)}`).fontSize(40)
+        Button('+')
+          .onClick(() => {
+            this.celsius++;
+          })
+      }
+      Text(`Fahrenheit ${this.fahrenheit.toFixed(2)}`).fontSize(40)
+      Text(`Kelvin ${this.kelvin.toFixed(2)}`).fontSize(40)
+    }
+    .width('100%')
+  }
+}
+```
+
+### @Computed装饰的属性可以初始化@Param
+
+使用@Computed初始化@Param：
+
+```arkts
+@ObservedV2
+class Article {
+  @Trace public quantity: number = 0;
+  public unitPrice: number = 0;
+  constructor(quantity: number, unitPrice: number) {
+    this.quantity = quantity;
+    this.unitPrice = unitPrice;
+  }
+}
+
+@Entry
+@ComponentV2
+struct ComputingInitParam {
+  @Local shoppingBasket: Article[] = [new Article(1, 20), new Article(5, 2)];
+  @Computed
+  get total(): number {
+    return this.shoppingBasket.reduce((acc: number, item: Article) => acc + (item.quantity * item.unitPrice), 0);
+  }
+  @Computed
+  get qualifiesForDiscount(): boolean {
+    return this.total >= 100;
+  }
+  build() {
+    Column() {
+      Text(`Shopping List: `)
+        .fontSize(30)
+      ForEach(this.shoppingBasket, (item: Article) => {
+        Row() {
+          Text(`unitPrice: ${item.unitPrice}`)
+          Button('-')
+            .onClick(() => {
+              if (item.quantity > 0) {
+                item.quantity--;
+              }
+            })
+          Text(`quantity: ${item.quantity}`)
+          Button('+')
+            .onClick(() => {
+              item.quantity++;
+            })
+        }
+        Divider()
+      })
+      Child({ total: this.total, qualifiesForDiscount: this.qualifiesForDiscount })
+    }.alignItems(HorizontalAlign.Start)
+  }
+}
+
+@ComponentV2
+struct Child {
+  @Param total: number = 0;
+  @Param qualifiesForDiscount: boolean = false;
+  build() {
+    Row() {
+      Text(`Total: ${this.total} `)
+        .fontSize(30)
+      Text(`Discount: ${this.qualifiesForDiscount} `)
+        .fontSize(30)
+    }
+  }
+}
+```

package/skills/hmos-incremental-ui-align/references/MVVM/345/274/200/345/217/221/346/226/207/346/241/243V2/@Event/350/243/205/351/245/260/345/231/250/357/274/232/350/247/204/350/214/203/347/273/204/344/273/266/350/276/223/345/207/272.md

@@ -0,0 +1,158 @@
+为了实现子组件向父组件要求更新@Param装饰变量的能力，开发者可以使用@Event装饰器。使用@Event装饰回调方法是一种规范，表明子组件需要传入更新数据源的回调。
+
+@Event主要配合@Param实现数据的双向同步。在阅读本文档前，建议提前阅读：[@Param](../@Param：组件外部输入/arkts-new-param.md)。
+
+说明
+
+从API version 12开始，在@ComponentV2装饰的自定义组件中支持使用@Event装饰器。
+
+从API version 12开始，该装饰器支持在元服务中使用。
+
+从API version 23开始，该装饰器支持在ArkTS卡片中使用。
+
+## 概述
+
+由于@Param装饰的变量在本地无法更改，使用@Event装饰器装饰回调方法并调用，可以实现更新数据源的变量，再通过[@Local](../@Local装饰器：组件内部状态/arkts-new-local.md)的同步机制，将修改同步回@Param装饰的变量，以此达到主动更新@Param装饰变量的效果。
+
+@Event用于装饰组件对外输出的方法：
+
+* @Event装饰的回调方法中参数以及返回值由开发者决定。
+* @Event装饰非回调类型的变量不会生效。当@Event没有初始化时，会自动生成一个空的函数作为默认回调。
+* 当@Event未被外部初始化，但本地有默认值时，会使用本地默认的函数进行处理。
+
+@Param标志着组件的输入，表明该变量受父组件影响，而@Event标志着组件的输出，可以通过该方法影响父组件。使用@Event装饰回调方法是一种规范，表明该回调作为自定义组件的输出。父组件需要判断是否提供对应方法用于子组件更改@Param变量的数据源。
+
+## 装饰器说明
+
+| @Event属性装饰器 | 说明 |
+| --- | --- |
+| 装饰器参数 | 无。 |
+| 允许装饰的变量类型 | 回调方法，例如()=>void、(x:number)=>boolean等。回调方法是否含有参数以及返回值由开发者决定。 |
+| 允许传入的函数类型 | 箭头函数。 |
+
+## 限制条件
+
+* @Event只能用在[@ComponentV2](../../../../学习UI范式基本语法/自定义组件/创建自定义组件/arkts-create-custom-components.md#componentv2)装饰的自定义组件中。当装饰非方法类型的变量时，不会有任何作用。
+
+  ```
+  1. @ComponentV2
+  2. struct Index {
+  3. @Event changeFactory: () => void = () => {}; // 正确用法
+  4. @Event message: string = 'abcd'; // 错误用法，装饰非函数类型变量，@Event无作用
+  5. }
+  6. @Component
+  7. struct Index {
+  8. @Event changeFactory: () => void = () => {}; // 错误用法，编译时报错
+  9. }
+  ```
+
+## 使用场景
+
+### 更改父组件中变量
+
+使用@Event可以更改父组件中变量，当该变量作为子组件@Param变量的数据源时，该变化会同步回子组件的@Param变量。
+
+```
+1. @Entry
+2. @ComponentV2
+3. struct Index {
+4. @Local title: string = 'Title One';
+5. @Local fontColor: Color = Color.Red;
+
+7. build() {
+8. Column() {
+9. Child({
+10. title: this.title,
+11. fontColor: this.fontColor,
+12. changeFactory: (type: number) => {
+13. if (type == 1) {
+14. this.title = 'Title One';
+15. this.fontColor = Color.Red;
+16. } else if (type == 2) {
+17. this.title = 'Title Two';
+18. this.fontColor = Color.Green;
+19. }
+20. }
+21. })
+22. }
+23. }
+24. }
+
+26. @ComponentV2
+27. struct Child {
+28. @Param title: string = '';
+29. @Param fontColor: Color = Color.Black;
+30. @Event changeFactory: (x: number) => void = (x: number) => {};
+
+32. build() {
+33. Column() {
+34. Text(`${this.title}`)
+35. .fontColor(this.fontColor)
+36. // 使用changeFactory更改父组件中的变量type
+37. Button('change to Title Two')
+38. .onClick(() => {
+39. this.changeFactory(2);
+40. })
+41. Button('change to Title One')
+42. .onClick(() => {
+43. this.changeFactory(1);
+44. })
+45. }
+46. }
+47. }
+```
+
+[EventDecoratorTest1.ets](https://gitcode.com/HarmonyOS_Samples/guide-snippets/blob/HarmonyOS-feature-20260402/ArkUISample/EventDecorator/entry/src/main/ets/pages/EventDecoratorTest1.ets#L15-L62)
+
+值得注意的是，使用@Event修改父组件的值是立刻生效的，但从父组件将变化同步回子组件的过程是异步的，即在调用完@Event的方法后，子组件内的值不会立刻变化。这是因为@Event将子组件值实际的变化能力交由父组件处理，在父组件实际决定如何处理后，将最终值在渲染之前同步回子组件。
+
+```
+1. import { hilog } from '@kit.PerformanceAnalysisKit';
+2. const TAG = '[Sample_EventDecorator]';
+3. const DOMAIN = 0xF811;
+4. @ComponentV2
+5. struct Child2 {
+6. @Param index: number = 0;
+7. @Event changeIndex: (val: number) => void;
+
+9. build() {
+10. Column() {
+11. Text(`Child index: ${this.index}`)
+12. .onClick(() => {
+13. this.changeIndex(20);
+14. // 输出子组件this.index，验证调用@Event后值不会立即同步回子组件
+15. hilog.info(DOMAIN, TAG, `after changeIndex ${this.index}`);
+16. })
+17. }
+18. }
+19. }
+20. @Entry
+21. @ComponentV2
+22. struct Index2 {
+23. @Local index: number = 0;
+
+25. build() {
+26. Column() {
+27. Child2({
+28. index: this.index,
+29. changeIndex: (val: number) => {
+30. this.index = val;
+31. // 输出父组件的index，用于对比子组件侧日志
+32. hilog.info(DOMAIN, TAG, `in changeIndex ${this.index}`);
+33. }
+34. })
+35. }
+36. }
+37. }
+```
+
+[EventDecoratorTest2.ets](https://gitcode.com/HarmonyOS_Samples/guide-snippets/blob/HarmonyOS-feature-20260402/ArkUISample/EventDecorator/entry/src/main/ets/pages/EventDecoratorTest2.ets#L15-L51)
+
+在上面的示例中，点击文字触发@Event函数事件改变子组件的值，打印出的日志为：
+
+```
+1. in changeIndex 20
+2. after changeIndex 0
+```
+
+这表明在调用changeIndex之后，父组件中index的值已经变化，但子组件中的index值还没有同步变化。