【共创季稿事节】HarmonyOS_栅格系统实战

祭曦念

289人浏览 · 2026-06-13 12:03:35

祭曦念 · 2026-06-13 12:03:35 发布

鸿蒙原生 ArkTS 布局方式之 GridRow 栅格系统实战（API 24）

一篇关于 HarmonyOS NEXT 12列栅格系统自适应布局的深度技术博客

一、前言

在 HarmonyOS NEXT 的 ArkUI 框架中，布局方式经历了从传统排版到现代栅格系统的演进。对于移动端、平板端乃至折叠屏等多尺寸设备，如何在代码层面高效、统一地完成自适应布局，是每个鸿蒙开发者必须面对的课题。尤其在折叠屏和跨形态设备兴起的当下，一个页面需要同时兼顾手机竖屏、手机横屏、平板竖屏、平板横屏以及桌面窗口等多种呈现形态，传统的手算百分比方式已完全无法胜任。

GridRow 栅格系统正是为解决这一课题而生。它借鉴了 Web 端成熟的 CSS Grid 思想，结合鸿蒙原生组件化能力，为 ArkTS 开发者提供了一套声明式、响应式、可嵌套的栅格布局方案。与传统的 LinearLayout 或 Flex 布局相比，GridRow 将「列」作为一等概念，开发者只需声明每列占据的网格份数，系统自动完成宽度计算与换行排列，从根源上消除了手算百分比的痛点。

不仅如此，GridRow 还深度集成了鸿蒙的断点系统。系统预定义了 xs、sm、md、lg、xl、xxl 共六个断点级别，每个断点对应一个屏幕宽度阈值。开发者可以为同一个 GridCol 在不同断点下指定不同的 span 值，从而实现真正的「一套代码，多屏适配」，无需编写任何条件判断语句。

本文将围绕一个完整的 12列栅格系统示例，从基础用法到高级特性，逐一拆解 GridRow + GridCol 的核心技术细节。文章中的所有代码均基于 HarmonyOS NEXT API 24 编写，已在 DevEco Studio 中通过编译验证。无论你是刚接触鸿蒙开发的新手，还是正在寻找更优雅布局方案的老手，本文都能为你提供切实可用的参考。

二、栅格系统设计思想

2.1 什么是栅格布局？

栅格布局（Grid Layout）将容器在水平方向划分为若干等宽的「列」，开发者通过指定元素跨越的列数（span）来控制其宽度。所有列的 span 之和等于总列数（通常是 12）时，元素自动填满一行；超过则换行。

这种布局思想源于平面设计中的网格系统，最早被应用于报刊排版，后来被 Bootstrap、Ant Design 等前端框架发扬光大。鸿蒙的 GridRow 本质上是对这一成熟设计模式的 ArkTS 实现。

与传统的绝对定位或 Flex 布局相比，栅格布局有几个关键优势：

宽度可预测：每一列的宽度是容器总宽度的 1/12，开发者永远知道一个 span=4 的区块占据 33.33% 的宽度，无需手算百分比。
排列自动化：无需手动管理换行，系统自动计算每行能容纳多少个 GridCol，超宽自动折行。
对齐零成本：通过 offset 属性即可实现居中、右对齐等常见需求，无需额外的容器或间距计算。
响应式原生：断点系统是栅格的一等特性，同一个 GridCol 在不同屏幕宽度下可自动切换 span 值。

2.2 为什么是12列？

12 是一个「高合成数」，拥有 1、2、3、4、6、12 共六个因子，能灵活组合出 1:1、1:2、1:3、2:1、3:1 等多种比例。这一特性使 12 列栅格成为业界最广泛采用的标准。

2.3 与其它布局方式的对比

布局方式	适用场景	自适应能力	嵌套复杂度	代码量
Stack (层叠)	层叠/定位	弱	低	少
Flex (弹性)	一维排列/均分	中	中	中
GridRow (栅格)	多列复杂版面	强	低	少
RelativeContainer (相对)	锚点对齐	中	高	多
绝对定位/百分比	简单比例	弱	低	多

