鸿蒙UI（ArkUI-方舟UI框架）-开发布局

返回主章节 → 鸿蒙UI（ArkUI-方舟UI框架）

开发布局

1、布局概述

1）布局结构

2）布局元素组成

3）如何选择布局

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

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

4）布局位置

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

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

5）对子元素的约束

• 拉伸：容器组件尺寸发生变化时，增加或减小的空间全部分配给容器组件内指定区域
  

• 缩放：子组件的宽高按照预设的比例，随容器组件发生变化，且变化过程中子组件的宽高比不变
  

• 占比：子组件的宽高按照预设的比例，随祖先容器组件发生变化
  

• 隐藏：隐藏能力是指容器组件内的子组件，按照其预设的显示优先级，随容器组件尺寸变化显示或隐藏，其中相同显示优先级的子组件同时显示或隐藏
  

2、构建布局

1）线性布局 (Row/Column)

概述

线性布局（LinearLayout）是开发中最常用的布局，通过线性容器Row和Column构建。线性布局是其他布局的基础，其子元素在线性方向上（水平方向和垂直方向）依次排列。线性布局的排列方向由所选容器组件决定，Column容器内子元素按照垂直方向排列，Row容器内子元素按照水平方向排列。根据不同的排列方向，开发者可选择使用Row或Column容器创建线性布局。

图1 Column（列，竖着走）容器内子元素排列示意图

图2 Row（行，横着走）容器内子元素排列示意图

布局子元素在排列方向上的间距

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

• Column容器内排列方向上的间距

  Column({ space: 20 }) {Text('space: 20').fontSize(15).fontColor(Color.Gray).width('90%')Row().width('90%').height(50).backgroundColor(0xF5DEB3)Row().width('90%').height(50).backgroundColor(0xD2B48C)Row().width('90%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%')
  

  

• Row容器内排列方向上的间距

  Row({ space: 35 }) {Text('space: 35').fontSize(15).fontColor(Color.Gray)Row().width('10%').height(150).backgroundColor(0xF5DEB3)Row().width('10%').height(150).backgroundColor(0xD2B48C)Row().width('10%').height(150).backgroundColor(0xF5DEB3)
  }.width('90%')
  

  

布局子元素在交叉轴上的对齐方式(alignItems)

在布局容器内，可以通过alignItems属性设置子元素在交叉轴（排列方向的垂直方向）上的对齐方式。

Column({}) {
}.width('100%').alignItems(HorizontalAlign.Start)

其中，交叉轴为垂直方向时，取值为VerticalAlign类型，水平方向取值为HorizontalAlign类型。

Column({}) {
}.width('100%').alignItems(VerticalAlign.Start)

• HorizontalAlign.Start：子元素在水平方向左对齐。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').alignItems(HorizontalAlign.Start).backgroundColor('rgb(242,242,242)')
  

  

• HorizontalAlign.Center：子元素在水平方向居中对齐。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').alignItems(HorizontalAlign.Center).backgroundColor('rgb(242,242,242)')
  

• HorizontalAlign.End：子元素在水平方向右对齐。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').alignItems(HorizontalAlign.End).backgroundColor('rgb(242,242,242)')
  

• VerticalAlign.Top：子元素在垂直方向顶部对齐。

  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.Top).backgroundColor('rgb(242,242,242)')
  

  

• VerticalAlign.Center：子元素在垂直方向居中对齐。

  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.Center).backgroundColor('rgb(242,242,242)')
  

  

• VerticalAlign.Bottom：子元素在垂直方向底部对齐。

  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)

在布局容器内，可以通过justifyContent属性设置子元素在容器主轴上的排列方式。
可以从主轴起始位置开始排布，也可以从主轴结束位置开始排布，或者均匀分割主轴的空间。

1、Column容器内子元素在垂直方向上的排列

• justifyContent(FlexAlign.Start)：元素在垂直方向首端对齐，第一个元素与行首对齐，同时后续的元素与前一个对齐。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.Start)
  

  

• justifyContent(FlexAlign.Center)：元素在垂直方向中心对齐，第一个元素与行首的距离与最后一个元素与行尾距离相同。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.Center)
  

  

• justifyContent(FlexAlign.End)：元素在垂直方向尾部对齐，最后一个元素与行尾对齐，其他元素与后一个对齐。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.End)
  

  

• justifyContent(FlexAlign.SpaceBetween)：垂直方向均匀分配元素，相邻元素之间距离相同。第一个元素与行首对齐，最后一个元素与行尾对齐。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceBetween)
  

• justifyContent(FlexAlign.SpaceAround)：垂直方向均匀分配元素，相邻元素之间距离相同。第一个元素到行首的距离和最后一个元素到行尾的距离是相邻元素之间距离的一半。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceAround)
  

• justifyContent(FlexAlign.SpaceEvenly)：垂直方向均匀分配元素，相邻元素之间的距离、第一个元素与行首的间距、最后一个元素到行尾的间距都完全一样。

  Column({}) {Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)Column() {}.width('80%').height(50).backgroundColor(0xD2B48C)Column() {}.width('80%').height(50).backgroundColor(0xF5DEB3)
  }.width('100%').height(300).backgroundColor('rgb(242,242,242)').justifyContent(FlexAlign.SpaceEvenly)
  

  
  1、Row容器内子元素在水平方向上的排列
  

• justifyContent(FlexAlign.Start)：元素在水平方向首端对齐，第一个元素与行首对齐，同时后续的元素与前一个对齐。

  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.Start)
  

  

• justifyContent(FlexAlign.Center)：元素在水平方向中心对齐，第一个元素与行首的距离与最后一个元素与行尾距离相同。

  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.Center)
  

  

• justifyContent(FlexAlign.End)：元素在水平方向尾部对齐，最后一个元素与行尾对齐，其他元素与后一个对齐

  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.End)
  

  

• justifyContent(FlexAlign.SpaceBetween)：水平方向均匀分配元素，相邻元素之间距离相同。第一个元素与行首对齐，最后一个元素与行尾对齐。

  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)
  

  

• justifyContent(FlexAlign.SpaceAround)：水平方向均匀分配元素，相邻元素之间距离相同。第一个元素到行首的距离和最后一个元素到行尾的距离是相邻元素之间距离的一半。

  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.SpaceAround)
  

  

• justifyContent(FlexAlign.SpaceEvenly)：水平方向均匀分配元素，相邻元素之间的距离、第一个元素与行首的间距、最后一个元素到行尾的间距都完全一样。

  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.SpaceEvenly)
  

  

自适应拉伸

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

@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属性设置子元素和兄弟元素在主轴上的权重，忽略元素本身尺寸设置，使它们在任意尺寸的设备下自适应占满剩余空间。

  @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%')}}
  }
  

  横屏
  
  竖屏
  

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

  @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组件：

  @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) // 滚动到边沿后回弹}
  }
  

  水平方向布局中使用Scroll组件：

  @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) {Row() {ForEach(this.arr, (item?:number|undefined) => {if(item){Text(item.toString()).height('90%').width(150).backgroundColor(0xFFFFFF).borderRadius(15).fontSize(16).textAlign(TextAlign.Center).margin({ left: 10 })}})}.height('100%')}.backgroundColor(0xDCDCDC).scrollable(ScrollDirection.Horizontal) // 滚动方向为水平方向.scrollBar(BarState.On) // 滚动条常驻显示.scrollBarColor(Color.Gray) // 滚动条颜色.scrollBarWidth(10) // 滚动条宽度.edgeEffect(EdgeEffect.Spring) // 滚动到边沿后回弹}
  }
  

2）层叠布局 (Stack)

概述

层叠布局（StackLayout）用于在屏幕上预留一块区域来显示组件中的元素，提供元素可以重叠的布局。层叠布局通过Stack容器组件实现位置的固定定位与层叠，容器中的子元素依次入栈，后一个子元素覆盖前一个子元素，子元素可以叠加，也可以设置位置。
层叠布局具有较强的页面层叠、位置定位能力，其使用场景有广告、卡片层叠效果等。

开发布局

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

// xxx.ets
let MTop:Record<string,number> = { 'top': 50 }@Entry
@Component
struct StackExample {build() {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所示，支持九种对齐方式。

// 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值小的组件上方。

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)
}.width(350).height(350).backgroundColor(0xe0e0e0)

场景实例

使用层叠布局快速搭建页面。

@Entry
@Component
struct StackSample {private arr: string[] = ['APP1', 'APP2', 'APP3', 'APP4', 'APP5', 'APP6', 'APP7', 'APP8'];build() {Stack({ alignContent: Alignment.Bottom }) {Flex({ wrap: FlexWrap.Wrap }) {ForEach(this.arr, (item:string) => {Text(item).width(100).height(100).fontSize(16).margin(10).textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)}, (item:string):string => item)}.width('100%').height('100%')Flex({ justifyContent: FlexAlign.SpaceAround, alignItems: ItemAlign.Center }) {Text('联系人').fontSize(16)Text('设置').fontSize(16)Text('短信').fontSize(16)}.width('50%').height(50).backgroundColor('#16302e2e').margin({ bottom: 15 }).borderRadius(15)}.width('100%').height('100%').backgroundColor('#CFD0CF')}
}

3）弹性布局（Flex）

概述

弹性布局（Flex）提供更加有效的方式对容器中的子元素进行排列、对齐和分配剩余空间。常用于页面头部导航栏的均匀分布、页面框架的搭建、多行数据的排列等。

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

基本概念

• 主轴：Flex组件布局方向的轴线，子元素默认沿着主轴排列。主轴开始的位置称为主轴起始点，结束位置称为主轴结束点。
• 交叉轴：垂直于主轴方向的轴线。交叉轴开始的位置称为交叉轴起始点，结束位置称为交叉轴结束点。

布局方向

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

• FlexDirection.Row（默认值）：主轴为水平方向，子元素从起始端沿着水平方向开始排布。

  Flex({ direction: FlexDirection.Row }) {Text('1').width('33%').height(50).backgroundColor(0xF5DEB3)Text('2').width('33%').height(50).backgroundColor(0xD2B48C)Text('3').width('33%').height(50).backgroundColor(0xF5DEB3)
  }
  .height(70)
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

  

• FlexDirection.RowReverse：主轴为水平方向，子元素从终点端沿着FlexDirection. Row相反的方向开始排布。

  Flex({ direction: FlexDirection.RowReverse }) {Text('1').width('33%').height(50).backgroundColor(0xF5DEB3)Text('2').width('33%').height(50).backgroundColor(0xD2B48C)Text('3').width('33%').height(50).backgroundColor(0xF5DEB3)
  }
  .height(70)
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

  

