DEV Community: Freerain

鸿蒙Next状态管理V2 - @Once初始化用法总结

Freerain — Fri, 27 Dec 2024 01:20:17 +0000

一、概述

@Once装饰器用于实现变量仅在初始化时同步一次外部传入值，后续数据源更改时不会将修改同步给子组件。其必须搭配@Param使用，且不影响@Param的观测能力，仅拦截数据源变化，与@Param装饰变量的先后顺序不影响实际功能，并且在搭配使用时可在本地修改@Param变量的值。

二、装饰器使用规则说明

（一）@Once变量装饰器

装饰器参数：无。
使用条件：无法单独使用，必须配合@Param装饰器使用。

（二）限制条件

@Once只能用在@ComponentV2装饰的自定义组件中且仅能与@Param搭配使用。例如：

@ComponentV2
struct CompA {
  @Param @Once onceParam: string = "onceParam"; // 正确用法
  @Once onceStr: string = "Once"; // 错误用法，@Once无法单独使用
  @Local @Once onceLocal: string = "onceLocal"; // 错误用法，@Once不能与@Local一起使用
}
@Component
struct Index {
  @Once @Param onceParam: string = "onceParam"; // 错误用法
}

@Once与@Param的先后顺序无关，如@ComponentV2结构中写成@Param @Once或@Once @param均可。

@ComponentV2
struct CompA {
  @Param @Once param1: number;
  @Once @Param param2: number;
}

三、使用场景

（一）变量仅初始化同步一次

适用于期望变量仅在初始化时同步数据源一次，之后不再继续同步变化的场景。例如：

@ComponentV2
struct CompA {
  @Param @Once onceParam: string = '';
  build() {
      Column() {
        Text(`onceParam: ${this.onceParam}`)
      }
  }
}

@Entry
@ComponentV2
struct CompB {
  @Local message: string = "Hello World";
  build() {
      Column() {
      Text(`Parent message: ${this.message}`)
      Button("change message")
       .onClick(() => {
          this.message = "Hello Tomorrow";
        })
      CompA({ onceParam: this.message })
      }
  }
}

（二）本地修改@Param变量

当@Once搭配@Param使用时，可解除@Param无法在本地修改的限制，且修改能触发UI刷新，此时相当于@Local，但@Param @Once能接受外部传入初始化。例如：

@ObservedV2
class Info {
  @Trace name: string;
  constructor(name: string ) {
    this.name = name;
  }
}

@ComponentV2
struct Child {
  @Param @Once onceParamNum: number = 0;
  @Param @Once @Require onceParamInfo: Info;
  build() {
    Column() {
      Text(`Child onceParamNum: ${this.onceParamNum}`)
      Text(`Child onceParamInfo: ${this.onceParamInfo.name}`)
      Button("changeOnceParamNum")
       .onClick(() => {
          this.onceParamNum++;
        })
      Button("changeParamInfo")
       .onClick(() => {
          this.onceParamInfo = new Info("Cindy");
        })
    }
  }
}

@Entry
@ComponentV2
struct Index {
  @Local localNum: number = 10;
  @Local localInfo: Info = new Info("Tom");
  build() {
    Column() {
      Text(`Parent localNum: ${this.localNum}`)
      Text(`Parent localInfo: ${this.localInfo.name}`)
      Button("changeLocalNum")
       .onClick(() => {
          this.localNum++;
        })
      Button("changeLocalInfo")
       .onClick(() => {
          this.localInfo = new Info("Cindy");
        })
      Child({
        onceParamNum: this.localNum,
        onceParamInfo: this.localInfo
      })
    }
  }
}

鸿蒙Next状态管理V2 - @Param装饰器总结

Freerain — Thu, 26 Dec 2024 00:37:50 +0000

一、概述

为增强子组件接受外部参数输入的能力，开发者可使用@Param装饰器。从API version 12开始，在@ComponentV2装饰的自定义组件中支持使用@Param装饰器。当前状态管理（V2试用版）相关功能尚未成熟，建议开发者尝鲜试用。

（一）功能特点

表示外部传入状态：使得父子组件之间的数据能够进行同步。
变量初始化：支持本地初始化，但不允许在组件内部直接修改变量本身（对于对象类型的变量，可修改其内部属性）。若不在本地初始化，则需和@Require装饰器一起使用，要求必须从外部传入初始化。
同步类型：由父到子单向同步。
接受多种数据源：可以接受任意类型的数据源，包括普通变量、状态变量、常量、函数返回值等，同时支持null、undefined以及联合类型。
触发UI刷新：@Param装饰的变量变化时，会刷新该变量关联的组件。

（二）与状态管理V1版本装饰器对比

状态管理V1版本常用的可接受外部传入的装饰器（如@State、@Prop、@Link、@ObjectLink）存在使用限制多、不易区分的问题，使用不当时还会导致性能问题。例如@State仅能在初始化时获得引用，改变后无法同步；@Prop单向同步复杂类型时深拷贝性能差；@Link要求数据源也是状态变量；@ObjectLink要求属性类型为@Observed装饰的类。因此推出@Param装饰器简化父子组件传值规则。

二、装饰器说明

（一）变量装饰器参数

无参数。

（二）能否本地修改

否，修改值需使用@Event装饰器的能力（对于对象类型变量，可修改其内部属性）。

（三）同步类型

由父到子单向同步。

（四）允许装饰的变量类型

包括Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型，支持null、undefined以及联合类型。

（五）被装饰变量的初始值

允许本地初始化，若不在本地初始化，则需要和@Require装饰器一起使用，要求必须从外部传入初始化。当同时存在本地初始值与外部传入值时，优先使用外部传入值进行初始化。

三、变量传递规则

（一）从父组件初始化

@Param装饰的变量允许本地初始化，若无本地初始化则必须从外部传入初始化。

（二）初始化子组件

@Param装饰的变量可以初始化子组件中@Param装饰的变量。

（三）同步

@Param可以和父组件传入的状态变量数据源（即@Local或@Param装饰的变量）进行同步，当数据源发生变化时，会将修改同步给子组件的@Param。

四、观察变化

（一）基本类型（boolean、string、number）

可以观察来自数据源同步的变化。例如：

@Entry
@ComponentV2
struct Index {
  @Local count: number = 0;
  @Local message: string = "Hello";
  @Local flag: boolean = false;
  build() {
    Column() {
      Text(`Local ${this.count}`)
      Text(`Local ${this.message}`)
      Text(`Local ${this.flag}`)
      Button("change Local")
      .onClick(() => {
          // 对数据源的更改会同步给子组件
          this.count++;
          this.message += " World";
          this.flag =!this.flag;
      })
      Child({
        count: this.count,
        message: this.message,
        flag: this.flag
      })
    }
  }
}
@ComponentV2
struct Child {
  @Require @Param count: number;
  @Require @Param message: string;
  @Require @Param flag: boolean;
  build() {
    Column() {
      Text(`Param ${this.count}`)
      Text(`Param ${this.message}`)
      Text(`Param ${this.flag}`)
    }
  }
}

（二）类对象

仅可以观察到对类对象整体赋值的变化，无法直接观察到对类成员属性赋值的变化，对类成员属性的观察依赖@ObservedV2和@Trace装饰器。例如：

class RawObject {
  name: string;
  constructor(name: string ) {
    this.name = name;
  }
}
@ObservedV2
class ObservedObject {
  @Trace name: string;
  constructor(name: string ) {
    this.name = name;
  }
}
@Entry
@ComponentV2
struct Index {
  @Local rawObject: RawObject = new RawObject("rawObject");
  @Local observedObject: ObservedObject = new ObservedObject("observedObject");
  build() {
    Column() {
      Text(`${this.rawObject.name}`)
      Text(`${this.observedObject.name}`)
      Button("change object")
      .onClick(() => {
          // 对类对象整体的修改均能观察到
          this.rawObject = new RawObject("new rawObject");
          this.observedObject = new ObservedObject("new observedObject");
      })
      Button("change name")
      .onClick(() => {
          // @Local与@Param均不具备观察类对象属性的能力，因此对rawObject.name的修改无法观察到
          this.rawObject.name = "new rawObject name";
          // 由于ObservedObject的name属性被@Trace装饰，因此对observedObject.name的修改能被观察到
          this.observedObject.name = "new observedObject name";
      })
      Child({
        rawObject: this.rawObject,
        observedObject: this.observedObject
      })
    }
  }
}
@ComponentV2
struct Child {
  @Require @Param rawObject: RawObject;
  @Require @Param observedObject: ObservedObject;
  build() {
    Column() {
      Text(`${this.rawObject.name}`)
      Text(`${this.observedObject.name}`)
    }
  }
}