结论：对于多列版面、响应式适配场景，GridRow 是效率最高、代码最简洁的选择。

三、核心 API 详解

3.1 GridRow 栅格容器

GridRow({
  columns: 12,           // 总列数，默认 12
  gutter: { x: 12, y: 12 },  // 列间距、行间距（vp）
  // breakpoints: { ... }     // 可选：自定义断点阈值
})

属性	类型	必填	说明
columns	number	否	划分的列数（默认 12）
gutter	{ x?: Length, y?: Length }	否	间距，x 为列间距，y 为行间距
breakpoints	BreakPoints	否	自定义断点阈值对象

3.2 GridCol 栅格列

GridCol({
  span: 4,             // 跨越的列数（必需）
  offset: 0,           // 向右偏移的列数（默认 0）
  // 响应式写法 —— 指定每个断点下的 span
  span: {
    xs: 12,   // 0 ~ 519 vp
    sm: 6,    // 520 ~ 839 vp
    md: 4,    // 840 ~ 999 vp
    lg: 3,    // 1000 ~ 1199 vp
    xl: 2,    // 1200 ~ 1599 vp
    xxl: 2,   // ≥ 1600 vp
  },
  // offset 同样支持响应式对象
  offset: {
    xs: 0,
    sm: 1,
    md: 2,
  }
})

3.3 断点系统（API 24）

系统预定义 6 个断点级别，单位为 vp（虚拟像素）：

断点	最小宽度	典型设备
xs	0 vp	小屏手机
sm	520 vp	大屏手机
md	840 vp	小屏平板 / 折叠屏展开
lg	1000 vp	平板横屏
xl	1200 vp	桌面窗口
xxl	1600 vp	大屏桌面 / 电视

开发者可通过 GridRow 的 breakpoints 属性自定义这些阈值。

四、项目环境与工程配置

在开始编写代码之前，需要确保你的开发环境满足以下条件：

DevEco Studio 版本：5.0.3.600 或更高
HarmonyOS SDK：API 24（HarmonyOS NEXT）
构建工具：hvigor 5.x+

4.1 创建项目

在 DevEco Studio 中创建一个「Empty Ability」模板项目，包名可自定义如 com.example.griddemos。项目创建完成后，目录结构大致如下：

AppScope/
  app.json5
entry/
  src/main/ets/
    entryability/EntryAbility.ets
    pages/Index.ets          ← 我们将修改此文件
  src/main/resources/
    base/element/string.json
    base/media/
  build-profile.json5
  oh-package.json5
oh_modules/
build-profile.json5
hvigor-config.json5

4.2 关于 import 的特殊说明

很多初次接触 GridRow 的开发者会被 import 问题困扰。这里需要明确一点：

在 HarmonyOS NEXT API 24 中，GridRow 和 GridCol 是系统内置组件，和 Column、Row、Text 一样，不需要手动 import。

如果你尝试以下写法，编译器会报错：

// ❌ 错误写法 —— API 24 没有导出这三个标识符
import { GridRow, GridCol, Gutter } from '@kit.ArkUI';

正确做法是直接使用，无需任何 import 语句。GridRow 首字母大写，说明它是一个组件而非普通函数。

此外，关于 Gutter 类型：它是 GridRow 内部使用的接口类型，同样不需要手动导入。直接在 gutter 属性中传入 { x: 12, y: 12 } 这样的对象字面量即可，系统会自动进行类型匹配。

4.3 代码文件入口

将以下完整的示例代码写入 entry/src/main/ets/pages/Index.ets，替换默认的 Hello World 模板。然后点击 Previewer 或使用 hvigorw assembleHap 命令编译运行。

五、五个实战示例详解

5.1 示例一：12 等分

目标： 将容器均匀分为 12 列，每列宽度相同。

GridRow({ columns: 12, gutter: { x: 12, y: 12 } }) {
  ForEach(range(12), (item: number, index: number) => {
    GridCol({ span: 1 }) {   // 每列占 1/12
      GridBlock({ span: 1, index, color: GRID_COLORS[index] })
    }
  })
}

