OpenHarmony 应用（HarmonyOS 原生应用）开发体验（4） - 渲染控制、布局、组件（ArkUI 开发）

juejin_cn2024-03-08 17:59

OpenHarmony 4.1 - UI 开发

官方文档学习笔记，查漏补缺（2023/03/08）

OpenHarmony 4.1 Release 版本的配套文档，对应API能力级别为 API 10 Release

OpenHarmony 4.1 Beta1 版本开始提供首批 API Level 11接口

渲染控制

if/else：条件渲染

ArkTS提供了渲染控制的能力。条件渲染可根据应用的不同状态，使用if、else和else if渲染对应状态下的UI内容。

  • 支持if、else和else if语句。
  • if、else if后跟随的条件语句可以使用状态变量。
  • 允许在容器组件内使用，通过条件渲染语句构建不同的子组件。
  • 条件渲染语句在涉及到组件的父子关系时是"透明"的，当父组件和子组件之间存在一个或多个if语句时，必须遵守父组件关于子组件使用的规则。
  • 每个分支内部的构建函数必须遵循构建函数的规则，并创建一个或多个组件。无法创建组件的空构建函数会产生语法错误。
  • 某些容器组件限制子组件的类型或数量，将条件渲染语句用于这些组件内时，这些限制将同样应用于条件渲染语句内创建的组件。例如，Grid容器组件的子组件仅支持GridItem组件，在Grid内使用条件渲染语句时，条件渲染语句内仅允许使用GridItem组件。

更新机制

当if、else if后跟随的状态判断中使用的状态变量值变化时，条件渲染语句会进行更新，更新步骤如下：

  1. 评估if和else if的状态判断条件，如果分支没有变化，无需执行以下步骤。如果分支有变化，则执行2、3步骤：
  2. 删除此前构建的所有子组件。
  3. 执行新分支的构造函数，将获取到的组件添加到if父容器中。如果缺少适用的else分支，则不构建任何内容。

条件可以包括Typescript表达式。对于构造函数中的表达式，此类表达式不得更改应用程序状态。

ts 复制代码 
@Component
struct CounterView {
  @Link counter: number;
  label: string = 'unknown';

  build() {
    Row() {
      Text(`${this.label}`)
      Button(`counter ${this.counter} +1`)
        .onClick(() => {
          this.counter += 1;
        })
    }
  }
}

@Entry
@Component
struct MainView {
  @State toggle: boolean = true;
  @State counter: number = 0;

  build() {
    Column() {
      if (this.toggle) {
        CounterView({ counter: this.counter, label: 'CounterView #positive' })
      } else {
        CounterView({ counter: this.counter, label: 'CounterView #negative' })
      }
      Button(`toggle ${this.toggle}`)
        .onClick(() => {
          this.toggle = !this.toggle;
        })
    }
  }
}

if语句的每个分支都包含一个构建函数。此类构建函数必须创建一个或多个子组件。在初始渲染时，if语句会执行构建函数，并将生成的子组件添加到其父组件中。

每当if或else if条件语句中使用的状态变量发生变化时，条件语句都会更新并重新评估新的条件值。如果条件值评估发生了变化，这意味着需要构建另一个条件分支。此时ArkUI框架将：

  1. 删除所有以前渲染的（早期分支的）组件。
  2. 执行新分支的构造函数，将生成的子组件添加到其父组件中。

ForEach：循环渲染

ForEach接口基于数组类型数据来进行循环渲染，需要与容器组件配合使用，且接口返回的组件应当是允许包含在ForEach父容器组件中的子组件。例如，ListItem组件要求ForEach的父容器组件必须为List组件。

ts 复制代码 
ForEach(
  arr: Array,
  itemGenerator: (item: any, index?: number) => void,
  keyGenerator?: (item: any, index?: number) => string
)

以下是参数的详细说明：

参数名 参数类型 是否必填 参数描述
arr Array 是 数据源 ，为Array类型的数组。 说明： - 可以设置为空数组，此时不会创建子组件。 - 可以设置返回值为数组类型的函数，例如arr.slice(1, 3)，但设置的函数不应改变包括数组本身在内的任何状态变量，例如不应使用Array.splice(),Array.sort()或Array.reverse()这些会改变原数组的函数。
itemGenerator (item: any, index?: number) => void 是 组件生成函数 。 - 为数组中的每个元素创建对应的组件。 - item参数：arr数组中的数据项。 - index参数（可选）：arr数组中的数据项索引。 说明： - 组件的类型必须是ForEach的父容器所允许的。例如，ListItem组件要求ForEach的父容器组件必须为List组件。
keyGenerator (item: any, index?: number) => string 否 键值生成函数 。 - 为数据源arr的每个数组项生成唯一且持久的键值 。函数返回值为开发者自定义的键值生成规则。 - item参数：arr数组中的数据项。 - index参数（可选）：arr数组中的数据项索引。 说明： - 如果函数缺省，框架默认的键值生成函数为(item: T, index: number) => { return index + '__' + JSON.stringify(item); } - 键值生成函数不应改变任何组件状态。

说明：

  • ForEach的itemGenerator函数可以包含if/else条件渲染逻辑。另外，也可以在if/else条件渲染语句中使用ForEach组件。
  • 在初始化渲染时，ForEach会加载数据源的所有数据，并为每个数据项创建对应的组件，然后将其挂载到渲染树上。如果数据源非常大或有特定的性能需求，建议使用LazyForEach组件。

键值生成规则

在ForEach循环渲染过程中，系统会为每个数组元素生成一个唯一且持久的键值 ，用于标识对应的组件 。当这个键值变化时，ArkUI框架将视为该数组元素已被替换或修改，并会基于新的键值创建一个新的组件。

ForEach提供了一个名为keyGenerator的参数，这是一个函数，开发者可以通过它自定义键值的生成规则。如果开发者没有定义keyGenerator函数，则ArkUI框架会使用默认的键值生成函数，即(item: any, index: number) => { return index + '__' + JSON.stringify(item); }。

组件创建规则

在确定键值生成规则后，ForEach的第二个参数itemGenerator函数会根据键值生成规则为数据源的每个数组项创建组件。组件的创建包括两种情况：ForEach首次渲染和ForEach非首次渲染。

首次渲染

在ForEach首次渲染时，会根据前述键值生成规则为数据源的每个数组项生成唯一键值，并创建相应的组件。

ts 复制代码 
@Entry
@Component
struct Parent {
  @State simpleList: Array<string> = ['one', 'two', 'three'];

  build() {
    Row() {
      Column() {
        ForEach(this.simpleList, (item: string) => {
          ChildItem({ item: item })
        }, (item: string) => item)
      }
      .width('100%')
      .height('100%')
    }
    .height('100%')
    .backgroundColor(0xF1F3F5)
  }
}

@Component
struct ChildItem {
  @Prop item: string;

  build() {
    Text(this.item)
      .fontSize(50)
  }
}

在上述代码中，键值生成规则是keyGenerator函数的返回值item。在ForEach渲染循环时，为数据源数组项依次生成键值one、two和three，并创建对应的ChildItem组件渲染到界面上。

当不同数组项按照键值生成规则生成的键值相同时，框架的行为是未定义的。例如，在以下代码中，ForEach渲染相同的数据项two时，只创建了一个ChildItem组件，而没有创建多个具有相同键值的组件。

ts 复制代码 
@State simpleList: Array<string> = ['one', 'two', 'two', 'three'];

在该示例中，最终键值生成规则为item。当ForEach遍历数据源simpleList，遍历到索引为1的two时，按照最终键值生成规则生成键值为two的组件并进行标记。当遍历到索引为2的two时，按照最终键值生成规则当前项的键值也为two，此时不再创建新的组件。

非首次渲染

在ForEach组件进行非首次渲染时，它会检查新生成的键值是否在上次渲染中已经存在。如果键值不存在，则会创建一个新的组件；如果键值存在，则不会创建新的组件，而是直接渲染该键值所对应的组件。例如，在以下的代码示例中，通过点击事件修改了数组的第三项值为"new three"，这将触发ForEach组件进行非首次渲染。

ts 复制代码 
@Entry
@Component
struct Parent {
  @State simpleList: Array<string> = ['one', 'two', 'three'];

  build() {
    Row() {
      Column() {
        Text('点击修改第3个数组项的值')
          .fontSize(24)
          .fontColor(Color.Red)
          .onClick(() => {
            this.simpleList[2] = 'new three';
          })

        ForEach(this.simpleList, (item: string) => {
          ChildItem({ item: item })
            .margin({ top: 20 })
        }, (item: string) => item)
      }
      .justifyContent(FlexAlign.Center)
      .width('100%')
      .height('100%')
    }
    .height('100%')
    .backgroundColor(0xF1F3F5)
  }
}

@Component
struct ChildItem {
  @Prop item: string;

  build() {
    Text(this.item)
      .fontSize(30)
  }
}

从本例可以看出@State 能够监听到简单数据类型数组数据源 simpleList 数组项的变化。

  1. 当 simpleList 数组项发生变化时，会触发 ForEach 进行重新渲染。
  2. ForEach 遍历新的数据源 ['one', 'two', 'new three']，并生成对应的键值one、two和new three。
  3. 其中，键值one和two在上次渲染中已经存在，所以 ForEach 复用了对应的组件并进行了渲染。对于第三个数组项 "new three"，由于其通过键值生成规则 item 生成的键值new three在上次渲染中不存在，因此 ForEach 为该数组项创建了一个新的组件。

ForEach组件在开发过程中的主要应用场景包括：数据源不变、数据源数组项发生变化（如插入、删除操作）、数据源数组项子属性变化。

在数据源数组项发生变化的场景下，例如进行数组插入、删除操作或者数组项索引位置发生交换时，数据源应为对象数组类型，并使用对象的唯一ID作为最终键值。例如，当在页面上通过手势上滑加载下一页数据时，会在数据源数组尾部新增新获取的数据项，从而使得数据源数组长度增大。

ts 复制代码 
class Article {
  id: string;
  title: string;
  brief: string;

  constructor(id: string, title: string, brief: string) {
    this.id = id;
    this.title = title;
    this.brief = brief;
  }
}

@Entry
@Component
struct ArticleListView {
  @State isListReachEnd: boolean = false;
  @State articleList: Array<Article> = [
    new Article('001', '第1篇文章', '文章简介内容'),
    new Article('002', '第2篇文章', '文章简介内容'),
    new Article('003', '第3篇文章', '文章简介内容'),
    new Article('004', '第4篇文章', '文章简介内容'),
    new Article('005', '第5篇文章', '文章简介内容'),
    new Article('006', '第6篇文章', '文章简介内容')
  ]

  loadMoreArticles() {
    this.articleList.push(new Article('007', '加载的新文章', '文章简介内容'));
  }

  build() {
    Column({ space: 5 }) {
      List() {
        ForEach(this.articleList, (item: Article) => {
          ListItem() {
            ArticleCard({ article: item })
              .margin({ top: 20 })
          }
        }, (item: Article) => item.id)
      }
      .onReachEnd(() => {
        this.isListReachEnd = true;
      })
      .parallelGesture(
        PanGesture({ direction: PanDirection.Up, distance: 80 })
          .onActionStart(() => {
            if (this.isListReachEnd) {
              this.loadMoreArticles();
              this.isListReachEnd = false;
            }
          })
      )
      .padding(20)
      .scrollBar(BarState.Off)
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xF1F3F5)
  }
}

@Component
struct ArticleCard {
  @Prop article: Article;

  build() {
    Row() {
      Image($r('app.media.icon'))
        .width(80)
        .height(80)
        .margin({ right: 20 })

      Column() {
        Text(this.article.title)
          .fontSize(20)
          .margin({ bottom: 8 })
        Text(this.article.brief)
          .fontSize(16)
          .fontColor(Color.Gray)
          .margin({ bottom: 8 })
      }
      .alignItems(HorizontalAlign.Start)
      .width('80%')
      .height('100%')
    }
    .padding(20)
    .borderRadius(12)
    .backgroundColor('#FFECECEC')
    .height(120)
    .width('100%')
    .justifyContent(FlexAlign.SpaceBetween)
  }
}

初始运行效果（左图）和手势上滑加载后效果（右图）如下图所示。

图6 数据源数组项变化案例运行效果图

在本示例中，ArticleCard组件作为ArticleListView组件的子组件，通过@Prop装饰器接收一个Article对象，用于渲染文章卡片。

  1. 当列表滚动到底部时，如果手势滑动距离超过指定的80，将触发loadMoreArticle()函数。此函数会在articleList数据源的尾部添加一个新的数据项，从而增加数据源的长度。
  2. 数据源被@State装饰器修饰，ArkUI框架能够感知到数据源长度的变化，并触发ForEach进行重新渲染。

使用建议

  • 尽量避免 在最终的键值生成规则中包含数据项索引index ，以防止出现渲染结果非预期 和渲染性能降低 。如果业务确实需要使用index，例如列表需要通过index进行条件渲染，开发者需要接受ForEach在改变数据源后重新创建组件所带来的性能损耗。
  • 为满足键值的唯一性，对于对象数据类型，建议使用对象数据中的唯一id作为键值。
  • 基本数据类型的数据项没有唯一ID属性。如果使用基本数据类型本身作为键值，必须确保数组项无重复。因此，对于数据源会发生变化的场景，建议将基本数据类型数组转化为具备唯一ID属性的对象数据类型数组，再使用ID属性作为键值生成规则。

LazyForEach：数据懒加载

LazyForEach从提供的数据源中按需迭代数据 ，并在每次迭代过程中创建相应的组件。当在滚动容器中使用了LazyForEach，框架会根据滚动容器可视区域按需创建组件 ，当组件滑出可视区域外 时，框架会进行组件销毁回收以降低内存占用。

ts 复制代码 
LazyForEach(
    dataSource: IDataSource,             // 需要进行数据迭代的数据源
    itemGenerator: (item: any, index?: number) => void,  // 子组件生成函数
    keyGenerator?: (item: any, index?: number) => string // 键值生成函数
): void

参数：