• FlexDirection.Column：主轴为垂直方向，子元素从起始端沿着垂直方向开始排布。

  Flex({ direction: FlexDirection.Column }) {Text('1').width('100%').height(50).backgroundColor(0xF5DEB3)Text('2').width('100%').height(50).backgroundColor(0xD2B48C)Text('3').width('100%').height(50).backgroundColor(0xF5DEB3)
  }
  .height(70)
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

  

• FlexDirection.ColumnReverse：主轴为垂直方向，子元素从终点端沿着FlexDirection. Column相反的方向开始排布。

  Flex({ direction: FlexDirection.ColumnReverse }) {Text('1').width('100%').height(50).backgroundColor(0xF5DEB3)Text('2').width('100%').height(50).backgroundColor(0xD2B48C)Text('3').width('100%').height(50).backgroundColor(0xF5DEB3)
  }
  .height(70)
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

  

布局换行

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

• FlexWrap. NoWrap（默认值）：不换行。如果子元素的宽度总和大于父元素的宽度，则子元素会被压缩宽度。

  Flex({ wrap: FlexWrap.NoWrap }) {Text('1').width('50%').height(50).backgroundColor(0xF5DEB3)Text('2').width('50%').height(50).backgroundColor(0xD2B48C)Text('3').width('50%').height(50).backgroundColor(0xF5DEB3)
  } 
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

  

• FlexWrap. Wrap：换行，每一行子元素按照主轴方向排列。

  Flex({ wrap: FlexWrap.Wrap }) {Text('1').width('50%').height(50).backgroundColor(0xF5DEB3)Text('2').width('50%').height(50).backgroundColor(0xD2B48C)Text('3').width('50%').height(50).backgroundColor(0xD2B48C)
  } 
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

  

• FlexWrap. WrapReverse：换行，每一行子元素按照主轴反方向排列。

  Flex({ wrap: FlexWrap.WrapReverse}) {Text('1').width('50%').height(50).backgroundColor(0xF5DEB3)Text('2').width('50%').height(50).backgroundColor(0xD2B48C)Text('3').width('50%').height(50).backgroundColor(0xF5DEB3)
  }
  .width('90%')
  .padding(10)
  .backgroundColor(0xAFEEEE)
  

主轴对齐方式(justifyContent)

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

交叉轴对齐方式（alignItems）

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

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

  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：交叉轴方向首部对齐。

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

  

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

  let SWh:Record<string,number|string> = { 'width': '90%', 'height': 80 }
  Flex({ alignItems: ItemAlign.Center }) {  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.End：交叉轴方向底部对齐。

  let SWh:Record<string,number|string> = { 'width': '90%', 'height': 80 }
  Flex({ alignItems: ItemAlign.End }) {  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.Stretch：交叉轴方向(竖向)拉伸填充，在未设置尺寸时，拉伸到容器尺寸。

let SWh:Record<string,number|string> = { 'width': '90%', 'height': 80 }
Flex({ alignItems: ItemAlign.Stretch }) {  Text('1').width('33%').backgroundColor(0xF5DEB3)  Text('2').width('33%').backgroundColor(0xD2B48C)  Text('3').width('33%').backgroundColor(0xF5DEB3)
}
.size(SWh)
.padding(10)
.backgroundColor(0xAFEEEE)

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

  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)
  

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

  • FlexAlign.Start：子元素各行与交叉轴起点对齐

    Flex({ justifyContent: FlexAlign.SpaceBetween, wrap: FlexWrap.Wrap, alignContent: FlexAlign.Start }) {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)          
    

    

  • FlexAlign.Center：子元素各行在交叉轴方向居中对齐
    

  • FlexAlign.End：子元素各行与交叉轴终点对齐。
    

  • FlexAlign.SpaceBetween：子元素各行与交叉轴两端对齐，各行间垂直间距平均分布
    

  • FlexAlign.SpaceAround：子元素各行间距相等，是元素首尾行与交叉轴两端距离的两倍。
    

  • FlexAlign.SpaceEvenly: 子元素各行间距，子元素首尾行与交叉轴两端距离都相等。
    

自适应拉伸

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

  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：设置父容器的剩余空间分配给此属性所在组件的比例。用于分配父组件的剩余空间。

  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的子元素不参与“瓜分”。

  第一个元素以及第二个元素以2:3分配剩下的100vp。第一个元素为100vp+100vp * 2/5=140vp，第二个元素为100vp+100vp * 3/5=160vp。

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

  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) 
  

  

4）相对布局 (RelativeContainer)

概述

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

基本概念

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

设置依赖关系

• 锚点设置
  锚点设置是指设置子元素相对于父元素或兄弟元素的位置依赖关系。在水平方向上，可以设置left、middle、right的锚点。在竖直方向上，可以设置top、center、bottom的锚点。

  为了明确定义锚点，必须为RelativeContainer及其子元素设置ID，用于指定锚点信息。ID默认为“container”，其余子元素的ID通过id属性设置。不设置id的组件能显示，但是不能被其他子组件作为锚点，相对布局容器会为其拼接id，此id的规律无法被应用感知。互相依赖，环形依赖时容器内子组件全部不绘制。同方向上两个以上位置设置锚点，但锚点位置逆序时此子组件大小为0，即不绘制。

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

    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' }@Entry
    @Component
    struct Index {build() {RelativeContainer() {Row() {Text('row1')}.justifyContent(FlexAlign.Center).width(100).height(100).backgroundColor('#a3cf62').alignRules(AlignRus).id("row1")Row() {Text('row2')}.justifyContent(FlexAlign.Center).width(100).height(100).backgroundColor('#00ae9d').alignRules(AlignRue).id("row2")}.width(300).height(300).margin(Mleft).border(BWC)}
    }
    

    

  • 以兄弟元素为锚点。

    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' }@Entry
    @Component
    struct Index {build() {RelativeContainer() {Row() {Text('row1')}.justifyContent(FlexAlign.Center).width(100).height(100).backgroundColor('#00ae9d').alignRules(AlignRus).id("row1")Row() {Text('row2')}.justifyContent(FlexAlign.Center).width(100).height(100).backgroundColor('#a3cf62').alignRules(RelConB).id("row2")}.width(300).height(300).margin(Mleft).border(BWC)}
    }
    

    

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

    @Entry
    @Component
    struct Index {build() {Row() {RelativeContainer() {Row(){Text('row1')}.justifyContent(FlexAlign.Center).width(100).height(100).backgroundColor('#a3cf62').alignRules({top: {anchor: "__container__", align: VerticalAlign.Top},left: {anchor: "__container__", align: HorizontalAlign.Start}}).id("row1")Row(){Text('row2')}.justifyContent(FlexAlign.Center).width(100).backgroundColor('#00ae9d').alignRules({top: {anchor: "__container__", align: VerticalAlign.Top},right: {anchor: "__container__", align: HorizontalAlign.End},bottom: {anchor: "row1", align: VerticalAlign.Center},}).id("row2")Row(){Text('row3')}.justifyContent(FlexAlign.Center).height(100).backgroundColor('#0a59f7').alignRules({top: {anchor: "row1", align: VerticalAlign.Bottom},left: {anchor: "row1", align: HorizontalAlign.Start},right: {anchor: "row2", align: HorizontalAlign.Start}}).id("row3")Row(){Text('row4')}.justifyContent(FlexAlign.Center).backgroundColor('#2ca9e0').alignRules({top: {anchor: "row3", align: VerticalAlign.Bottom},left: {anchor: "row1", align: HorizontalAlign.Center},right: {anchor: "row2", align: HorizontalAlign.End},bottom: {anchor: "__container__", align: VerticalAlign.Bottom}}).id("row4")}.width(300).height(300).margin({left: 50}).border({width:2, color: "#6699FF"})}.height('100%')}
    }
    

    

• 设置相对于锚点的对其位置
  设置了锚点之后，可以通过align设置相对于锚点的对齐位置。
  在水平方向上，对齐位置可以设置为HorizontalAlign.Start、HorizontalAlign.Center、HorizontalAlign.End。
  
  在竖直方向上，对齐位置可以设置为VerticalAlign.Top、VerticalAlign.Center、VerticalAlign.Bottom。
  

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

  @Entry
  @Component
  struct Index {
  build() {Row() {RelativeContainer() {Row() {Text('row1')}.justifyContent(FlexAlign.Center).width(100).height(100).backgroundColor('#a3cf62').alignRules({top: { anchor: "__container__", align: VerticalAlign.Top },left: { anchor: "__container__", align: HorizontalAlign.Start }}).id("row1")Row() {Text('row2')}.justifyContent(FlexAlign.Center).width(100).backgroundColor('#00ae9d').alignRules({top: { anchor: "__container__", align: VerticalAlign.Top },right: { anchor: "__container__", align: HorizontalAlign.End },bottom: { anchor: "row1", align: VerticalAlign.Center },}).offset({x: -40,y: -20}).id("row2")Row() {Text('row3')}.justifyContent(FlexAlign.Center).height(100).backgroundColor('#0a59f7').alignRules({top: { anchor: "row1", align: VerticalAlign.Bottom },left: { anchor: "row1", align: HorizontalAlign.End },right: { anchor: "row2", align: HorizontalAlign.Start }}).offset({x: -10,y: -20}).id("row3")Row() {Text('row4')}.justifyContent(FlexAlign.Center).backgroundColor('#2ca9e0').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() {Text('row5')}.justifyContent(FlexAlign.Center).backgroundColor('#30c9f7').alignRules({top: { anchor: "row3", align: VerticalAlign.Bottom },bottom: { anchor: "__container__", align: VerticalAlign.Bottom },left: { anchor: "row2", align: HorizontalAlign.Start },right: { anchor: "row2", align: HorizontalAlign.End }}).offset({x: 10,y: 20}).id("row5")Row() {Text('row6')}.justifyContent(FlexAlign.Center).backgroundColor('#ff33ffb5').alignRules({top: { anchor: "row3", align: VerticalAlign.Bottom },bottom: { anchor: "row4", align: VerticalAlign.Bottom },left: { anchor: "row3", align: HorizontalAlign.Start },right: { anchor: "row3", align: HorizontalAlign.End }}).offset({x: -15,y: 10}).backgroundImagePosition(Alignment.Bottom).backgroundImageSize(ImageSize.Cover).id("row6")}.width(300).height(300).margin({ left: 50 }).border({ width: 2, color: "#6699FF" })}.height('100%')
  }
  }
  

多种组件的对其布局

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

