鸿蒙 GridRow 与 GridCol 组件解析：响应式网格布局指南

本文链接：https://blog.youkuaiyun.com/hqy1989/article/details/148908654

一、引言：网格布局 —— 现代 UI 的结构化基石

在鸿蒙应用开发中，GridRow 与 GridCol 组件构成了构建高效网格布局的核心体系。作为线性布局的进阶方案，网格布局通过行列交织的结构化设计，将界面划分为规则的单元格，完美适配商品展示、功能矩阵、图片墙等多元素排列场景。与传统布局相比，网格系统具有以下显著优势：

视觉秩序感：通过标准化的单元格排列，建立清晰的视觉层级
响应式能力：动态适应不同屏幕尺寸，自动调整行列分布
开发高效性：减少布局嵌套，通过声明式语法快速实现复杂排列

本文将系统解析这两个组件的核心机制、属性配置与实战技巧，助你掌握现代化界面布局的关键技术。

二、核心概念与基础架构

2.1 网格布局的设计哲学

GridRow 与 GridCol 基于二维坐标系设计：

GridRow：水平方向（行）布局容器，管理子组件的列分布
GridCol：垂直方向（列）布局容器，管理子组件的行分布
协同工作：两者嵌套使用可构建完整网格体系，类似表格的行列结构

这种设计使开发者能够以 "单元格" 为单位规划界面，通过统一的间距、尺寸规则建立视觉一致性，尤其适合需要展示大量同类数据的场景。

2.2 基础语法与最简实现

GridRow 基础示例

// xxx.ets
@Entry
@Component
struct GridRowExample {
  @State bgColors: Color[] = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown]
  @State currentBp: string = 'unknown'


  build() {
    Column() {
      GridRow({
        columns: 5,
        gutter: { x: 5, y: 10 },
        breakpoints: { value: ["400vp", "600vp", "800vp"],
          reference: BreakpointsReference.WindowSize },
        direction: GridRowDirection.Row
      }) {
        ForEach(this.bgColors, (color: Color) => {
          GridCol({ span: { xs: 1, sm: 2, md: 3, lg: 4 }, offset: 0, order: 0 }) {
            Row().width("100%").height("20vp")
          }.borderColor(color).borderWidth(2)
        })
      }.width("100%").height("100%")
      .onBreakpointChange((breakpoint) => {
        this.currentBp = breakpoint
      })
    }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200)
    .border({ color: '#880606', width: 2 })
  }
}

运行逻辑：GridRow 自动将子组件按水平方向排列，根据容器宽度与子组件尺寸计算列数与列宽。

GridCol 基础示例

// xxx.ets
@Entry
@Component
struct GridColExample {
  @State bgColors: Color[] =
    [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Pink, Color.Grey, Color.Blue, Color.Brown]
  @State currentBp: string = 'unknown'


  build() {
    Column() {
      GridRow({
        columns: 5,
        gutter: { x: 5, y: 10 },
        breakpoints: {
          value: ["400vp", "600vp", "800vp"],
          reference: BreakpointsReference.WindowSize
        },
        direction: GridRowDirection.Row
      }) {
        ForEach(this.bgColors, (color: Color) => {
          GridCol({
            span: { xs: 1, sm: 2, md: 3, lg: 4 },
            offset: 0,
            order: 0
          }) {
            Row().width("100%").height("20vp")
          }.borderColor(color).borderWidth(2)
        })
      }.width("100%").height("100%")
      .onBreakpointChange((breakpoint) => {
        this.currentBp = breakpoint
      })
    }.width('80%').margin({ left: 10, top: 5, bottom: 5 }).height(200)
    .border({ color: '#880606', width: 2 })
  }
}

布局特点：GridCol 沿垂直方向排列子组件，支持通过 rows 属性显式设置行数。

GridRow：栅格容器组件，仅可以和栅格子组件(GridCol)在栅格布局场景中使用。
GridCol：栅格子组件，必须作为栅格容器组件(GridRow)的子组件使用。

三、核心属性详解：精准布局控制

3.1 GridRow 关键属性