参数名 参数类型 必填 参数描述
dataSource IDataSource 是 LazyForEach数据源，需要开发者实现相关接口。
itemGenerator (item: any， index?:number) => void 是 子组件生成函数，为数组中的每一个数据项创建一个子组件。 说明： item是当前数据项，index是数据项索引值。 itemGenerator的函数体必须使用大括号{...}。itemGenerator每次迭代只能并且必须生成一个子组件 。itemGenerator中可以使用if语句，但是必须保证if语句每个分支都会创建一个相同类型的子组件 。itemGenerator中不允许使用ForEach和LazyForEach语句。
keyGenerator (item: any, index?:number) => string 否 键值生成函数，用于给数据源中的每一个数据项生成唯一且固定的键值。当数据项在数组中的位置更改时，其键值不得更改 ，当数组中的数据项被新项替换时，被替换项的键值和新项的键值必须不同 。键值生成器的功能是可选的，但是，为了使开发框架能够更好地识别数组更改，提高性能，建议提供 。如将数组反向时，如果没有提供键值生成器，则LazyForEach中的所有节点都将重建。 说明： item是当前数据项，index是数据项索引值。 数据源中的每一个数据项生成的键值不能重复。

IDataSource类型说明

ts 复制代码 
interface IDataSource {
    totalCount(): number; // 获得数据总数
    getData(index: number): Object; // 获取索引值对应的数据
    registerDataChangeListener(listener: DataChangeListener): void; // 注册数据改变的监听器
    unregisterDataChangeListener(listener: DataChangeListener): void; // 注销数据改变的监听器
}
接口声明 参数类型 说明
totalCount(): number - 获得数据总数。
getData(index: number): any number 获取索引值index对应的数据。 index：获取数据对应的索引值。
registerDataChangeListener(listener:[DataChangeListener](#接口声明 参数类型 说明 totalCount(): number - 获得数据总数。 getData(index: number): any number 获取索引值index对应的数据。 index：获取数据对应的索引值。 registerDataChangeListener(listener:DataChangeListener): void DataChangeListener 注册数据改变的监听器。 listener：数据变化监听器 unregisterDataChangeListener(listener:DataChangeListener): void DataChangeListener 注销数据改变的监听器。 listener：数据变化监听器 "#datachangelistener%E7%B1%BB%E5%9E%8B%E8%AF%B4%E6%98%8E")): void [DataChangeListener](#接口声明 参数类型 说明 totalCount(): number - 获得数据总数。 getData(index: number): any number 获取索引值index对应的数据。 index：获取数据对应的索引值。 registerDataChangeListener(listener:DataChangeListener): void DataChangeListener 注册数据改变的监听器。 listener：数据变化监听器 unregisterDataChangeListener(listener:DataChangeListener): void DataChangeListener 注销数据改变的监听器。 listener：数据变化监听器 "#datachangelistener%E7%B1%BB%E5%9E%8B%E8%AF%B4%E6%98%8E") 注册数据改变的监听器。 listener：数据变化监听器
unregisterDataChangeListener(listener:[DataChangeListener](#接口声明 参数类型 说明 totalCount(): number - 获得数据总数。 getData(index: number): any number 获取索引值index对应的数据。 index：获取数据对应的索引值。 registerDataChangeListener(listener:DataChangeListener): void DataChangeListener 注册数据改变的监听器。 listener：数据变化监听器 unregisterDataChangeListener(listener:DataChangeListener): void DataChangeListener 注销数据改变的监听器。 listener：数据变化监听器 "#datachangelistener%E7%B1%BB%E5%9E%8B%E8%AF%B4%E6%98%8E")): void [DataChangeListener](#接口声明 参数类型 说明 totalCount(): number - 获得数据总数。 getData(index: number): any number 获取索引值index对应的数据。 index：获取数据对应的索引值。 registerDataChangeListener(listener:DataChangeListener): void DataChangeListener 注册数据改变的监听器。 listener：数据变化监听器 unregisterDataChangeListener(listener:DataChangeListener): void DataChangeListener 注销数据改变的监听器。 listener：数据变化监听器 "#datachangelistener%E7%B1%BB%E5%9E%8B%E8%AF%B4%E6%98%8E") 注销数据改变的监听器。 listener：数据变化监听器

DataChangeListener类型说明

ts 复制代码 
interface DataChangeListener {
    onDataReloaded(): void; // 重新加载数据完成后调用
    onDataAdd(index: number): void; // 添加数据完成后调用
    onDataMove(from: number, to: number): void; // 数据移动起始位置与数据移动目标位置交换完成后调用
    onDataDelete(index: number): void; // 删除数据完成后调用
    onDataChange(index: number): void; // 改变数据完成后调用
}
接口声明 参数类型 说明
onDataReloaded(): void - 通知组件重新加载所有数据。 键值没有变化的数据项会使用原先的子组件，键值发生变化的会重建子组件。
onDataAdd(index: number): void8+ number 通知组件index的位置有数据添加。 index：数据添加位置的索引值。
onDataMove(from: number, to: number): void8+ from: number, to: number 通知组件数据有移动。 from: 数据移动起始位置，to: 数据移动目标位置。 说明： 数据移动前后键值要保持不变，如果键值有变化，应使用删除数据和新增数据接口。
onDataDelete(index: number):void8+ number 通知组件删除index位置的数据并刷新LazyForEach的展示内容。 index：数据删除位置的索引值。 说明： 需要保证dataSource中的对应数据已经在调用onDataDelete前删除，否则页面渲染将出现未定义的行为。
onDataChange(index: number): void8+ number 通知组件index的位置有数据有变化。 index：数据变化位置的索引值。

使用限制

  • LazyForEach必须在容器组件内 使用，仅有List、Swiper以及WaterFlow组件支持数据懒加载（可配置cachedCount属性，即只加载可视部分以及其前后少量数据用于缓冲），其他组件仍然是一次性加载所有的数据。
  • LazyForEach在每次迭代中，必须创建且只允许创建一个子组件。
  • 生成的子组件必须是允许包含在LazyForEach父容器组件中的子组件。
  • 允许LazyForEach包含在if/else条件渲染语句中，也允许LazyForEach中出现if/else条件渲染语句。
  • 键值生成器必须针对每个数据生成唯一的值，如果键值相同，将导致键值相同的UI组件被框架忽略，从而无法在父容器内显示。
  • LazyForEach必须使用DataChangeListener对象来进行更新，第一个参数dataSource使用状态变量时，状态变量改变不会触发LazyForEach的UI刷新。
  • 为了高性能渲染，通过DataChangeListener对象的onDataChange方法来更新UI时，需要生成不同于原来的键值来触发组件刷新。

键值生成规则

在LazyForEach循环渲染过程中，系统会为每个item生成一个唯一且持久的键值 ，用于标识对应的组件。当这个键值变化时，ArkUI框架将视为该数组元素已被替换或修改，并会基于新的键值创建一个新的组件。

LazyForEach提供了一个名为keyGenerator的参数，这是一个函数，开发者可以通过它自定义键值的生成规则。如果开发者没有定义keyGenerator函数，则ArkUI框架会使用默认的键值生成函数，即(item: any, index: number) => { return viewId + '-' + index.toString(); }, viewId在编译器转换过程中生成，同一个LazyForEach组件内其viewId是一致的。

组件创建规则

在确定键值生成规则后，LazyForEach的第二个参数itemGenerator函数会根据键值生成规则为数据源的每个数组项创建组件。组件的创建包括两种情况：LazyForEach首次渲染和LazyForEach非首次渲染。

在LazyForEach首次渲染时，会根据上述键值生成规则为数据源的每个数组项生成唯一键值，并创建相应的组件。

ts 复制代码 
// Basic implementation of IDataSource to handle data listener
class BasicDataSource implements IDataSource {
  private listeners: DataChangeListener[] = [];
  private originDataArray: string[] = [];

  public totalCount(): number {
    return 0;
  }

  public getData(index: number): string {
    return this.originDataArray[index];
  }

  // 该方法为框架侧调用，为LazyForEach组件向其数据源处添加listener监听
  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      console.info('add listener');
      this.listeners.push(listener);
    }
  }

  // 该方法为框架侧调用，为对应的LazyForEach组件在数据源处去除listener监听
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener);
    if (pos >= 0) {
      console.info('remove listener');
      this.listeners.splice(pos, 1);
    }
  }

  // 通知LazyForEach组件需要重载所有子组件
  notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded();
    })
  }

  // 通知LazyForEach组件需要在index对应索引处添加子组件
  notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdd(index);
    })
  }

  // 通知LazyForEach组件在index对应索引处数据有变化，需要重建该子组件
  notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChange(index);
    })
  }

  // 通知LazyForEach组件需要在index对应索引处删除该子组件
  notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDelete(index);
    })
  }
}

class MyDataSource extends BasicDataSource {
  private dataArray: string[] = [];

  public totalCount(): number {
    return this.dataArray.length;
  }

  public getData(index: number): string {
    return this.dataArray[index];
  }

  public addData(index: number, data: string): void {
    this.dataArray.splice(index, 0, data);
    this.notifyDataAdd(index);
  }

  public pushData(data: string): void {
    this.dataArray.push(data);
    this.notifyDataAdd(this.dataArray.length - 1);
  }
}

@Entry
@Component
struct MyComponent {
  private data: MyDataSource = new MyDataSource();
   
  aboutToAppear() {
    for (let i = 0; i <= 20; i++) {
      this.data.pushData(`Hello ${i}`)
    }
  }

  build() {
    List({ space: 3 }) {
      LazyForEach(this.data, (item: string) => {
        ListItem() {
          Row() {
            Text(item).fontSize(50)
              .onAppear(() => {
                console.info("appear:" + item)
              })
          }.margin({ left: 10, right: 10 })
        }
      }, (item: string) => item)
    }.cachedCount(5)
  }
}

当LazyForEach数据源发生变化，需要再次渲染 时，开发者应根据数据源的变化情况调用listener对应的接口，通知LazyForEach做相应的更新。

ts 复制代码 
class BasicDataSource implements IDataSource {
  private listeners: DataChangeListener[] = [];
  private originDataArray: string[] = [];

  public totalCount(): number {
    return 0;
  }

  public getData(index: number): string {
    return this.originDataArray[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      console.info('add listener');
      this.listeners.push(listener);
    }
  }

  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener);
    if (pos >= 0) {
      console.info('remove listener');
      this.listeners.splice(pos, 1);
    }
  }

  notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded();
    })
  }

  notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdd(index);
    })
  }

  notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChange(index);
    })
  }

  notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDelete(index);
    })
  }
}

class MyDataSource extends BasicDataSource {
  private dataArray: string[] = [];

  public totalCount(): number {
    return this.dataArray.length;
  }

  public getData(index: number): string {
    return this.dataArray[index];
  }

  public addData(index: number, data: string): void {
    this.dataArray.splice(index, 0, data);
    this.notifyDataAdd(index);
  }

  public pushData(data: string): void {
    this.dataArray.push(data);
    this.notifyDataAdd(this.dataArray.length - 1);
  }
}

@Entry
@Component
struct MyComponent {
  private data: MyDataSource = new MyDataSource();

  aboutToAppear() {
    for (let i = 0; i <= 20; i++) {
      this.data.pushData(`Hello ${i}`)
    }
  }

  build() {
    List({ space: 3 }) {
      LazyForEach(this.data, (item: string) => {
        ListItem() {
          Row() {
            Text(item).fontSize(50)
              .onAppear(() => {
                console.info("appear:" + item)
              })
          }.margin({ left: 10, right: 10 })
        }
        .onClick(() => {
          // 点击追加子组件
          this.data.pushData(`Hello ${this.data.totalCount()}`);
        })
      }, (item: string) => item)
    }.cachedCount(5)
  }
}

布局

布局概述

布局元素组成图

如何选择布局

声明式UI提供了以下9种常见布局，开发者可根据实际应用场景选择合适的布局进行页面开发。

布局 应用场景
线性布局（Row、Column） 如果布局内子元素超过1个时，且能够以某种方式线性排列时优先考虑此布局。
层叠布局（Stack） 组件需要有堆叠效果 时优先考虑此布局。层叠布局的堆叠效果不会占用或影响其他同容器内子组件的布局空间。例如 Panel 作为子组件弹出时将其他组件覆盖更为合理，则优先考虑在外层使用堆叠布局。
弹性布局（Flex） 弹性布局是与线性布局类似的布局方式。区别在于弹性布局默认能够使子组件压缩或拉伸。在子组件需要计算拉伸或压缩比例时优先使用此布局，可使得多个容器内子组件能有更好的视觉上的填充效果。
相对布局（RelativeContainer） 相对布局是在二维空间中的布局方式，不需要遵循线性布局的规则，布局方式更为自由。通过在子组件上设置锚点 规则（AlignRules）使子组件能够将自己在横轴、纵轴中的位置与容器或容器内其他子组件的位置对齐。设置的锚点规则可以天然支持子元素压缩、拉伸、堆叠或形成多行效果。在页面元素分布复杂或通过线性布局会使容器嵌套层数过深时推荐使用。
栅格布局（GridRow、GridCol） 栅格是多设备场景下通用的辅助定位工具，可将空间分割为有规律的栅格。栅格 不同于网格布局固定的空间划分，可以实现不同设备下不同的布局，空间划分更随心所欲，从而显著降低适配不同屏幕尺寸的设计及开发成本，使得整体设计和开发流程更有秩序和节奏感，同时也保证多设备上应用显示的协调性和一致性，提升用户体验。推荐内容相同但布局不同时使用。
媒体查询（@ohos.mediaquery） 媒体查询可根据不同设备类型或同设备不同状态修改应用的样式。例如根据设备和应用的不同属性信息设计不同的布局，以及屏幕发生动态改变时更新应用的页面布局。
列表（List） 使用列表可以高效地显示结构化、可滚动的信息。在ArkUI中，列表具有垂直和水平布局能力和自适应交叉轴方向上排列个数的布局能力，超出屏幕时可以滚动。列表适合用于呈现同类数据类型或数据类型集，例如图片和文本。
网格（Grid） 网格布局具有较强的页面均分能力、子元素占比控制能力。网格布局可以控制元素所占的网格数量、设置子元素横跨几行或者几列，当网格容器尺寸发生变化时，所有子元素以及间距等比例调整。推荐在需要按照固定比例或者均匀分配空间的布局场景下使用，例如计算器、相册、日历等。
轮播（Swiper） 轮播组件通常用于实现广告轮播、图片预览等。