效果分析： 每个 GridCol 的 span: 1 意味着它占据 12 列中的 1 列宽度。12 个这样的列水平排列，正好填满整行。gutter: { x: 12 } 在每列之间插入 12vp 的间距。

5.2 示例二：不规则分布

目标： 展示多种比例组合，验证栅格系统的灵活性。

第1行:  2列 + 3列 + 4列 + 3列 = 12列
第2行:  6列 + 6列            = 12列
第3行:  4列 + 4列 + 4列      = 12列

GridRow({ columns: 12, gutter: { x: 12, y: 12 } }) {
  // 第1行
  GridCol({ span: 2 }) { GridBlock({ span: 2, index: 0, color: '#2979FF' }) }
  GridCol({ span: 3 }) { GridBlock({ span: 3, index: 1, color: '#FF9100' }) }
  GridCol({ span: 4 }) { GridBlock({ span: 4, index: 2, color: '#00E676' }) }
  GridCol({ span: 3 }) { GridBlock({ span: 3, index: 3, color: '#FF4081' }) }

  // 第2行
  GridCol({ span: 6 }) { GridBlock({ span: 6, index: 4, color: '#651FFF' }) }
  GridCol({ span: 6 }) { GridBlock({ span: 6, index: 5, color: '#00BCD4' }) }

  // 第3行
  GridCol({ span: 4 }) { GridBlock({ span: 4, index: 6, color: '#795548' }) }
  GridCol({ span: 4 }) { GridBlock({ span: 4, index: 7, color: '#D500F9' }) }
  GridCol({ span: 4 }) { GridBlock({ span: 4, index: 8, color: '#FF1744' }) }
}

关键理解： GridRow 会按顺序排列 GridCol，当一行累计 span 达到 12 时自动换行。开发者无需手动管理换行。

5.3 示例三：嵌套栅格

目标： 演示 GridCol 内部嵌套子 GridRow，实现更复杂的版面。

布局示意：

┌───────────── 8列 ────────────┬── 4列 ──┐
│  ┌── 子4列 ──┬── 子4列 ──┐  │  右侧    │
│  │           │           │  │  4列     │
│  └───────────┴───────────┘  │          │
└─────────────────────────────┴──────────┘

GridRow({ columns: 12, gutter: { x: 12, y: 12 } }) {
  // 左侧 8列
  GridCol({ span: 8 }) {
    Column({ space: 8 }) {
      Text('左侧 8列（内部再分 4+4）')
      // 子栅格：外层8列 → 内部按8列重新划分
      GridRow({ columns: 8, gutter: { x: 8, y: 8 } }) {
        GridCol({ span: 4 }) { /* 子4列 */ }
        GridCol({ span: 4 }) { /* 子4列 */ }
      }
    }
    .width('100%').padding(8)
    .backgroundColor('#4682B4').borderRadius(8)
  }

  // 右侧 4列
  GridCol({ span: 4 }) { /* 右侧内容 */ }
}

注意： 子 GridRow 的 columns 要与外层 GridCol 的 span 值匹配。外层 span: 8 对应宽度 8/12，子层 columns: 8 表示在这 8 列宽度内再次 8 等分。

5.4 示例四：响应式断点

目标： 通过断点对象让同一组 GridCol 在不同屏幕宽度下自动调整列数。

GridCol({
  span: {
    xs: 12,     // 宽度 < 520vp  → 满宽
    sm: 6,      // 520~839vp     → 半宽
    md: 6,      // 840~999vp     → 半宽
    lg: 4,      // 1000~1199vp   → 1/3宽
    xl: 3,      // 1200~1599vp   → 1/4宽
    xxl: 2,     // ≥ 1600vp      → 1/6宽
  },
})

行为说明：