@Entry
@Component
struct Index {
@State value: number = 0build() {Row() {RelativeContainer() {Row().width(100).height(100).backgroundColor('#a3cf62').alignRules({top: { anchor: "__container__", align: VerticalAlign.Top },left: { anchor: "__container__", align: HorizontalAlign.Start }}).id("row1")Column().width('50%').height(30).backgroundColor('#00ae9d').alignRules({top: { anchor: "__container__", align: VerticalAlign.Top },left: { anchor: "__container__", align: HorizontalAlign.Center }}).id("row2")Flex({ direction: FlexDirection.Row }) {Text('1').width('20%').height(50).backgroundColor('#0a59f7')Text('2').width('20%').height(50).backgroundColor('#2ca9e0')Text('3').width('20%').height(50).backgroundColor('#0a59f7')Text('4').width('20%').height(50).backgroundColor('#2ca9e0')}.padding(10).backgroundColor('#30c9f7').alignRules({top: { anchor: "row2", align: VerticalAlign.Bottom },left: { anchor: "__container__", align: HorizontalAlign.Start },bottom: { anchor: "__container__", align: VerticalAlign.Center },right: { anchor: "row2", align: HorizontalAlign.Center }}).id("row3")Stack({ alignContent: Alignment.Bottom }) {Text('First child, show in bottom').width('90%').height('100%').backgroundColor('#a3cf62').align(Alignment.Top)Text('Second child, show in top').width('70%').height('60%').backgroundColor('#00ae9d').align(Alignment.Top)}.margin({ top: 5 }).alignRules({top: { anchor: "row3", align: VerticalAlign.Bottom },left: { anchor: "__container__", align: HorizontalAlign.Start },bottom: { anchor: "__container__", align: VerticalAlign.Bottom },right: { anchor: "row3", align: HorizontalAlign.End }}).id("row4")}.width(300).height(300).margin({ left: 50 }).border({ width: 2, color: "#6699FF" })}.height('100%')
}
}

组件尺寸

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

5）栅格布局 (GridRow/GridCol)

概述

栅格布局是一种通用的辅助定位工具，对移动设备的界面设计有较好的借鉴作用。主要优势包括：
提供可循的规律：栅格布局可以为布局提供规律性的结构，解决多尺寸多设备的动态布局问题。通过将页面划分为等宽的列数和行数，可以方便地对页面元素进行定位和排版。

1. 统一的定位标注：栅格布局可以为系统提供一种统一的定位标注，保证不同设备上各个模块的布局一致性。这可以减少设计和开发的复杂度，提高工作效率。
2. 灵活的间距调整方法：栅格布局可以提供一种灵活的间距调整方法，满足特殊场景布局调整的需求。通过调整列与列之间和行与行之间的间距，可以控制整个页面的排版效果。
3. 自动换行和自适应：栅格布局可以完成一对多布局的自动换行和自适应。当页面元素的数量超出了一行或一列的容量时，他们会自动换到下一行或下一列，并且在不同的设备上自适应排版，使得页面布局更加灵活和适应性强。

栅格容器GridRow

1）栅格系统断点
栅格系统以设备的水平宽度（屏幕密度像素值，单位vp）作为断点依据，定义设备的宽度类型，形成了一套断点规则。开发者可根据需求在不同的断点区间实现不同的页面布局效果。
栅格系统默认断点将设备宽度分为xs、sm、md、lg四类，尺寸范围如下：

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

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

  breakpoints: {value: ['100vp', '200vp']}
  

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

  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列，通过断点设置将应用宽度分成六个区间，在各区间中，每个栅格子元素占用的列数均不同:

@State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)'];
...
GridRow({breakpoints: {value: ['200vp', '300vp', '400vp', '500vp', '600vp'],reference: BreakpointsReference.WindowSize}
}) {ForEach(this.bgColors, (color:ResourceColor, 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)})
}                                                                    

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

• columns默认值为12，即在未设置columns时，任何断点下，栅格布局被分成12列。

  @State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)', 'rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)'];
  ...
  GridRow() {ForEach(this.bgColors, (item:ResourceColor, index?:number|undefined) => {GridCol() {Row() {Text(`${index}`)}.width('100%').height('50')}.backgroundColor(item)})
  }           
  

  
  当columns为自定义值，栅格布局在任何尺寸设备下都被分为columns列。下面分别设置栅格布局列数为4和8，子元素默认占一列，效果如下：

  class CurrTmp{currentBp: string = 'unknown';set(val:string){this.currentBp = val}
  }
  let BorderWH:Record<string,Color|number> = { 'color': Color.Blue, 'width': 2 }
  @State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)'];
  @State currentBp: string = 'unknown';
  ...
  Row() {GridRow({ columns: 4 }) {ForEach(this.bgColors, (item: ResourceColor, index?:number|undefined) => {GridCol() {Row() {Text(`${index}`)}.width('100%').height('50')}.backgroundColor(item)})}.width('100%').height('100%').onBreakpointChange((breakpoint:string) => {let CurrSet:CurrTmp = new CurrTmp()CurrSet.set(breakpoint)})
  }
  .height(160)
  .border(BorderWH)
  .width('90%')Row() {GridRow({ columns: 8 }) {ForEach(this.bgColors, (item: ResourceColor, index?:number|undefined) => {GridCol() {Row() {Text(`${index}`)}.width('100%').height('50')}.backgroundColor(item)})}.width('100%').height('100%').onBreakpointChange((breakpoint:string) => {let CurrSet:CurrTmp = new CurrTmp()CurrSet.set(breakpoint)})
  }
  .height(160)
  .border(BorderWH)
  .width('90%')
  

  

3）排列方向
栅格布局中，可以通过设置GridRow的direction属性来指定栅格子组件在栅格容器中的排列方向。该属性可以设置为GridRowDirection.Row（从左往右排列）或GridRowDirection.RowReverse（从右往左排列），以满足不同的布局需求。通过合理的direction属性设置，可以使得页面布局更加灵活和符合设计要求。

• 子组件默认从左往右排列。

  GridRow({ direction: GridRowDirection.Row }){}
  

  
• 子组件从右往左排列。

  GridRow({ direction: GridRowDirection.RowReverse }){}
  

  

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

GridRow({ gutter: 10 }){}

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

  GridRow({ gutter: { x: 20, y: 50 } }){}
  

  

子组件GridCol

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

• 设置span

  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

  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) 
  

• 设置order

  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)
  

1）span
子组件占栅格布局的列数，决定了子组件的宽度，默认为1。

• 当类型为number时，子组件在所有尺寸设备下占用的列数相同。

  @State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)'];
  ...
  GridRow({ columns: 8 }) {ForEach(this.bgColors, (color:ResourceColor, index?:number|undefined) => {GridCol({ span: 2 }) {      Row() {Text(`${index}`)}.width('100%').height('50vp')          }.backgroundColor(color)})
  }                
  

  

• 当类型为GridColColumnOption时，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备中子组件所占列数设置，各个尺寸下数值可不同。

  @State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)'];
  ...
  GridRow({ columns: 8 }) {ForEach(this.bgColors, (color:ResourceColor, index?:number|undefined) => {GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 } }) {      Row() {Text(`${index}`)}.width('100%').height('50vp')          }.backgroundColor(color)})
  }                
  

  

2）offset
栅格子组件相对于前一个子组件的偏移列数，默认为0。

• 当类型为number时，子组件偏移相同列数。

  @State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)'];
  ...
  GridRow() {ForEach(this.bgColors, (color:ResourceColor, index?:number|undefined) => {GridCol({ offset: 2 }) {      Row() {Text('' + index)}.width('100%').height('50vp')          }.backgroundColor(color)})
  }                
  

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

• 当类型为GridColColumnOption时，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备中子组件所占列数设置,各个尺寸下数值可不同。

  @State bgColors: ResourceColor[] =['rgb(213,213,213)', 'rgb(150,150,150)', 'rgb(0,74,175)', 'rgb(39,135,217)', 'rgb(61,157,180)', 'rgb(23,169,141)','rgb(255,192,0)', 'rgb(170,10,33)'];
  ...GridRow() {ForEach(this.bgColors, (color:ResourceColor, index?:number|undefined) => {GridCol({ offset: { xs: 1, sm: 2, md: 3, lg: 4 } }) {      Row() {Text('' + index)}.width('100%').height('50vp')          }.backgroundColor(color)})
  }                 
  

  

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

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

• 当类型为number时，子组件在任何尺寸下排序次序一致。

  GridRow() {
  GridCol({ order: 4 }) {Row() {Text('1')}.width('100%').height('50vp')
  }.backgroundColor('rgb(213,213,213)')
  GridCol({ order: 3 }) {Row() {Text('2')}.width('100%').height('50vp')
  }.backgroundColor('rgb(150,150,150)')
  GridCol({ order: 2 }) {Row() {Text('3')}.width('100%').height('50vp')
  }.backgroundColor('rgb(0,74,175)')
  GridCol({ order: 1 }) {Row() {Text('4')}.width('100%').height('50vp')
  }.backgroundColor('rgb(39,135,217)')
  }
  

  

• 当类型为GridColColumnOption时，支持六种不同尺寸（xs, sm, md, lg, xl, xxl）设备中子组件排序次序设置。在xs设备中，子组件排列顺序为1234；sm为2341，md为3412，lg为2431。

  GridRow() {GridCol({ order: { xs:1, sm:5, md:3, lg:7}}) {Row() {Text('1')}.width('100%').height('50vp')}.backgroundColor(Color.Red)GridCol({ order: { xs:2, sm:2, md:6, lg:1} }) {Row() {Text('2')}.width('100%').height('50vp')}.backgroundColor(Color.Orange)GridCol({ order: { xs:3, sm:3, md:1, lg:6} }) {Row() {Text('3')}.width('100%').height('50vp')}.backgroundColor(Color.Yellow)GridCol({ order: { xs:4, sm:4, md:2, lg:5} }) {Row() {Text('4')}.width('100%').height('50vp')}.backgroundColor(Color.Green)
  } 
  

  

栅格组件的嵌套使用

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

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

@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')}GridCol({ span: { sm: 12 } }) {Row() {Text('footer').width('100%').textAlign(TextAlign.Center)}.width('100%').height('10%').backgroundColor(Color.Pink)}}.width('100%').height(300)}
}

6）媒体查询 (@ohos.mediaquery)

概述

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

引入和使用流程

媒体查询通过mediaquery模块接口，设置查询条件并绑定回调函数，任一媒体特征改变时，均会触发回调函数，返回匹配结果，根据返回值更改页面布局或者实现业务逻辑，实现页面的响应式设计。具体步骤如下：

1）首先导入媒体查询模块：