布局位置

position、offset等属性影响了布局容器相对于自身或其他组件的位置。

定位能力 使用场景 实现方式
绝对定位 对于不同尺寸的设备，使用绝对定位的适应性会比较差，在屏幕的适配上有缺陷。 使用position实现绝对定位，设置元素左上角相对于父容器左上角偏移位置。在布局容器中，设置该属性不影响父容器布局，仅在绘制时进行位置调整。
相对定位 相对定位不脱离文档流，即原位置依然保留，不影响元素本身的特性，仅相对于原位置进行偏移。 使用offset可以实现相对定位，设置元素相对于自身的偏移量。设置该属性，不影响父容器布局，仅在绘制时进行位置调整。

对子元素的约束

对子元素的约束能力 使用场景 实现方式
拉伸 容器组件尺寸发生变化时，增加或减小的空间全部分配给容器组件内指定区域。 flexGrow和flexShrink属性： 1. flexGrow基于父容器的剩余空间分配来控制组件拉伸 。 2. flexShrink设置父容器的压缩尺寸来控制组件压缩。
缩放 子组件的宽高按照预设的比例，随容器组件发生变化，且变化过程中子组件的宽高比不变。 aspectRatio属性指定当前组件的宽高比来控制缩放，公式为：aspectRatio=width/height。
占比 占比能力是指子组件的宽高按照预设的比例，随父容器组件发生变化。 基于通用属性的两种实现方式： 1. 将子组件的宽高设置为父组件宽高的百分比 。 2. layoutWeight属性，使得子元素自适应占满剩余空间。
隐藏 隐藏能力是指容器组件内的子组件，按照其预设的显示优先级，随容器组件尺寸变化显示或隐藏，其中相同显示优先级的子组件同时显示或隐藏。 通过displayPriority属性来控制组件的显示和隐藏。

线性布局 (Row/Column)

Column容器内子元素按照垂直方向排列，Row容器内子元素按照水平方向排列。

在布局容器内，可以通过space属性设置排列方向上子元素的间距，使各子元素在排列方向上有等间距效果。

ts 复制代码 
Column({ space: 20 }) {
  ...
}.width('100%')

在布局容器内，可以通过alignItems属性设置子元素在交叉轴 （排列方向的垂直方向）上的对齐方式。且在各类尺寸屏幕中，表现一致。其中，交叉轴为垂直方向时，取值为VerticalAlign类型，水平方向取值为HorizontalAlign。

alignSelf属性用于控制单个子元素在容器交叉轴上的对齐方式，其优先级高于alignItems属性，如果设置了alignSelf属性，则在单个子元素上会覆盖alignItems属性。

ts 复制代码 
Row({}) {
  Column() {
  }.width('20%').height(30).backgroundColor(0xF5DEB3)

  Column() {
  }.width('20%').height(30).backgroundColor(0xD2B48C)

  Column() {
  }.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).alignItems(VerticalAlign.Bottom).backgroundColor('rgb(242,242,242)')

在布局容器内，可以通过justifyContent属性设置子元素在容器主轴上的排列方式。

ts 复制代码 
Row({}) {
  Column() {
  }.width('20%').height(30).backgroundColor(0xF5DEB3)

  Column() {
  }.width('20%').height(30).backgroundColor(0xD2B48C)

  Column() {
  }.width('20%').height(30).backgroundColor(0xF5DEB3)
}.width('100%').height(200).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceBetween)

自适应拉伸

在线性布局下，常用空白填充组件 Blank，在容器主轴方向自动填充空白空间，达到自适应拉伸效果。Row和Column作为容器，只需要添加宽高为百分比，当屏幕宽高发生变化时，会产生自适应效果。

ts 复制代码 
@Entry
@Component
struct BlankExample {
  build() {
    Column() {
      Row() {
        Text('Bluetooth').fontSize(18)
        Blank()
        Toggle({ type: ToggleType.Switch, isOn: true })
      }.backgroundColor(0xFFFFFF).borderRadius(15).padding({ left: 12 }).width('100%')
    }.backgroundColor(0xEFEFEF).padding(20).width('100%')
  }
}

自适应缩放

自适应缩放是指子元素随容器尺寸的变化而按照预设的比例自动调整尺寸，适应各种不同大小的设备。在线性布局中，可以使用以下两种方法实现自适应缩放。

  • 父容器尺寸确定时，使用 layoutWeight 属性设置子元素和兄弟元素在主轴上的权重，忽略元素本身尺寸设置，使它们在任意尺寸的设备下自适应占满剩余空间。

    ts 复制代码 
    @Entry
@Component
struct layoutWeightExample {
  build() {
    Column() {
      Text('1:2:3').width('100%')
      Row() {
        Column() {
          Text('layoutWeight(1)')
            .textAlign(TextAlign.Center)
        }.layoutWeight(1).backgroundColor(0xF5DEB3).height('100%')

        Column() {
          Text('layoutWeight(2)')
            .textAlign(TextAlign.Center)
        }.layoutWeight(2).backgroundColor(0xD2B48C).height('100%')

        Column() {
          Text('layoutWeight(3)')
            .textAlign(TextAlign.Center)
        }.layoutWeight(3).backgroundColor(0xF5DEB3).height('100%')

      }.backgroundColor(0xffd306).height('30%')

      Text('2:5:3').width('100%')
      Row() {
        Column() {
          Text('layoutWeight(2)')
            .textAlign(TextAlign.Center)
        }.layoutWeight(2).backgroundColor(0xF5DEB3).height('100%')

        Column() {
          Text('layoutWeight(5)')
            .textAlign(TextAlign.Center)
        }.layoutWeight(5).backgroundColor(0xD2B48C).height('100%')

        Column() {
          Text('layoutWeight(3)')
            .textAlign(TextAlign.Center)
        }.layoutWeight(3).backgroundColor(0xF5DEB3).height('100%')
      }.backgroundColor(0xffd306).height('30%')
    }
  }
}

  • 父容器尺寸确定时，使用百分比设置子元素和兄弟元素的宽度，使他们在任意尺寸的设备下保持固定的自适应占比。

    ts 复制代码 
    @Entry
@Component
struct WidthExample {
  build() {
    Column() {
      Row() {
        Column() {
          Text('left width 20%')
            .textAlign(TextAlign.Center)
        }.width('20%').backgroundColor(0xF5DEB3).height('100%')

        Column() {
          Text('center width 50%')
            .textAlign(TextAlign.Center)
        }.width('50%').backgroundColor(0xD2B48C).height('100%')

        Column() {
          Text('right width 30%')
            .textAlign(TextAlign.Center)
        }.width('30%').backgroundColor(0xF5DEB3).height('100%')
      }.backgroundColor(0xffd306).height('30%')
    }
  }
}

自适应延伸

自适应延伸是指在不同尺寸设备下，当页面的内容超出屏幕大小而无法完全显示时，可以通过滚动条进行拖动展示。这种方法适用于线性布局中内容无法一屏展示的场景。通常有以下两种实现方式。

  • 在List中添加滚动条：当List子项过多一屏放不下时，可以将每一项子元素放置在不同的组件中，通过滚动条进行拖动展示。可以通过scrollBar属性设置滚动条的常驻状态，edgeEffect属性设置拖动到内容最末端的回弹效果。

  • 使用Scroll组件：在线性布局中，开发者可以进行垂直方向或者水平方向的布局。当一屏无法完全显示时，可以在Column或Row组件的外层包裹一个可滚动的容器组件Scroll来实现可滑动的线性布局。

    垂直方向布局中使用Scroll组件：

    ts 复制代码 
    @Entry
@Component
struct ScrollExample {
  scroller: Scroller = new Scroller();
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

  build() {
    Scroll(this.scroller) {
      Column() {
        ForEach(this.arr, (item?:number|undefined) => {
          if(item){
            Text(item.toString())
            .width('90%')
            .height(150)
            .backgroundColor(0xFFFFFF)
            .borderRadius(15)
            .fontSize(16)
            .textAlign(TextAlign.Center)
            .margin({ top: 10 })
          }
        }, (item:number) => item.toString())
      }.width('100%')
    }
    .backgroundColor(0xDCDCDC)
    .scrollable(ScrollDirection.Vertical) // 滚动方向为垂直方向
    .scrollBar(BarState.On) // 滚动条常驻显示
    .scrollBarColor(Color.Gray) // 滚动条颜色
    .scrollBarWidth(10) // 滚动条宽度
    .edgeEffect(EdgeEffect.Spring) // 滚动到边沿后回弹
  }
}

层叠布局 (Stack)

层叠布局（StackLayout）用于在屏幕上预留一块区域 来显示组件中的元素，提供元素可以重叠 的布局。层叠布局通过Stack容器组件实现位置的固定定位与层叠 ，容器中的子元素依次入栈 ，后一个子元素覆盖前一个子元素，子元素可以叠加，也可以设置位置。

层叠布局具有较强的页面层叠、位置定位 能力，其使用场景有广告、卡片层叠效果等。

如图1，Stack作为容器，容器内的子元素的顺序为Item1->Item2->Item3。

Stack组件为容器组件，容器内可包含各种子元素。其中子元素默认进行居中堆叠。子元素被约束在Stack下，进行自己的样式定义以及排列。

ts 复制代码 
let MTop:Record<string,number> = { 'top': 50 }
Column(){
  Stack({ }) {
    Column(){}.width('90%').height('100%').backgroundColor('#ff58b87c')
    Text('text').width('60%').height('60%').backgroundColor('#ffc3f6aa')
    Button('button').width('30%').height('30%').backgroundColor('#ff8ff3eb').fontColor('#000')
  }.width('100%').height(150).margin(MTop)
}

对齐方式

Stack组件通过 alignContent 参数实现位置的相对移动。如图2所示，支持九种对齐方式。

ts 复制代码 
// xxx.ets
@Entry
@Component
struct StackExample {
  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      Text('Stack').width('90%').height('100%').backgroundColor('#e1dede').align(Alignment.BottomEnd)
      Text('Item 1').width('70%').height('80%').backgroundColor(0xd2cab3).align(Alignment.BottomEnd)
      Text('Item 2').width('50%').height('60%').backgroundColor(0xc1cbac).align(Alignment.BottomEnd)
    }.width('100%').height(150).margin({ top: 5 })
  }
}

Z序控制

Stack容器中兄弟组件显示层级关系可以通过Z序控制的zIndex属性改变。zIndex值越大，显示层级越高，即zIndex值大的组件会覆盖在zIndex值小的组件上方。

在层叠布局中，如果后面子元素尺寸大于前面子元素尺寸，则前面子元素完全隐藏。

ts 复制代码 
let MTopM:Record<string,number> = { 'top': 100 }
Stack({ alignContent: Alignment.BottomStart }) {
  Column() {
    Text('Stack子元素1').fontSize(20)
  }.width(100).height(100).backgroundColor(0xffd306).zIndex(2)

  Column() {
    Text('Stack子元素2').fontSize(20)
  }.width(150).height(150).backgroundColor(Color.Pink).zIndex(1)

  Column() {
    Text('Stack子元素3').fontSize(20)
  }.width(200).height(200).backgroundColor(Color.Grey)
}.margin(MTopM).width(350).height(350).backgroundColor(0xe0e0e0)

弹性布局 (Flex)

容器默认存在主轴与交叉轴，子元素默认沿主轴排列，子元素在主轴方向的尺寸称为主轴尺寸，在交叉轴方向的尺寸称为交叉轴尺寸。

布局方向

在弹性布局中，容器的子元素可以按照任意方向排列。通过设置参数direction，可以决定主轴的方向，从而控制子元素的排列方向。

  • FlexDirection.Row（默认值）：主轴为水平方向，子元素从起始端沿着水平方向开始排布。
  • FlexDirection.RowReverse：主轴为水平方向，子元素从终点端沿着FlexDirection. Row相反的方向开始排布。
  • FlexDirection.Column：主轴为垂直方向，子元素从起始端沿着垂直方向开始排布。
  • FlexDirection.ColumnReverse：主轴为垂直方向，子元素从终点端沿着FlexDirection. Column相反的方向开始排布。

布局换行

弹性布局分为单行布局和多行布局。默认情况下，Flex容器中的子元素都排在一条线（又称"轴线"）上。wrap属性控制当子元素主轴尺寸之和大于容器主轴尺寸时，Flex是单行布局还是多行布局。在多行布局时，通过交叉轴方向，确认新行排列方向。

  • FlexWrap.NoWrap（默认值）：不换行。如果子元素的宽度总和大于父元素的宽度，则子元素会被压缩宽度。
  • FlexWrap.Wrap：换行，每一行子元素按照主轴方向排列。
  • FlexWrap.WrapReverse：换行，每一行子元素按照主轴反方向排列。

主轴对齐方式

通过justifyContent参数设置子元素在主轴方向的对齐方式。

交叉轴对齐方式

容器和子元素都可以设置交叉轴对齐方式，且子元素设置的对齐方式优先级较高。

可以通过Flex组件的alignItems参数设置子元素在交叉轴的对齐方式。

  • ItemAlign.Auto：使用Flex容器中默认配置。

    ts 复制代码 
    let SWh:Record<string,number|string> = { 'width': '90%', 'height': 80 }
Flex({ alignItems: ItemAlign.Auto }) {  
  Text('1').width('33%').height(30).backgroundColor(0xF5DEB3)  
  Text('2').width('33%').height(40).backgroundColor(0xD2B48C)  
  Text('3').width('33%').height(50).backgroundColor(0xF5DEB3)
}
.size(SWh)
.padding(10)
.backgroundColor(0xAFEEEE)

  • ItemAlign.Start：交叉轴方向首部对齐。

  • ItemAlign.Center：交叉轴方向居中对齐。

  • ItemAlign.End：交叉轴方向底部对齐。

  • ItemAlign.Stretch：交叉轴方向拉伸填充，在未设置尺寸时，拉伸到容器尺寸。

  • ItemAlign. Baseline：交叉轴方向文本基线对齐。

