输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
指南与API参考指南应用框架ArkUI（方舟UI框架）UI开发 (ArkTS声明式开发范式)列表与网格创建网格 (Grid/GridItem)

创建网格 (Grid/GridItem)

更新时间: 2026-09-09 06:54
复制页面
本文导读
展开章节

概述

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

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前面的数值大小，用于计算该行或列在网格布局对应方向上的尺寸占比，最终决定该行的高度或列的宽度。

图3 行列数量占比示例

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

只要将rowsTemplate设置为'1fr 1fr 1fr'，同时将columnsTemplate设置为'1fr 2fr 1fr'，即可实现上述网格布局。

收起
自动换行
深色代码主题
复制
  1. Grid() {
  2.   // ···
  3. }
  4. .rowsTemplate('1fr 1fr 1fr')
  5. .columnsTemplate('1fr 2fr 1fr')
GridLayout.ets
说明

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

设置子组件所占行列数

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

图4 不均匀网格布局

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

图5 计算器

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

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

收起
自动换行
深色代码主题
复制
  1. layoutOptions: GridLayoutOptions = {
  2.   regularSize: [1, 1],
  3.   onGetRectByIndex: (index: number) => {
  4.   // ···
  5.     if (index == key1) { // key1是“0”按键对应的index
  6.       return [6, 0, 1, 2];
  7.     } else if (index == key2) { // key2是“=”按键对应的index
  8.       return [5, 3, 2, 1];
  9.     }
  10.     // ···
  11.     // 这里需要根据具体布局返回其他item的位置
  12.   }
  13. }
  14. // ···
  15. Grid(undefined, this.layoutOptions) {
  16.   // ···
  17. }
  18. .columnsTemplate('1fr 1fr 1fr 1fr')
  19. .rowsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr')
GridCalculator.ets

设置主轴方向

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

图6 主轴方向示意图

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

收起
自动换行
深色代码主题
复制
  1. Grid() {
  2.   // ···
  3. }
  4. .maxCount(3)
  5. .layoutDirection(GridDirection.Row)
GridLayout.ets
说明
  • layoutDirection属性仅在不设置rowsTemplate和columnsTemplate时生效，此时元素在layoutDirection方向上排列。
  • 仅设置rowsTemplate时，Grid主轴为水平方向，交叉轴为垂直方向。
  • 仅设置columnsTemplate时，Grid主轴为垂直方向，交叉轴为水平方向。

在网格布局中显示数据

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

图7 通用办公服务

Grid组件可以通过二维布局的方式显示一组GridItem子组件。

收起
自动换行
深色代码主题
复制
  1. Grid() {
  2.   GridItem() {
  3.     // app.string.Meeting资源文件中的value值为‘会议’
  4.     Text($r('app.string.Meeting'))
  5.     // ...
  6.   }
  7. 

  8.   GridItem() {
  9.     // app.string.Check_in资源文件中的value值为‘签到’
  10.     Text($r('app.string.Check_in'))
  11.     // ...
  12.   }
  13. 

  14.   GridItem() {
  15.     // app.string.Voting资源文件中的value值为‘投票’
  16.     Text($r('app.string.Voting'))
  17.     // ...
  18.   }
  19. 

  20.   GridItem() {
  21.     // app.string.Printing资源文件中的value值为‘打印’
  22.     Text($r('app.string.Printing'))
  23.     // ...
  24.   }
  25. }
  26. // ...
  27. .rowsTemplate('1fr 1fr')
  28. .columnsTemplate('1fr 1fr')