（三）简单类型数组

可以观察到数组整体或数组项的变化。例如：

@Entry
@ComponentV2
struct Index {
  @Local numArr: number[] = [1,2,3,4,5];
  @Local dimensionTwo: number[][] = [[1,2,3],[4,5,6]];
  build() {
    Column() {
      Text(`${this.numArr[0]}`)
      Text(`${this.numArr[1]}`)
      Text(`${this.numArr[2]}`)
      Text(`${this.dimensionTwo[0][0]}`)
      Text(`${this.dimensionTwo[1][1]}`)
      Button("change array item")
      .onClick(() => {
          this.numArr[0]++;
          this.numArr[1] += 2;
          this.dimensionTwo[0][0] = 0;
          this.dimensionTwo[1][1] = 0;
        })
      Button("change whole array")
      .onClick(() => {
          this.numArr = [5,4,3,2,1];
          this.dimensionTwo = [[7,8,9],[0,1,2]];
        })
      Child({
        numArr: this.numArr,
        dimensionTwo: this.dimensionTwo
      })
    }
  }
}
@ComponentV2
struct Child {
  @Require @Param numArr: number[];
  @Require @Param dimensionTwo: number[][];
  build() {
    Column() {
      Text(`${this.numArr[0]}`)
      Text(`${this.numArr[1]}`)
      Text(`${this.numArr[2]}`)
      Text(`${this.dimensionTwo[0][0]}`)
      Text(`${this.dimensionTwo[1][1]}`)
    }
  }
}

（四）嵌套类或对象数组

@Param无法观察深层对象属性的变化，对深层对象属性的观测依赖@ObservedV2与@Trace装饰器。例如：

@ObservedV2
class Region {
  @Trace x: number;
  @Trace y: number;
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}
@ObservedV2
class Info {
  @Trace region: Region;
  @Trace name: string;
  constructor(name: string, x: number, y: number ) {
    this.name = name;
    this.region = new Region(x, y);
  }
}
@Entry
@ComponentV2
struct Index {
  @Local infoArr: Info[] = [new Info("Ocean", 28, 120), new Info("Mountain", 26, 20)];
  @Local originInfo: Info = new Info("Origin", 0, 0);
  build() {
    Column() {
      ForEach(this.infoArr, (info: Info) => {
        Row() {
          Text(`name: ${info.name}`)
          Text(`region: ${info.region.x}-${info.region.y}`)
        }
      })
      Row() {
        Text(`Origin name: ${this.originInfo.name}`)
        Text(`Origin region: ${this.originInfo.region.x}-${this.originInfo.region.y}`)
      }
      Button("change infoArr item")
      .onClick(() => {
          // 由于属性name被@Trace装饰，所以能够观察到
          this.infoArr[0].name = "Win";
        })
      Button("change originInfo")
      .onClick(() => {
          // 由于变量originInfo被@Local装饰，所以能够观察到
          this.originInfo = new Info("Origin", 100, 100);
        })
      Button("change originInfo region")
      .onClick(() => {
          // 由于属性x、y被@Trace装饰，所以能够观察到
          this.originInfo.region.x = 25;
          this.originInfo.region.y = 25;
        })
    }
  }
}
@ComponentV2
struct Child {
  @Param infoArr: Info[] = [];
  @Param originInfo: Info = new Info("O", 0, 0);
  build() {
    Column() {
      ForEach(this.infoArr, (info: Info) => {
        Row() {
          Text(`name: ${info.name}`)
          Text(`region: ${info.region.x}-${info.region.y}`)
        }
      })
      Row() {
        Text(`Origin name: ${this.originInfo.name}`)
        Text(`Origin region: ${this.originInfo.region.x}-${this.originInfo.region.y}`)
      }
    }
  }
}

（五）内置类型（Array、Date、Map、Set）

Array：可以观察到变量整体赋值以及通过API调用（如push、pop、shift、unshift、splice、copyWithin、fill、reverse、sort）带来的变化。
Date：可以观察到数据源对Date整体的赋值，以及调用Date的接口（如setFullYear、setMonth、setDate、setHours、setMinutes、setSeconds、setMilliseconds、setTime、setUTCFullYear、setUTCMonth、setUTCDate、setUTCHours、setUTCMinutes、setUTCSeconds、setUTCMilliseconds）带来的变化。
Map：可以观察到数据源对Map整体的赋值，以及调用Map的接口（如set、clear、delete）带来的变化。
Set：可以观察到数据源对Set整体的赋值，以及调用Set的接口（如add、clear、delete）带来的变化。

五、限制条件

@Param装饰器只能在@ComponentV2装饰器的自定义组件中使用。
@Param装饰的变量表示组件外部输入，需要被初始化。支持使用本地初始值做初始化，当存在外部传入值时，将优先使用外部传入的值初始化，既不使用本地初始值，也不使用外部传入值是不允许的。
@Param装饰的变量在子组件中无法进行修改（但对于对象类型变量，可修改其内部属性）。

六、使用场景

（一）从父组件到子组件变量传递与同步

@Param能够接受父组件@Local或@Param传递的数据并与之变化同步。例如：

@ObservedV2
class Region {
  @Trace x: number;
  @Trace y: number;
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}
@ObservedV2
class Info {
  @Trace name: string;
  @Trace age: number;
  @Trace region: Region;
  constructor(name: string, age: number, x: number, y: number ) {
    this.name = name;
    this.age = age;
    this.region = new Region(x, y);
  }
}
@Entry
@ComponentV2
struct Index {
  @Local infoList: Info[] = [new Info("Alice", 8, 0, 0), new Info("Barry", 10, 1, 20), new Info("Cindy", 18, 24, 40)];
  build() {
    Column() {
      ForEach(this.infoList, (info: Info) => {
        MiddleComponent({ info: info })
      })
      Button("change")
      .onClick(() => {
          this.infoList[0] = new Info("Atom", 40, 27, 90);
          this.infoList[1].name = "Bob";
          this.infoList[2].region = new Region(7, 9);
        })
    }
  }
}
@ComponentV2
struct MiddleComponent {
  @Require @Param info: Info;
  build() {
    Column() {
      Text(`name: ${this.info.name}`)
      Text(`age: ${this.info.age}`)
      SubComponent({ region: this.info.region })
    }
  }
}
@ComponentV2
struct SubComponent {
  @Require @Param region: Region;
  build() {
    Column() {
      Text(`region: ${this.region.x}-${this.region.y}`)
    }
  }
}

（二）装饰特定类型变量

Date类型变量：可以观察到数据源对Date整体的赋值，以及调用Date相关接口带来的变化。
Map类型变量：可以观察到数据源对Map整体的赋值，以及调用Map相关接口带来的变化。
Set类型变量：可以观察到数据源对Set整体的赋值，以及调用Set相关接口带来的变化。

（三）联合类型

@Param支持null、undefined以及联合类型。例如：

@Entry
@ComponentV2
struct Index {
  @Local count: number | undefined = 0;
  build() {
    Column() {
      // 相关操作及UI展示
    }
  }
}

综上所述，@Param装饰器在鸿蒙Next状态管理V2中为父子组件间的数据传递与同步提供了更方便的机制，开发者在使用时需注意其功能特点、变量传递规则、观察变化范围、限制条件以及不同类型变量的使用场景等，以便更好地在项目中应用该装饰器进行状态管理。

鸿蒙Next状态管理V2-Local装饰器总结

Freerain — Wed, 25 Dec 2024 00:53:58 +0000

一、引言

在鸿蒙Next的开发中，状态管理是构建高效、响应式应用的关键部分。@Local装饰器作为状态管理V2中的重要特性，为开发者提供了一种有效的方式来管理组件内部状态。本文将对@Local装饰器进行全面总结，包括其功能、使用方法、与@State装饰器的对比以及常见问题的解决方法等。

二、@Local装饰器概述

（一）功能

@Local装饰器用于标识组件内部状态，使自定义组件内被装饰的变量具备观测变化的能力，当变量值改变时，能自动刷新使用该变量的组件。

（二）版本支持

从API version 12开始，可在@ComponentV2装饰的自定义组件中使用@Local装饰器。需注意当前状态管理（V2试用版）仍在开发中，功能尚未成熟。

三、装饰器说明

（一）参数

无参数。

（二）可装饰变量类型

支持Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型，还支持null、undefined以及联合类型。

（三）变量初始化

必须在组件内部进行初始化，不允许从外部传入初始化值。

四、变量传递规则

（一）从父组件初始化

@Local装饰的变量不允许从外部传入初始化。

（二）初始化子组件

可以用于初始化子组件中@Param装饰的变量。

五、观察变化机制

（一）简单类型（boolean、string、number）