子元素设置交叉轴对齐

子元素的alignSelf属性也可以设置子元素在父容器交叉轴的对齐格式，且会覆盖Flex布局容器中alignItems配置。

ts 复制代码 
Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { // 容器组件设置子元素居中
  Text('alignSelf Start').width('25%').height(80)
    .alignSelf(ItemAlign.Start)
    .backgroundColor(0xF5DEB3)
  Text('alignSelf Baseline')
    .alignSelf(ItemAlign.Baseline)
    .width('25%')
    .height(80)
    .backgroundColor(0xD2B48C)
  Text('alignSelf Baseline').width('25%').height(100)
    .backgroundColor(0xF5DEB3)
    .alignSelf(ItemAlign.Baseline)
  Text('no alignSelf').width('25%').height(100)
    .backgroundColor(0xD2B48C)
  Text('no alignSelf').width('25%').height(100)
    .backgroundColor(0xF5DEB3)

}.width('90%').height(220).backgroundColor(0xAFEEEE)

内容对齐

可以通过alignContent参数设置子元素各行在交叉轴剩余空间内的对齐方式，只在多行的Flex布局中生效，可选值有：

  • FlexAlign.Start：子元素各行与交叉轴起点对齐。
  • FlexAlign.Center：子元素各行在交叉轴方向居中对齐。
  • FlexAlign.End：子元素各行与交叉轴终点对齐。
  • FlexAlign.SpaceBetween：子元素各行与交叉轴两端对齐，各行间垂直间距平均分布。
  • FlexAlign.SpaceAround：子元素各行间距相等，是元素首尾行与交叉轴两端距离的两倍。
  • FlexAlign.SpaceEvenly: 子元素各行间距，子元素首尾行与交叉轴两端距离都相等。
ts 复制代码 
Flex({ justifyContent: FlexAlign.SpaceBetween, wrap: FlexWrap.Wrap, alignContent: FlexAlign.SpaceEvenly }) {
  Text('1').width('30%').height(20).backgroundColor(0xF5DEB3)
  Text('2').width('60%').height(20).backgroundColor(0xD2B48C)
  Text('3').width('40%').height(20).backgroundColor(0xD2B48C)
  Text('4').width('30%').height(20).backgroundColor(0xF5DEB3)
  Text('5').width('20%').height(20).backgroundColor(0xD2B48C)
}
.width('90%')
.height(100)
.backgroundColor(0xAFEEEE)

自适应拉伸

在弹性布局父组件尺寸过小时，通过子元素的以下属性设置其在父容器的占比，达到自适应布局。

  • flexBasis：设置子元素在父容器主轴方向上的基准尺寸。如果设置了该属性，则子项占用的空间为该属性所设置的值；如果没设置该属性，那子项的空间为width/height的值。

    ts 复制代码 
    Flex() {
  Text('flexBasis("auto")')
    .flexBasis('auto') // 未设置width以及flexBasis值为auto，内容自身宽度
    .height(100)
    .backgroundColor(0xF5DEB3)
  Text('flexBasis("auto")'+' width("40%")')
    .width('40%')
    .flexBasis('auto') //设置width以及flexBasis值auto，使用width的值
    .height(100)
    .backgroundColor(0xD2B48C)

  Text('flexBasis(100)')  // 未设置width以及flexBasis值为100，宽度为100vp
    .flexBasis(100)  
    .height(100)
    .backgroundColor(0xF5DEB3)

  Text('flexBasis(100)')
    .flexBasis(100)
    .width(200) // flexBasis值为100，覆盖width的设置值，宽度为100vp
    .height(100)
    .backgroundColor(0xD2B48C)
}.width('90%').height(120).padding(10).backgroundColor(0xAFEEEE)

  • flexGrow：设置父容器的剩余空间分配给此属性所在组件的比例。用于分配父组件的剩余空间。

    ts 复制代码 
    Flex() {
  Text('flexGrow(2)')
    .flexGrow(2)
    .width(100)
    .height(100)
    .backgroundColor(0xF5DEB3)
  Text('flexGrow(3)')
    .flexGrow(3)
    .width(100)
    .height(100)
    .backgroundColor(0xD2B48C)

  Text('no flexGrow')
    .width(100)
    .height(100)
    .backgroundColor(0xF5DEB3)
}.width(420).height(120).padding(10).backgroundColor(0xAFEEEE)

    父容器宽度420vp，三个子元素原始宽度为100vp，左右padding为20vp，总和320vp，剩余空间100vp根据flexGrow值的占比分配给子元素，未设置flexGrow的子元素不参与"瓜分"。

  • flexShrink: 当父容器空间不足 时，子元素的压缩比例。

    ts 复制代码 
    Flex({ direction: FlexDirection.Row }) {
  Text('flexShrink(3)')
    .flexShrink(3)
    .width(200)
    .height(100)
    .backgroundColor(0xF5DEB3)
  
  Text('no flexShrink')
    .width(200)
    .height(100)
    .backgroundColor(0xD2B48C)

  Text('flexShrink(2)')
    .flexShrink(2)
    .width(200)
    .height(100)
    .backgroundColor(0xF5DEB3)  
}.width(400).height(120).padding(10).backgroundColor(0xAFEEEE)

相对布局 (RelativeContainer)

在应用的开发过程中，经常需要设计复杂界面，此时涉及到多个相同或不同组件之间的嵌套。如果布局组件嵌套深度过深，或者嵌套组件数过多，会带来额外的开销。如果在布局的方式上进行优化，就可以有效的提升性能，减少时间开销。

RelativeContainer为采用相对布局 的容器，支持容器内部的子元素设置相对位置关系，适用于界面复杂场景的情况，对多个子组件进行对齐和排列。子元素支持指定兄弟元素作为锚点，也支持指定父容器作为锚点，基于锚点做相对位置布局。

子元素并不完全是上图中的依赖关系。比如，Item4可以以Item2为依赖锚点，也可以以RelativeContainer父容器为依赖锚点。

  • 锚点：通过锚点设置当前元素基于哪个元素确定位置。
  • 对齐方式：通过对齐方式，设置当前元素是基于锚点的上中下对齐，还是基于锚点的左中右对齐。

锚点设置

锚点设置是指设置子元素相对于父元素或兄弟元素的位置依赖关系。在水平方向上，可以设置left、middle、right的锚点。在竖直方向上，可以设置top、center、bottom的锚点。 为了明确定义锚点，必须为RelativeContainer及其子元素设置ID ，用于指定锚点信息。ID默认为"__container__"，其余子元素的ID通过id属性设置。未设置ID的子元素在 RelativeContainer中不会显示 。互相依赖，环形依赖时容器内子组件全部不绘制 。同方向上两个以上位置设置锚点，但锚点位置逆序时此子组件大小为0，即不绘制。

在使用锚点时要注意子元素的相对位置关系，避免出现错位或遮挡的情况。

  • RelativeContainer父组件为锚点，__container__代表父容器的ID。

    ts 复制代码 
    let AlignRus:Record<string,Record<string,string|VerticalAlign|HorizontalAlign>> = {
  'top': { 'anchor': '__container__', 'align': VerticalAlign.Top },
  'left': { 'anchor': '__container__', 'align': HorizontalAlign.Start }
}
let AlignRue:Record<string,Record<string,string|VerticalAlign|HorizontalAlign>> = {
  'top': { 'anchor': '__container__', 'align': VerticalAlign.Top },
  'right': { 'anchor': '__container__', 'align': HorizontalAlign.End }
}
let Mleft:Record<string,number> = { 'left': 20 }
let BWC:Record<string,number|string> = { 'width': 2, 'color': '#6699FF' }
RelativeContainer() {
  Row().width(100).height(100)
    .backgroundColor("#FF3333")
    .alignRules(AlignRus)
    .id("row1")

  Row().width(100).height(100)
    .backgroundColor("#FFCC00")
    .alignRules(AlignRue)
    .id("row2")
}.width(300).height(300)
.margin(Mleft)
.border(BWC)

  • 以兄弟元素为锚点。

    ts 复制代码 
    let AlignRus:Record<string,Record<string,string|VerticalAlign|HorizontalAlign>> = {
  'top': { 'anchor': '__container__', 'align': VerticalAlign.Top },
  'left': { 'anchor': '__container__', 'align': HorizontalAlign.Start }
}
let RelConB:Record<string,Record<string,string|VerticalAlign|HorizontalAlign>> = {
  'top': { 'anchor': 'row1', 'align': VerticalAlign.Bottom },
  'left' : { 'anchor': 'row1', 'align': HorizontalAlign.Start }
}
let Mleft:Record<string,number> = { 'left': 20 }
let BWC:Record<string,number|string> = { 'width': 2, 'color': '#6699FF' }
RelativeContainer() {
  Row().width(100).height(100)
    .backgroundColor("#FF3333")
    .alignRules(AlignRus)
    .id("row1")

  Row().width(100).height(100)
    .backgroundColor("#FFCC00")
    .alignRules(RelConB)
    .id("row2")
}.width(300).height(300)
.margin(Mleft)
.border(BWC)

  • 子组件锚点可以任意选择，但需注意不要相互依赖。

设置相对于锚点的对齐位置

设置了锚点之后，可以通过align设置相对于锚点的对齐位置。

在水平方向上，对齐位置可以设置为HorizontalAlign.Start、HorizontalAlign.Center、HorizontalAlign.End。

在竖直方向上，对齐位置可以设置为VerticalAlign.Top、VerticalAlign.Center、VerticalAlign.Bottom。

子组件位置偏移

子组件经过相对位置对齐后，位置可能还不是目标位置，开发者可根据需要进行额外偏移设置offset。

ts 复制代码 
        Row()
          .backgroundColor("#FF9966")
          .alignRules({
            top: {anchor: "row3", align: VerticalAlign.Bottom},
            bottom: {anchor: "__container__", align: VerticalAlign.Bottom},
            left: {anchor: "__container__", align: HorizontalAlign.Start},
            right: {anchor: "row1", align: HorizontalAlign.End}
          })
          .offset({
            x:-10,
            y:-30
          })
          .id("row4")

Row、Column、Flex、Stack等多种布局组件，可按照RelativeContainer组件规则进行对其排布。

子组件尺寸大小不会受到相对布局规则的影响。若子组件某个方向上设置两个或以上alignRules时最好不设置此方向尺寸大小，否则对齐规则确定的组件尺寸与开发者设置的尺寸可能产生冲突。

栅格布局 (GridRow/GridCol)

栅格布局是一种通用的辅助定位工具，对移动设备的界面设计有较好的借鉴作用。

自动换行和自适应：栅格布局可以完成一对多布局的自动换行和自适应。

GridRow为栅格容器组件，需与栅格子组件GridCol在栅格布局场景中联合使用。

栅格系统断点

栅格系统以设备的水平宽度（屏幕密度像素值，单位vp）作为断点依据，定义设备的宽度类型，形成了一套断点规则。开发者可根据需求在不同的断点区间实现不同的页面布局效果。

栅格系统默认断点将设备宽度分为xs、sm、md、lg四类，尺寸范围如下：

断点名称 取值范围（vp） 设备描述
xs [0, 320） 最小宽度类型设备。
sm [320, 520) 小宽度类型设备。
md [520, 840) 中等宽度类型设备。
lg [840, +∞) 大宽度类型设备。

在GridRow栅格组件中，允许开发者使用breakpoints自定义修改断点的取值范围，最多支持6个断点，除了默认的四个断点外，还可以启用xl，xxl两个断点，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备的布局设置。

断点名称 设备描述
xs 最小宽度类型设备。
sm 小宽度类型设备。
md 中等宽度类型设备。
lg 大宽度类型设备。
xl 特大宽度类型设备。
xxl 超大宽度类型设备。

  • 针对断点位置，开发者根据实际使用场景，通过一个单调递增数组设置。由于breakpoints最多支持六个断点，单调递增数组长度最大为5。

    css 复制代码 
    breakpoints: {value: ['100vp', '200vp']}

    表示启用xs、sm、md共3个断点，小于100vp为xs，100vp-200vp为sm，大于200vp为md。

    css 复制代码 
    breakpoints: {value: ['320vp', '520vp', '840vp', '1080vp']}

    表示启用xs、sm、md、lg、xl共5个断点，小于320vp为xs，320vp-520vp为sm，520vp-840vp为md，840vp-1080vp为lg，大于1080vp为xl。

  • 栅格系统通过监听窗口或容器的尺寸变化进行断点，通过reference设置断点切换参考物。 考虑到应用可能以非全屏窗口的形式显示，以应用窗口宽度为参照物更为通用。

例如，使用栅格的默认列数12列，通过断点设置将应用宽度分成六个区间，在各区间中，每个栅格子元素占用的列数均不同。

ts 复制代码 
@State bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown];
...
GridRow({
  breakpoints: {
    value: ['200vp', '300vp', '400vp', '500vp', '600vp'],
    reference: BreakpointsReference.WindowSize
  }
}) {
   ForEach(this.bgColors, (color:Color, index?:number|undefined) => {
     GridCol({
       span: {
         xs: 2, // 在最小宽度类型设备上，栅格子组件占据的栅格容器2列。
         sm: 3, // 在小宽度类型设备上，栅格子组件占据的栅格容器3列。
         md: 4, // 在中等宽度类型设备上，栅格子组件占据的栅格容器4列。
         lg: 6, // 在大宽度类型设备上，栅格子组件占据的栅格容器6列。
         xl: 8, // 在特大宽度类型设备上，栅格子组件占据的栅格容器8列。
         xxl: 12 // 在超大宽度类型设备上，栅格子组件占据的栅格容器12列。
       }
     }) {
       Row() {
         Text(`${index}`)
       }.width("100%").height('50vp')
     }.backgroundColor(color)
   })
}

布局的总列数

GridRow中通过columns设置栅格布局的总列数。

  • columns默认值为12，即在未设置columns时，任何断点下，栅格布局被分成12列。
  • 当columns为自定义值，栅格布局在任何尺寸设备下都被分为columns列。下面分别设置栅格布局列数为4和8，子元素默认占一列，效果如下：
  • 当columns类型为GridRowColumnOption时，支持下面六种不同尺寸（xs, sm, md, lg, xl, xxl）设备的总列数设置，各个尺寸下数值可不同。