DataInGrid.ets

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

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. export struct DataInGrid {
  4.   // ...
  5. 

  6.   @State services: Array<string> = [
  7.     // app.string.Meeting资源文件中的value值为‘会议’
  8.     this.context!.resourceManager.getStringSync($r('app.string.Meeting').id),
  9.     // app.string.Check_in资源文件中的value值为‘签到’
  10.     this.context!.resourceManager.getStringSync($r('app.string.Check_in').id),
  11.     // app.string.Voting资源文件中的value值为‘投票’
  12.     this.context!.resourceManager.getStringSync($r('app.string.Voting').id),
  13.     // app.string.Printing资源文件中的value值为‘打印’
  14.     this.context!.resourceManager.getStringSync($r('app.string.Printing').id)
  15.   ];
  16.   // ...
  17. 

  18.   build() {
  19.     // ...
  20.       Column() {
  21.         // ...
  22.           Grid() {
  23.             ForEach(this.services, (service: string) => {
  24.               GridItem() {
  25.                 Text(service)
  26.               }
  27.               // ...
  28.             }, (service: string): string => service)
  29.           }
  30.           .rowsTemplate(('1fr 1fr') as string)
  31.           .columnsTemplate(('1fr 1fr') as string)
  32.           // ...
  33.       }
  34.       // ...
  35.   }
  36. }
DataInGrid.ets

设置行列间距

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

图8 网格的行列间距

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

收起
自动换行
深色代码主题
复制
  1. Grid() {
  2.   // ···
  3. }
  4. .columnsGap(10)
  5. .rowsGap(15)
GridColumnsGap.ets

构建可滚动的网格布局

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

图9 横向可滚动网格布局

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

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

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. export struct ScrollableGrid {
  4.   // ...
  5.   @State services: Array<string> = [
  6.     // 请将$r('app.string.Live_Streaming')替换为实际资源文件，在本示例中该资源文件的value值为"直播"
  7.     this.context!.resourceManager.getStringSync($r('app.string.Live_Streaming').id),
  8.     // 请将$r('app.string.Imported')替换为实际资源文件，在本示例中该资源文件的value值为"进口"
  9.     this.context!.resourceManager.getStringSync($r('app.string.Imported').id)
  10.     ];
  11.   // ...
  12.   build() {
  13.     // ...
  14. 

  15.       Column({ space: 5 }) {
  16.         // ...
  17. 

  18.           Grid() {
  19.             ForEach(this.services, (service: string, index: number) => {
  20.               GridItem() {
  21.                 // ...
  22.               }
  23.               .width('25%')
  24.               // ...
  25.             }, (service: string): string => service)
  26.           }
  27.           .rowsTemplate('1fr 1fr') // 只设置rowsTemplate属性，当内容超出Grid区域时，可水平滚动。
  28.           .rowsGap(15)
  29. 

  30.           // ...
  31.         }
  32.       }
  33.       // ...
  34. }
ScrollableGrid.ets

控制滚动位置

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

图10 日历翻页

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

收起
自动换行
深色代码主题
复制
  1. private scroller: Scroller = new Scroller();
ScrollPositionGrid.ets

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

收起
自动换行
深色代码主题
复制
  1. Column({ space: 5 }){
  2.   Grid(this.scroller) {
  3.     // ...
  4.   }
  5.   .columnsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr')
  6.   // ...
  7.   Row({ space: 20 }) {
  8.     // 请将$r('app.string.Previous_Page')替换为实际资源文件，在本示例中该资源文件的value值为"上一页"
  9.     Button($r('app.string.Previous_Page'))
  10.       .onClick(() => {
  11.         this.scroller.scrollPage({
  12.           next: false
  13.         });
  14.       })
  15.     // 请将$r('app.string.Next_page')替换为实际资源文件，在本示例中该资源文件的value值为"下一页"
  16.     Button($r('app.string.Next_page'))
  17.       .onClick(() => {
  18.         this.scroller.scrollPage({
  19.           next: true
  20.         });
  21.       })
  22.   }
  23. }
GridSideToSide.ets

添加外置滚动条