能观测到对变量的赋值变化，如在示例中对count、message、flag的操作，改变值后UI会刷新。

（二）类对象类型

仅能观测到对类对象整体赋值的变化，对类成员属性赋值的变化需依赖@ObservedV2和@Trace装饰器。例如，对rawObject整体赋值可观测，而直接修改其成员属性name无法观测，但对于observedObject（其name属性被@Trace装饰），修改name可被观测。

（三）简单类型数组

可以观察到数组整体或数组项的变化，如修改numArr的数组项或整体赋值，UI都会刷新。

（四）嵌套类或对象数组

@Local无法观察深层对象属性的变化，深层对象属性的观测依赖@ObservedV2与@Trace装饰器。如infoArr数组中Info类对象的name属性（被@Trace装饰）变化可被观测，而直接修改region属性（被@Trace装饰）无法被@Local观测到，但originInfo整体赋值可被观测。

（五）内置类型（Array、Date、Map、Set）

可以观察到变量整体赋值以及通过相应API调用带来的变化，如Date类型可通过特定API更新属性，Map和Set类型可通过其接口进行数据更新并被观测到。

六、限制条件

（一）组件使用限制

只能在@ComponentV2装饰的自定义组件中使用，在@Component装饰的组件中使用会报错。

（二）外部初始化限制

表示组件内部状态，不允许从外部传入初始化值，否则会报错。

七、@Local与@State对比

（一）从父组件初始化

@State可选从外部初始化。
@Local不允许外部初始化。 ### （二）观察能力
@State能观测变量本身以及一层的成员属性，但无法深度观测。
@Local能观测变量本身，深度观测依赖@Trace装饰器。 ### （三）数据传递两者都可以作为数据源和子组件中状态变量同步。

八、使用场景

（一）观测对象整体变化

对于被@ObservedV2与@Trace装饰的类对象实例，虽有深度观测属性能力，但对象整体赋值时UI可能无法刷新，而@Local装饰对象可观测对象本身变化，如info2整体赋值时UI会刷新。

（二）装饰Date类型变量

可观察到Date整体赋值及通过其接口更新属性，如在DatePickerExample中对selectedDate的操作。

（三）装饰Map类型变量

能观察到Map整体赋值及通过接口set、clear、delete更新数据，如MapSample中的message。

（四）装饰Set类型变量

可观察到Set整体赋值及通过接口add、clear、delete更新数据，如SetSample中的message。

（五）联合类型

支持null、 undefined以及联合类型，如count为number | undefined类型，改变其类型时UI会刷新。

九、常见问题及解决方法

（一）问题描述

复杂类型常量重复赋值给状态变量会触发刷新，即使新值和本地初始化值相同。

（二）原因分析

状态管理V2中，对使用状态变量装饰器（如@Trace、@Local）装饰的Date、Map、Set、Array添加了代理用于观测API调用变化，再次赋值时，由于类型判断不同（代理类型和原始类型）会触发赋值和刷新。

（三）解决方法

使用UIUtils.getTarget()获取原始对象提前进行新旧值判断，当两者相同时不执行赋值，避免不必要的刷新。

十、总结

@Local装饰器在鸿蒙Next状态管理V2中为组件内部状态管理提供了重要功能，但在使用时需注意其限制条件和与其他装饰器的区别，根据具体场景合理运用，同时要注意常见问题的处理，以确保应用的高效运行和正确响应。随着鸿蒙系统的不断发展，@Local装饰器将在更多的应用场景中发挥重要作用，帮助开发者构建更加稳定和高效的应用程序。

鸿蒙Next类属性观测器V2

Freerain — Tue, 24 Dec 2024 00:27:27 +0000

一、引言

在鸿蒙Next开发中，类属性的观测对于状态管理至关重要。本文将详细介绍@ObservedV2装饰器和@Trace装饰器的功能、使用方法、限制以及应用场景，帮助开发者更好地理解和运用这两个装饰器进行类属性变化观测，从而实现更高效的状态管理。

二、装饰器概述

（一）功能

@ObservedV2与@Trace装饰器配合使用，赋予类和属性深度观测能力，使被装饰的类和属性在变化时能触发相应UI组件刷新，增强状态管理框架对类对象属性的观测能力。

（二）版本支持

从API version 12开始支持@ObservedV2与@Trace装饰器。

（三）注意事项

当前状态管理（V2试用版）仍在开发中，功能尚未成熟，开发者可尝鲜试用。

三、装饰器说明

（一）@ObservedV2类装饰器

参数：无。
作用：装饰class，放在class定义前，用于创建类对象，使类具备被观测的能力。

（二）@trace成员变量装饰器

参数：无。
作用：装饰class中的成员属性，属性类型可为number、string、boolean、class、Array、Date、Map、Set等，使被装饰属性变化时可被观测。

四、观察变化机制

（一）触发UI刷新条件

使用@ObservedV2装饰的类中，被@Trace装饰的属性值变化时，会触发该属性绑定的UI组件刷新。

（二）不同场景下的观测能力

嵌套类场景
- 当嵌套类中的属性被@Trace装饰且嵌套类被@ObservedV2装饰时，该属性变化具有触发UI刷新的能力。
- 例如，在Pencil类（被@ObservedV2装饰）中，属性length（被@Trace装饰）变化时，关联的UI组件会刷新。但如果son变量（非状态变量）重新赋值，即使length属性变化，UI也不会刷新。
继承类场景
- 无论是在基类还是继承类中，被@Trace装饰的属性变化都可被观测并触发UI刷新。
- 如在GrandFather类（被@ObservedV2装饰）中，属性age（被@Trace装饰），在Son类或Cousin类实例中改变age值，UI会相应刷新。
静态属性场景
- 类中被@Trace装饰的静态属性变化时，也能触发UI刷新。

（三）对内置类型的观测

@Trace装饰内置类型（如Array、Date、Map、Set等）时，可观测各自API导致的变化，具体API如下：
|类型|可观测变化的API|
|---|---|
|Array|push、pop、shift、unshift、splice、copyWithin、fill、reverse、sort|
|Date|setFullYear, setMonth, setDate, setHours, setMinutes, setSeconds, setMilliseconds, setTime, setUTCFullYear, setUTCMonth, setUTCDate, setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds|
|Map|set, clear, delete|
|Set|add, clear, delete|

五、使用限制

（一）UI刷新限制

非@Trace装饰的成员属性用在UI上无法触发UI刷新。

（二）装饰器使用限制

@Trace不能用在未被@ObservedV2装饰的class上。
@Trace不能用在struct中。
@ObservedV2、@Trace不能与@Observed、@Track混合使用。
使用@ObservedV2与@Trace装饰的类不能和@State等V1的装饰器混合使用，继承自@ObservedV2的类也无法和@State等V1的装饰器混用。
@ObservedV2的类实例目前不支持使用JSON.stringify进行序列化。

六、使用场景

（一）嵌套类场景

在嵌套类结构中，如Pencil类（被@ObservedV2装饰）中的length属性（被@Trace装饰），其变化可触发关联UI组件刷新。但如果外层非状态变量重新赋值，会导致UI无法观测到内部属性变化。

（二）继承类场景

在类继承关系中，如GrandFather类（被@ObservedV2装饰）的age属性（被@Trace装饰），在Son类或Cousin类实例中改变age值，UI会刷新。

（三）装饰不同类型

基础类型数组：@Trace装饰Arr类中的numberArr数组（@ObservedV2装饰Arr类），使用支持的数组API操作时可观测到变化。
对象数组：@Trace装饰Info类中的personList对象数组（@ObservedV2装饰Info类）以及Person类中的age属性，当personList或age改变时可观测到变化。
Map类型：@Trace装饰Info类中的memberMap（@ObservedV2装饰Info类），调用set、clear、delete等API时可观测到变化，对memberMap赋值也可观测。

七、总结

@ObservedV2装饰器和@Trace装饰器为鸿蒙Next开发者提供了强大的类属性观测能力，但在使用过程中需注意其使用限制，根据不同场景合理运用，以实现高效的状态管理和UI响应。随着状态管理框架的不断发展，这两个装饰器将在鸿蒙Next应用开发中发挥更重要的作用。

鸿蒙Next ArkTS高性能编程实战

Freerain — Mon, 23 Dec 2024 07:40:24 +0000

一、引言

在应用开发中，高性能编程对于提升用户体验至关重要。本文将详细介绍鸿蒙Next ArkTS在高性能编程方面的实践经验，包括声明与表达式、函数、数组以及异常处理等方面的优化技巧，助力开发者打造高效能的应用。

二、声明与表达式

（一）使用const声明不变的变量