ts 复制代码 
@State bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown]
GridRow({ columns: { sm: 4, md: 8 }, breakpoints: { value: ['200vp', '300vp', '400vp', '500vp', '600vp'] } }) {
  ForEach(this.bgColors, (item:Color, index?:number|undefined) => {
    GridCol() {
      Row() {
        Text(`${index}`)
      }.width('100%').height('50')
    }.backgroundColor(item)
  })
}

若只设置sm, md的栅格总列数，则较小的尺寸使用默认columns值12，较大的尺寸使用前一个尺寸的columns。这里只设置sm:4, md:8，则较小尺寸的xs:12，较大尺寸的参照md的设置，lg:8, xl:8, xxl:8

排列方向

栅格布局中，可以通过设置GridRow的direction属性来指定栅格子组件在栅格容器中的排列方向。该属性可以设置为GridRowDirection.Row（从左往右排列）或GridRowDirection.RowReverse（从右往左排列），以满足不同的布局需求。

子组件间距

GridRow中通过gutter属性设置子元素在水平和垂直方向的间距。

  • 当gutter类型为number时，同时设置栅格子组件间水平和垂直方向边距且相等。

  • 当gutter类型为GutterOption时，单独设置栅格子组件水平垂直边距，x属性为水平方向间距，y为垂直方向间距。

    ts 复制代码 
    GridRow({ gutter: { x: 20, y: 50 } }){}

子组件GridCol

GridCol组件作为GridRow组件的子组件，通过给GridCol传参或者设置属性两种方式，设置span（占用列数），offset（偏移列数），order（元素序号）的值。

  • 设置span。

    子组件占栅格布局的列数，决定了子组件的宽度，默认为1。当类型为number时，子组件在所有尺寸设备下占用的列数相同。当类型为GridColColumnOption时，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备中子组件所占列数设置，各个尺寸下数值可不同。

    ts 复制代码 
    let Gspan:Record<string,number> = { 'xs': 1, 'sm': 2, 'md': 3, 'lg': 4 }
GridCol({ span: 2 }){}
GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 } }){}
GridCol(){}.span(2)
GridCol(){}.span(Gspan)

  • 设置offset。

    栅格子组件相对于前一个子组件的偏移列数，默认为0。当类型为number时，子组件偏移相同列数。当类型为GridColColumnOption时，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备中子组件所占列数设置,各个尺寸下数值可不同。

    ts 复制代码 
    let Goffset:Record<string,number> = { 'xs': 1, 'sm': 2, 'md': 3, 'lg': 4 }
GridCol({ offset: 2 }){}
GridCol({ offset: { xs: 2, sm: 2, md: 2, lg: 2 } }){}
GridCol(){}.offset(Goffset)
    ts 复制代码 
    GridRow() {
  ForEach(this.bgColors, (color:Color, index?:number|undefined) => {
    GridCol({ offset: 2 }) {      
      ...        
    }
    .backgroundColor(color)
  })
}

    栅格默认分成12列，每一个子组件默认占1列，偏移2列，每个子组件及间距共占3列，一行放四个子组件。

  • 设置order。

    栅格子组件的序号，决定子组件排列次序。当子组件不设置order或者设置相同的order, 子组件按照代码顺序展示。当子组件设置不同的order时，order较小的组件在前，较大的在后。

    当子组件部分设置order，部分不设置order时，未设置order的子组件依次排序靠前，设置了order的子组件按照数值从小到大排列。

    当类型为number时，子组件在任何尺寸下排序次序一致。当类型为GridColColumnOption时，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备中子组件排序次序设置。

    ts 复制代码 
    let Gorder:Record<string,number> = { 'xs': 1, 'sm': 2, 'md': 3, 'lg': 4 }
GridCol({ order: 2 }){}
GridCol({ order: { xs: 1, sm: 2, md: 3, lg: 4 } }){}
GridCol(){}.order(2)
GridCol(){}.order(Gorder)

栅格组件也可以嵌套使用，完成一些复杂的布局。

以下示例中，栅格把整个空间分为12份。第一层GridRow嵌套GridCol，分为中间大区域以及"footer"区域。第二层GridRow嵌套GridCol，分为"left"和"right"区域。子组件空间按照上一层父组件的空间划分，粉色的区域是屏幕空间的12列，绿色和蓝色的区域是父组件GridCol的12列，依次进行空间的划分。

ts 复制代码 
@Entry
@Component
struct GridRowExample {
  build() {
    GridRow() {
      GridCol({ span: { sm: 12 } }) {
        GridRow() {
          GridCol({ span: { sm: 2 } }) {
            Row() {
              Text('left').fontSize(24)
            }
            .justifyContent(FlexAlign.Center)
            .height('90%')
          }.backgroundColor('#ff41dbaa')

          GridCol({ span: { sm: 10 } }) {
            Row() {
              Text('right').fontSize(24)
            }
            .justifyContent(FlexAlign.Center)
            .height('90%')
          }.backgroundColor('#ff4168db')
        }
        .backgroundColor('#19000000')
        .height('100%')
      }

      GridCol({ span: { sm: 12 } }) {
        Row() {
          Text('footer').width('100%').textAlign(TextAlign.Center)
        }.width('100%').height('10%').backgroundColor(Color.Pink)
      }
    }.width('100%').height(300)
  }
}

媒体查询 (@ohos.mediaquery)

媒体查询作为响应式设计的核心，在移动设备上应用十分广泛。媒体查询可根据不同设备类型或同设备不同状态修改应用的样式。媒体查询常用于下面两种场景：

  1. 针对设备和应用的属性信息（比如显示区域、深浅色、分辨率），设计出相匹配的布局。
  2. 当屏幕发生动态改变时（比如分屏、横竖屏切换），同步更新应用的页面布局。

引入与使用流程

媒体查询通过mediaquery模块接口，设置查询条件并绑定回调函数，在对应的条件的回调函数里更改页面布局或者实现业务逻辑，实现页面的响应式设计。具体步骤如下：

首先导入媒体查询模块。

ts 复制代码 
import mediaquery from '@ohos.mediaquery';

通过matchMediaSync接口设置媒体查询条件，保存返回的条件监听句柄listener。例如监听横屏事件：

ts 复制代码 
// 监听横屏事件
let listener: mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)');

给条件监听句柄listener绑定回调函数onPortrait，当listener检测设备状态变化时执行回调函数。在回调函数内，根据不同设备状态更改页面布局或者实现业务逻辑。

ts 复制代码 
onPortrait(mediaQueryResult: mediaquery.MediaQueryResult) {
  if (mediaQueryResult.matches as boolean) {
    // do something here
  } else {
    // do something here
  }
}

listener.on('change', onPortrait);

媒体查询条件

媒体查询条件由媒体类型、逻辑操作符、媒体特征组成，其中媒体类型可省略，逻辑操作符用于连接不同媒体类型与媒体特征，其中，媒体特征要使用"()"包裹且可以有多个。

语法规则包括媒体类型（media-type）、媒体逻辑操作（media-logic-operations）和媒体特征（media-feature）。

css 复制代码 
[media-type] [media-logic-operations] [(media-feature)]

例如：

  • screen and (round-screen: true) ：表示当设备屏幕是圆形时条件成立。
  • (max-height: 800px) ：表示当高度小于等于800px时条件成立。
  • (height <= 800px) ：表示当高度小于等于800px时条件成立。
  • screen and (device-type: tv) or (resolution < 2) ：表示包含多个媒体特征的多条件复杂语句查询，当设备类型为tv或设备分辨率小于2时条件成立。

媒体类型（media-type）

类型 说明
screen 按屏幕相关参数进行媒体查询。

媒体逻辑操作（media-logic-operations）

媒体逻辑操作符：and、or、not、only用于构成复杂媒体查询，也可以通过comma（, ）将其组合起来，详细解释说明如下表。

媒体特征（media-feature）

媒体特征包括应用显示区域的宽高、设备分辨率以及设备的宽高等属性，详细说明如下表。

// 省略

dark-mode 系统为深色模式时为true，否则为false。

创建列表 (List)

使用列表可以轻松高效地显示结构化、可滚动的信息。通过在List组件中按垂直或者水平方向线性排列子组件ListItemGroup或ListItem，为列表中的行或列提供单个视图，或使用循环渲染 迭代一组行或列，或混合任意数量的单个视图和ForEach结构，构建一个列表。List组件支持使用条件渲染、循环渲染、懒加载等渲染控制方式生成子组件。

布局与约束

列表作为一种容器，会自动按其滚动方向排列子组件，向列表中添加组件或从列表中移除组件会重新排列子组件。

ListItemGroup用于列表数据的分组展示，其子组件也是ListItem。ListItem表示单个列表项，可以包含单个子组件。

图1 List、ListItemGroup和ListItem组件关系

List的子组件必须是ListItemGroup或ListItem，ListItem和ListItemGroup必须配合List来使用。

布局

List除了提供垂直和水平布局能力、超出屏幕时可以滚动的自适应延伸能力之外，还提供了自适应交叉轴方向上排列个数的布局能力。

利用垂直布局能力可以构建单列或者多列垂直滚动列表。

利用水平布局能力可以是构建单行或多行水平滚动列表。

约束

列表的主轴方向是指子组件列的排列方向，也是列表的滚动方向。垂直于主轴的轴称为交叉轴，其方向与主轴方向相互垂直。

如下图所示，垂直列表的主轴是垂直方向，交叉轴是水平方向；水平列表的主轴是水平方向，交叉轴是垂直方向。

如果List组件主轴或交叉轴方向设置了尺寸，则其对应方向上的尺寸为设置值。

如果List组件主轴方向没有设置尺寸，当List子组件主轴方向总尺寸小于List的父组件尺寸时，List主轴方向尺寸自动适应子组件的总尺寸。

如果子组件主轴方向总尺寸超过List父组件尺寸时，List主轴方向尺寸适应List的父组件尺寸。

List组件交叉轴方向在没有设置尺寸时，其尺寸默认自适应父组件尺寸。

开发布局 - 设置主轴方向

List组件主轴默认是垂直方向，即默认情况下不需要手动设置List方向，就可以构建一个垂直滚动列表。

若是水平滚动列表场景，将List的listDirection属性设置为Axis.Horizontal即可实现。listDirection默认为Axis.Vertical，即主轴默认是垂直方向。

ts 复制代码 
List() {
  // ...
}
.listDirection(Axis.Horizontal)

开发布局 - 设置交叉轴布局

List组件的交叉轴布局可以通过lanes和alignListItem属性进行设置，lanes属性用于确定交叉轴排列的列表项数量，alignListItem用于设置子组件在交叉轴方向的对齐方式。

List组件的lanes属性通常用于在不同尺寸的设备自适应构建不同行数或列数的列表，即一次开发、多端部署的场景。lanes属性的取值类型是"number | LengthConstrain"，即整数或者LengthConstrain类型。以垂直列表为例，如果将lanes属性设为2，表示构建的是一个两列的垂直列表。lanes的默认值为1，即默认情况下，垂直列表的列数是1。

ts 复制代码 
List() {
  // ...
}
.lanes(2)

当其取值为LengthConstrain类型时，表示会根据LengthConstrain与List组件的尺寸自适应决定行或列数。

ts 复制代码 
@Entry
@Component
struct EgLanes {
  @State egLanes: LengthConstrain = { minLength: 200, maxLength: 300 }
  build() {
    List() {
      // ...
    }
    .lanes(this.egLanes)
  }
}

例如，假设在垂直列表中设置了lanes的值为{ minLength: 200, maxLength: 300 }。此时，

  • 当List组件宽度为300vp时，由于minLength为200vp，此时列表为一列。
  • 当List组件宽度变化至400vp时，符合两倍的minLength，则此时列表自适应为两列。

同样以垂直列表为例，当alignListItem属性设置为ListItemAlign.Center表示列表项在水平方向上居中对齐。alignListItem的默认值是ListItemAlign.Start，即列表项在列表交叉轴方向上默认按首部对齐。

ts 复制代码 
List() {
  // ...
}
.alignListItem(ListItemAlign.Center)

在列表中显示数据

在最简单的列表形式中，List静态地创建其列表项ListItem的内容。在List组件中，ForEach除了可以用来循环渲染ListItem，也可以用来循环渲染ListItemGroup。

自定义列表样式

  • 设置内容间距

在初始化列表时，如需在列表项之间添加间距，可以使用space参数。

  • 添加分隔线

List提供了divider属性用于给列表项之间添加分隔线。在设置divider属性时，可以通过strokeWidth和color属性设置分隔线的粗细和颜色。startMargin和endMargin属性分别用于设置分隔线距离列表侧边起始端的距离和距离列表侧边结束端的距离。

  • 添加滚动条

在使用List组件时，可通过scrollBar属性控制列表滚动条的显示。scrollBar的取值类型为BarState，当取值为BarState.Auto表示按需显示滚动条。此时，当触摸到滚动条区域时显示控件，可上下拖拽滚动条快速浏览内容，拖拽时会变粗。若不进行任何操作，2秒后滚动条自动消失。

scrollBar属性API version 9及以下版本默认值为BarState.Off，从API version 10版本开始默认值为BarState.Auto。

支持分组列表

图11 联系人分组列表

在List组件中可以直接使用一个或者多个ListItemGroup组件，ListItemGroup的宽度默认充满List组件。在初始化ListItemGroup时，可通过header参数设置列表分组的头部组件。

ts 复制代码 
@Entry
@Component
struct ContactsList {
  
  @Builder itemHead(text: string) {
    // 列表分组的头部组件，对应联系人分组A、B等位置的组件
    Text(text)
      .fontSize(20)
      .backgroundColor('#fff1f3f5')
      .width('100%')
      .padding(5)
  }

  build() {
    List() {
      ListItemGroup({ header: this.itemHead('A') }) {
        // 循环渲染分组A的ListItem
      }

      ListItemGroup({ header: this.itemHead('B') }) {
        // 循环渲染分组B的ListItem
      }
    }
  }
}

添加粘性标题