属性名	类型	必填	功能描述
columns	number \| GridRowColumnOption	否	设置布局列数。取值为大于0的整数。 - API version 20之前：默认值为12。 - API version 20及之后：默认值为{ xs: 2, sm: 4, md: 8, lg: 12, xl: 12, xxl: 12 }。
gutter	Length \| GutterOption	否	栅格布局间距。默认值：0
breakpoints	BreakPoints	否	设置断点值的断点数列以及基于窗口或容器尺寸的相应参照。默认值： { value: ["320vp", "600vp", "840vp"], reference: BreakpointsReference.WindowSize }
direction	GridRowDirection	否	栅格布局排列方向。默认值：GridRowDirection.Row

进阶用法示例：

    GridRow({
      columns: 5, // 列数
      gutter: { x: 5, y: 10 }, // 列间距
      breakpoints: {
        value: ["400vp", "600vp", "800vp"], // 响应式断点
        reference: BreakpointsReference.WindowSize // 参考窗口大小
      },
      direction: GridRowDirection.Row // 排列方向
    }) {
      // 子组件...
    }

3.2 GridCol 关键属性

属性名	类型	必填	功能描述
span	number \| GridColColumnOption	否	栅格子组件占用栅格容器组件的列数。span为0表示该元素不参与布局计算，即不会被渲染。取值为非负整数，默认值为1。
offset	number \| GridColColumnOption	否	栅格子组件相对于原本位置偏移的列数。取值为非负整数，默认值为0。
order	number \| GridColColumnOption	否	元素的序号，根据栅格子组件的序号，从小到大对栅格子组件做排序。取值为非负整数，默认值为0。说明：当子组件不设置order或者设置相同的order，子组件按照代码顺序展示。当子组件部分设置order，部分不设置order时，未设置order的子组件依次排序靠前，设置了order的子组件按照数值从小到大排列。

属性名

类型

必填

功能描述

span

number | GridColColumnOption

否

栅格子组件占用栅格容器组件的列数。span为0表示该元素不参与布局计算，即不会被渲染。

取值为非负整数，默认值为1。

offset

number | GridColColumnOption

否

栅格子组件相对于原本位置偏移的列数。

取值为非负整数，默认值为0。

order

number | GridColColumnOption

否

元素的序号，根据栅格子组件的序号，从小到大对栅格子组件做排序。

取值为非负整数，默认值为0。

说明：

当子组件不设置order或者设置相同的order，子组件按照代码顺序展示。

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

典型配置示例：

      GridCol({
        span: {
          xs: 1,
          sm: 2,
          md: 3,
          lg: 4
        }, // 列数
        offset: 0, // 偏移量
        order: 0 // 排序
      }) {
        // 子组件...
      }

3.3 动态布局管理

通过数据绑定与循环渲染实现动态网格：

@Entry
@Component
struct DynamicGridDemo {
  @State items: string[] = ['数据项1', '数据项2', '数据项3', '数据项4', '数据项5']

  build() {
    GridRow({ columns: 2, gutter: { x: 12, y: 12 } }) {
      ForEach(this.items, (item: string, index: number) => {
        Text(item)
          .width(100)
          .height(100)
          .backgroundColor('#E0E0E0')
          .textAlign(TextAlign.Center)
          .id(`item-${index}`) // 建议为动态组件设置唯一ID
      })
    }
    .width('100%')
    .padding(16)
  }
}

动态更新机制：当 items 数组变化时，GridRow 会自动重新计算布局，更新子组件排列。

四、实战案例：典型场景实现

4.1 电商商品网格展示

// 商品数据模型
interface Product {
  id: number
  name: string
  price: number
  image: Resource
}

@Entry
@Component
struct ProductGridDemo {
  /**
   * 商品数据列表
   */
  @State products: Product[] = [
    {
      id: 1,
      name: '无线耳机',
      price: 299.0,
      image: $r('app.media.headphone')
    },
    {
      id: 2,
      name: '智能手表',
      price: 1299.0,
      image: $r('app.media.watch')
    },
    {
      id: 3,
      name: '运动手环',
      price: 199.0,
      image: $r('app.media.bracelet')
    },
    {
      id: 4,
      name: '蓝牙音箱',
      price: 399.0,
      image: $r('app.media.speaker')
    }
  ]