窗口宽度	每行可容纳的 D 区块数	每个 D 区块宽度
< 520 vp（手机竖屏）	1 个（满宽）	100%
520 ~ 839 vp（手机横屏）	2 个	50%
840 ~ 999 vp（平板竖屏）	2 个（D为满宽）	50% / 100%
1000 ~ 1199 vp（平板横屏）	3 个	33%
≥ 1200 vp（桌面）	4 个	25%
≥ 1600 vp（大屏桌面）	2 个或 6 个	50% / 16.7%

调试技巧： 在 DevEco Studio 的 Previewer 中拖拽窗口边框即可实时观察栅格响应变化。

5.5 示例五：偏移 offset

目标： 使用 offset 属性实现居中、右对齐等精确控制。

居中公式： offset = (总列数 - span) / 2

// 居中对齐：span=8，offset=(12-8)/2=2
GridCol({ span: 8, offset: 2 }) {
  /* 居中区块 */
}

// 右对齐：左侧 span=4，右侧 span=4，offset=12-4-4=4
GridCol({ span: 4 }) { /* 左 */ }
GridCol({ span: 4, offset: 4 }) { /* 右 */ }

应用场景：

表单标签与输入框的对齐
卡片列表的不对称布局
模态框在栅格中的精确定位
分页导航的左右分布

5.6 断点自定义配置

除了使用系统默认的六个断点阈值之外，GridRow 还允许开发者通过 breakpoints 属性自定义断点。这在项目有特殊适配要求时非常有用。

GridRow({
  columns: 12,
  gutter: { x: 12, y: 12 },
  breakpoints: {
    xs: 0,     // 默认 0
    sm: 400,   // 改为 400 vp（默认 520）
    md: 700,   // 改为 700 vp（默认 840）
    lg: 1000,  // 默认 1000
    xl: 1300,  // 改为 1300 vp（默认 1200）
    xxl: 1700, // 改为 1700 vp（默认 1600）
  }
}) {
  GridCol({
    span: {
      xs: 12,   // < 400 vp → 满宽
      sm: 6,    // 400 ~ 699 vp → 半宽
      md: 4,    // 700 ~ 999 vp → 三分之一
      lg: 3,    // 1000 ~ 1299 vp → 四分之一
      xl: 2,    // 1300 ~ 1699 vp → 六分之一
      xxl: 2,   // ≥ 1700 vp → 六分之一
    }
  }) {
    // 内容
  }
}

自定义断点的注意事项：

所有断点值必须按升序排列，从 xs 到 xxl 依次增大。
断点值的单位是 vp（虚拟像素），与 ArkUI 中的其他尺寸单位一致。
自定义断点会覆盖系统默认值，未指定的断点仍使用系统默认值。
建议在项目根组件的 GridRow 中统一设置断点，保持全局一致。

六、常见编译错误与避坑指南

6.1 误导入 GridRow / GridCol

错误：

Module '"@kit.ArkUI"' has no exported member 'GridRow'.

原因： API 24 中 GridRow、GridCol 是内置组件，不需要 import。

解决： 删除 import { GridRow, GridCol } from '@kit.ArkUI';

6.2 Color 枚举值不存在

错误：

Property 'Indigo' does not exist on type 'typeof Color'.

原因： Color 枚举只包含基础颜色（Red、Orange、Yellow、Green、Blue、Pink、Grey、Brown、Black、White 等），不包含 Indigo、Violet、Cyan、Purple、DarkGreen。

解决： 改用十六进制字符串 '#651FFF'，类型标注为 ResourceColor。

6.3 对象字面量必须匹配显式类型

错误：

Object literal must correspond to some explicitly declared class or interface.

原因： ArkTS 对对象字面量的类型检查比 TypeScript 更严格。当系统无法推断其类型时，会报此错。

常见触发场景：

场景	错误写法	正确写法
gutter 类型	`gutter: { x: 12, y: 12 } as Gutter`	`gutter: { x: 12, y: 12 }`（去掉 as）
span 响应式对象	`span: { xs: 12, sm: 6 }`	不变，但需确保 GridCol 类型被正确识别
自定义类型入参	任意对象字面量	提取为 const 常量并标注类型

