官方文档 (opens new window)

在 ArkTS 中，我们可以自定义组件，例如：

// 定义名为TitleComponent的自定义组件
@Component
struct TitleComponent {
	...
	build () {}
}

// 定义名为RankPage的自定义组件，在其中使用TitleComponent组件
@Entry
@Component
struct RankPage {
	@State myText: string = 'hello harmonyOs';
	...
	build () {
		Column () {
			TitleComponent()
		}
	}
}

• @Component 装饰的 struct 表示该结构体具有组件化能力，能够成为一个独立的组件
• @Entry 表示该自定义组件为入口组件，即页面的根节点，一个页面有且仅能有一个 @Entry。只有被 @Entry 装饰的组件才可以调用页面的生命周期。
• @State 表示组件中的状态变量，状态变量变化会触发 UI 刷新
• build () 函数：用于定义自定义组件的声明式 UI 描述，自定义组件必须定义 build () 函数。
• @Prop：与 @State 有相同的语义，但初始化方式不同，@Porp 装饰的变量必须使用其父组件提供的 @State 变量进行初始化，允许组件内部修改 @Prop 变量，但更改不会通知给父组件，即 @Prop 属于单向数据绑定。
• @Link：使用 @Link 装饰的变量可以和父组件的 @State 变量建立双向数据绑定，需要注意的是：@Link 变量不能在组件内部进行初始化。
• @Builder：用于定义组件的声明式 UI 描述，在一个自定义组件内快速生成多个布局内容。
• @Watch：监听状态变化

所有声明在 build () 函数的语言，统称为 UI 描述语言，UI 描述语言需要遵循以下规则：

• @Entry 装饰的自定义组件，其 build () 函数下的根节点唯一且必要，且必须为容器组件，其中 ForEach 禁止作为根节点。
• @Component 装饰的自定义组件，其 build () 函数下的根节点唯一且必要，可以为非容器组件，其中 ForEach 禁止作为根节点。

@Entry
@Component
struct MyComponent {
  build() {
    // 根节点唯一且必要，必须为容器组件
    Row() {
      ChildComponent() 
    }
  }
}

@Component
struct ChildComponent {
  build() {
    // 根节点唯一且必要，可为非容器组件
    Image('test.jpg')
  }
}

• 不允许声明本地变量，反例：

build() {
  // 反例：不允许声明本地变量
  let a: number = 1;
}

• 不允许在 UI 描述里直接使用 console.info，但允许在方法或函数里使用，反例：

build() {
  // 反例：不允许console.info
  console.info('print debug log');
}

• 不允许创建本地的作用于，反例：

build() {
  // 反例：不允许本地作用域
  {
    ...
  }
}

• 不允许调用除了被 @Builder 装饰以外的方法，允许系统组件的参数是 TS 方法的返回值

@Component
struct ParentComponent {
  doSomeCalculations() {
  }

  calcTextValue(): string {
    return 'Hello World';
  }

  @Builder doSomeRender() {
    Text(`Hello World`)
  }

  build() {
    Column() {
      // 反例：不能调用没有用@Builder装饰的方法
      this.doSomeCalculations();
      // 正例：可以调用
      this.doSomeRender();
      // 正例：参数可以为调用TS方法的返回值
      Text(this.calcTextValue())
    }
  }
}

• 不允许 switch 语法，如果需要使用条件判断，请使用 if。反例：

build() {
  Column() {
    // 反例：不允许使用switch语法
    switch (expression) {
      case 1:
        Text('...')
        break;
      case 2:
        Image('...')
        break;
      default:
        Text('...')
        break;
    }
  }
}

• 不允许使用表达式，反例：

build() {
  Column() {
    // 反例：不允许使用表达式
    (this.aVar > 10) ? Text('...') : Image('...')
  }
}