OpenHarmony 入门——ArkUI自定义组件的基础语法（一）

文章大纲

• 引言
• 一、自定义组件的基本语法
• • [1、@Component 装饰器 和 @Entry 装饰器](#1、@Component 装饰器 和 @Entry 装饰器)
  • 2、build函数
  • 3、@Reuseable
  • 4、定义成员函数/变量
• 二、自定义组件的使用

引言

在OpenHarmony 系统里ArkUI子系统显示的内容均为组件 ，由框架直接提供的称为系统组件，由开发者定义的称为自定义组件 。在进行 UI 界面开发时，通常不是简单的将系统组件进行组合使用，而是需要考虑代码可复用性、业务逻辑与UI分离，后续版本演进等因素。本文基本就是把官网文档重新整理了下。

一、自定义组件的基本语法

在OpenHarmony定义一个自定义组件语法很简单，通常来说只需要三步：

• 定义一个被@Component 装饰器修饰的struct类型的自定义组件名
• 在这个自定义组件的代码块内实现build函数

@Component
struct MyComponent {
  build() {
  }
}

1、@Component 装饰器 和 @Entry 装饰器

@Component 装饰器像其他一些装饰器一样是华为的ArkTS语言（基于原生TypeScript的扩展）开发的机制，编译时会自动生成一些"胶水代码"完成一些相应的任务，比如说@State背后的原理就类似于观察者模式的应用，@Component装饰器仅能装饰struct关键字声明的数据结构。struct被@Component装饰后且实现了build方法描述UI结构后才具备组件化的能力，一个struct只能被一个@Component装饰。@Component可以接受一个可选的bool类型参数。

//是否开启组件冻结。
@Entry
@Component({ freezeWhenInactive: true })
struct MyComponent {
}

并不是每一个组件都必须使用@Entry 装饰器，只有把这个自定义组件将作为UI页面的入口时才需要使用@Entry修饰。在单个UI页面中最多可以使用@Entry装饰一个自定义组件。@Entry可选参数：

从API version 10开始，@Entry可以接受一个可选的LocalStorage的参数或者一个可选的EntryOptions参数。

class PropB {
 code: number;
 constructor(code: number) {
   this.code = code;
 }
}
// 创建新实例并使用给定对象初始化
let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
storage.setOrCreate('PropB', new PropB(50));

@Component
struct Child {
 // @LocalStorageLink变量装饰器与LocalStorage中的'PropA'属性建立双向绑定
 @LocalStorageLink('PropA') childLinkNumber: number = 1;
 // @LocalStorageLink变量装饰器与LocalStorage中的'PropB'属性建立双向绑定
 @LocalStorageLink('PropB') childLinkObject: PropB = new PropB(0);
 build() {
   Column() {
     Button(`Child from LocalStorage ${this.childLinkNumber}`) // 更改将同步至LocalStorage中的'PropA'以及Parent.parentLinkNumber
       .onClick(() => {
         this.childLinkNumber += 1;
       })
     Button(`Child from LocalStorage ${this.childLinkObject.code}`) // 更改将同步至LocalStorage中的'PropB'以及Parent.parentLinkObject.code
       .onClick(() => {
         this.childLinkObject.code += 1;
       })
   }
 }
}
// 使LocalStorage可从@Component组件访问
@Entry(storage)
@Component
struct CompA {
 // @LocalStorageLink变量装饰器与LocalStorage中的'PropA'属性建立双向绑定
 @LocalStorageLink('PropA') parentLinkNumber: number = 1;
 // @LocalStorageLink变量装饰器与LocalStorage中的'PropB'属性建立双向绑定
 @LocalStorageLink('PropB') parentLinkObject: PropB = new PropB(0);

 build() {
   Column({ space: 15 }) {
     Button(`Parent from LocalStorage ${this.parentLinkNumber}`) // initial value from LocalStorage will be 47, because 'PropA' initialized already
       .onClick(() => {
         this.parentLinkNumber += 1;
       })

     Button(`Parent from LocalStorage ${this.parentLinkObject.code}`) // initial value from LocalStorage will be 50, because 'PropB' initialized already
       .onClick(() => {
         this.parentLinkObject.code += 1;
       })
     // @Component子组件自动获得对CompA LocalStorage实例的访问权限。
     Child()
   }
 }
}

2、build函数

build()函数用于定义自定义组件的声明式UI描述，自定义组件必须定义build()函数。同时build函数里有一些约束规则：

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

• 不允许声明本地变量或者本地代码块（作用域），反例如下。

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

• 不允许在UI描述里直接使用console.info，但允许在函数里使用。

• 不允许调用没有用@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；也不允许使用三元表达式。
• 不允许直接改变状态变量

@Component
struct CompA {
  @State col1: Color = Color.Yellow;
  @State col2: Color = Color.Green;
  @State count: number = 1;
  build() {
    Column() {
      // 应避免直接在Text组件内改变count的值
      Text(`${this.count++}`)
        .width(50)
        .height(50)
        .fontColor(this.col1)
        .onClick(() => {
          this.col2 = Color.Red;
        })
    }
  }
}

3、@Reuseable

@Reusable装饰的自定义组件具备可复用能力，结合懒加载等机制可以提高UI的性能。

@Reusable
@Component
struct MyComponent {
}

4、定义成员函数/变量

自定义组件除了必须要实现build()函数外，还可以实现其他成员函数，成员函数具有以下约束：

• 自定义组件的成员函数为私有的，且不建议声明成静态函数。
• 自定义组件可以包含成员变量，成员变量具有以下约束：

自定义组件的成员变量为私有的，且不建议声明成静态变量。

• 自定义组件的成员变量本地初始化有些是可选的，有些是必选的。具体是否需要本地初始化，是否需要从- 父组件通过参数传递初始化子组件的成员变量，请参考状态管理。

@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
@Component
struct Parent {
  @State cnt: number = 0
  build() {
    Column() {
      Text(`${this.cnt}`)
      Son({ name:"crazymo" })
    }
  }
}

@Component
struct Son {
	private name: string;
	Son(str: string){
		this.name= str;
	}
  build() {
    Row() {
      Button('add')
        .width(80)
        })
    }
  }
}

如果在另外的文件中引用该自定义组件，需要使用export关键字导出，并在使用的页面import该自定义组件。