在编程过程中，对于那些在后续代码中不会发生改变的变量，应使用const进行声明。这样做不仅可以使代码意图更加清晰，还能帮助编译器进行优化。例如：

const index = 10000; // 该变量在后续过程中未发生改变，建议声明成常量

（二）number类型变量避免整型和浮点型混用

ArkTS运行时在优化时会区分整型和浮点型数据，因此建议在初始化后避免改变number类型变量的数据类型。例如：

let intNum = 1;
intNum = 1.1; // 该变量在声明时为整型数据，建议后续不要赋值浮点型数据

let doubleNum = 1.1;
doubleNum = 1; // 该变量在声明时为浮点型数据，建议后续不要赋值整型数据

（三）数值计算避免溢出

在进行数值计算时，要特别注意可能导致溢出的情况。常见的溢出场景包括加法、减法、乘法、指数运算以及&（and）、>>>（无符号右移）等运算操作。溢出会导致引擎进入慢速的溢出逻辑分支处理，影响性能。因此，应确保数值在合适的范围内，避免大于INT32_MAX或小于INT32_MIN（对于某些运算操作，如&、>>>等，应避免大于INT32_MAX）。

（四）循环中常量提取，减少属性访问次数

在循环中，如果存在大量对常量的访问操作，且这些常量在循环过程中不会改变，那么可以将其提取到循环外部。这样可以减少属性访问的次数，提高性能。例如：

class Time {
    static start: number = 0;
    static info: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
}

function getNum(num: number): number {
    let total: number = 348;
    for (let index: number = 0x8000; index > 0x8; index >>= 1) {
        // 此处会多次对Time的info及start进行查找，并且每次查找出来的值是相同的
        total += ((Time.info[num - Time.start] & index)!== 0)? 1 : 0;
    }
    return total;
}

// 优化后代码
function getNum(num: number): number {
    let total: number = 348;
    const info = Time.info[num - Time.start]; // 从循环中提取不变量
    for (let index: number = 0x8000; index > 0x8; index >>= 1) {
        if ((info & index)!== 0) {
            total++;
        }
    }
    return total;
}

三、函数

（一）建议使用参数传递函数外的变量

使用闭包会带来额外的闭包创建和访问开销。在性能敏感场景中，应尽量使用参数传递函数外的变量来替代闭包。例如：

// 不推荐使用闭包的方式
let arr = [0, 1, 2];
function foo(): number {
    return arr[0] + arr[1];
}
foo();

// 推荐使用参数传递变量
let arr = [0, 1, 2];
function foo(array: number[]): number {
    return array[0] + array[1];
}
foo(arr);

（二）避免使用可选参数

函数的可选参数表示参数可能为undefined，在函数内部使用该参数时，需要进行非空值的判断，这会造成额外的开销。因此，根据业务需求，应将函数参数声明为必须参数，或者考虑使用默认参数。例如：

// 不推荐使用可选参数
function add(left?: number, right?: number): number | undefined {
    if (left!== undefined && right!== undefined) {
        return left + right;
    }
    return undefined;
}

// 推荐使用默认参数
function add(left: number = 0, right: number = 0): number {
    return left + right;
}

四、数组

（一）数值数组推荐使用TypedArray

在涉及纯数值计算的场景中，推荐使用TypedArray数据结构。它能够提供更好的性能表现。例如：

// 优化前
const arr1 = new Array<number>([1, 2, 3]);
const arr2 = new Array<number>([4, 5, 6]);
let res = new Array<number>(3);
for (let i = 0; i < 3; i++) {
    res[i] = arr1[i] + arr2[i];
}

// 优化后
const typedArray1 = new Int8Array([1, 2, 3]);
const typedArray2 = new Int8Array([4, 5, 6]);
let res = new Int8Array(3);
for (let i = 0; i < 3; i++) {
    res[i] = typedArray1[i] + typedArray2[i];
}

（二）避免使用稀疏数组

当运行时分配超过1024大小的数组或者处理稀疏数组时，会采用hash表的方式来存储元素，这相比于用偏移访问数组元素速度较慢。因此，在代码开发过程中，应尽量避免数组变成稀疏数组。例如：

// 直接分配100000大小的数组，运行时会处理成用hash表来存储元素
let count = 100000;
let result: number[] = new Array(count);

// 创建数组后，直接在9999处赋值，会变成稀疏数组
let result: number[] = new Array();
result[9999] = 0;

（三）避免使用联合类型数组

应避免在数值数组中混合使用整型数据和浮点型数据，以及使用联合类型数组。根据业务需求，将相同类型的数据放置在同一数组中。例如：

// 不推荐的写法
let arrNum: number[] = [1, 1.1, 2]; // 数值数组中混合使用整型数据和浮点型数据
let arrUnion: (number | string)[] = [1, 'hello']; // 联合类型数组

// 推荐的写法
let arrInt: number[] = [1, 2, 3];
let arrDouble: number[] = [0.1, 0.2, 0.3];
let arrString: string[] = ['hello', 'world'];

五、异常

避免频繁抛出异常

创建异常时会构造异常的栈帧，这会造成性能损耗。在性能敏感场景下，如for循环语句中，应避免频繁抛出异常。例如：

// 优化前
function div(a: number, b: number): number {
    if (a <= 0 || b <= 0) {
        throw new Error('Invalid numbers.')
    }
    return a / b
}

function sum(num: number): number {
    let sum = 0
    try {
        for (let t = 1; t < 100; t++) {
            sum += div(t, num)
        }
    } catch (e) {
        console.log(e.message)
    }
    return sum
}

// 优化后
function div(a: number, b: number): number {
    if (a <= 0 || b <= 0) {
        return NaN
    }
    return a / b
}

function sum(num: number): number {
    let sum = 0
    for (let t = 1; t < 100; t++) {
        if (t <= 0 || num <= 0) {
            console.log('Invalid numbers.')
        }
        sum += div(t, num)
    }
    return sum
}

通过遵循以上鸿蒙Next ArkTS高性能编程实践中的各项建议，开发者可以在实际开发中显著提升应用的性能表现，为用户带来更加流畅和高效的使用体验。同时，不断总结和运用高性能编程技巧，也是打造优质应用的重要环节。

鸿蒙Next ArkTS编程规范总结

Freerain — Mon, 23 Dec 2024 06:52:25 +0000

一、目标和适用范围

ArkTS编程规范参考业界标准及实践，结合ArkTS语言特点，旨在提高代码的规范、安全和性能，适用于开发者使用ArkTS编写代码的系统开发或应用开发场景。

二、规则来源

ArkTS在TypeScript基础上强化静态检查和分析，部分规则源于《OpenHarmony应用TS&JS编程指南》，并为ArkTS新增语法添加规则，以提升代码可读性和执行性能。

三、总体原则

规则分为要求和建议两个级别。要求原则上应遵从，目前本文所有内容均为针对ArkTS的要求；建议条款属于最佳实践，开发者可根据实际情况考虑是否采用。

四、命名规范

（一）标识符命名基本原则

能清晰表达意图，避免单个字母或无惯例缩写，使用正确英文单词且符合语法，避免误导。

（二）类名、枚举名、命名空间名

采用UpperCamelCase风格（首字母大写驼峰命名法），类名应为名词或名词短语，避免使用动词或模糊词。例如：

// 类名
class User {
  username: string
  constructor(username: string) {
    this.username = username;
  }
  sayHi() {
    console.log('hi' + this.username);
  }
}
// 枚举名
enum UserType {
  TEACHER = 0,
  STUDENT = 1
};
// 命名空间
namespace Base64Utils {
  function encrypt() {
    // todo encrypt
  }
  function decrypt() {
    // todo decrypt
  }
};

（三）变量名、方法名、参数名

采用lowerCamelCase风格（小驼峰命名法），函数名通常为动词或动词短语，变量名通常为名词或名词短语。例如：

let msg = 'Hello world';
function sendMsg(msg: string) {
  // todo send message
}
let userName = 'Zhangsan';
function findUser(userName: string) {
  // todo find user by user name
}

（四）常量名、枚举值名

采用全部大写，单词间用下划线隔开，且尽量表达完整语义。例如：

const MAX_USER_SIZE = 10000;
enum UserType {
  TEACHER = 0,
  STUDENT = 1
};

（五）布尔型变量名

布尔型局部变量或方法应加上表达是非意义的前缀（如is、has、can、should等），避免使用否定的布尔变量名。例如：

// 反例
let isNoError = true;
let isNotFound = false;
function empty() {}
function next() {}

// 正例
let isError = false;
let isFound = true;
function isEmpty() {}
function hasNext() {}

五、格式规范

（一）缩进