List组件的sticky属性配合ListItemGroup组件使用，用于设置ListItemGroup中的头部组件是否呈现吸顶效果或者尾部组件是否呈现吸底效果。

通过给List组件设置sticky属性为StickyStyle.Header，即可实现列表的粘性标题效果。如果需要支持吸底效果，可以通过footer参数初始化ListItemGroup的底部组件，并将sticky属性设置为StickyStyle.Footer。

控制滚动位置

控制滚动位置在实际应用中十分常见，例如当新闻页列表项数量庞大，用户滚动列表到一定位置时，希望快速滚动到列表底部或返回列表顶部。此时，可以通过控制滚动位置来实现列表的快速定位。

List组件初始化时，可以通过scroller参数绑定一个Scroller对象，进行列表的滚动控制。例如，用户在新闻应用中，点击新闻页面底部的返回顶部按钮时，就可以通过Scroller对象的scrollToIndex方法使列表滚动到指定的列表项索引位置。

首先，需要创建一个Scroller的对象listScroller。

ts 复制代码 
private listScroller: Scroller = new Scroller();

然后，通过将listScroller用于初始化List组件的scroller参数，完成listScroller与列表的绑定。在需要跳转的位置指定scrollToIndex的参数为0，表示返回列表顶部。

ts 复制代码 
Stack({ alignContent: Alignment.Bottom }) {
  // 将listScroller用于初始化List组件的scroller参数，完成listScroller与列表的绑定。
  List({ space: 20, scroller: this.listScroller }) {
    // ...
  }

  Button() {
    // ...
  }
  .onClick(() => {
    // 点击按钮时，指定跳转位置，返回列表顶部
    this.listScroller.scrollToIndex(0)
  })
}

响应滚动位置

许多应用需要监听列表的滚动位置变化并作出响应。例如，在联系人列表滚动时，如果跨越了不同字母开头的分组，则侧边字母索引栏也需要更新到对应的字母位置。

此场景可以通过监听List组件的 onScrollIndex 事件来实现，右侧索引栏需要使用字母表索引组件AlphabetIndexer。

响应列表项侧滑

ListItem的swipeAction属性可用于实现列表项的左右滑动功能。swipeAction属性方法初始化时有必填参数SwipeActionOptions，其中，start参数表示设置列表项右滑时起始端滑出的组件，end参数表示设置列表项左滑时尾端滑出的组件。

在消息列表中，end参数表示设置ListItem左滑时尾端划出自定义组件，即删除按钮。在初始化end方法时，将滑动列表项的索引传入删除按钮组件，当用户点击删除按钮时，可以根据索引值来删除列表项对应的数据，从而实现侧滑删除功能。

给列表项添加标记

在ListItem中使用Badge组件可实现给列表项添加标记功能。Badge是可以附加在单个组件上用于信息标记的容器组件。

下拉刷新与上拉加载

这两种操作的原理都是通过响应用户的触摸事件，在顶部或者底部显示一个刷新或加载视图，完成后再将此视图隐藏。

以下拉刷新为例，其实现主要分成三步：

  1. 监听手指按下事件，记录其初始位置的值。
  2. 监听手指按压移动事件，记录并计算当前移动的位置与初始值的差值，大于0表示向下移动，同时设置一个允许移动的最大值。
  3. 监听手指抬起事件，若此时移动达到最大值，则触发数据加载并显示刷新视图，加载完成后将此视图隐藏。

下拉刷新与上拉加载的具体实现可参考 新闻数据加载。若开发者希望快速实现此功能，也可使用三方组件PullToRefresh。

长列表的处理

循环渲染适用于短列表，当构建具有大量列表项的长列表时，如果直接采用循环渲染方式，会一次性加载所有的列表元素，会导致页面启动时间过长，影响用户体验。因此，推荐使用数据懒加载（LazyForEach）方式实现按需迭代加载数据，从而提升列表性能。

当使用懒加载方式渲染列表时，为了更好的列表滚动体验，减少列表滑动时出现白块，List组件提供了cachedCount参数用于设置列表项缓存数，只在懒加载LazyForEach中生效。

创建网格 (Grid/GridItem)

ArkUI提供了Grid容器组件和子组件GridItem，用于构建网格布局。Grid用于设置网格布局相关参数，GridItem定义子组件相关特征。Grid组件支持使用条件渲染、循环渲染、懒加载等方式生成子组件。

布局与约束

Grid组件为网格容器，其中容器内各条目对应一个GridItem组件，如下图所示。

图1 Grid与GridItem组件关系

说明：

Grid的子组件必须是GridItem组件。

网格布局是一种二维布局。Grid组件支持自定义行列数和每行每列尺寸占比、设置子组件横跨几行或者几列，同时提供了垂直和水平布局能力。当网格容器组件尺寸发生变化时，所有子组件以及间距会等比例调整，从而实现网格布局的自适应能力。根据Grid的这些布局能力，可以构建出不同样式的网格布局，如下图所示。

图2 网格布局

如果Grid组件设置了宽高属性，则其尺寸为设置值。如果没有设置宽高属性，Grid组件的尺寸默认适应其父组件的尺寸。

Grid组件根据行列数量与占比属性的设置，可以分为三种布局情况：

  • 行、列数量与占比同时设置 ：Grid只展示固定行列数的元素，其余元素不展示，且Grid不可滚动。（推荐使用该种布局方式）
  • 只设置行、列数量与占比中的一个 ：元素按照设置的方向进行排布，超出的元素可通过滚动的方式展示。
  • 行列数量与占比都不设置 ：元素在布局方向上排布，其行列数由布局方向、单个网格的宽高等多个属性共同决定。超出行列容纳范围的元素不展示 ，且Grid不可滚动。

设置排列方式

  • 设置行列数量与占比

通过设置行列数量与尺寸占比可以确定网格布局的整体排列方式。Grid组件提供了rowsTemplate和columnsTemplate属性用于设置网格布局行列数量与尺寸占比。

rowsTemplate和columnsTemplate属性值是一个由多个空格和'数字+fr'间隔拼接的字符串，fr的个数即网格布局的行或列数，fr前面的数值大小，用于计算该行或列在网格布局宽度上的占比，最终决定该行或列宽度。

ts 复制代码 
Grid() {
  ...
}
.rowsTemplate('1fr 1fr 1fr')
.columnsTemplate('1fr 2fr 1fr')

图3 行列数量占比示例

说明：

当Grid组件设置了rowsTemplate或columnsTemplate时，Grid的layoutDirection、maxCount、minCount、cellLength属性不生效，属性说明可参考Grid-属性。

  • 设置子组件所占行列数

在Grid组件中，通过设置GridItem的rowStart、rowEnd、columnStart和columnEnd可以实现如图所示的单个网格横跨多行或多列的场景，rowStart/rowEnd合理取值范围为 0 ~ 总行数-1，columnStart/columnEnd合理取值范围为 0 ~ 总列数-1，更多起始行号、终点行号、起始列号、终点列号的生效规则请看GridItem。

例如计算器的按键布局就是常见的不均匀网格布局场景。使用Grid构建的网格布局，其行列标号从0开始，依次编号。

图5 计算器

在单个网格单元中，rowStart和rowEnd属性表示指定当前元素起始行号和终点行号，columnStart和columnEnd属性表示指定当前元素的起始列号和终点列号。

"0"按键横跨第一列和第二列

ts 复制代码 
GridItem() {
  Text(key)
    ...
}
.columnStart(0)
.columnEnd(1)
.rowStart(5)
.rowEnd(5)
  • 设置主轴方向

使用Grid构建网格布局时，若没有设置行列数量与占比，可以通过layoutDirection设置网格布局的主轴方向，决定子组件的排列方式。此时可以结合minCount和maxCount属性来约束主轴方向上的网格数量。

图6 主轴方向示意图

当前layoutDirection设置为Row时，先从左到右排列，排满一行再排下一行。当前layoutDirection设置为Column时，先从上到下排列，排满一列再排下一列，如上图所示。此时，将maxCount属性设为3，表示主轴方向上最大显示的网格单元数量为3。

ts 复制代码 
Grid() {
  ...
}
.maxCount(3)
.layoutDirection(GridDirection.Row)

layoutDirection属性仅在不设置rowsTemplate和columnsTemplate时生效，此时元素在layoutDirection方向上排列。

  • 设置行列间距

在两个网格单元之间的网格横向间距称为行间距，网格纵向间距称为列间距。

通过Grid的rowsGap和columnsGap可以设置网格布局的行列间距。在图5所示的计算器中，行间距为15vp，列间距为10vp。

ts 复制代码 
Grid() {
  ...
}
.columnsGap(10)
.rowsGap(15)

构建可滚动的网格布局

在设置Grid的行列数量与占比时，如果仅设置行、列数量与占比中的一个，即仅设置rowsTemplate或仅设置columnsTemplate属性，网格单元按照设置的方向排列，超出Grid显示区域后，Grid拥有可滚动能力。

控制滚动位置

Grid组件初始化时，可以绑定一个Scroller对象，用于进行滚动控制，例如通过Scroller对象的scrollPage方法进行翻页。

ts 复制代码 
private scroller: Scroller = new Scroller()

在日历页面中，用户在点击"下一页"按钮时，应用响应点击事件，通过指定scrollPage方法的参数next为true，滚动到下一页。

ts 复制代码 
Column({ space: 5 }) {
  Grid(this.scroller) {
  }
  .columnsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr')

  Row({space: 20}) {
    Button('上一页')
      .onClick(() => {
        this.scroller.scrollPage({
          next: false
        })
      })

    Button('下一页')
      .onClick(() => {
        this.scroller.scrollPage({
          next: true
        })
      })
  }
}

性能优化

与长列表的处理类似，循环渲染适用于数据量较小的布局场景，当构建具有大量网格项的可滚动网格布局时，推荐使用数据懒加载方式实现按需迭代加载数据，从而提升列表性能。

当使用懒加载方式渲染网格时，为了更好的滚动体验，减少滑动时出现白块，Grid组件中也可通过cachedCount属性设置GridItem的预加载数量，只在懒加载LazyForEach中生效。

设置预加载数量后，会在Grid显示区域前后各缓存cachedCount*列数个GridItem，超出显示和缓存范围的GridItem会被释放。

ts 复制代码 
Grid() {
  LazyForEach(this.dataSource, () => {
    GridItem() {
    }
  })
}
.cachedCount(3)

创建轮播 (Swiper)

Swiper组件提供滑动轮播显示的能力。Swiper本身是一个容器组件，当设置了多个子组件后，可以对这些子组件进行轮播显示。

针对复杂页面场景，可以使用 Swiper 组件的预加载 机制，利用主线程的空闲时间来提前构建和布局绘制组件，优化滑动体验。详细指导见Swiper高性能开发指导。

布局与约束

Swiper作为一个容器组件，如果设置了自身尺寸属性，则在轮播显示过程中均以该尺寸生效。如果自身尺寸属性未被设置，则分两种情况：如果设置了prevMargin或者nextMargin属性，则Swiper自身尺寸会跟随其父组件；如果未设置prevMargin或者nextMargin属性，则会自动根据子组件的大小设置自身的尺寸。

  • 循环播放

通过loop属性控制是否循环播放，该属性默认值为true。

  • 自动轮播

Swiper通过设置autoPlay属性，控制是否自动轮播子组件。该属性默认值为false。

  • 导航点样式

Swiper提供了默认的导航点样式，导航点默认显示在Swiper下方居中位置，开发者也可以通过indicatorStyle属性自定义导航点的位置和样式。

通过indicatorStyle属性，开发者可以设置导航点相对于Swiper组件上下左右四个方位的位置，同时也可以设置每个导航点的尺寸、颜色、蒙层和被选中导航点的颜色。

  • 页面切换方式

Swiper支持手指滑动、点击导航点和通过控制器三种方式切换页面。

  • 轮播方向

Swiper支持水平和垂直方向上进行轮播，主要通过vertical属性控制。

当vertical为true时，表示在垂直方向上进行轮播；为false时，表示在水平方向上进行轮播。vertical默认值为false。

  • 每页显示多个子页面

Swiper支持在一个页面内同时显示多个子组件，通过displayCount属性设置。

组件

按钮 (Button)

Button是按钮组件，通常用于响应用户的点击操作，其类型包括胶囊按钮、圆形按钮、普通按钮。Button做为容器使用时可以通过添加子组件实现包含文字、图片等元素的按钮。具体用法请参考Button。

Button通过调用接口来创建，接口调用有以下两种形式：

  • 创建不包含子组件的按钮。

    ts 复制代码 
    Button(label?: ResourceStr, options?: { type?: ButtonType, stateEffect?: boolean })

    其中，label用来设置按钮文字，type用于设置Button类型，stateEffect属性设置Button是否开启点击效果。

  • 创建包含子组件的按钮。

    ts 复制代码 
    Button(options?: {type?: ButtonType, stateEffect?: boolean})

    只支持包含一个子组件，子组件可以是基础组件 或者容器组件。

    ts 复制代码 
    Button({ type: ButtonType.Normal, stateEffect: true }) {
  Row() {
    Image($r('app.media.loading')).width(20).height(40).margin({ left: 12 })
    Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 })
  }.alignItems(VerticalAlign.Center)
}.borderRadius(8).backgroundColor(0x317aff).width(90).height(40)

单选框 (Radio)

Radio是单选框组件，通常用于提供相应的用户交互选择项，同一组的Radio中只有一个可以被选中。具体用法请参考Radio。

ts 复制代码 
Radio(options: {value: string, group: string})

其中，value是单选框的名称，group是单选框的所属群组名称。checked属性可以设置单选框的状态，状态分别为false和true，设置为true时表示单选框被选中。

Radio支持设置选中状态和非选中状态的样式，不支持自定义形状。

ts 复制代码 
Radio({ value: 'Radio1', group: 'radioGroup' })
  .checked(false)
Radio({ value: 'Radio2', group: 'radioGroup' })
  .checked(true)

切换按钮 (Toggle)

Toggle组件提供状态按钮样式、勾选框样式和开关样式，一般用于两种状态之间的切换。具体用法请参考Toggle。

ts 复制代码 
Toggle(options: { type: ToggleType, isOn?: boolean })