  build() {
    GridRow({
      columns: 2, // 每行2列
      gutter: {
        x: 20, // 行间距20vp
        y: 16, // 列间距16vp
      },
      direction: GridRowDirection.Row // 行布局

    }) {
      ForEach(this.products, (product: Product) => {
        GridCol() {
          Row() {
            Image(product.image)
              .width('100%')
              .height(180)
              .objectFit(ImageFit.Contain)
              .borderRadius(8)

            Text(product.name)
              .fontSize(14)
              .margin({ top: 8, bottom: 4 })
              .fontColor('#333')

            Text(`¥${product.price}`)
              .fontSize(16)
              .fontWeight(FontWeight.Bold)
              .fontColor(Color.Red)
          }
        }
        .width('100%')
        .backgroundColor(Color.White)
        .borderRadius(12)
        .shadow({
          radius: 4,
          color: '#0000001A',
          offsetX: 2,
          offsetY: 2
        })
        .onClick(() => {
          console.log(`点击商品: ${product.name}`)
          // 跳转详情页逻辑
        })
      })
    }
    .width('100%')
    .padding({
      top: 16,
      bottom: 40,
      left: 16,
      right: 16
    })
  }
}

布局要点：

使用 GridRow 控制列数与间距
GridCol 管理单个商品卡片的垂直结构
响应式设计：通过百分比宽度适配不同屏幕

4.2 多功能仪表盘布局

// 功能项数据模型
interface FunctionItem {
  icon: Resource
  name: string
  desc: string
}

@Entry
@Component
struct DashboardDemo {
  /**
   * 功能项列表
   */
  private functions: FunctionItem[] = [
    { icon: $r('app.media.icon_setting'), name: '系统设置', desc: '设备基础设置' },
    { icon: $r('app.media.icon_weather'), name: '天气查询', desc: '实时天气信息' },
    { icon: $r('app.media.icon_calendar'), name: '日程管理', desc: '行程安排提醒' },
    { icon: $r('app.media.icon_note'), name: '备忘录', desc: '记录重要事项' },
    { icon: $r('app.media.icon_health'), name: '健康监测', desc: '身体数据记录' },
    { icon: $r('app.media.icon_news'), name: '资讯阅读', desc: '热点新闻推送' }
  ]

  build() {
    GridRow({
      columns: 3, // 3列布局
      gutter: {
        x: 20, // 列间距20vp
        y: 20, // 行间距20vp
      },
      direction: GridRowDirection.Row // 行布局
    }) {
      ForEach(this.functions, (item:FunctionItem) => {
        GridCol() {
          Row() {
            Image(item.icon)
              .width(32)
              .aspectRatio(1)
              .margin({
                bottom: 8
              })

            Text(item.name)
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
              .margin({
                bottom: 4
              })

            Text(item.desc)
              .fontSize(12)
              .textAlign(TextAlign.Center)
              .width(100)
              .lineHeight(16)
          }
        }
        .width(120)
        .height(140)
        .backgroundColor('#F8F8F8')
        .borderRadius(12)
        .shadow({
          radius: 3,
          color: '#0000000D',
          offsetX: 1,
          offsetY: 1
        })
        .onClick(() => {
          console.log(`打开功能: ${item.name}`)
          // 功能跳转逻辑
        })
      })
    }
    .width('100%')
    .padding(24)
  }
}

设计亮点：

统一的单元格尺寸与间距，建立视觉秩序
图标 + 文字的标准结构，提升识别效率
卡片式设计配合阴影效果，增强立体感

五、工程实践最佳指南

5.1 性能优化策略

布局扁平化：

// 优化前（深层嵌套）
GridRow() {
  GridCol() { /*...*/ }
}

// 优化后（直接布局）
GridRow({ columns: 2 }) { /*...*/ }

动态更新优化：

// 对静态数据使用cache()
ForEach(this.items, (item) => {
  Text(item).cache() // 避免重复渲染
})

尺寸预计算：

    GridRow({
      columns: 3,
      gutter: 16,
    }) { /*...*/ }

5.2 多端适配方案

@Entry
@Component
struct AdaptiveGridDemo {
  build() {
    GridRow({ 
      // 根据设备类型动态设置列数
      columns: DeviceType.isPhone() ? 2 : 3,
      gutter:16
    }) {
      // 子组件...
    }
    .width('100%')
    .padding(16)
  }
}

5.3 常见问题解决方案

问题场景	解决方案
子组件溢出	设置`maxWidth/maxHeight`或包裹`Scroll`组件
间距异常	检查`rowGap/columnGap`是否与父容器冲突，优先使用组件自身间距属性
动态更新卡顿	对大数据集使用`LazyForEach`延迟加载不可见项
多端显示不一致	通过`DeviceType`枚举动态调整`columns/rows`及尺寸