使用空格缩进，禁止使用tab字符。建议大部分场景用2个空格，换行导致的缩进用4个空格，可在代码编辑器中配置。例如：

class DataSource {
  id: number = 0
  title: string = ''
  content: string = ''
}
const dataSource: DataSource[] = [
  {
    id: 1,
    title: 'Title 1',
    content: 'Content 1'
  },
  {
    id: 2,
    title: 'Title 2',
    content: 'Content 2'
  }
];
function test(dataSource: DataSource[]) {
  if (!dataSource.length) {
    return;
  }
  for (let data of dataSource) {
    if (!data ||!data.id ||!data.title ||!data.content) {
      continue;
    }
    // some code
  }
  // some code
}

（二）行宽

行宽不超过120个字符，以提升代码可读性，避免过长函数、变量命名和过多嵌套层数。例外情况包括注释包含长命令或URL、预处理error信息等。

（三）条件和循环语句大括号

if、for、do、while等语句的执行体必须使用大括号，以增强代码清晰度，避免错误。例如：

// 反例
if (condition)
  console.log('success');
for (let idx = 0; idx < 5; ++idx)
  console.log(idx);

// 正例
if (condition) {
  console.log('success');
}
for (let idx = 0; idx < 5; ++idx) {
  console.log(idx);
}

（四）switch语句缩进

switch的case和default需缩进一层（2个空格），开关标签后换行的语句再缩进一层（2个空格）。例如：

switch (condition) {
  case 0: {
    doSomething();
    break;
  }
  case 1: {
    doOtherthing();
    break;
  }
  default:
    break;
}

（五）表达式换行

当语句过长或可读性不佳时，在合适处换行，将操作符放在行末，保持与格式化工具默认配置一致。例如：

// 假设条件语句超出行宽
if (userCount > MAX_USER_COUNT ||
  userCount < MIN_USER_COUNT) {
  doSomething();
}

（六）变量定义和赋值语句

每个语句只声明一个变量，避免写在一行，便于添加变量声明、调试和减少错误。例如：

// 反例
let maxCount = 10, isCompleted = false;
let pointX, pointY;
pointX = 10; pointY = 0;

// 正例
let maxCount = 10;
let isCompleted = false;
let pointX = 0;
let pointY = 0;

（七）空格使用

空格应突出关键字和重要信息，遵循特定规则，如关键字与左括号间加空格、函数名与参数列表左括号间不加空格等，避免不必要空格和连续空格。例如：

// if 和左括号之间加一个空格
if (isJedi) {
  fight();
}
// 函数名fight和左括号 ( 之间不加空格
function fight(): void {
  console.log('Swooosh!');
}
// else 与其前面的大括号 } 之间增加空格
if (flag) {
  //...
} else {
  //...
}
// 函数声明时，左大括号 { 之前加个空格
function foo() {
  //...
}
bar('attr', {
  age: '1 year',
  sbreed: 'Bernese Mountain Dog',
});
// 数组初始化中的逗号后面加个空格，逗号前面不加空格
const arr = [1, 2, 3];
// 函数的多个参数之间的逗号后加个空格，逗号前面不加空格
myFunc(bar, foo, baz);

（八）字符串引号

建议使用单引号，约定俗成。例如：

// 反例
let message = "world";
console.log(message);

// 正例
let message = 'world';
console.log(message);

（九）对象字面量属性换行

对象字面量属性超过4个时，建议统一换行，要么全换行，要么全在一行。例如：

// 反例
interface I {
  name: string
  age: number
  value: number
  sum: number
  foo: boolean
  bar: boolean
}
let obj: I = { name: 'tom', age: 16, value: 1, sum: 2, foo: true, bar: false }

// 正例
interface I {
  name: string
  age: number
  value: number
  sum: number
  foo: boolean
  bar: boolean
}
let obj: I = {
  name: 'tom',
  age: 16,
  value: 1,
  sum: 2,
  foo: true,
  bar: false
}

（十）else/catch位置

写条件语句时，else放在if代码块关闭括号同一行；写异常处理语句时，catch放在try代码块关闭括号同一行。例如：

// 反例
if (isOk) {
  doThing1();
  doThing2();
}
else {
  doThing3();
}
try {
  doSomething();
}
catch (err) {
  // 处理错误
}

// 正例
if (isOk) {
  doThing1();
  doThing2();
} else {
  doThing3();
}
try {
  doSomething();
} catch (err) {
  // 处理错误
}

（十一）大括号位置

大括号应放在控制语句或声明语句同一行，保持一致风格。例如：

// 反例
function foo()
{
  //...
}

// 正例
function foo() {
  //...
}

六、编程实践规范

（一）类属性可访问修饰符

建议添加private、protected或public可访问修饰符，提升代码安全性和可读性，注意含private属性的类无法通过对象字面量初始化。例如：

// 反例
class C {
  count: number = 0
  getCount(): number {
    return this.count
  }
}

// 正例
class C {
  private count: number = 0
  public getCount(): number {
    return this.count
  }
}

（二）浮点数表示

不建议省略浮点数小数点前后的0，以提高代码可读性。例如：

// 反例
const num =.5;
const num = 2.;
const num = -.7;

// 正例
const num = 0.5;
const num = 2.0;
const num = -0.7;

（三）判断Number.NaN

必须使用Number.isNaN()方法判断变量是否为Number.NaN，因为Number.NaN不等于任何值（包括自身），直接比较结果易混淆。例如：

// 反例
if (foo == Number.NaN) {
  //...
}
if (foo!= Number.NaN) {
  //...
}

// 正例
if (Number.isNaN(foo)) {
  //...
}
if (!Number.isNaN(foo)) {
  //...
}

（四）数组遍历

优先使用Array对象方法（如forEach()、map()、every()、filter()、find()、findIndex()、reduce()、some()）进行数组遍历处理。例如：

// 反例
const numbers = [1, 2, 3, 4, 5];
// 依赖已有数组来创建新的数组时，通过for遍历，生成一个新数组
const increasedByOne: number[] = [];
for (let i = 0; i < numbers.length; i++) {
  increasedByOne.push(numbers[i] + 1);
}

// 正例
const numbers = [1, 2, 3, 4, 5];
// better: 使用map方法是更好的方式
const increasedByOne: number[] = numbers.map(num => num + 1);

（五）控制性条件表达式

不要在控制性条件表达式（if、while、for、?:等）中执行赋值操作，以免导致意料之外行为和可读性差。例如：

// 反例
// 在控制性判断中赋值不易理解
if (isFoo = false) {
 ...
}

// 正例
const isFoo = someBoolean; // 在上面赋值，if条件判断中直接使用
if (isFoo) {
 ...
}

（六）finally代码块

finally代码块中不要使用return、break、continue或抛出异常，保证其正常结束，否则会影响try或catch代码块中异常抛出和方法返回值。例如：

// 反例
function foo() {
  try {
   ...
    return 1;
  } catch (err) {
   ...
    return 2;
  } finally {
    return 3;
  }
}

// 正例
function foo() {
  try {
   ...
    return 1;
  } catch (err) {
   ...
    return 2;
  } finally {
    console.log('XXX!');
  }
}

（七）避免使用ESObject

非跨语言调用场景中，避免使用ESObject标注类型，以免引入不必要跨语言调用和性能开销。例如：

// 反例
// lib.ets
export interface I {
  sum: number
}
export function getObject(value: number): I {
  let obj: I = { sum: value };
  return obj
}
// app.ets
import { getObject } from 'lib'
let obj: ESObject = getObject(123);

// 正例
// lib.ets
export interface I {
  sum: number
}
export function getObject(value: number): I {
  let obj: I = { sum: value };
  return obj
}
// app.ets
import { getObject, I } from 'lib'
let obj: I = getObject(123);

（八）数组类型表示

建议所有数组类型用T[]表示，而非Array，以提高代码可读性。例如：

// 反例
let x: Array<number> = [1, 2, 3];
let y: Array<string> = ['a', 'b', 'c'];

// 正例
// 统一使用T[]语法
let x: number[] = [1, 2, 3];
let y: string[] = ['a', 'b', 'c'];

遵循这些ArkTS编程规范，有助于开发者编写规范、高效、易读和易于维护的代码，提升鸿蒙Next应用的整体质量。

鸿蒙Next ArkTS语法适配背景概述

Freerain — Mon, 23 Dec 2024 01:16:08 +0000

一、引言

ArkTS在保持TypeScript（TS）基本语法风格的基础上，通过规范强化静态检查和分析，在程序开发期检测更多错误，提升程序稳定性与运行性能。本文将阐述为何建议将TS代码适配为ArkTS代码。

二、程序稳定性

（一）动态类型语言的问题