其中，ToggleType为开关类型，包括Button、Checkbox和Switch，isOn为切换按钮的状态。

接口调用有以下两种形式：

  • 创建不包含子组件的Toggle。 当ToggleType为Checkbox或者Switch时，用于创建不包含子组件的Toggle：

    ts 复制代码 
    Toggle({ type: ToggleType.Checkbox, isOn: true })
Toggle({ type: ToggleType.Switch, isOn: false })

  • 创建包含子组件的Toggle。 当ToggleType为Button时，只能包含一个子组件。

进度条 (Progress)

Progress是进度条显示组件，显示内容通常为目标操作的当前进度。具体用法请参考Progress。

ts 复制代码 
Progress(options: {value: number, total?: number, type?: ProgressType})

其中，value用于设置初始进度值，total用于设置进度总长度，type用于设置Progress样式。

Progress有5种可选类型，通过ProgressType可以设置进度条样式，ProgressType类型包括：ProgressType.Linear（线性样式）、 ProgressType.Ring（环形无刻度样式）、ProgressType.ScaleRing（环形有刻度样式）、ProgressType.Eclipse（圆形样式）和ProgressType.Capsule（胶囊样式）。

ts 复制代码 
// 默认前景色为蓝色渐变，默认strokeWidth进度条宽度为2.0vp
Progress({ value: 40, total: 150, type: ProgressType.Ring }).width(100).height(100)

文本显示 (Text/Span)

Text是文本组件，通常用于展示用户视图，如显示文章的文字。具体用法请参考Text。

Text可通过以下两种方式来创建：

  • string字符串

    ts 复制代码 
    Text('我是一段文本')

  • 引用Resource资源

    资源引用类型可以通过$r创建Resource类型对象，文件位置为/resources/base/element/string.json。

    ts 复制代码 
    Text($r('app.string.module_desc'))
  .baselineOffset(0)
  .fontSize(30)
  .border({ width: 1 })
  .padding(10)
  .width(300)

添加子组件

Span只能作为Text和RichEditor组件的子组件显示文本内容。

  • 创建Span。

    Span组件需要写到Text组件内，单独写Span组件不会显示信息，Text与Span同时配置文本内容时，Span内容覆盖Text内容。

    ts 复制代码 
    Text('我是Text') {
  Span('我是Span')
}

  • 通过decoration设置文本装饰线及颜色。

  • 通过textCase设置文字一直保持大写或者小写状态。

  • 添加事件。由于Span组件无尺寸信息，事件仅支持添加点击事件onClick。

自定义文本样式

  • 通过textAlign属性设置文本对齐样式。

  • 通过textOverflow属性控制文本超长处理，textOverflow需配合maxLines一起使用（默认情况下文本自动折行）。

ts 复制代码 
Text('当文本溢出其尺寸时，文本将滚动显示。When the text overflows its dimensions, the text will scroll for displaying.')       
  .width(250)
  .textOverflow({ overflow: TextOverflow.MARQUEE })                 
  .maxLines(1)       
  .fontSize(12)
  .border({ width: 1 })
  .padding(10)

  • 通过lineHeight属性设置文本行高。

  • 通过decoration属性设置文本装饰线样式及其颜色。

  • 通过baselineOffset属性设置文本基线的偏移量。

  • 通过letterSpacing属性设置文本字符间距。

  • 通过minFontSize与maxFontSize自适应字体大小，minFontSize设置文本最小显示字号，maxFontSize设置文本最大显示字号，minFontSize与maxFontSize必须搭配同时使用，以及需配合maxline或布局大小限制一起使用，单独设置不生效。

  • 通过textCase属性设置文本大小写。

  • 通过copyOption属性设置文本是否可复制粘贴。

  • Text组件可以添加通用事件，可以绑定onClick、onTouch等事件来响应操作。

文本输入 (TextInput/TextArea)

TextInput、TextArea是输入框组件，通常用于响应用户的输入操作，比如评论区的输入、聊天框的输入、表格的输入等，也可以结合其它组件构建功能页面，例如登录注册页面。具体用法请参考TextInput、TextArea。

TextInput为单行输入框、TextArea为多行输入框。通过以下接口来创建。

ts 复制代码 
TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})
ts 复制代码 
TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController})

  • 单行输入框 TextInput有9种可选类型，分别为Normal基本输入模式、Password密码输入模式、Email邮箱地址输入模式、Number纯数字输入模式、PhoneNumber电话号码输入模式、USER_NAME用户名输入模式、NEW_PASSWORD新密码输入模式、NUMBER_PASSWORD纯数字密码输入模式、SCREEN_LOCK_PASSWORD锁屏应用密码输入模式、NUMBER_DECIMAL带小数点的数字输入模式。通过type属性进行设置。

    ts 复制代码 
    TextInput()
  .type(InputType.Password)

  • 多行输入框

    css 复制代码 
    TextArea()

自定义样式

  • 设置无输入时的提示文本。 TextInput({placeholder:'我是提示文本'})

  • 设置输入框当前的文本内容。

    ts 复制代码 
    TextInput({placeholder:'我是提示文本',text:'我是当前文本内容'})

  • 添加backgroundColor改变输入框的背景颜色。

添加事件

绑定onChange事件可以获取输入框内改变的内容。用户也可以使用通用事件来进行相应的交互操作。

ts 复制代码 
TextInput()
  .onChange((value: string) => {
    console.info(value);
  })
  .onFocus(() => {
    console.info('获取焦点');
  })

自定义弹窗 (CustomDialog)

CustomDialog是自定义弹窗，可用于广告、中奖、警告、软件更新等与用户交互响应操作。开发者可以通过CustomDialogController类显示自定义弹窗。具体用法请参考自定义弹窗。

创建自定义弹窗

  1. 使用 @CustomDialog装饰器装饰自定义弹窗。

  2. @CustomDialog装饰器用于装饰自定义弹框，此装饰器内进行自定义内容（也就是弹框内容）。

    ts 复制代码 
    @CustomDialog
struct CustomDialogExample {
  controller: CustomDialogController = new CustomDialogController({
    builder: CustomDialogExample({}),
  })

  build() {
    Column() {
      Text('我是内容')
        .fontSize(20)
        .margin({ top: 10, bottom: 10 })
    }
  }
}

  3. 创建构造器，与装饰器呼应相连。

    ts 复制代码 
     @Entry
 @Component
 struct CustomDialogUser {
   dialogController: CustomDialogController = new CustomDialogController({
     builder: CustomDialogExample(),
   })
 }

  4. 点击与onClick事件绑定的组件使弹窗弹出。

    ts 复制代码 
    @Entry
@Component
struct CustomDialogUser {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: CustomDialogExample(),
  })

  build() {
    Column() {
      Button('click me')
        .onClick(() => {
          this.dialogController.open()
        })
    }.width('100%').margin({ top: 5 })
  }
}

弹窗的交互

弹窗可用于数据交互，完成用户一系列响应操作。

  1. 在@CustomDialog装饰器内添加按钮，同时添加数据函数。

    ts 复制代码 
    @CustomDialog
struct CustomDialogExample {
  cancel?: () => void
  confirm?: () => void
  controller: CustomDialogController

  build() {
    Column() {
      Text('我是内容').fontSize(20).margin({ top: 10, bottom: 10 })
      Flex({ justifyContent: FlexAlign.SpaceAround }) {
        Button('cancel')
          .onClick(() => {
            this.controller.close()
            if (this.cancel) {
              this.cancel()
            }
          }).backgroundColor(0xffffff).fontColor(Color.Black)
        Button('confirm')
          .onClick(() => {
            this.controller.close()
            if (this.confirm) {
              this.confirm()
            }
          }).backgroundColor(0xffffff).fontColor(Color.Red)
      }.margin({ bottom: 10 })
    }
  }
}

  2. 页面内需要在构造器内进行接收，同时创建相应的函数操作。

    ts 复制代码 
    @Entry
@Component
struct CustomDialogUser {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: CustomDialogExample({
      cancel: ()=> { this.onCancel() },
      confirm: ()=> { this.onAccept() },
    }),
  })

  onCancel() {
    console.info('Callback when the first button is clicked')
  }

  onAccept() {
    console.info('Callback when the second button is clicked')
  }

  build() {
    Column() {
      Button('click me')
        .onClick(() => {
          this.dialogController.open()
        })
    }.width('100%').margin({ top: 5 })
  }
}

弹窗的动画

弹窗通过定义openAnimation控制弹窗出现动画的持续时间，速度等参数。

ts 复制代码 
  dialogController: CustomDialogController | null = new CustomDialogController({
    builder: CustomDialogExample(),
    openAnimation: {
      duration: 1200,
      curve: Curve.Friction,
      delay: 500,
      playMode: PlayMode.Alternate,
      onFinish: () => {
        console.info('play end')
      }
    },
    autoCancel: true,
    alignment: DialogAlignment.Bottom,
    offset: { dx: 0, dy: -20 },
    gridCount: 4,
    customStyle: false,
    backgroundColor: 0xd9ffffff,
    cornerRadius: 10,
  })

视频播放 (Video)

Video组件用于播放视频文件并控制其播放状态，常用于为短视频和应用内部视频的列表页面。当视频完整出现时会自动播放，用户点击视频区域则会暂停播放，同时显示播放进度条，通过拖动播放进度条指定视频播放到具体位置。具体用法请参考Video。

创建视频组件

Video通过调用接口来创建，接口调用形式如下：

Video(value: VideoOptions)

VideoOptions对象包含参数src、currentProgressRate、previewUri、controller。其中，src指定视频播放源的路径，currentProgressRate用于设置视频播放倍速，previewUri指定视频未播放时的预览图片路径，controller设置视频控制器，用于自定义控制视频。

加载视频资源

Video组件支持加载本地视频和网络视频。

加载本地视频

  • 普通本地视频。

    加载本地视频时，首先在本地rawfile目录指定对应的文件，如下图所示。

    再使用资源访问符$rawfile()引用视频资源。

    ts 复制代码 
    @Component
export struct VideoPlayer{
  private controller: VideoController | undefined;
  private previewUris: Resource = $r('app.media.preview');
  private innerResource: Resource = $rawfile('videoTest.mp4');
  build(){
    Column() {
      Video({
        src: this.innerResource,
        previewUri: this.previewUris,
        controller: this.controller
      })
    }
  }
}

  • Data Ability提供的视频路径带有dataability://前缀，使用时确保对应视频资源存在即可。

加载沙箱路径视频

支持file:///data/storage路径前缀的字符串，用于读取应用沙箱路径内的资源，需要保证应用沙箱目录路径下的文件存在并且有可读权限。

加载网络视频

加载网络视频时，需要申请权限ohos.permission.INTERNET，具体申请方式请参考声明权限。此时，Video的src属性为网络视频的链接。

添加属性

Video组件属性主要用于设置视频的播放形式。例如设置视频播放是否静音、播放是否显示控制条等。

ts 复制代码 
@Component
export struct VideoPlayer {
  private controller: VideoController | undefined;

  build() {
    Column() {
      Video({
        controller: this.controller
      })
        .muted(false) //设置是否静音
        .controls(false) //设置是否显示默认控制条
        .autoPlay(false) //设置是否自动播放
        .loop(false) //设置是否循环播放
        .objectFit(ImageFit.Contain) //设置视频适配模式
    }
  }
}

事件调用

Video组件回调事件主要为播放开始、暂停结束、播放失败、视频准备和操作进度条等事件，除此之外，Video组件也支持通用事件的调用，如点击、触摸等事件的调用。详细事件请参考事件说明。

Video控制器使用

Video控制器主要用于控制视频的状态，包括播放、暂停、停止以及设置进度等，详细使用请参考VideoController使用说明。

  • 默认的控制器支持视频的开始、暂停、进度调整、全屏显示四项基本功能。

  • 使用自定义的控制器，先将默认控制器关闭掉，之后可以使用button以及slider等组件进行自定义的控制与显示，适合自定义较强的场景下使用。

Video组件已经封装好了视频播放的基础能力，开发者无需进行视频实例的创建，视频信息的设置获取，只需要设置数据源以及基础信息即可播放视频，相对扩展能力较弱。如果开发者想自定义视频播放，请参考媒体系统播放音视频。

自定义绘制 (XComponent)

XComponent组件作为一种绘制组件，通常用于满足开发者较为复杂的自定义绘制需求，例如相机预览流的显示和游戏画面的绘制。

其可通过指定其type字段来实现不同的功能，主要有两个"surface"和"component"字段可供选择。

对于"surface"类型，开发者可将相关数据传入XComponent单独拥有的"NativeWindow"来渲染画面。

对于"component"类型，主要用于实现动态加载显示内容的目的。

气泡提示 (Popup)

气泡分为两种类型，一种是系统提供的气泡PopupOptions，一种是开发者可以自定义的气泡CustomPopupOptions。其中PopupOptions为系统提供的气泡，通过配置primaryButton、secondaryButton来设置带按钮的气泡。CustomPopupOptions通过配置builder参数来设置自定义的气泡。

文本提示气泡

文本提示气泡常用于只展示带有文本的信息提示，不带有任何交互的场景。Popup属性需绑定组件，当bindPopup属性中参数show为true时会弹出气泡提示。

在Button组件上绑定Popup属性，每次点击Button按钮，handlePopup会切换布尔值，当值为true时，触发bindPopup弹出气泡。

通过onStateChange参数为气泡添加状态变化的事件回调，可以判断当前气泡的显示状态。

ts 复制代码 
@Entry
@Component
struct PopupExample {
  @State handlePopup: boolean = false

  build() {
    Column() {
      Button('PopupOptions')
        .onClick(() => {
          this.handlePopup = !this.handlePopup
        })
        .bindPopup(this.handlePopup, {
          message: 'This is a popup with PopupOptions',
          onStateChange: (e)=> { // 返回当前的气泡状态
            if (!e.isVisible) {
              this.handlePopup = false
            }
          }
        })
    }.width('100%').padding({ top: 5 })
  }
}

带按钮的提示气泡

通过primaryButton、secondaryButton属性为气泡最多设置两个Button按钮，通过此按钮进行简单的交互，开发者可以通过配置action参数来设置想要触发的操作。