网格组件Grid可与ScrollBar组件配合使用，为网格添加外置滚动条。两者通过绑定同一个Scroller滚动控制器对象实现联动。

  1. 首先，需要创建一个Scroller类型的对象gridScroller。

    收起
    自动换行
    深色代码主题
    复制
    1. private gridScroller: Scroller = new Scroller();
    GridScrollbar.ets

  2. 然后，通过scroller参数绑定滚动控制器。

    收起
    自动换行
    深色代码主题
    复制
    1. // gridScroller初始化Grid组件的scroller参数，绑定gridScroller与网格。
    2. Grid( this.gridScroller) {
    3. // ···
    4. }
    GridScrollbar.ets

  3. 最后，滚动条通过scroller参数绑定滚动控制器。

    收起
    自动换行
    深色代码主题
    复制
    1. // gridScroller初始化ScrollBar组件的scroller参数，绑定gridScroller与滚动条。
    2. ScrollBar({ scroller: this.gridScroller })
    GridScrollbar.ets

图11 网格的外置滚动条

说明

手指滑动多选

从API版本26.0.0开始，Grid支持在编辑模式下实现手指滑动多选能力。进入编辑模式后，用户可以通过手指滑动经过多个GridItem，批量选择或取消选择网格项。应用可以在GridItem上设置是否允许被选择，并根据回调记录已选择的网格项。该能力适用于相册、文件管理、视频列表等需要连续批量选择网格项的场景。

Grid手指滑动多选示例效果图

设置编辑模式

通过enableEditMode设置是否进入编辑模式。设置为true，Grid进入编辑模式，用户可以单指滑动经过多个GridItem进行批量选择或取消选择；设置为false，Grid退出编辑模式。通过onEditModeChange监听编辑模式变化，将系统返回、侧滑返回或双指滑动触发的编辑模式变化同步到业务状态。

通过editModeOptions配置编辑模式下的多选行为。editModeOptions中有两个滑动多选相关参数，分别是useDefaultMultiSelectStyle和enableTwoFingerMultiSelect，默认值均为true。前者控制是否显示GridItem右下角的系统复选框，后者控制是否允许用户通过双指滑动自动进入编辑模式并进行多选。开发者需要自定义样式时，可将useDefaultMultiSelectStyle设置为false。开发者需要关闭双指滑动自动进入编辑模式时，可将enableTwoFingerMultiSelect设置为false。

收起
自动换行
深色代码主题
复制
  1. Grid() {
  2.   // ...
  3. }
  4. .enableEditMode(this.enableEditMode)
  5. .onEditModeChange((enabled: boolean) => {
  6.   this.setEditMode(enabled);
  7. })
  8. .editModeOptions({ useDefaultMultiSelectStyle: true, enableTwoFingerMultiSelect: true })
GridSwipeSelect.ets

记录网格项选择结果

在GridItem上配置selectable、selected和onSelect。selectable用于设置网格项是否允许被选择，selected用于设置网格项当前是否被选中。滑动多选过程中，组件会触发onSelect回调，应用可以在回调中记录每个网格项的最新选择结果。

收起
自动换行
深色代码主题
复制
  1. GridItem() {
  2.   this.GridCard(item, index)
  3. }
  4. .selectable(true)
  5. .selected(this.isSelected(item.id))
  6. .onSelect((selected: boolean) => {
  7.   this.updateSelected(item.id, selected);
  8. })
GridSwipeSelect.ets
说明
  • 建议使用网格项数据中不会随位置变化的唯一标识（例如文件ID）记录选择结果，不建议仅使用当前下标，避免动态增删数据后选中项错位。
  • 当业务需要在退出编辑模式后保留选择结果时，可在onEditModeChange回调中保存选择结果。
  • 使用LazyForEach时，数据源发生变化后应通过DataChangeListener通知组件刷新，确保滑动多选过程中网格项状态与数据源一致。

性能优化

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

关于按需加载优化的具体实现可参考数据懒加载章节中的示例。

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

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

收起
自动换行
深色代码主题
复制
  1. Grid() {
  2.   LazyForEach(this.dataSource, () => {
  3.     GridItem() {
  4.     }
  5.   })
  6. }
  7. .cachedCount(3)
LongGrid.ets
说明

cachedCount的增加会增大UI的CPU、内存开销。使用时需要根据实际情况，综合性能和用户体验进行调整。

示例代码

弧形列表 (ArcList)（圆形屏幕推荐使用）
Grid网格元素拖拽
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明