以JavaScript（JS）为代表的动态类型语言，虽能让开发者快速编写代码，但容易在运行时产生非预期错误。如未检查值是否为undefined，可能导致程序崩溃。

（二）TypeScript的局限性

TS通过标注类型检查错误，多数错误在编译时可被检测，但不强制变量类型标注，限制了编译时检查。

（三）ArkTS的改进

ArkTS强制使用静态类型，要求类的属性在声明或构造函数中显式初始化，减少运行时错误。例如：

TS非严格模式下的类定义（存在问题）

class Person {
    name: string; // undefined
    setName(n: string): void {
        this.name = n;
    }
    getName(): string {
        return this.name;
    }
}
let buddy = new Person();
buddy.getName().length; // 运行时异常: name is undefined

ArkTS改进后的类定义（更安全）

class Person {
    name: string = '';
    setName(n: string): void {
        this.name = n;
    }
    getName(): string {
        return this.name;
    }
}
let buddy = new Person();
buddy.getName().length; // 0, 没有运行时异常

三、程序性能

（一）动态类型语言的运行时检查

动态类型语言为保证正确性，在运行时检查对象类型，如JS访问undefined属性时会检查类型，这虽可优化但仍影响性能。TS编译成JS后也有同样问题。

（二）ArkTS的解决方案

ArkTS使能静态类型检查，编译成方舟字节码文件而非JS代码，运行速度更快且更易优化。

（三）Null Safety特性

示例函数及问题

function notify(who: string, what: string) {
    console.log(`Dear ${who}, a message for you: ${what}`);
}
notify('Jack', 'You look great today');
notify(null, undefined); // 程序仍运行，但引擎做了额外类型检查

ArkTS的严格检查 ArkTS强制严格null检查，保证null不是合法string类型变量的值，不符合类型的代码无法编译，有助于优化性能。如上述notify(null, undefined)在ArkTS中会编译报错。

四、.ets代码兼容性

（一）语法规则变化

API version 10之前，ArkTS（.ets文件）采用标准TS语法。从API version 10 Release起，ArkTS语法规则明确定义，SDK增加编译时语法检查。

（二）编译策略

标准模式（compatibleSdkVersion >= 10）：违反ArkTS语法规则的.ets文件代码会导致工程编译失败，需完全适配。
兼容模式（compatibleSdkVersion < 10）：以warning提示违反规则代码，工程可编译成功，但需适配才能在标准模式下编译。

五、方舟运行时与TS/JS的关系

（一）应用环境限制

强制使用严格模式（use strict）。
禁止使用eval()。
禁止使用with() {}。
禁止以字符串为代码创建函数。 ### （二）语法差异标准TS/JS中JSON数字格式要求小数点后必须有数字，方舟运行时允许2.e3这类科学计数法。

综上所述，ArkTS在多方面的改进和特性使其相比TS更具优势，在鸿蒙Next开发中进行ArkTS语法适配有助于提升程序质量和开发效率。

鸿蒙Next自定义组件属性访问限定符

Freerain — Fri, 20 Dec 2024 00:52:22 +0000

在鸿蒙Next开发中，ArkTS对自定义组件的成员变量使用的访问限定符private/public/protected有特定的校验规则，当不按规范使用时会产生相应的日志信息。

一、使用限制概述

（一）private修饰相关限制

对于@State/@prop/@Provide/@BuilderParam/常规成员变量（不涉及更新的普通变量），使用private修饰时，在自定义组件构造时不允许进行赋值传参，否则会有编译告警日志提示。 ### （二）public修饰相关限制
对于@StorageLink/@StorageProp/@LocalStorageLink/@LocalStorageProp/@Consume变量，使用public修饰时，会有编译告警日志提示。 ### （三）private与特定装饰器同时修饰限制
对于@Link/@ObjectLink变量，使用private修饰时，会有编译告警日志提示。 ### （四）protected修饰限制
由于struct没有继承能力，所有上述变量使用protected修饰时，会有编译告警日志提示。 ### （五）@Require与private同时修饰限制
当@Require和private同时修饰自定义组件struct的@State/@prop/@Provide/@BuilderParam/常规成员变量（不涉及更新的普通变量）时，会有编译告警日志提示。

二、错误使用场景示例

（一）private与@State/@prop/@Provide/@BuilderParam同时修饰

代码示例

@Entry
@Component
struct AccessRestrictions {
  @Builder
  buildTest() {
    Text("Parent builder")
  }
  build() {
    Column() {
      ComponentsChild({
        state_value: "Hello",
        prop_value: "Hello",
        provide_value: "Hello",
        builder_value: this.buildTest,
        regular_value: "Hello"
      })
    }
  .width('100%')
  }
}
@Component
struct ComponentsChild {
  @State private state_value: string = "Hello";
  @Prop private prop_value: string = "Hello";
  @Provide private provide_value: string = "Hello";
  @BuilderParam private builder_value: () => void = this.buildTest;
  private regular_value: string = "Hello";
  @Builder
  buildTest() {
    Text("Child builder")
  }
  build() {
    Column() {
      Text("Hello")
      .fontSize(50)
      .fontWeight(FontWeight.Bold)
    }
  }
}

编译告警日志
- Property'state_value' is private and can not be initialized through the component constructor.
- Property 'prop_value' is private and can not be initialized through the component constructor.
- Property 'provide_value' is private and can not be initialized through the component constructor.
- Property 'builder_value' is private and can not be initialized through the component constructor.
- Property'regular_value' is private and can not be initialized through the component constructor.

（二）public与@StorageLink/@StorageProp/@LocalStorageLink/@LocalStorageProp/@Consume同时修饰

代码示例

@Entry
@Component
struct AccessRestrictions {
  @Provide consume_value: string = "Hello";
  build() {
    Column() {
      ComponentChild()
    }
  .width('100%')
  }
}
@Component
struct ComponentChild {
  @LocalStorageProp("sessionLocalProp") public local_prop_value: string = "Hello";
  @LocalStorageLink("sessionLocalLink") public local_link_value: string = "Hello";
  @StorageProp("sessionProp") public storage_prop_value: string = "Hello";
  @StorageLink("sessionLink") public storage_link_value: string = "Hello";
  @Consume public consume_value: string;
  build() {
    Column() {
      Text("Hello")
      .fontSize(50)
      .fontWeight(FontWeight.Bold)
    }
  }
}

编译告警日志
- Property 'local_prop_value' can not be decorated with both @LocalStorageProp and public.
- Property 'local_link_value' can not be decorated with both @LocalStorageLink and public.
- Property'storage_prop_value' can not be decorated with both @StorageProp and public.
- Property'storage_link_value' can not be decorated with both @StorageLink and public.
- Property 'consume_value' can not be decorated with both @Consume and public.

（三）private与@Link/@ObjectLink同时修饰

代码示例

@Entry
@Component
struct AccessRestrictions {
  @State link_value: string = "Hello";
  @State objectLink_value: ComponentObj = new ComponentObj();
  build() {
    Column() {
      ComponentChild({link_value: this.link_value, objectLink_value: this.objectLink_value})
    }
  .width('100%')
  }
}
@Observed
class ComponentObj {
  count: number = 0;
}
@Component
struct ComponentChild {
  @Link private link_value: string;
  @ObjectLink private objectLink_value: ComponentObj;
  build() {
    Column() {
      Text("Hello")
      .fontSize(50)
      .fontWeight(FontWeight.Bold)
    }
  }
}

编译告警日志
- Property 'link_value' can not be decorated with both @link and private.
- Property 'objectLink_value' can not be decorated with both @ObjectLink and private.

（四）protected修饰

代码示例

@Entry
@Component
struct AccessRestrictions {
  build() {
    Column() {
      ComponentChild({regular_value: "Hello"})
    }
  .width('100%')
  }
}
@Component
struct ComponentChild {
  protected regular_value: string = "Hello";
  build() {
    Column() {
      Text("Hello")
      .fontSize(50)
      .fontWeight(FontWeight.Bold)
    }
  }
}

编译告警日志
- The member attributes of a struct can not be protected.

（五）private、@Require与@State/@prop/@Provide/@BuilderParam同时修饰

代码示例

@Entry
@Component
struct AccessRestrictions {
  build() {
    Column() {
      ComponentChild({prop_value: "Hello"})
    }
  .width('100%')
  }
}
@Component
struct ComponentChild {
  @Require @Prop private prop_value: string = "Hello";
  build() {
    Column() {
      Text("Hello")
      .fontSize(50)
      .fontWeight(FontWeight.Bold)
    }
  }
}

编译告警日志
- Property 'prop_value' can not be decorated with both @Require and private.
- Property 'prop_value' is private and can not be initialized through the component constructor.