import { mediaquery } from '@kit.ArkUI';

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

let listener: mediaquery.MediaQueryListener = this.getUIContext().getMediaQuery().matchMediaSync('(orientation: landscape)');

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

onPortrait(mediaQueryResult: mediaquery.MediaQueryResult) {if (mediaQueryResult.matches as boolean) {// do something here} else {// do something here}
}listener.on('change', onPortrait);

媒体查询条件

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

7）创建列表 (List)

概述

列表是一种复杂的容器，当列表项达到一定数量，内容超过屏幕大小时，可以自动提供滚动功能。它适合用于呈现同类数据类型或数据类型集，例如图片和文本。在列表中显示数据集合是许多应用程序中的常见要求（如通讯录、音乐列表、购物清单等）。

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

布局与约束

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

如下图所示，在垂直列表中，List按垂直方向自动排列ListItemGroup或ListItem。

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

1）布局
List除了提供垂直和水平布局能力、超出屏幕时可以滚动的自适应延伸能力之外，还提供了自适应交叉轴方向上排列个数的布局能力。
利用垂直布局能力可以构建单列或者多列垂直滚动列表，如下图所示。

利用水平布局能力可以是构建单行或多行水平滚动列表，如下图所示。

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

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

如下图所示，一个垂直列表B没有设置高度时，其父组件A高度为200vp，若其所有子组件C的高度总和为150vp，则此时列表B的高度为150vp。

如下图所示，同样是没有设置高度的垂直列表B，其父组件A高度为200vp，若其所有子组件C的高度总和为300vp，则此时列表B的高度为200vp。

开发布局

1）设置主轴方向

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

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

List() {// ...
}
.listDirection(Axis.Horizontal)

2）设置交叉轴布局

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

• lanes
  lanes属性的取值类型是 “number | LengthConstrain” ，即整数或者LengthConstrain类型

  lanes的默认值为1，即默认情况下，垂直列表的列数是1。

  List() {// ...
  }
  .lanes(2)
  

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

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

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

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

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

  List() {// ...
  }
  .alignListItem(ListItemAlign.Center)
  

在列表中显示数据

列表视图垂直或水平显示项目集合，在行或列超出屏幕时提供滚动功能，使其适合显示大型数据集合。在最简单的列表形式中，List静态地创建其列表项ListItem的内容。

@Entry
@Component
struct CityList {build() {List() {ListItem() {Text('北京').fontSize(24)}ListItem() {Text('杭州').fontSize(24)}ListItem() {Text('上海').fontSize(24)}}.backgroundColor('#FFF1F3F5').alignListItem(ListItemAlign.Center)}
}

由于在ListItem中只能有一个根节点组件，不支持以平铺形式使用多个组件。因此，若列表项是由多个组件元素组成的，则需要将这多个元素组合到一个容器组件内或组成一个自定义组件。

联系人列表的列表项中，每个联系人都有头像和名称。此时，需要将Image和Text封装到一个Row容器内。

List() {ListItem() {Row() {Image($r('app.media.iconE')).width(40).height(40).margin(10)Text('小明').fontSize(20)}}ListItem() {Row() {Image($r('app.media.iconF')).width(40).height(40).margin(10)Text('小红').fontSize(20)}}
}

迭代列表内容

应用通过数据集合动态地创建列表。使用循环渲染可从数据源中迭代获取数据，并在每次迭代过程中创建相应的组件，降低代码复杂度。 **例如：** ArkTS通过ForEach提供了组件的循环渲染能力。以简单形式的联系人列表为例，将联系人名称和头像数据以Contact类结构存储到contacts数组，使用ForEach中嵌套ListItem的形式来代替多个平铺的、内容相似的ListItem，从而减少重复代码。

import { util } from '@kit.ArkTS'class Contact {key: string = util.generateRandomUUID(true);name: string;icon: Resource;constructor(name: string, icon: Resource) {this.name = name;this.icon = icon;}
}@Entry
@Component
struct SimpleContacts {private contacts: Array<object> = [new Contact('小明', $r("app.media.iconA")),new Contact('小红', $r("app.media.iconB")),]build() {List() {ForEach(this.contacts, (item: Contact) => {ListItem() {Row() {Image(item.icon).width(40).height(40).margin(10)Text(item.name).fontSize(20)}.width('100%').justifyContent(FlexAlign.Start)}}, (item: Contact) => JSON.stringify(item))}.width('100%')}
}

在List组件中，ForEach除了可以用来循环渲染ListItem，也可以用来循环渲染ListItemGroup。ListItemGroup的循环渲染详细使用请参见支持分组列表。

自定义列表样式

1）设置内容间距
在初始化列表时，如需在列表项之间添加间距，可以使用space参数。例如，在每个列表项之间沿主轴方向添加10vp的间距：

List({ space: 10 }) {// ...
}

2）添加分割线
分隔线用来将界面元素隔开，使单个元素更加容易识别。如下图所示，当列表项左边有图标（如蓝牙图标），由于图标本身就能很好的区分，此时分隔线从图标之后开始显示即可。

List提供了divider属性用于给列表项之间添加分隔线。在设置divider属性时，可以通过strokeWidth和color属性设置分隔线的粗细和颜色。

startMargin和endMargin属性分别用于设置分隔线距离列表侧边起始端的距离和距离列表侧边结束端的距离。

class DividerTmp {strokeWidth: Length = 1startMargin: Length = 60endMargin: Length = 10color: ResourceColor = '#ffe9f0f0'constructor(strokeWidth: Length, startMargin: Length, endMargin: Length, color: ResourceColor) {this.strokeWidth = strokeWidththis.startMargin = startMarginthis.endMargin = endMarginthis.color = color}
}
@Entry
@Component
struct EgDivider {@State egDivider: DividerTmp = new DividerTmp(1, 60, 10, '#ffe9f0f0')build() {List() {// ...}.divider(this.egDivider)}
}

此示例表示从距离列表侧边起始端60vp开始到距离结束端10vp的位置，画一条粗细为1vp的分割线，可以实现上图设置列表分隔线的样式。

3）添加滚动条
当列表项高度（宽度）超出屏幕高度（宽度）时，列表可以沿垂直（水平)方向滚动。在页面内容很多时，若用户需快速定位，可拖拽滚动条，如下图所示。

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

4）支持分组列表
在列表中支持数据的分组展示，可以使列表显示结构清晰，查找方便，从而提高使用效率。分组列表在实际应用中十分常见，如下图所示联系人列表。

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

@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}}}
}

如果多个ListItemGroup结构类似，可以将多个分组的数据组成数组，然后使用ForEach对多个分组进行循环渲染。例如在联系人列表中，将每个分组的联系人数据contacts（可参考迭代列表内容章节）和对应分组的标题title数据进行组合，定义为数组contactsGroups。然后在ForEach中对contactsGroups进行循环渲染，即可实现多个分组的联系人列表。可参考添加粘性标题章节示例代码。

5）添加粘性标题
粘性标题是一种常见的标题模式，常用于定位字母列表的头部元素。如下图所示，在联系人列表中滚动A部分时，B部分开始的头部元素始终处于A的下方。而在开始滚动B部分时，B的头部会固定在屏幕顶部，直到所有B的项均完成滚动后，才被后面的头部替代。

粘性标题不仅有助于阐明列表中数据的表示形式和用途，还可以帮助用户在大量信息中进行数据定位，从而避免用户在标题所在的表的顶部与感兴趣区域之间反复滚动。

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

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

import { util } from '@kit.ArkTS'
class Contact {key: string = util.generateRandomUUID(true);name: string;icon: Resource;constructor(name: string, icon: Resource) {this.name = name;this.icon = icon;}
}
class ContactsGroup {title: string = ''contacts: Array<object> | null = nullkey: string = ""
}
export let contactsGroups: object[] = [{title: 'A',contacts: [new Contact('艾佳', $r('app.media.iconA')),new Contact('安安', $r('app.media.iconB')),new Contact('Angela', $r('app.media.iconC')),],key: util.generateRandomUUID(true)} as ContactsGroup,{title: 'B',contacts: [new Contact('白叶', $r('app.media.iconD')),new Contact('伯明', $r('app.media.iconE')),],key: util.generateRandomUUID(true)} as ContactsGroup,// ...
]
@Entry
@Component
struct ContactsList {// 定义分组联系人数据集合contactsGroups数组@Builder itemHead(text: string) {// 列表分组的头部组件，对应联系人分组A、B等位置的组件Text(text).fontSize(20).backgroundColor('#fff1f3f5').width('100%').padding(5)}build() {List() {// 循环渲染ListItemGroup，contactsGroups为多个分组联系人contacts和标题title的数据集合ForEach(contactsGroups, (itemGroup: ContactsGroup) => {ListItemGroup({ header: this.itemHead(itemGroup.title) }) {// 循环渲染ListItemif (itemGroup.contacts) {ForEach(itemGroup.contacts, (item: Contact) => {ListItem() {// ...}}, (item: Contact) => JSON.stringify(item))}}}, (itemGroup: ContactsGroup) => JSON.stringify(itemGroup))}.sticky(StickyStyle.Header)  // 设置吸顶，实现粘性标题效果}
}

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

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

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

private listScroller: Scroller = new Scroller();

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

Stack({ alignContent: Alignment.Bottom }) {// 将listScroller用于初始化List组件的scroller参数，完成listScroller与列表的绑定。List({ space: 20, scroller: this.listScroller }) {// ...}Button() {// ...}.onClick(() => {// 点击按钮时，指定跳转位置，返回列表顶部this.listScroller.scrollToIndex(0)})
}

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

除了字母索引之外，滚动列表结合多级分类索引在应用开发过程中也很常见，例如购物应用的商品分类页面，多级分类也需要监听列表的滚动位置。

如上图所示，当联系人列表从A滚动到B时，右侧索引栏也需要同步从选中A状态变成选中B状态。此场景可以通过监听List组件的onScrollIndex事件来实现，右侧索引栏需要使用字母表索引组件AlphabetIndexer。

在列表滚动时，根据列表此时所在的索引值位置firstIndex，重新计算字母索引栏对应字母的位置selectedIndex。由于AlphabetIndexer组件通过selected属性设置了选中项索引值，当selectedIndex变化时会触发AlphabetIndexer组件重新渲染，从而显示为选中对应字母的状态。