自定义气泡

开发者可以使用构建器CustomPopupOptions创建自定义气泡，@Builder中可以放自定义的内容。除此之外，还可以通过popupColor等参数控制气泡样式。

ts 复制代码 
@Entry
@Component
struct Index {
  @State customPopup: boolean = false
  // popup构造器定义弹框内容
  @Builder popupBuilder() {
    Row({ space: 2 }) {
      Image($r("app.media.icon")).width(24).height(24).margin({ left: 5 })
      Text('This is Custom Popup').fontSize(15)
    }.width(200).height(50).padding(5)
  }
  build() {
    Column() {
      Button('CustomPopupOptions')
        .position({x:100,y:200})
        .onClick(() => {
          this.customPopup = !this.customPopup
        })
        .bindPopup(this.customPopup, {
          builder: this.popupBuilder, // 气泡的内容
          placement:Placement.Bottom, // 气泡的弹出位置
          popupColor:Color.Pink, // 气泡的背景色
          onStateChange: (e) => {
            console.info(JSON.stringify(e.isVisible))
            if (!e.isVisible) {
              this.customPopup = false
            }
          }
        })
    }
    .height('100%')
  }
}

菜单（Menu）

Menu是菜单接口，一般用于鼠标右键弹窗、点击弹窗等。具体用法请参考Menu控制。

创建默认样式的菜单

菜单需要调用bindMenu接口来实现。bindMenu响应绑定组件的点击事件，绑定组件后手势点击对应组件后即可弹出。

ts 复制代码 
Button('click for Menu')
  .bindMenu([
    {
      value: 'Menu1',
      action: () => {
        console.info('handle Menu1 select')
      }
    }
  ])

创建自定义样式的菜单

当默认样式不满足开发需求时，可使用 @Builder 定义菜单内容，通过bindMenu接口进行菜单的自定义。

@Builder开发菜单内的内容

ts 复制代码 
class Tmp {
  iconStr2: ResourceStr = $r("app.media.view_list_filled")

  set(val: Resource) {
    this.iconStr2 = val
  }
}

@Entry
@Component
struct menuExample {
  @State select: boolean = true
  private iconStr: ResourceStr = $r("app.media.view_list_filled")
  private iconStr2: ResourceStr = $r("app.media.view_list_filled")

  @Builder
  SubMenu() {
    Menu() {
      MenuItem({ content: "复制", labelInfo: "Ctrl+C" })
      MenuItem({ content: "粘贴", labelInfo: "Ctrl+V" })
    }
  }

  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: $r("app.media.icon"), content: "菜单选项" })
      MenuItem({ startIcon: $r("app.media.icon"), content: "菜单选项" }).enabled(false)
      MenuItem({
        startIcon: this.iconStr,
        content: "菜单选项",
        endIcon: $r("app.media.arrow_right_filled"),
        // 当builder参数进行配置时，表示与menuItem项绑定了子菜单。鼠标hover在该菜单项时，会显示子菜单。
        builder: this.SubMenu
      })
      MenuItemGroup({ header: '小标题' }) {
        MenuItem({ content: "菜单选项" })
          .selectIcon(true)
          .selected(this.select)
          .onChange((selected) => {
            console.info("menuItem select" + selected);
            let Str: Tmp = new Tmp()
            Str.set($r("app.media.icon"))
          })
        MenuItem({
          startIcon: $r("app.media.view_list_filled"),
          content: "菜单选项",
          endIcon: $r("app.media.arrow_right_filled"),
          builder: this.SubMenu
        })
      }

      MenuItem({
        startIcon: this.iconStr2,
        content: "菜单选项",
        endIcon: $r("app.media.arrow_right_filled")
      })
    }
  }

  build() {
    // ...
  }
}
ts 复制代码 
Button('click for Menu')
  .bindMenu(this.MyMenu)

创建支持右键或长按的菜单

通过bindContextMenu接口自定义菜单，设置菜单弹出的触发方式，触发方式为右键或长按。使用bindContextMenu弹出的菜单项是在独立子窗口内的，可显示在应用窗口外部。

  • @Builder开发菜单内的内容与上文写法相同。

  • 确认菜单的弹出方式，使用bindContextMenu属性绑定组件。示例中为右键弹出菜单。

    ts 复制代码 
    Button('click for Menu')
  .bindContextMenu(this.MyMenu, ResponseType.RightClick)

组件导读

行列与分栏

  • Column

    沿垂直方向布局的容器组件。

  • ColumnSplit

    垂直方向分隔布局容器组件，将子组件纵向布局，并在每个子组件之间插入一根横向的分割线。

  • Row

    沿水平方向布局的容器组件。

  • RowSplit

    水平方向分隔布局容器组件，将子组件横向布局，并在每个子组件之间插入一根纵向的分割线。

  • SideBarContainer

    提供侧边栏可以显示和隐藏的侧边栏容器组件，通过子组件定义侧边栏和内容区，第一个子组件表示侧边栏，第二个子组件表示内容区。

堆叠Flex与栅格

  • Stack

    堆叠容器组件，子组件按照顺序依次入栈，后一个子组件覆盖前一个子组件。

  • Flex

    以弹性方式布局子组件的容器组件。

  • GridContainer

    纵向排布栅格布局容器组件，仅在栅格布局场景中使用。

  • GridRow

    栅格容器组件，仅可以和栅格子组件(GridCol)在栅格布局场景中使用。

  • GridCol

    栅格子组件，必须作为栅格容器组件(GridRow)的子组件使用。

  • RelativeContainer

    相对布局组件，用于复杂场景中元素对齐的布局。

列表与宫格

  • List

    列表包含一系列相同宽度的列表项，适合连续、多行呈现同类数据，例如图片和文本。

  • ListItem

    用来展示具体列表项，必须配合List来使用。

  • ListItemGroup

    用来展示分组列表项的组件，必须配合List组件来使用。

  • Grid

    网格容器组件，由"行"和"列"分割的单元格所组成，通过指定"项目"所在的单元格做出各种各样的布局。

  • GridItem

    网格容器中单项内容容器。

滚动与滑动

  • Scroll

    可滚动的容器组件，当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。

  • Swiper

    滑块视图容器组件，提供子组件滑动轮播显示的能力。

  • WaterFlow

    瀑布流容器组件，由"行"和"列"分割的单元格所组成，通过容器自身的排列规则，将不同大小的"项目"自上而下，如瀑布般紧密布局。

  • FlowItem

    瀑布流组件WaterFlow的子组件，用来展示瀑布流具体item。

导航

  • Navigator

    路由容器组件，提供路由跳转能力。

  • Navigation

    一般作为Page页面的根容器，通过属性设置来展示页面的标题栏、工具栏、导航栏等。

  • NavRouter

    导航组件，默认提供点击响应处理，不需要开发者自定义点击事件逻辑。

  • NavDestination

    作为NavRouter组件的子组件，用于显示导航内容区。

  • Stepper

    步骤导航器组件，适用于引导用户按照步骤完成任务的导航场景。

  • StepperItem

    Stepper组件的子组件。

  • Tabs

    通过页签进行内容视图切换的容器组件，每个页签对应一个内容视图。

  • TabContent

    仅在Tabs组件中使用，对应一个切换页签的内容视图。

按钮与选择

  • Button

    按钮组件，可快速创建不同样式的按钮。

  • Toggle

    组件提供勾选框样式、状态按钮样式及开关样式。

  • Checkbox

    提供多选框组件，通常用于某选项的打开或关闭。

  • CheckboxGroup

    多选框群组，用于控制多选框全选或者不全选状态。

  • CalendarPicker

    提供下拉日历弹窗，可以让用户选择日期。

  • DatePicker

    选择日期的滑动选择器组件。

  • TextPicker

    滑动选择文本内容的组件。

  • TimePicker

    滑动选择时间的组件。

  • Radio

    单选框，提供相应的用户交互选择项。

  • Rating

    提供在给定范围内选择评分的组件。

  • Select

    提供下拉选择菜单，可以让用户在多个选项之间选择。

  • Slider

    滑动条组件，通常用于快速调节设置值，如音量调节、亮度调节等应用场景。

  • Counter

    计数器组件，提供相应的增加或者减少的计数操作。

文本与输入

  • Text

    显示一段文本的组件。

  • Span

    作为Text组件的子组件，用于显示行内文本片段的组件。

  • Search

    搜索框组件，适用于浏览器的搜索内容输入框等应用场景。

  • TextArea

    多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。

  • TextInput

    单行文本输入框组件。

  • PatternLock

    图案密码锁组件，以九宫格图案的方式输入密码，用于密码验证场景。手指在PatternLock组件区域按下时开始进入输入状态，手指离开屏幕时结束输入状态完成密码输入。

  • RichText

    富文本组件，解析并显示HTML格式文本。

  • RichEditor

    支持图文混排和文本交互式编辑的组件。

图片视频与媒体

  • Image

    图片组件，支持本地图片和网络图片的渲染展示。

  • ImageAnimator

    提供逐帧播放图片能力的帧动画组件，可以配置需要播放的图片列表，每张图片可以配置时长。

  • Video

    用于播放视频文件并控制其播放状态的组件。

  • PluginComponent

    提供外部应用组件嵌入式显示功能，即外部应用提供的UI可在本应用内显示。

  • XComponent

    用于EGL/OpenGLES和媒体数据写入。

信息展示

  • DataPanel

    数据面板组件，用于将多个数据占比情况使用占比图进行展示。

  • Gauge

    数据量规图表组件，用于将数据展示为环形图表。

  • LoadingProgress

    用于显示加载动效的组件。

  • Marquee

    跑马灯组件，用于滚动展示一段单行文本，仅当文本内容宽度超过跑马灯组件宽度时滚动。

  • Progress

    进度条组件，用于显示内容加载或操作处理等进度。

  • QRCode

    用于显示单个二维码的组件。

  • TextClock

    通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。

  • TextTimer

    通过文本显示计时信息并控制其计时器状态的组件。

空白与分隔

  • Blank

    空白填充组件，在容器主轴方向上，空白填充组件具有自动填充容器空余部分的能力。仅当父组件为Row/Column时生效。

  • Divider

    分隔器组件，分隔不同内容块/内容元素。

画布与图形绘制

  • Canvas

    提供画布组件，用于自定义绘制图形。

  • Circle

    用于绘制圆形的组件。

  • Ellipse

    椭圆绘制组件。

  • Line

    直线绘制组件。

  • Polyline

    折线绘制组件。

  • Polygon

    多边形绘制组件。

  • Path

    路径绘制组件，根据绘制路径生成封闭的自定义形状。

  • Rect

    矩形绘制组件。

  • Shape

    作为绘制组件的父组件，实现类似SVG的效果，父组件中会描述所有绘制组件均支持的通用属性。

其他

  • ScrollBar

    滚动条组件，用于配合可滚动组件使用，如List、Grid、Scroll等。

  • Badge

    可以附加在单个组件上用于信息标记的容器组件。

  • AlphabetIndexer

    可以与容器组件联动用于按逻辑结构快速定位容器显示区域的索引条组件。

  • Panel

    可滑动面板，提供一种轻量的内容展示窗口，方便在不同尺寸中切换。

  • Refresh

    可以进行页面下拉操作并显示刷新动效的容器组件。

  • AbilityComponent

    独立显示Ability的容器组件。

  • RemoteWindow

    远程控制窗口组件，可以通过此组件控制应用窗口，提供启动退出过程中控件动画和应用窗口联动动画的能力。

  • FormComponent

    提供卡片组件，实现卡片的显示功能。

  • FormLink

    提供静态卡片事件交互功能。

  • Hyperlink

    超链接组件，组件宽高范围内点击实现跳转。

  • Menu

    以垂直列表形式显示的菜单。

  • MenuItem

    用来展示菜单Menu中具体的item菜单项。

  • MenuItemGroup

    用来展示菜单MenuItem的分组。

  • UIExtensionComponent

    在页面中嵌入显示带UI界面的Ability扩展的容器组件。

  • LocationButton

    安全控件的位置控件，用户通过点击该位置控件，可以临时获取精准定位权限，而不需要权限弹框授权确认。

  • PasteButton

    安全控件的粘贴控件，用户通过点击该粘贴控件，可以临时获取读取剪贴板权限，而不会触发toast提示。

  • SaveButton

    安全控件的保存控件，用户通过点击该保存控件，可以临时获取存储权限，而不需要权限弹框授权确认。

完整 ArkUI API 参考

相关推荐
nashane10 小时前
HarmonyOS 6学习：CapsLock键失效诊断与长截图完整实现指南
学习·华为·harmonyos
richard_yuu12 小时前
鸿蒙心理测评模块实战｜PHQ-9/GAD7双量表答题、实时计分与结果本地化存储
华为·harmonyos
不爱吃糖的程序媛15 小时前
2026年Electron 鸿蒙PC环境搭建指南
人工智能·华为·harmonyos
nashane15 小时前
HarmonyOS 6学习：长截图功能开发中的滚动拼接与权限处理实战
人工智能·华为·harmonyos
大师兄666816 小时前
从零开发一个 HarmonyOS 输入法——KikaInputMethod 完整拆解
harmonyos·服务卡片·harmonyos6·formkit
Python私教21 小时前
鸿蒙 NEXT 也能接 MCP？用 ArkTS 跑通 AI Agent 工具链
人工智能·华为·harmonyos
Swift社区1 天前
分布式能力在鸿蒙 PC 上到底怎么用？
分布式·华为·harmonyos
nashane1 天前
HarmonyOS 6学习：外接键盘CapsLock与长截图功能的实战调试与完整解决方案
学习·华为·计算机外设·harmonyos
aqi002 天前
一文理清 HarmonyOS 6.0.2 涵盖的十个升级点
android·华为·harmonyos·鸿蒙·harmony
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05几个好用的ip纯净度检测网站06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07装上就回不去了：CodeGraph 让 AI 编程效率飙升 92%，它到底做了什么？08【AI】2026 年具身智能模型和世界模型总结09codex app每次打开重连5次Reconnecting问题解决10用了半年 OpenRouter，我换到了 Ofox.ai — 两个 AI API 聚合平台的真实对比