开发者在使用鸿蒙Next自定义组件时，需遵循这些访问限定符的使用规则，避免因不规范使用而产生编译告警，确保组件的正确构建和功能实现。同时，注意这些规则从API version 12开始支持，在开发过程中要根据实际的API版本进行相应的处理。

鸿蒙Next自定义组件的布局

Freerain — Thu, 19 Dec 2024 00:26:57 +0000

一、引言

在鸿蒙Next开发中，当需要通过精确测算的方式来布局自定义组件内子组件的位置时，可以使用特定的接口来实现。本文将详细介绍如何使用onMeasureSize和onPlaceChildren接口来完成自定义组件的布局，包括接口的功能、使用示例以及实现效果等方面的内容。

二、布局接口介绍

onMeasureSize接口
- 功能：组件每次布局时触发，用于计算子组件的尺寸。其执行时间先于onPlaceChildren接口。
- 参数：
  - selfLayoutInfo：类型为GeometryInfo，提供组件自身的布局信息。
  - children：类型为Array<Measurable>，是可测量的子组件数组。
  - constraint：类型为ConstraintSizeOptions，用于约束子组件的尺寸。
onPlaceChildren接口
- 功能：组件每次布局时触发，用于设置子组件的起始位置。
- 参数：
  - selfLayoutInfo：同onMeasureSize接口中的selfLayoutInfo。
  - children：类型为Array<Layoutable>，是可布局的子组件数组。
  - constraint：同onMeasureSize接口中的constraint。

三、使用示例

（一）整体结构

Index.ets文件
- 包含@Entry装饰的Index组件，在其build方法中使用Column组件包裹了一个自定义布局组件CustomLayout，并通过builder方式传入子组件。
自定义组件相关代码
- CustomLayout组件实现了自定义布局功能，包括onMeasureSize和onPlaceChildren方法的定义，以及build方法来构建组件。

（二）具体实现步骤

计算子组件大小（onMeasureSize方法）
- 在CustomLayout组件的onMeasureSize方法中，首先初始化一个size变量为100。然后遍历传入的子组件数组children，对于每个子组件，使用measure方法测量其尺寸，并将测量结果的宽度的一半累加到size变量上。最后设置this.result.width为100，this.result.height为400，并返回this.result，从而实现组件大小递增的效果。例如，第一个子组件大小为100，第二个子组件大小为100加上第一个子组件宽度100的一半（即50），以此类推。
放置子组件位置（onPlaceChildren方法）
- 在onPlaceChildren方法中，定义startPos为300。然后遍历子组件数组children，对于每个子组件，计算其位置pos为startPos减去子组件自身的高度。最后使用layout方法将子组件布局到计算得到的位置(pos, pos)，使得所有子组件的右下角在顶点位置(300, 300)，实现了一个从右下角开始展示组件的类似Stack组件的效果。

（三）子组件传递方式

在Index组件中，通过@Builder装饰的ColumnChildren函数来构建子组件。使用ForEach循环遍历一个数组[1, 2, 3]，对于每个元素创建一个Text组件，并设置其样式（如字体大小、宽度、高度、边框宽度、偏移量等）。然后将这个ColumnChildren函数作为builder参数传递给CustomLayout组件。

四、总结

通过使用onMeasureSize和onPlaceChildren接口，开发者可以根据自己的需求精确计算和设置自定义组件内子组件的大小和位置，实现各种复杂的布局效果。这种方式提供了更大的灵活性和控制力，有助于打造出更加美观、高效的用户界面。在实际开发中，可以根据具体的布局需求灵活运用这些接口，实现个性化的组件布局设计。

鸿蒙Next页面和自定义组件生命周期

Freerain — Wed, 18 Dec 2024 01:21:08 +0000

一、引言

在鸿蒙Next应用开发中，理解页面和自定义组件的生命周期至关重要。它有助于开发者精确控制组件和页面在不同阶段的行为，优化应用性能，提升用户体验。本文将深入探讨鸿蒙Next中页面和自定义组件的生命周期，包括创建、渲染、重新渲染、删除以及监听页面生命周期等方面的内容。

二、自定义组件和页面的关系

自定义组件
- 由@Component装饰的UI单元，可组合多个系统组件实现UI复用，并能调用组件的生命周期。
页面
- 应用的UI页面，可由一个或多个自定义组件组成。其中，@Entry装饰的自定义组件是页面的入口组件（根节点），一个页面只能有一个@Entry。只有被@Entry装饰的组件才能调用页面的生命周期。

三、生命周期接口

页面生命周期接口（被@Entry装饰的组件）
- onPageShow：页面每次显示时触发，如路由过程、应用进入前台等场景。
- onPageHide：页面每次隐藏时触发，如路由过程、应用进入后台等场景。
- onBackPress：用户点击返回按钮时触发。
组件生命周期接口（一般@Component装饰的自定义组件）
- aboutToAppear：组件即将出现时回调，在创建实例后、执行build()函数前执行。
- onDidBuild：组件build()函数执行完成后回调，不建议在此函数中更改状态变量或使用某些功能（如animateTo），以免导致UI表现不稳定。
- aboutToDisappear：组件析构销毁前执行，不允许在此函数中改变状态变量（特别是@Link变量修改可能导致应用不稳定）。

四、生命周期流程

（一）自定义组件的创建和渲染流程

实例创建
- 由ArkUI框架创建自定义组件实例。
成员变量初始化
- 通过本地默认值或构造方法传递参数初始化成员变量，顺序按定义顺序。
aboutToAppear执行（若定义）
- 若开发者定义了aboutToAppear方法，则执行该方法。
首次渲染
- 执行build方法渲染系统组件，若子组件为自定义组件，则创建其实例。首次渲染时框架记录状态变量与组件映射关系，以便状态变量改变时驱动相关组件刷新。
onDidBuild执行（若定义）
- 若开发者定义了onDidBuild方法，则执行该方法。

（二）自定义组件重新渲染

当以下情况发生时触发重新渲染：

事件句柄触发（如点击事件）改变状态变量。
LocalStorage / AppStorage中的属性更改导致绑定的状态变量值改变。
- 框架观察到变化后启动重新渲染，根据记录的映射关系找到相关UI组件及其更新函数，执行更新函数实现最小化更新。

（三）自定义组件的删除

触发条件
- if组件分支改变或ForEach循环渲染中数组个数改变时，组件将被删除。
删除过程
- 调用aboutToDisappear生命周期函数标记节点将要销毁。ArkUI节点删除机制为后端节点从组件树摘下并销毁，对前端节点解引用，前端节点无引用时被JS虚拟机垃圾回收。
- 自定义组件及其变量被删除，同步变量（如@Link、@Prop、@StorageLink）从同步源取消注册。

（四）注意事项

不建议在aboutToDisappear生命周期内使用async await，因为若使用异步操作，自定义组件将保留在Promise闭包中，直到回调方法执行完，这会阻止组件的垃圾回收。

五、生命周期调用时机示例

（一）示例代码结构

Index.ets
- 包含@Entry装饰的MyComponent（页面入口组件）和Child（MyComponent的子组件）。
- MyComponent中声明页面生命周期函数（onPageShow、onPageHide、onBackPress）和组件生命周期函数（aboutToAppear、onDidBuild、aboutToDisappear）。
- 通过按钮操作控制Child组件的显示与隐藏、页面跳转等。
page.ets
- 新页面的定义，包含页面生命周期函数（onPageShow、onPageHide、onBackPress）和组件初始化逻辑。

（二）不同操作下的生命周期调用

应用冷启动
- 初始化流程：MyComponent aboutToAppear -> MyComponent build -> MyComponent onDidBuild -> Child aboutToAppear -> Child build -> Child onDidBuild -> Index onPageShow。
点击“delete Child”按钮
- if绑定的this.showChild变为false，删除Child组件，执行Child aboutToDisappear方法。
点击“push to next page”按钮
- 调用router.pushUrl接口跳转到新页面，当前Index页面隐藏，执行Index onPageHide。新页面初始化流程执行。若调用router.replaceUrl，Index页面销毁，执行Index onPageHide -> MyComponent aboutToDisappear -> Child aboutToDisappear后初始化新页面生命周期流程。
点击返回按钮
- 触发Index onBackPress，且返回一个页面后Index页面销毁。
最小化应用或进入后台
- 触发Index onPageHide，Index页面未销毁，不执行组件的aboutToDisappear。应用回到前台时执行Index onPageShow。
退出应用
- 执行Index onPageHide -> MyComponent aboutToDisappear -> Child aboutToDisappear。

六、自定义组件监听页面生命周期

通过使用无感监听页面路由的能力，在自定义组件中监听页面生命周期。