解决： 首先确认 GridRow / GridCol 已正确识别（参考 6.1），然后去掉 as Gutter、as BreakPoints 等强制转换。

6.4 new Array(n) 在 ArkTS 中受限

错误（或编译警告）：

ArkTS 不支持带单个数字参数的 Array 构造函数

原因： ArkTS 禁用了 new Array(n) 创建稀疏数组的写法。

解决： 改用循环或工具函数：

// ❌ 不支持
ForEach(new Array<number>(12).fill(0), ...)

// ✅ 推荐
function range(n: number): number[] {
  const arr: number[] = [];
  for (let i = 0; i < n; i++) arr.push(i);
  return arr;
}
ForEach(range(12), ...)

七、性能优化建议

栅格布局虽然极大地简化了布局代码，但如果使用不当，也可能带来性能隐患。以下是几条在实践中总结的优化建议。

7.1 避免过度嵌套

栅格嵌套每加深一层，布局计算量指数增长。这是因为 GridRow 在每次布局时需要执行以下步骤：

遍历所有直接子 GridCol，收集它们的 span 和 offset 值。
计算每行可容纳的列数，确定换行位置。
根据 gutter 计算每列的实际像素宽度。
如果有嵌套的 GridRow，递归重复上述步骤。

建议：

最多嵌套 3 层，超过应考虑拆分为独立页面组件。
嵌套时子 GridRow 的 columns 值应与父 GridCol 的 span 匹配，避免内部栅格宽度与外层分配宽度不一致。
对于深嵌套场景，可以使用 Row + Column 组合替代局部深嵌套。

7.2 合理使用 gutter

gutter 是 GridRow 中控制间距的重要参数，使用不当会导致视觉偏差：

过大 gutter（如 { x: 48, y: 48 }）会导致内容区严重缩水，在大屏上尤其明显。
推荐值范围：{ x: 8 ~ 16, y: 8 ~ 16 }。
不同断点可设置不同 gutter。虽然 ArkTS 语法层面不支持直接在 gutter 属性上使用响应式对象，但你可以通过 @State 变量在断点变化时手动切换 gutter 值：

@Component
struct AdaptiveGrid {
  @State currentGutter: { x: number, y: number } = { x: 8, y: 8 };

  build() {
    // 根据断点手动调整 gutter（需配合 onBreakpointChange 或媒体查询）
    GridRow({
      columns: 12,
      gutter: this.currentGutter,
    }) {
      // GridCol 内容
    }
  }
}

7.3 懒加载与虚拟化

当 GridRow 中嵌套的 GridCol 数量较多时（如商品列表超过 50 项），直接使用 ForEach 会导致全部渲染，影响首帧加载速度。

使用 LazyForEach 替代 ForEach，让 GridRow 只渲染当前可见区域内的 GridCol：

class MyDataSource implements IDataSource {
  private dataArr: MyItemType[] = [];

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