const alphabets = ['#', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K','L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'];
@Entry
@Component
struct ContactsList {@State selectedIndex: number = 0;private listScroller: Scroller = new Scroller();build() {Stack({ alignContent: Alignment.End }) {List({ scroller: this.listScroller }) {}.onScrollIndex((firstIndex: number) => {// 根据列表滚动到的索引值，重新计算对应联系人索引栏的位置this.selectedIndex})// 字母表索引组件AlphabetIndexer({ arrayValue: alphabets, selected: 0 }).selected(this.selectedIndex)}}
}

说明
计算索引值时，ListItemGroup作为一个整体占一个索引值，不计算ListItemGroup内部ListItem的索引值。

8）响应列表项侧滑
侧滑菜单在许多应用中都很常见。例如，通讯类应用通常会给消息列表提供侧滑删除功能，即用户可以通过向左侧滑列表的某一项，再点击删除按钮删除消息，如下图所示。其中，列表项头像右上角标记设置参考给列表项添加标记。

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

1. 实现尾端滑出组件的构建。

   @Builder itemEnd(index: number) {// 构建尾端滑出组件Button({ type: ButtonType.Circle }) {Image($r('app.media.ic_public_delete_filled')).width(20).height(20)}.onClick(() => {// this.messages为列表数据源，可根据实际场景构造。点击后从数据源删除指定数据项。this.messages.splice(index, 1);})
   }
   

2. 绑定swipeAction属性到可左滑的ListItem上。

   // 构建List时，通过ForEach基于数据源this.messages循环渲染ListItem。
   ListItem() {// ...
   }
   .swipeAction({end: {// index为该ListItem在List中的索引值。builder: () => { this.itemEnd(index) },}
   }) // 设置侧滑属性.
   

9）给列表项添加标记
添加标记是一种无干扰性且直观的方法，用于显示通知或将注意力集中到应用内的某个区域。例如，当消息列表接收到新消息时，通常对应的联系人头像的右上方会出现标记，提示有若干条未读消息，如下图所示。

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

在消息列表中，若希望在联系人头像右上角添加标记，可在实现消息列表项ListItem的联系人头像时，将头像Image组件作为Badge的子组件。

在Badge组件中，count和position参数用于设置需要展示的消息数量和提示点显示位置，还可以通过style参数灵活设置标记的样式。

ListItem() {Badge({count: 1,position: BadgePosition.RightTop,style: { badgeSize: 16, badgeColor: '#FA2A2D' }}) {// Image组件实现消息联系人头像// ...}
}

10）下拉刷新与上拉刷新
页面的下拉刷新与上拉加载功能在移动应用中十分常见，例如，新闻页面的内容刷新和加载。这两种操作的原理都是通过响应用户的触摸事件，在顶部或者底部显示一个刷新或加载视图，完成后再将此视图隐藏。
以下拉刷新为例，其实现主要分成三步：

1. 监听手指按下事件，记录其初始位置的值。

2. 监听手指按压移动事件，记录并计算当前移动的位置与初始值的差值，大于0表示向下移动，同时设置一个允许移动的最大值。

3. 监听手指抬起事件，若此时移动达到最大值，则触发数据加载并显示刷新视图，加载完成后将此视图隐藏。

   说明： 页面的下拉刷新操作推荐使用Refresh组件实现。

下拉刷新与上拉加载的具体实现可参考新闻数据加载。

11）编辑列表
列表的编辑模式用途十分广泛，常见于待办事项管理、文件管理、备忘录的记录管理等应用场景。在列表的编辑模式下，新增和删除列表项是最基础的功能，其核心是对列表项对应的数据集合进行数据添加和删除。

1. 新增列表项
   如下图所示，当用户点击添加按钮时，提供用户新增列表项内容选择或填写的交互界面，用户点击确定后，列表中新增对应的项目。
   

   • 1、定义列表项数据结构，以待办事项管理为例，首先定义待办数据结构。

     //ToDo.ets
     import { util } from '@kit.ArkTS'export class ToDo {key: string = util.generateRandomUUID(true);name: string;constructor(name: string) {this.name = name;}
     }
     

   • 2、构建列表整体布局和列表项。

     //ToDoListItem.ets
     import { ToDo } from './ToDo';
     @Component
     export struct ToDoListItem {@Link isEditMode: boolean@Link selectedItems: ToDo[]private toDoItem: ToDo = new ToDo("");build() {Flex({ justifyContent: FlexAlign.SpaceBetween, alignItems: ItemAlign.Center }) {// ...}.width('100%').height(80)//.padding() 根据具体使用场景设置.borderRadius(24)//.linearGradient() 根据具体使用场景设置.gesture(GestureGroup(GestureMode.Exclusive,LongPressGesture().onAction(() => {// ...})))}
     }
     

   • 3、初始化待办列表数据和可选事项，最后，构建列表布局和列表项。

     //ToDoList.ets
     import { ToDo } from './ToDo';
     import { ToDoListItem } from './ToDoListItem';@Entry
     @Component
     struct ToDoList {@State toDoData: ToDo[] = []@Watch('onEditModeChange') @State isEditMode: boolean = false@State selectedItems: ToDo[] = []private availableThings: string[] = ['读书', '运动', '旅游', '听音乐', '看电影', '唱歌']onEditModeChange() {if (!this.isEditMode) {this.selectedItems = []}}build() {Column() {Row() {if (this.isEditMode) {Text('X').fontSize(20).onClick(() => {this.isEditMode = false;}).margin({ left: 20, right: 20 })} else {Text('待办').fontSize(36).margin({ left: 40 })Blank()Text('+') //提供新增列表项入口，即给新增按钮添加点击事件.onClick(() => {this.getUIContext().showTextPickerDialog({range: this.availableThings,onAccept: (value: TextPickerResult) => {let arr = Array.isArray(value.index) ? value.index : [value.index];for (let i = 0; i < arr.length; i++) {this.toDoData.push(new ToDo(this.availableThings[arr[i]])); // 新增列表项数据toDoData(可选事项)}},})})}List({ space: 10 }) {ForEach(this.toDoData, (toDoItem: ToDo) => {ListItem() {// 将toDoData的每个数据放入到以model的形式放进ListItem里ToDoListItem({isEditMode: this.isEditMode,toDoItem: toDoItem,selectedItems: this.selectedItems })}}, (toDoItem: ToDo) => toDoItem.key.toString())}}}}
     }
     

2. 删除列表项

   如下图所示，当用户长按列表项进入删除模式时，提供用户删除列表项选择的交互界面，用户勾选完成后点击删除按钮，列表中删除对应的项目。
   

   • 列表的删除功能一般进入编辑模式后才可使用，所以需要提供编辑模式的入口。

     // 结构参考
     export class ToDo {key: string = util.generateRandomUUID(true);name: string;toDoData: ToDo[] = [];constructor(name: string) {this.name = name;}
     }
     

     // 实现参考
     Flex({ justifyContent: FlexAlign.SpaceBetween, alignItems: ItemAlign.Center }) {// ...
     }
     .gesture(
     GestureGroup(GestureMode.Exclusive,LongPressGesture().onAction(() => {if (!this.isEditMode) {this.isEditMode = true; //进入编辑模式}}))
     )
     

   • 需要响应用户的选择交互，记录要删除的列表项数据。
     在待办列表中，通过勾选框的勾选或取消勾选，响应用户勾选列表项变化，记录所有选择的列表项。

     // 结构参考
     import { util } from '@kit.ArkTS'
     export class ToDo {key: string = util.generateRandomUUID(true);name: string;toDoData: ToDo[] = [];constructor(name: string) {this.name = name;}
     }
     

     // 实现参考
     if (this.isEditMode) {Checkbox().onChange((isSelected) => {if (isSelected) {this.selectedItems.push(toDoList.toDoItem) // this.selectedItems为勾选时，记录选中的列表项，可根据实际场景构造} else {let index = this.selectedItems.indexOf(toDoList.toDoItem)if (index !== -1) {this.selectedItems.splice(index, 1) // 取消勾选时，则将此项从selectedItems中删除}}})
     }
     

   • 需要响应用户点击删除按钮事件，删除列表中对应的选项

     // 结构参考
     import { util } from '@kit.ArkTS'
     export class ToDo {key: string = util.generateRandomUUID(true);name: string;toDoData: ToDo[] = [];constructor(name: string) {this.name = name;}
     }
     

     // 实现参考
     Button('删除').onClick(() => {// this.toDoData为待办的列表项，可根据实际场景构造。点击后删除选中的列表项对应的toDoData数据let leftData = this.toDoData.filter((item) => {return !this.selectedItems.find((selectedItem) => selectedItem == item);})this.toDoData = leftData;this.isEditMode = false;})
     

12）长列表的处理

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

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

List() {// ...
}.cachedCount(3)

以垂直列表为例：

• 若懒加载是用于ListItem，当列表为单列模式时，会在List显示的ListItem前后各缓存cachedCount个ListItem；若是多列模式下，会在List显示的ListItem前后各缓存cachedCount * 列数个ListItem。

• 若懒加载是用于ListItemGroup，无论单列模式还是多列模式，都是在List显示的ListItem前后各缓存cachedCount个ListItemGroup。

  1. cachedCount的增加会增大UI的CPU、内存开销。使用时需要根据实际情况，综合性能和用户体验进行调整。
  2. 列表使用数据懒加载时，除了显示区域的列表项和前后缓存的列表项，其他列表项会被销毁。

13）示范代码

• 二维列表
• List组件嵌套滑动
• 列表编辑效果

创建网格 (Grid/GridItem)

概述

网格布局是由“行”和“列”分割的单元格所组成，通过指定“项目”所在的单元格做出各种各样的布局。网格布局具有较强的页面均分能力，子组件占比控制能力，是一种重要自适应布局，其使用场景有九宫格图片展示、日历、计算器等。

约束与布局

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

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

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

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

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

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

设置排列方式

设置行列数量与占比

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

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

如上图所示，构建的是一个三行三列的网格布局，其在垂直方向上分为三等份，每行占一份；在水平方向上分为四等份，第一列占一份，第二列占两份，第三列占一份。

只要将rowsTemplate的值为’1fr 1fr 1fr’，同时将columnsTemplate的值为’1fr 2fr 1fr’，即可实现上述网格布局。

Grid() {...
}
.rowsTemplate('1fr 1fr 1fr')
.columnsTemplate('1fr 2fr 1fr')

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

设置子组件所占行列数

除了大小相同的等比例网格布局，由不同大小的网格组成不均匀分布的网格布局场景在实际应用中十分常见，如下图所示。在Grid组件中，可以通过创建Grid时传入合适的GridLayoutOptions实现如图所示的单个网格横跨多行或多列的场景，其中，irregularIndexes和onGetIrregularSizeByIndex可对仅设置rowsTemplate或columnsTemplate的Grid使用；onGetRectByIndex可对同时设置rowsTemplate和columnsTemplate的Grid使用。

例如： 计算器的按键布局就是常见的不均匀网格布局场景。如下图，计算器中的按键“0”和“=”，按键“0”横跨第一、二两列，按键“=”横跨第五、六两行。使用Grid构建的网格布局，其行列标号从0开始，依次编号。

在网格中，可以通过onGetRectByIndex返回的**[rowStart,columnStart,rowSpan,columnSpan]**来实现跨行跨列布局，其中rowStart和columnStart属性表示指定当前元素起始行号和起始列号，rowSpan和columnSpan属性表示指定当前元素的占用行数和占用列数。

所以“0”按键横跨第一列和第二列，“=”按键横跨第五行和第六行，只要将
“0”对应onGetRectByIndex的rowStart和columnStart设为5和0，rowSpan和columnSpan设为1和2，将
“=”对应onGetRectByIndex的rowStart和columnStart设为4和3，rowSpan和columnSpan设为2和1即可。

layoutOptions: GridLayoutOptions = {regularSize: [1, 1],onGetRectByIndex: (index: number) => {if (index == key1) { // key1是“0”按键对应的indexreturn [5, 0, 1, 2]} else if (index == key2) { // key2是“=”按键对应的indexreturn [4, 3, 2, 1]}// ...// 这里需要根据具体布局返回其他item的位置}
}Grid(undefined, this.layoutOptions) {// ...
}
.columnsTemplate('1fr 1fr 1fr 1fr')
.rowsTemplate('2fr 1fr 1fr 1fr 1fr 1fr')

设置主轴方向

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

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

Grid() {...
}
.maxCount(3)
.layoutDirection(GridDirection.Row)

说明
layoutDirection属性仅在不设置rowsTemplate和columnsTemplate时生效，此时元素在layoutDirection方向上排列。
仅设置rowsTemplate时，Grid主轴为水平方向，交叉轴为垂直方向。
仅设置columnsTemplate时，Grid主轴为垂直方向，交叉轴为水平方向。

在网格布局中显示数据

网格布局采用二维布局的方式组织其内部元素，如下图所示。

Grid() {GridItem() {Text('会议')...}GridItem() {Text('签到')...}GridItem() {Text('投票')...}GridItem() {Text('打印')...}
}
.rowsTemplate('1fr 1fr')
.columnsTemplate('1fr 1fr')

对于内容结构相似的多个GridItem，通常更推荐使用ForEach语句中嵌套GridItem的形式，来减少重复代码。

@Entry
@Component
struct OfficeService {@State services: Array<string> = ['会议', '投票', '签到', '打印']build() {Column() {Grid() {ForEach(this.services, (service:string) => {GridItem() {Text(service)}}, (service:string):string => service)}.rowsTemplate(('1fr 1fr') as string).columnsTemplate(('1fr 1fr') as string)}}
}

设置行列间距

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

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

Grid() {...
}
.columnsGap(10)
.rowsGap(15)

构建可滚动的网格布局

可滚动的网格布局常用在文件管理、购物或视频列表等页面中，如下图所示。在设置Grid的行列数量与占比时，如果仅设置行、列数量与占比中的一个，即仅设置rowsTemplate或仅设置columnsTemplate属性，网格单元按照设置的方向排列，超出Grid显示区域后，Grid拥有可滚动能力。

如果设置的是columnsTemplate，Grid的滚动方向为垂直方向；如果设置的是rowsTemplate，Grid的滚动方向为水平方向。

如上图所示的横向可滚动网格布局，只要设置rowsTemplate属性的值且不设置columnsTemplate属性，当内容超出Grid组件宽度时，Grid可横向滚动进行内容展示。

@Entry
@Component
struct Shopping {@State services: Array<string> = ['直播', '进口']build() {Column({ space: 5 }) {Grid() {ForEach(this.services, (service: string, index) => {GridItem() {}.width('25%')}, (service:string):string => service)}.rowsTemplate('1fr 1fr') // 只设置rowsTemplate属性，当内容超出Grid区域时，可水平滚动。.rowsGap(15)}}
}

控制滚动位置

与新闻列表的返回顶部场景类似，控制滚动位置功能在网格布局中也很常用，例如下图所示日历的翻页功能。

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

private scroller: Scroller = new Scroller()

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

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() {LazyForEach(this.dataSource, () => {GridItem() {}})
}
.cachedCount(3)

创建轮播 (Swiper)

Swiper组件提供滑动轮播显示的能力。Swiper本身是一个容器组件，当设置了多个子组件后，可以对这些子组件进行轮播显示。通常，在一些应用首页显示推荐的内容时，需要用到轮播显示的能力。

布局与约束

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

循环播放

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

当loop为true时，在显示第一页或最后一页时，可以继续往前切换到前一页或者往后切换到后一页。如果loop为false，则在第一页或最后一页时，无法继续向前或者向后切换页面。

• loop为true

  Swiper() {Text('0').width('90%').height('100%').backgroundColor(Color.Gray).textAlign(TextAlign.Center).fontSize(30)Text('1').width('90%').height('100%').backgroundColor(Color.Green).textAlign(TextAlign.Center).fontSize(30)Text('2').width('90%').height('100%').backgroundColor(Color.Pink).textAlign(TextAlign.Center).fontSize(30)
  }
  .loop(true)
  

  
• loop为false

  Swiper() {// ...
  }
  .loop(false)
  

  

自动轮播

Swiper通过设置autoPlay属性，控制是否自动轮播子组件。该属性默认值为false。
autoPlay为true时，会自动切换播放子组件，子组件与子组件之间的播放间隔通过interval属性设置。interval属性默认值为3000，单位毫秒。

Swiper() {// ...
}
.loop(true)
.autoPlay(true)
.interval(1000)

导航点样式

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

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

• 导航点使用默认样式

  Swiper() {Text('0').width('90%').height('100%').backgroundColor(Color.Gray).textAlign(TextAlign.Center).fontSize(30)Text('1').width('90%').height('100%').backgroundColor(Color.Green).textAlign(TextAlign.Center).fontSize(30)Text('2').width('90%').height('100%').backgroundColor(Color.Pink).textAlign(TextAlign.Center).fontSize(30)
  }
  

  

• 自定义导航点样式
  导航点直径设为30vp，左边距为0，导航点颜色设为红色。

  Swiper() {// ...
  }
  .indicator(Indicator.dot().left(0).itemWidth(15).itemHeight(15).selectedItemWidth(30).selectedItemHeight(15).color(Color.Red).selectedColor(Color.Blue)
  )
  

  

Swiper通过设置displayArrow属性，可以控制导航点箭头的大小、位置、颜色，底板的大小及颜色，以及鼠标悬停时是否显示箭头。

• 箭头使用默认样式

  Swiper() {// ...
  }
  .displayArrow(true, false)
  

  

• 自定义箭头样式
  箭头显示在组件两侧，大小为18vp，导航点箭头颜色设为蓝色。

  Swiper() {// ...
  }
  .displayArrow({ showBackground: true,isSidebarMiddle: true,backgroundSize: 24,backgroundColor: Color.White,arrowSize: 18,arrowColor: Color.Blue}, false)
  

  

页面切换方式

Swiper支持手指滑动、点击导航点和通过控制器三种方式切换页面，以下示例展示通过控制器切换页面的方法。

@Entry
@Component
struct SwiperDemo {private swiperController: SwiperController = new SwiperController();build() {Column({ space: 5 }) {Swiper(this.swiperController) {Text('0').width(250).height(250).backgroundColor(Color.Gray).textAlign(TextAlign.Center).fontSize(30)Text('1').width(250).height(250).backgroundColor(Color.Green).textAlign(TextAlign.Center).fontSize(30)Text('2').width(250).height(250).backgroundColor(Color.Pink).textAlign(TextAlign.Center).fontSize(30)}.indicator(true)Row({ space: 12 }) {Button('showNext').onClick(() => {this.swiperController.showNext(); // 通过controller切换到后一页})Button('showPrevious').onClick(() => {this.swiperController.showPrevious(); // 通过controller切换到前一页})}.margin(5)}.width('100%').margin({ top: 5 })}
}

轮播方向

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

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

• 设置水平方向轮播

Swiper() {// ...
}
.indicator(true)
.vertical(false)

• 设置垂直方向轮播

Swiper() {// ...
}
.indicator(true)
.vertical(true)

每页显示多个子页面

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

Swiper() {Text('0').width(250).height(250).backgroundColor(Color.Gray).textAlign(TextAlign.Center).fontSize(30)Text('1').width(250).height(250).backgroundColor(Color.Green).textAlign(TextAlign.Center).fontSize(30)Text('2').width(250).height(250).backgroundColor(Color.Pink).textAlign(TextAlign.Center).fontSize(30)Text('3').width(250).height(250).backgroundColor(Color.Blue).textAlign(TextAlign.Center).fontSize(30)
}
.indicator(true)
.displayCount(2)

自定义切换动画

Swiper支持通过customContentTransition设置自定义切换动画，可以在回调中对视窗内所有页面逐帧设置透明度、缩放比例、位移、渲染层级等属性实现自定义切换动画。

@Entry
@Component
struct SwiperCustomAnimationExample {private DISPLAY_COUNT: number = 2private MIN_SCALE: number = 0.75@State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange]@State opacityList: number[] = []@State scaleList: number[] = []@State translateList: number[] = []@State zIndexList: number[] = []aboutToAppear(): void {for (let i = 0; i < this.backgroundColors.length; i++) {this.opacityList.push(1.0)this.scaleList.push(1.0)this.translateList.push(0.0)this.zIndexList.push(0)}}build() {Column() {Swiper() {ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => {Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center).backgroundColor(backgroundColor).opacity(this.opacityList[index]).scale({ x: this.scaleList[index], y: this.scaleList[index] }).translate({ x: this.translateList[index] }).zIndex(this.zIndexList[index])})}.height(300).indicator(false).displayCount(this.DISPLAY_COUNT, true).customContentTransition({timeout: 1000,transition: (proxy: SwiperContentTransitionProxy) => {if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) {// 同组页面完全滑出视窗外时，重置属性值this.opacityList[proxy.index] = 1.0this.scaleList[proxy.index] = 1.0this.translateList[proxy.index] = 0.0this.zIndexList[proxy.index] = 0} else {// 同组页面未滑出视窗外时，对同组中左右两个页面，逐帧根据position修改属性值if (proxy.index % this.DISPLAY_COUNT === 0) {this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNTthis.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT)this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0} else {this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNTthis.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT)this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0}this.zIndexList[proxy.index] = -1}}})}.width('100%')}
}

示例代码

短视频切换

选项卡 (Tabs)

当页面信息较多时，为了让用户能够聚焦于当前显示的内容，需要对页面内容进行分类，提高页面空间利用率。Tabs组件可以在一个页面内快速实现视图内容的切换，一方面提升查找信息的效率，另一方面精简用户单次获取到的信息量。

基本布局

Tabs组件的页面组成包含两个部分，分别是TabContent和TabBar。TabContent是内容页，TabBar是导航页签栏，页面结构如下图所示，根据不同的导航类型，布局会有区别，可以分为底部导航、顶部导航、侧边导航，其导航栏分别位于底部、顶部和侧边。

说明
TabContent组件不支持设置通用宽度属性，其宽度默认撑满Tabs父组件。
TabContent组件不支持设置通用高度属性，其高度由Tabs父组件高度与TabBar组件高度决定。

每一个TabContent对应的内容需要有一个页签，可以通过TabContent的tabBar属性进行配置。在如下TabContent组件上设置tabBar属性，可以设置其对应页签中的内容，tabBar作为内容的页签。

 TabContent() {Text('首页的内容').fontSize(30)}
.tabBar('首页')

设置多个内容时，需在Tabs内按照顺序放置。

Tabs() {TabContent() {Text('首页的内容').fontSize(30)}.tabBar('首页')TabContent() {Text('推荐的内容').fontSize(30)}.tabBar('推荐')TabContent() {Text('发现的内容').fontSize(30)}.tabBar('发现')TabContent() {Text('我的内容').fontSize(30)}.tabBar("我的")
}

底部导航

底部导航是应用中最常见的一种导航方式。底部导航位于应用一级页面的底部，用户打开应用，能够分清整个应用的功能分类，以及页签对应的内容，并且其位于底部更加方便用户单手操作。底部导航一般作为应用的主导航形式存在，其作用是将用户关心的内容按照功能进行分类，迎合用户使用习惯，方便在不同模块间的内容切换。

导航栏位置使用Tabs的barPosition参数进行设置。默认情况下，导航栏位于顶部，此时，barPosition为BarPosition.Start。设置为底部导航时，需要将barPosition设置为BarPosition.End。

Tabs({ barPosition: BarPosition.End }) {// TabContent的内容：首页、发现、推荐、我的...
}

顶部导航

当内容分类较多，用户对不同内容的浏览概率相差不大，需要经常快速切换时，一般采用顶部导航模式进行设计，作为对底部导航内容的进一步划分，常见一些资讯类应用对内容的分类为关注、视频、数码，或者主题应用中对主题进行进一步划分为图片、视频、字体等。

Tabs({ barPosition: BarPosition.Start }) {// TabContent的内容:关注、视频、游戏、数码、科技、体育、影视...
}

侧边导航

侧边导航是应用较为少见的一种导航模式，更多适用于横屏界面，用于对应用进行导航操作，由于用户的视觉习惯是从左到右，侧边导航栏默认为左侧侧边栏。

实现侧边导航栏需要将Tabs的vertical属性设置为true，vertical默认值为false，表明内容页和导航栏垂直方向排列。

Tabs({ barPosition: BarPosition.Start }) {// TabContent的内容:首页、发现、推荐、我的...
}
.vertical(true)
.barWidth(100)
.barHeight(200)

说明
vertical为false时，tabbar的宽度默认为撑满屏幕的宽度，需要设置barWidth为合适值。
vertical为true时，tabbar的高度默认为实际内容的高度，需要设置barHeight为合适值。

限制导航栏的滑动切换

默认情况下，导航栏都支持滑动切换，在一些内容信息量需要进行多级分类的页面，如支持底部导航+顶部导航组合的情况下，底部导航栏的滑动效果与顶部导航出现冲突，此时需要限制底部导航的滑动，避免引起不好的用户体验。

控制滑动切换的属性为scrollable，默认值为true，表示可以滑动，若要限制滑动切换页签则需要设置为false。

Tabs({ barPosition: BarPosition.End }) {TabContent(){Column(){Tabs(){// 顶部导航栏内容...}}.backgroundColor('#ff08a8f1').width('100%')}.tabBar('首页')// 其他TabContent内容：发现、推荐、我的...
}
.scrollable(false)

固定导航栏

当内容分类较为固定且不具有拓展性时，例如底部导航内容分类一般固定，分类数量一般在3-5个，此时使用固定导航栏。固定导航栏不可滚动，无法被拖拽滚动，内容均分tabBar的宽度。

Tabs的barMode属性用于控制导航栏是否可以滚动，默认值为BarMode.Fixed。

Tabs({ barPosition: BarPosition.End }) {// TabContent的内容：首页、发现、推荐、我的...
}
.barMode(BarMode.Fixed)

滚动导航栏

滚动导航栏需要设置Tabs组件的barMode属性，默认值为BarMode.Fixed表示为固定导航栏，BarMode.Scrollable表示可滚动导航栏。

Tabs({ barPosition: BarPosition.Start }) {// TabContent的内容：关注、视频、游戏、数码、科技、体育、影视、人文、艺术、自然、军事...
}
.barMode(BarMode.Scrollable)

自定义导航栏

对于底部导航栏，一般作为应用主页面功能区分，为了更好的用户体验，会组合文字以及对应语义图标表示页签内容，这种情况下，需要自定义导航页签的样式。

设置自定义导航栏需要使用tabBar的参数，以其支持的CustomBuilder的方式传入自定义的函数组件样式。例如这里声明tabBuilder的自定义函数组件，传入参数包括页签文字title，对应位置index，以及选中状态和未选中状态的图片资源。通过当前活跃的currentIndex和页签对应的targetIndex匹配与否，决定UI显示的样式。

@Builder tabBuilder(title: string, targetIndex: number, selectedImg: Resource, normalImg: Resource) {Column() {Image(this.currentIndex === targetIndex ? selectedImg : normalImg).size({ width: 25, height: 25 })Text(title).fontColor(this.currentIndex === targetIndex ? '#1698CE' : '#6B6B6B')}.width('100%').height(50).justifyContent(FlexAlign.Center)
}

在TabContent对应tabBar属性中传入自定义函数组件，并传递相应的参数。

TabContent() {Column(){Text('我的内容')  }.width('100%').height('100%').backgroundColor('#007DFF')
}
.tabBar(this.tabBuilder('我的', 0, $r('app.media.mine_selected'), $r('app.media.mine_normal')))

切换至指定页签

在不使用自定义导航栏时，默认的Tabs会实现切换逻辑。在使用了自定义导航栏后，默认的Tabs仅实现滑动内容页和点击页签时内容页的切换逻辑，页签切换逻辑需要自行实现。即用户滑动内容页和点击页签时，页签栏需要同步切换至内容页对应的页签。

内容页和页签不联动

此时需要使用Tabs提供的onChange事件方法，监听索引index的变化，并将当前活跃的index值传递给currentIndex，实现页签的切换。

@Entry
@Component
struct TabsExample1 {@State currentIndex: number = 2@Builder tabBuilder(title: string, targetIndex: number) {Column() {Text(title).fontColor(this.currentIndex === targetIndex ? '#1698CE' : '#6B6B6B')}}build() {Column() {Tabs({ barPosition: BarPosition.End }) {TabContent() {...}.tabBar(this.tabBuilder('首页', 0))TabContent() {...}.tabBar(this.tabBuilder('发现', 1))TabContent() {...}.tabBar(this.tabBuilder('推荐', 2))TabContent() {...}.tabBar(this.tabBuilder('我的', 3))}.animationDuration(0).backgroundColor('#F1F3F5').onChange((index: number) => {this.currentIndex = index})}.width('100%')}
}

开发应用沉浸式效果

概述

典型应用全屏窗口UI元素包括状态栏、应用界面和底部导航条，其中状态栏和导航条，通常在沉浸式布局下称为避让区；避让区之外的区域称为安全区。开发应用沉浸式效果主要指通过调整状态栏、应用界面和导航条的显示效果来减少状态栏导航条等系统界面的突兀感，从而使用户获得最佳的UI体验。

开发应用沉浸式效果主要要考虑如下几个设计要素：

• UI元素避让处理：导航条底部区域可以响应点击事件，除此之外的可交互UI元素和应用关键信息不建议放到导航条区域。状态栏显示系统信息，如果与界面元素有冲突，需要考虑避让状态栏。
• 沉浸式效果处理：将状态栏和导航条颜色与界面元素颜色相匹配，不出现明显的突兀感。

针对上面的设计要求，可以通过如下两种方式实现应用沉浸式效果：

• 窗口全屏布局方案
  调整布局系统为全屏布局，界面元素延伸到状态栏和导航条区域实现沉浸式效果。当不隐藏避让区时，可通过接口查询状态栏和导航条区域进行可交互元素避让处理，并设置状态栏或导航条的颜色等属性与界面元素匹配。当隐藏避让区时，通过对应接口设置全屏布局即可。
• 组件安全区方案
  布局系统保持安全区内布局，然后通过接口延伸绘制内容（如背景色，背景图）到状态栏和导航条区域实现沉浸式效果。

窗口全屏布局方案

窗口全屏布局方案主要涉及以下应用扩展布局，全屏显示，不隐藏避让区和应用扩展布局，隐藏避让区两个应用场景。

应用扩展布局，全屏显示，不隐藏避让区

可以通过调用窗口强制全屏布局接口setWindowLayoutFullScreen() 实现界面元素延伸到状态栏和导航条；然后通过接口getWindowAvoidArea()和on(‘avoidAreaChange’) 获取并动态监听避让区域的变更信息，页面布局根据避让区域信息进行动态调整；设置状态栏或导航条的颜色等属性与界面元素进行匹配。

1. 调用setWindowLayoutFullScreen()接口设置窗口全屏。

   // EntryAbility.ets
   import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
   import { window } from '@kit.ArkUI';
   import { BusinessError } from '@kit.BasicServicesKit';export default class EntryAbility extends UIAbility {// ...onWindowStageCreate(windowStage: window.WindowStage): void {windowStage.loadContent('pages/Index', (err, data) => {if (err.code) {return;}let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口// 1. 设置窗口全屏let isLayoutFullScreen = true;windowClass.setWindowLayoutFullScreen(isLayoutFullScreen).then(() => {console.info('Succeeded in setting the window layout to full-screen mode.');}).catch((err: BusinessError) => {console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));});// 进行后续步骤2-3中的操作});}
   }
   

2. 使用getWindowAvoidArea()接口获取当前布局遮挡区域（例如状态栏、导航条）。

   // EntryAbility.ets
   // 2. 获取布局避让遮挡的区域
   let type = window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR; // 以导航条避让为例
   let avoidArea = windowClass.getWindowAvoidArea(type);
   let bottomRectHeight = avoidArea.bottomRect.height; // 获取到导航条区域的高度
   AppStorage.setOrCreate('bottomRectHeight', bottomRectHeight);type = window.AvoidAreaType.TYPE_SYSTEM; // 以状态栏避让为例
   avoidArea = windowClass.getWindowAvoidArea(type);
   let topRectHeight = avoidArea.topRect.height; // 获取状态栏区域高度     
   AppStorage.setOrCreate('topRectHeight', topRectHeight);
   

3. 注册监听函数，动态获取避让区域的实时数据。常见的触发避让区回调的场景如下：应用窗口在全屏模式、悬浮模式、分屏模式之间的切换；应用窗口旋转；多折叠设备在屏幕折叠态和展开态之间的切换；应用窗口在多设备之间的流转。

   // EntryAbility.ets
   // 3. 注册监听函数，动态获取避让区域数据
   windowClass.on('avoidAreaChange', (data) => {if (data.type === window.AvoidAreaType.TYPE_SYSTEM) {let topRectHeight = data.area.topRect.height;AppStorage.setOrCreate('topRectHeight', topRectHeight);} else if (data.type == window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR) {let bottomRectHeight = data.area.bottomRect.height;AppStorage.setOrCreate('bottomRectHeight', bottomRectHeight);}
   });
   

4. 布局中的UI元素需要避让状态栏和导航条，否则可能产生UI元素重叠等情况。

   说明
   避让区域存在大小为0的情况，当获取到的避让区域为0时，开发者需注意针对性处理适配此时的页面区域和布局，避免贴边、内容裁剪等问题，影响应用界面正常显示或美观性。

应用扩展布局，隐藏避让区

此场景下导航条会自动隐藏，适用于游戏、电影等应用场景。可以通过从底部上滑唤出导航条。

1. 调用setWindowLayoutFullScreen()接口设置窗口全屏。

   // EntryAbility.ets
   import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
   import { window } from '@kit.ArkUI';
   import { BusinessError } from '@kit.BasicServicesKit';export default class EntryAbility extends UIAbility {// ...onWindowStageCreate(windowStage: window.WindowStage): void {windowStage.loadContent('pages/Index', (err, data) => {if (err.code) {return;}let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口// 1. 设置窗口全屏let isLayoutFullScreen = true;windowClass.setWindowLayoutFullScreen(isLayoutFullScreen).then(() => {console.info('Succeeded in setting the window layout to full-screen mode.');}).catch((err: BusinessError) => {console.error(`Failed to set the window layout to full-screen mode. Code is ${err.code}, message is ${err.message}`);});// 进行后续步骤2中的状态栏和导航条的隐藏操作});}
   }
   

2. 调用setSpecificSystemBarEnabled() 接口设置状态栏和导航条的具体显示/隐藏状态，此场景下将其设置为隐藏

   // EntryAbility.ets
   // 2. 设置状态栏隐藏
   windowClass.setSpecificSystemBarEnabled('status', false).then(() => {console.info('Succeeded in setting the status bar to be invisible.');
   }).catch((err: BusinessError) => {console.error(`Failed to set the status bar to be invisible. Code is ${err.code}, message is ${err.message}`);
   });
   // 2. 设置导航条隐藏
   windowClass.setSpecificSystemBarEnabled('navigationIndicator', false).then(() => {console.info('Succeeded in setting the navigation indicator to be invisible.');
   }).catch((err: BusinessError) => {console.error(`Failed to set the navigation indicator to be invisible. Code is ${err.code}, message is ${err.message}`);
   });
   

3. 在界面中无需进行导航条避让操作。

   // Index.ets
   @Entry()
   @Component
   struct Index {build() {Row() {Column() {Row() {Text('ROW1').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW2').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW3').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW4').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW5').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW6').fontSize(40)}.backgroundColor(Color.Orange).padding(20)}.width('100%').height('100%').alignItems(HorizontalAlign.Center).justifyContent(FlexAlign.SpaceBetween).backgroundColor('#008000')}}
   }
   

组件安全区方案

应用未使用setWindowLayoutFullScreen() 接口设置窗口全屏布局时，默认使能组件安全区布局。
应用在默认情况下窗口背景绘制范围是全屏，但UI元素被限制在安全区内（自动排除状态栏和导航条）进行布局，来避免界面元素被状态栏和导航条遮盖。

针对状态栏和导航条颜色与界面元素颜色不匹配问题，可以通过如下两种方式实现沉浸式效果：

1. 状态栏和导航条颜色相同场景，可以通过设置窗口的背景色来实现沉浸式效果。窗口背景色可通过setWindowBackgroundColor() 进行设置。

   import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
   import { window } from '@kit.ArkUI';export default class EntryAbility extends UIAbility {// ...onWindowStageCreate(windowStage: window.WindowStage): void {windowStage.loadContent('pages/Index', (err, data) => {if (err.code) {return;}// 设置全窗颜色和应用元素颜色一致windowStage.getMainWindowSync().setWindowBackgroundColor('#008000');});}
   }
   

   界面状态栏和导航条颜色相同场景。

   // xxx.ets
   @Entry
   @Component
   struct Example {build() {Column() {Row() {Text('ROW1').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW2').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW3').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW4').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW5').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW6').fontSize(40)}.backgroundColor(Color.Orange).padding(20)}.width('100%').height('100%').alignItems(HorizontalAlign.Center).justifyContent(FlexAlign.SpaceBetween).backgroundColor('#008000')}
   }
   

   

2. 状态栏和导航条颜色不同时，可以使用expandSafeArea属性扩展安全区域属性进行调整。

   // xxx.ets
   @Entry
   @Component
   struct Example {build() {Column() {Row() {Text('Top Row').fontSize(40).textAlign(TextAlign.Center).width('100%')}.backgroundColor('#F08080')// 设置顶部绘制延伸到状态栏.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP])Row() {Text('ROW2').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW3').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW4').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW5').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('Bottom Row').fontSize(40).textAlign(TextAlign.Center).width('100%')}.backgroundColor(Color.Orange)// 设置底部绘制延伸到导航条.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])}.width('100%').height('100%').alignItems(HorizontalAlign.Center).backgroundColor('#008000').justifyContent(FlexAlign.SpaceBetween)}
   }
   

   

扩展安全区域属性原理

• 布局阶段按照安全区范围大小进行UI元素布局。
• 布局完成后查看设置了expandSafeArea 的组件边界（不包括margin）是否和安全区边界相交。
• 如果设置了expandSafeArea 的组件和安全区边界相交，根据expandSafeArea传递的属性则进一步扩大组件绘制区域大小覆盖状态栏、导航条这些非安全区域。
• 上述过程仅改变组件自身绘制大小，不进行二次布局，不影响子节点和兄弟节点的大小和位置。
• 子节点可以单独设置该属性，只需要自身边界和安全区域重合就可以延伸自身大小至非安全区域内，需要确保父组件未设置clip等裁切属性。
• 配置expandSafeArea属性组件进行绘制扩展时，需要关注组件不能配置固定宽高尺寸，百分比除外。

背景图和视频场景

设置背景图、视频控件大小为安全区域大小并配置expandSafeArea属性。

// xxx.ets
@Entry
@Component
struct SafeAreaExample1 {build() {Stack() {Image($r('app.media.bg')).height('100%').width('100%').expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]) // 图片组件的绘制区域扩展至状态栏和导航条。}.height('100%').width('100%')}
}

滚动类场景

要求需要List滚动类组件滚动过程中元素可以和导航条重合，滚动至底部时，元素在导航条上面需要避让。

由于expandSafeArea不改变子节点布局，因此，List等滚动类组件可以调用expandSafeArea，延伸List组件视图窗口大小而不改变ListItem内在布局。实现ListItem在滑动过程中显示在导航条下，但滚动至最后一个时显示在导航条上，示意图如下：
未适配时列表下方被导航条遮盖:

List配置expandSafeArea属性后的效果：

底部页签场景

要求页签背景色能够延伸到导航条区域，但页签内部可操作元素需要在导航条之上。

针对底部的页签部分，Navigation组件和Tabs组件默认实现了页签的延伸处理，开发者只需要保证Navigation和Tabs组件的底部边界和底部导航条重合即可。若开发者显式调用expandSafeArea接口，则安全区效果由expandSafeArea参数指定。

如果未使用上述组件而是采用自定义方式实现页签的场景，可以针对底部元素设置expandSafeArea属性实现底部元素的背景扩展。

图7 顶部和底部UI元素未设置和设置expandSafeArea属性效果对比

// xxx.ets
@Entry
@Component
struct VideoCreateComponent {build() {Column() {Row() {Text('Top Row').fontSize(40).textAlign(TextAlign.Center).width('100%')}.backgroundColor('#F08080')// 设置顶部绘制延伸到状态栏.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP])Row() {Text('ROW2').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW3').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW4').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('ROW5').fontSize(40)}.backgroundColor(Color.Orange).padding(20)Row() {Text('Bottom Row').fontSize(40).textAlign(TextAlign.Center).width('100%')}.backgroundColor(Color.Orange)// 设置底部绘制延伸到导航条.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])}.width('100%').height('100%').alignItems(HorizontalAlign.Center).justifyContent(FlexAlign.SpaceBetween).backgroundColor(Color.Green)}
}

图文场景

当状态栏元素和底部导航条元素不同时，无法单纯通过窗口背景色或者背景图组件延伸实现，此时需要对顶部元素和底部元素分别配置expandSafeArea属性，
顶部元素配置expandSafeArea([SafeAreaType.SYSTEM],[SafeAreaEdge.TOP])，
底部元素配置expandSafeArea([SafeAreaType.SYSTEM],[SafeAreaEdge.BOTTOM])。

@Entry
@Component
struct Index {build() {Swiper() {Column() {Image($r('app.media.start')).height('50%').width('100%')// 设置图片延伸到状态栏.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP])Column() {Text('HarmonyOS 第一课').fontSize(32).margin(30)Text('通过循序渐进的学习路径，无经验和有经验的开发者都可以掌握ArkTS语言声明式开发范式，体验更简洁、更友好的HarmonyOS应用开发旅程。').fontSize(20).margin(20)}.height('50%').width('100%').backgroundColor(Color.White)// 设置文本内容区背景延伸到导航栏.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])}}.width('100%').height('100%')// 关闭Swiper组件默认的裁切效果以便子节点可以绘制在Swiper外。.clip(false)}
}