示例代码（以Index.ets为例）
- 导入相关模块（uiObserver、router、UIObserver）。
- 在Index组件中定义listener函数，根据uiObserver.RouterPageInfo判断页面状态并打印相应日志。
- 在aboutToAppear中注册监听，在aboutToDisappear中取消监听。
- SubComponent组件中同样进行类似操作实现对页面生命周期的监听。

掌握鸿蒙Next页面和自定义组件的生命周期，开发者能够更精准地把握应用运行过程中的各个阶段，合理安排代码逻辑，优化应用性能，为用户提供更加稳定、高效的应用体验。

鸿蒙Next创建自定义组件总结

Freerain — Wed, 18 Dec 2024 01:04:32 +0000

一、引言

在鸿蒙Next开发中，自定义组件是构建高效、可维护UI的重要组成部分。它具有可组合、可重用以及数据驱动UI更新等特点，能帮助开发者更好地实现代码复用、业务逻辑与UI分离等目标。本文将详细总结创建自定义组件的相关知识，包括其基本结构、成员函数/变量、参数规定、build()函数以及通用样式等方面。

二、自定义组件基本结构

基于struct实现
- 自定义组件由struct + 自定义组件名 + {...}构成，不能有继承关系，struct实例化可省略new。且自定义组件名不能和系统组件名相同。
@Component装饰器
- 仅能装饰struct关键字声明的数据结构，被装饰后具备组件化能力，需实现build方法描述UI，一个struct只能被一个@Component装饰。从API version 11开始，@Component可接受一个可选的bool类型参数freezeWhenInactive用于控制组件冻结。
build()函数
- 用于定义自定义组件的声明式UI描述，是自定义组件必须定义的函数。
@Entry装饰器
- 装饰的自定义组件将作为UI页面的入口，单个UI页面最多只能有一个@Entry装饰的自定义组件。从API version 10开始，@Entry可接受可选的LocalStorage参数或EntryOptions参数。
@Reusable装饰器（API version 10开始支持在ArkTS卡片中使用）
- 使自定义组件具备可复用能力。

三、成员函数/变量

成员函数
- 为私有，不建议声明为静态函数。
成员变量
- 为私有，不建议声明为静态变量。成员变量本地初始化要求因情况而异，具体参考状态管理。部分情况下可从父组件通过参数传递初始化。

四、自定义组件参数规定

初始化参数

在build方法里创建自定义组件时，根据装饰器规则初始化参数。例如：

 @Component
 struct MyComponent {
   private countDownFrom: number = 0;
   private color: Color = Color.Blue;
   build() {
   }
 }
 @Entry
 @Component
 struct ParentComponent {
   private someColor: Color = Color.Pink;
   build() {
     Column() {
       // 创建MyComponent实例并初始化参数
       MyComponent({ countDownFrom: 10, color: this.someColor })
     }
   }
 }

传递函数作为参数

父组件可将函数传递给子组件，子组件可调用该函数，如：

 @Entry
 @Component
 struct Parent {
   @State cnt: number = 0
   submit: () => void = () => {
     this.cnt++;
   }
   build() {
     Column() {
       Text(`${this.cnt}`)
       Son({ submitArrow: this.submit })
     }
   }
 }
 @Component
 struct Son {
   submitArrow?: () => void
   build() {
     Row() {
       Button('add')
        .width(80)
        .onClick(() => {
           if (this.submitArrow) {
             this.submitArrow()
           }
         })
     }
    .justifyContent(FlexAlign.SpaceBetween)
    .height(56)
   }
 }

五、build()函数规则

根节点要求
- @Entry装饰的自定义组件，build()函数下根节点唯一且必须为容器组件（ForEach禁止作为根节点）。
- @Component装饰的自定义组件，build()函数下根节点唯一且可为非容器组件（ForEach禁止作为根节点）。
其他限制
- 不允许声明本地变量。
- 不允许在UI描述里直接使用console.info（方法或函数里可用）。
- 不允许创建本地作用域。
- 不允许调用没有用@Builder装饰的方法，但系统组件参数可为TS方法返回值。
- 不允许使用switch语法，需用if进行条件判断。
- 不允许使用表达式。
- 不允许直接改变状态变量（会造成循环渲染风险，不同版本更新方式有差异且可能影响性能）。

六、自定义组件通用样式

通过“.”链式调用的形式设置通用样式，但给自定义组件设置样式时，实际上是给组件套了一个不可见容器组件，样式设置在该容器组件上而非直接在组件自身。例如：

@Component
struct MyComponent2 {
  build() {
    Button(`Hello World`)
  }
}
@Entry
@Component
struct MyComponent {
  build() {
    Row() {
      MyComponent2()
       .width(200)
       .height(300)
       .backgroundColor(Color.Red)
    }
  }
}

掌握鸿蒙Next中创建自定义组件的这些知识，开发者能够更加灵活、高效地构建应用UI，提升应用的质量和可维护性。

鸿蒙Next声明式UI描述

Freerain — Tue, 17 Dec 2024 05:37:59 +0000

一、引言

在鸿蒙Next开发中，ArkTS以声明方式组合和扩展组件来描述应用程序的UI，为开发者提供了高效、灵活的方式来构建用户界面。本文将详细介绍鸿蒙Next中声明式UI的相关内容，包括组件创建、属性配置、事件配置以及子组件配置等方面，帮助开发者更好地理解和运用这一技术。

二、创建组件

（一）无参数创建

如果组件的接口定义没有包含必选构造参数，则组件后面的“()”不需要配置任何内容。例如，Divider组件不包含构造参数，可按如下方式创建：

Column() {
  Text('item 1')
  Divider()
  Text('item 2')
}

（二）有参数创建

若组件的接口定义包含构造参数，则在组件后面的“()”需要配置相应参数。如Image组件的必选参数src，以及Text组件的非必选参数content（有多种赋值方式）：

直接赋值字符串
- Image('https://xyz/test.jpg')
- Text('test')
使用$r形式引入应用资源（适用于多语言场景）
- Text($r('app.string.title_value'))
无参数形式
- Text()
使用变量或表达式赋值
- 变量赋值：Image(this.imagePath)
- 表达式赋值：Image('https://' + this.imageUrl)，Text(count: ${this.count})

三、配置属性

属性方法以“.”链式调用的方式配置系统组件的样式和其他属性，建议每个属性方法单独写一行。

配置单个属性
- 配置Text组件字体大小：Text('test').fontSize(12)
配置多个属性
- Image('test.jpg').alt('error.jpg').width(100).height(100)
使用变量或表达式配置属性
- Text('hello').fontSize(this.size)
- Image('test.jpg').width(this.count % 2 === 0? 100 : 200).height(this.offset + 100)
使用枚举类型配置属性（针对系统组件）
- 配置Text组件颜色和字体样式：Text('hello').fontSize(20).fontColor(Color.Red).fontWeight(FontWeight.Bold)

四、配置事件

事件方法以“.”链式调用的方式配置系统组件支持的事件，建议每个事件方法单独写一行。

使用箭头函数配置事件方法
- Button('Click me').onClick(() => {this.myText = 'ArkUI';})
使用箭头函数表达式配置事件方法
- Button('add counter').onClick(() => {this.counter += 2;})
使用组件的成员函数配置事件方法（需bind this，不推荐）
- 定义成员函数：
```
 myClickHandler(): void {
   this.counter += 2;
 }
```

绑定事件：Button('add counter').onClick(this.myClickHandler.bind(this))
1. 使用声明的箭头函数配置事件方法（可直接调用，不需要bind this）

声明箭头函数：

 fn = () => {
   console.info(`counter: ${this.counter}`)
   this.counter++
 }

绑定事件：Button('add counter').onClick(this.fn)

注意：箭头函数内部的this是词法作用域，由上下文确定。匿名函数可能会有this指向不明确问题，在ArkTS中不允许使用。

五、配置子组件

如果组件支持子组件配置，则需在尾随闭包"{...}"中为组件添加子组件的UI描述。Column、Row、Stack、Grid、List等组件都是容器组件。

简单Column组件配置子组件示例

   Column() {
     Text('Hello')
      .fontSize(100)
     Divider()
     Text(this.myText)
      .fontSize(100)
      .fontColor(Color.Red)
   }

容器组件多级嵌套示例

   Column() {
     Row() {
       Image('test1.jpg')
        .width(100)
        .height(100)
       Button('click +1')
        .onClick(() => {
           console.info('+1 clicked!');
         })
     }
   }

通过以上对鸿蒙Next声明式UI描述中组件创建、属性配置、事件配置和子组件配置的介绍，开发者可以更加熟练地运用这些技术构建出功能丰富、交互性强的用户界面，为用户提供优质的应用体验。