  getData(index: number): MyItemType {
    return this.dataArr[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {}
  unregisterDataChangeListener(listener: DataChangeListener): void {}
}

build() {
  GridRow({ columns: 12 }) {
    LazyForEach(this.dataSource, (item: MyItemType, index: number) => {
      GridCol({ span: { xs: 12, sm: 6, md: 4 } }) {
        ProductCard({ product: item })
      }
    }, (item: MyItemType) => item.id)
  }
}

LazyForEach 配合 GridRow 使用时，系统会按需创建和销毁 GridCol 实例，显著降低内存占用和布局计算开销。

7.4 使用常量避免重复创建对象

在 ArkTS 中，对象字面量在每次 build 调用时都会重新创建。对于 gridConfig、breakpoints 等不会变化的配置，提取为类成员常量，避免重复分配：

@Component
struct OptimizedGrid {
  // 提取为常量，避免每次 build 重新创建对象字面量
  private readonly gridGutter: Record<string, number> = { x: 12, y: 12 };

  build() {
    GridRow({ columns: 12, gutter: this.gridGutter }) {
      GridCol({ span: 6 }) { /* ... */ }
      GridCol({ span: 6 }) { /* ... */ }
    }
  }
}

注意：在 ArkTS 中，如果对象字面量作为组件参数传入，编译器可能会报 arkts-no-untyped-obj-literals 错误。此时需要提取为具名常量并使用 Record<string, number> 进行类型标注。

八、与其它框架栅格的对比

特性	HarmonyOS GridRow	CSS Grid	Flutter GridView	Android GridLayout
声明式语法	✅ 原生 ArkTS	✅ CSS	✅ Dart Widget	❌ XML
响应式断点	✅ 内置 6 级	✅ CSS Media Query	❌ 需手动	❌ 需资源限定
嵌套支持	✅ 零成本	✅	✅	✅
offset 偏移	✅ GridCol 属性	✅ grid-column-start	❌	✅ layout_column
间距 gutter	✅ 双向	✅ gap	✅ SliverGridDelegate	❌ margin
容器总列数	✅ 可配置	✅ 可配置	✅ 可配置	❌ 固定
自动换行	✅	✅	✅	❌ 需手动
自学成本	低	中	中	高

综合评价： GridRow 的语法简洁度与 CSS Grid 相当，但得益于鸿蒙 ArkTS 编译器的静态类型检查，在开发时即可捕获大部分类型错误。对于鸿蒙原生应用开发者，GridRow 是构建多列版面的最优路径。

九、典型应用场景

9.1 商品列表 / 卡片墙

GridRow({ columns: 12, gutter: { x: 12, y: 16 } }) {
  ForEach(this.products, (item: Product) => {
    GridCol({ span: { xs: 12, sm: 6, md: 4, lg: 3 } }) {
      ProductCard({ product: item })
    }
  })
}

效果：手机上一列，平板两列，桌面四列。

9.2 后台管理系统仪表盘

GridRow({ columns: 12, gutter: { x: 16, y: 16 } }) {
  GridCol({ span: { xs: 12, md: 8 } }) { /* 主图表区 */ }
  GridCol({ span: { xs: 12, md: 4 } }) { /* 侧边统计 */ }
  GridCol({ span: { xs: 12, sm: 6, md: 4 } }) { /* 卡片1 */ }
  GridCol({ span: { xs: 12, sm: 6, md: 4 } }) { /* 卡片2 */ }
  GridCol({ span: { xs: 12, sm: 6, md: 4 } }) { /* 卡片3 */ }
  GridCol({ span: { xs: 12, sm: 6, md: 4 } }) { /* 卡片4 */ }
}

9.3 图文混排内容页

GridRow({ columns: 12, gutter: { x: 24 } }) {
  GridCol({ span: { xs: 12, md: 8 } }) {
    // 文章正文区
  }
  GridCol({ span: { xs: 12, md: 4 } }) {
    // 目录 / 广告位
  }
}

十、总结

GridRow 栅格系统是 HarmonyOS NEXT ArkUI 框架中最重要的布局工具之一。本文从实际代码出发，覆盖了以下核心知识点：

基础用法 — GridRow 容器 + GridCol 列的 span 控制宽度
间距控制 — gutter 双方向间距
换行规则 — 超 12 列自动换行
偏移定位 — offset 属性实现精确对齐
嵌套系统 — GridCol 内嵌子 GridRow
响应式断点 — xs/sm/md/lg/xl/xxl 六级别自适应
实战避坑 — 常用编译错误及解决方案

掌握这些知识后，你可以用 GridRow 替代大部分手算百分比宽度的场景，让布局代码更简洁、可维护性更好、跨设备适配更自然。

10.1 关键要点速查

// 一行代码完成响应式布局核心声明
GridRow({ columns: 12, gutter: { x: 12, y: 12 } }) {
  GridCol({ span: { xs: 12, sm: 6, md: 4, lg: 3 } }) {
    // 内容自动响应
  }
}

10.2 学习路线建议

先掌握 span 定宽 → 再学习 offset 偏移
先写 固定列数 → 再引入 响应式断点
先单层 GridRow → 再尝试嵌套
先在 Previewer 调试 → 再上真机验证

本文基于 HarmonyOS NEXT API 24 编写，代码已在 DevEco Studio 中通过编译验证。
示例完整源码可通过 entry/src/main/ets/pages/Index.ets 获取。

十一、常见问题与解答

Q1：GridRow 和 Row + Flex 有什么区别？什么时候该用哪个？

A： Row + Flex 适合一维排列场景，如水平导航栏、操作按钮组等，子元素数量不固定或不需要对齐到网格。GridRow 适合多列版面场景，如商品列表、仪表盘、文章排版等，需要子元素按照固定网格对齐。

简单判断标准：如果页面中所有列的宽度都能用 1/12、2/12、3/12 等分数精确描述，就用 GridRow；如果需要按内容自动伸缩，就用 Row + Flex。

Q2：GridCol 的 span 总和超过 12 会怎样？

A： GridRow 会自动换行。例如，连续放置 span 分别为 8、6、4 的三个 GridCol，前两个（8+6=14>12）会在第一行放一个 8，第二行放 6 和 4。开发者无需手动插入换行标记。

Q3：我可以混合使用 GridCol 和非 GridCol 子组件吗？

A： GridRow 的直接子组件必须是 GridCol。如果你需要在栅格容器中放置非 GridCol 的内容，可以将其放入一个 GridCol 内部。

Q4：Previewer 中看布局是正常的，真机上却错位了，可能是什么原因？

A：最常见的原因是断点差异。Previewer 窗口的宽度可能触发某个断点，而真机（尤其是折叠屏或平板）触发的是另一个断点。建议在真机调试时打开 DevEco Studio 的 Profiler 工具，查看当前触发的断点值。另外，检查 gutter 的单位是否正确，所有尺寸建议使用 vp 而非 px。

Q5：如何让 GridCol 中的内容垂直居中？

A： GridCol 本身是一个容器组件，在其中使用 Column 并设置 justifyContent(FlexAlign.Center) 即可：

GridCol({ span: 4 }) {
  Column() {
    Text('垂直居中').fontSize(16)
  }
  .width('100%')
  .height(100)
  .justifyContent(FlexAlign.Center)
  .alignItems(HorizontalAlign.Center)
}

Q6：ArkTS 中如何声明对象字面量的类型，避免编译错误？

A：对于简单的键值对对象，使用 Record<string, number> 或 Record<string, Object> 进行类型标注：

private gutterValue: Record<string, number> = { x: 12, y: 12 };
private spanValue: Record<string, number> = { xs: 12, sm: 6, md: 4 };

这样传入 GridRow 或 GridCol 的属性时，编译器就能正确匹配类型。

Q7：GridRow 和 GridCol 有 onClick 事件吗？

A： GridRow 和 GridCol 没有直接的 onClick 事件。但可以在 GridCol 内部放置一个带有 .onClick() 的容器组件（如 Column、Row 或 Stack）来实现点击交互。

GridCol({ span: 4 }) {
  Column()
    .onClick(() => {
      console.info('GridCol clicked');
    })
    // ...
}

Q8：为什么我的 GridRow 在两个 GridCol 之间有多余的空白？如何消除？

A：多出的空白通常来源于 gutter。如果希望列之间没有间隔，将 gutter 设为 { x: 0, y: 0 } 即可。另外，检查 GridCol 的 margin 和 padding 是否设为了非零值。

Q9：GridRow 的 columns 可以动态修改吗？

A：可以。将 columns 绑定到一个 @State 变量，在运行时修改该变量即可触发 GridRow 重新布局。这在需要动态切换栅格精细度的场景中非常有用。

@Component
struct DynamicGrid {
  @State cols: number = 12;

  build() {
    GridRow({ columns: this.cols }) {
      GridCol({ span: this.cols / 2 }) { /* 始终占一半 */ }
      GridCol({ span: this.cols / 2 }) { /* 始终占一半 */ }
    }
  }
}