目标平台： HarmonyOS NEXT
API Level： 24
技术栈： ArkTS / ArkUI 声明式开发
代码仓库： MyApplication44（Index.ets 完整示例）

---

项目演示

目录

• 第 1 章 引言：从线性布局到网格布局的范式跃迁
• 第 2 章 Grid 组件基础详解（API Level 24）
• 第 3 章 模板系统深度解析：columnsTemplate 与 rowsTemplate
• 第 4 章 自定义 Span 机制的数学原理
• 第 5 章 完整实战：杂志风格瀑布流 4×7 不规则网格
• 第 6 章 高级技巧：动态网格与多端响应式
• 第 7 章 性能优化：Grid 渲染瓶颈与突破
• 第 8 章 API Level 24 新特性全景
• 第 9 章 常见问题 FAQ 与踩坑记录
• 第 10 章 总结与展望

---

第 1 章 引言：从线性布局到网格布局的范式跃迁

1.1 移动端界面布局的演进之路

自移动互联网诞生以来，界面布局范式经历了三次标志性的跃迁。第一代是绝对坐标布局，开发者手动计算每个控件的 (x, y, width, height)，这在功能机时代尚能胜任，但随着屏幕尺寸碎片化，这种方式的维护成本呈指数级上升。第二代是线性盒式布局，iOS 的 AutoLayout、Android 的 ConstraintLayout、Web 的 Flexbox 都属于这一范畴，其核心思想是"一维排列 + 嵌套组合"——通过水平 Row 和垂直 Column 的层层嵌套，模拟二维排版。这一范式统治了移动开发近十年，至今仍是主流。

然而，当内容消费进入"杂志化、瀑布流化、个性化推荐"时代，线性布局的结构性缺陷开始暴露。设想以下场景：首页 Banner 需要横跨 2 列纵跨 2 行；内容流中插入一张广告卡片需要占据 4 列通栏；用户画像卡需要纵向延伸 3 行……在线性布局中，你需要引入 Row 嵌套 Column 再嵌套 Row，再配合 flex: 2、aspectRatio、SizedBox 等"补丁"才能勉强实现，代码可读性和可维护性急剧下降。

Grid 布局（CSS Grid 的移动端实现）就是为解决这个问题而生的第三代布局范式。

1.2 为什么是 Grid：线性布局 vs 网格布局

我们用一个经典案例来直观对比。需求：4 列网格中，A 卡片占 2×2，B 卡片占 1×2，其余卡片占 1×1。

方案 A：使用 Row/Column + Flex 嵌套

// 嵌套层数 = 3，代码复杂度高，修改一个span需要重排整个结构
Column() {
  Row() {
    Column() {
      CardA()
        .width('50%')
        .aspectRatio(1) // 高度依赖宽度估算，不精准
      Row() {
        CardE().layoutWeight(1)
        CardF().layoutWeight(1)
      }
    }
    .layoutWeight(2)
    Column() {
      CardB().layoutWeight(1)
      CardC().layoutWeight(1)
    }
    .layoutWeight(1)
    CardD().layoutWeight(1)
  }
  // ... 后续行还需要手动对齐第一行的列宽
}

方案 B：使用 Grid + 自定义 Span

// 嵌套层数 = 1，结构扁平，每个卡片独立声明自身范围
Grid() {
  GridItem() { CardA() }.columnStart(1).columnEnd(3).rowStart(1).rowEnd(3)
  GridItem() { CardB() }.columnStart(3).columnEnd(4).rowStart(1).rowEnd(3)
  GridItem() { CardC() }.columnStart(4).columnEnd(5).rowStart(1).rowEnd(2)
  GridItem() { CardD() }.columnStart(4).columnEnd(5).rowStart(2).rowEnd(3)
  GridItem() { CardE() }.columnStart(1).columnEnd(2).rowStart(3).rowEnd(4)
  GridItem() { CardF() }.columnStart(2).columnEnd(3).rowStart(3).rowEnd(4)
}
.columnsTemplate('1fr 1fr 1fr 1fr')

差距一目了然：Grid 的代码量减少 60%，嵌套层数从 3 层降为 1 层，每个卡片的位置和跨度是自描述的，不需要阅读父容器的代码就能理解排版意图。

1.3 Grid 布局在 HarmonyOS NEXT 中的定位

在 HarmonyOS NEXT 的 ArkUI 框架中，Grid 不是对 Row/Column 的替代，而是互补。三者的分工如下：

布局组件	维度	最佳场景	典型代表
Row / Column	一维	导航栏、按钮组、表单行	顶部 TitleBar、底部操作栏
List / WaterFlow	伪二维	同质内容的无限滚动	商品列表、聊天记录
Grid / GridItem	真二维	非同质内容的不规则排版	首页仪表盘、杂志封面、瀑布流杂志

HarmonyOS NEXT API Level 24 对 Grid 组件做了三轮增强：模板系统支持混合单位（fr + vp + px + 百分比）、Span 机制支持动态修改、新增 layoutDirection 以适配 RTL 语言、cachedCount 虚拟化缓存机制。本文的所有代码和特性均严格基于 API Level 24 的规范。

1.4 本文的组织结构

本文将遵循"基础概念 → 原理剖析 → 完整实战 → 高级技巧 → 性能优化 → FAQ"的渐进式路径，每一章都附带可运行的 ArkTS 代码片段。最终章提供一个完整的 4×7 杂志风格瀑布流案例，读者可以直接复制到 DevEco Studio 的 Index.ets 中预览效果。

---

第 2 章 Grid 组件基础详解（API Level 24）

2.1 Grid 与 GridItem 的父子契约

Grid 布局由两个组件协同完成：Grid（父容器） 和 GridItem（子元素）。它们之间的契约可以用一句话概括：

父容器定义"格子"的形状与间距，子元素声明"我占哪几个格子"。

父容器 Grid 的职责：

• 定义横向切几刀（列数与列宽规则）→ columnsTemplate
• 定义纵向切几刀（行数与行高规则）→ rowsTemplate
• 定义格子之间的缝隙 → columnsGap / rowsGap
• 定义溢出滚动策略 → scrollBar / edgeEffect

子元素 GridItem 的职责：

• 声明自己在第几列开始 / 结束 → columnStart / columnEnd
• 声明自己在第几行开始 / 结束 → rowStart / rowEnd

这种关注点分离的设计使得布局结构极其清晰。父容器不关心子元素的个体差异，子元素不关心其他兄弟的位置。

2.2 最小可运行示例：Hello Grid

在深入复杂特性之前，先确保读者能在 DevEco Studio 中跑通一个最小示例。创建 Index.ets 文件并粘贴以下代码：

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

@Entry
@Component
struct HelloGrid {
  @State colors: string[] = [
    '#EF4444', '#F59E0B', '#22C55E', '#3B82F6',
    '#8B5CF6', '#EC4899', '#14B8A6', '#F97316'
  ];

  build() {
    Column() {
      Grid() {
        ForEach(this.colors, (color: string, idx: number): void => {
          GridItem() {
            Text(`#${idx + 1}`)
              .fontSize(24)
              .fontColor(Color.White)
              .fontWeight(FontWeight.Bold)
          }
          .width('100%')
          .height(80)
          .backgroundColor(color)
          .borderRadius(12)
          .justifyContent(FlexAlign.Center)
          .onClick(() => {
            promptAction.showToast({ message: `点击格子 ${idx + 1}`, duration: 1000 });
          })
        }, (item: string, idx: number): string => `${idx}_${item}`)
      }
      .columnsTemplate('1fr 1fr 1fr')   // 3列等宽
      .rowsTemplate('auto auto auto')   // 3行自适应
      .columnsGap(8)
      .rowsGap(8)
      .padding(16)
      .width('100%')
      .backgroundColor('#F8FAFC')
    }
    .width('100%')
    .height('100%')
  }
}

运行后将看到 3×3 的彩色网格。这个迷你示例涵盖了 Grid 布局的 80% 基础要素：模板定义、间距设置、ForEach 渲染、点击交互。

2.3 导入语句与依赖

在 HarmonyOS NEXT API Level 24 中，Grid 组件是 ArkUI 内置组件，不需要额外导入模块，可以直接使用。但本文示例中用到的 promptAction（Toast 提示）需要显式导入：

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

另外，如果你需要使用全局枚举（如 FontWeight、Alignment、GradientDirection、BarState 等），它们同样属于 @kit.ArkUI 的子命名空间，但编译器会自动解析，不需要逐条导入。本文建议在文件开头只写一个 promptAction 的导入即可，保持代码整洁。

2.4 装饰器规范：@Entry、@Component、@State

Grid 页面必须遵循 ArkTS 声明式开发的标准三件套：

• @Entry：标记该组件为页面入口，由框架注入路由栈。一个 .ets 文件最多一个 @Entry。
• @Component：标记该结构体为可复用 UI 组件，必须实现 build() 方法。
• @State：标记组件内部状态变量，值变化时触发所属组件的 build() 重新执行（局部刷新）。

对于 Card 数据类，如果需要在 ForEach 中支持字段级响应式更新，需要在类定义前添加 @Observed 装饰器：

@Observed
class CardItem {
  title: string = '';
  // 构造函数内部初始化所有字段，避免使用 ! 断言
  constructor(t: string) {
    this.title = t;
  }
}

2.5 Grid 核心属性速查表（API Level 24）

下表完整列出 Grid 父容器在 API Level 24 中可用的全部核心属性：

属性名	类型	默认值	作用
columnsTemplate	string	'1fr 1fr'	列模板，空格分隔的多段长度声明
rowsTemplate	string	'auto'	行模板，空格分隔的多段高度声明
columnsGap	Length	0	列与列之间的水平间距
rowsGap	Length	0	行与行之间的垂直间距
cachedCount	number	0	预加载缓存的 GridItem 数量，提升长列表滚动性能
layoutDirection	GridDirection	Row	主布局方向：Row 先横向填充，Column 先纵向填充
maxCount	number	Infinity	最大列/行数（与 layoutDirection 对应）
minCount	number	1	最小列/行数
cellLength	number	0	强制单元格尺寸，优先级低于 Template
multiSelectable	boolean	false	是否支持多选模式
supportAnimation	boolean	true	是否启用内部动画（插入/删除时）

GridItem 子元素在 API Level 24 中可用的核心属性：

属性名	类型	作用
columnStart	number	起始列索引（从 1 开始，包含）
columnEnd	number	结束列索引（从 1 开始，不包含）
rowStart	number	起始行索引（从 1 开始，包含）
rowEnd	number	结束行索引（从 1 开始，不包含）
forceRebuild	boolean	是否强制重建（默认 false，复用渲染节点）

---

第 3 章 模板系统深度解析：columnsTemplate 与 rowsTemplate

3.1 Template 语法的本质

Grid 的模板系统源于 CSS Grid 的 grid-template-columns 和 grid-template-rows，并针对移动端做了裁剪和增强。它是一个空格分隔的字符串，每一段代表一行或一列的尺寸规则。

.columnsTemplate('1fr 2fr 1fr')  // 3 列：1 : 2 : 1 的宽度比例
.rowsTemplate('80vp 80vp 80vp')  // 3 行：每行 80 虚拟像素

3.2 五种长度单位详解

API Level 24 支持在 Template 中混用以下五种单位：

（1）fr（fraction，弹性份额）

fr 是 Grid 最核心的单位，表示"剩余空间的份数比"。例如 4 列各占 1fr，意味着总宽度扣除 gap 后平均分为 4 份，每列拿 1 份。fr 的强大之处在于与其他单位混合使用：

// 场景：左侧固定广告位 120vp，中间 3 列内容等分剩余空间，右侧边栏 80vp
.columnsTemplate('120vp 1fr 1fr 1fr 80vp')

这种写法用 Row/Column 嵌套需要至少 3 层结构，而 Grid 一句话就完成了。

（2）vp（virtual pixel，虚拟像素）

vp 是鸿蒙系统特有的长度单位，1vp ≈ 160dpi 屏幕上的 1 物理像素。在 Template 中使用 vp 可以获得跨设备一致的绝对尺寸：

.rowsTemplate('120vp 1fr 80vp')  // 头 120vp，尾 80vp，中间自适应

（3）px（physical pixel，物理像素）

在极少数需要精准控制物理像素的场景（如图像素材对齐），可以使用 px。但 99% 的移动端布局推荐使用 vp 而非 px。

（4）%（百分比）

百分比是相对于 Grid 父容器自身的内容宽度/高度（即扣除 padding 后的尺寸）：

.columnsTemplate('25% 25% 25% 25%')  // 等价于 '1fr 1fr 1fr 1fr'（无 gap 时）

⚠️ 注意：当存在 columnsGap 时，4 × 25% 会超出容器宽度导致溢出，此时应当使用 fr 而非百分比。fr 会自动扣除 gap 总宽度后再分配。

（5）auto（自适应内容）

auto 是模板系统的灵魂。它会让行/列的尺寸自动适配其内部的最大内容。对于瀑布流和杂志风格的不规则布局，行模板几乎总是使用 auto：

.rowsTemplate('auto auto auto auto auto auto auto')  // 7 行，每行高度由内容自动撑开

3.3 repeat() 函数的省略写法

在 CSS Grid 中可以使用 repeat(12, 1fr) 快速重复。在 ArkUI 中，由于 Template 参数是纯字符串而非可执行表达式，不支持 repeat() 函数，需要手动展开。因此 12 列网格的正确写法是：

.columnsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr')

或者通过 ArkTS 的字符串拼接动态生成：

private genColumnsTemplate(count: number): string {
  let result: string = '';
  for (let i: number = 0; i < count; i++) {
    result += '1fr ';
  }
  return result.trim();
}
// 使用
.columnsTemplate(this.genColumnsTemplate(12))

3.4 混合单位实战：杂志首页模板

让我们设计一个典型的杂志首页布局，用混合单位的 Template 一行定义完所有列规则：

Grid() {
  GridItem() { Text('侧边栏').backgroundColor('#6366F1') }
    .columnStart(1).columnEnd(2).rowStart(1).rowEnd(4)
  GridItem() { Text('头条Banner').backgroundColor('#EF4444') }
    .columnStart(2).columnEnd(6).rowStart(1).rowEnd(2)
  GridItem() { Text('文章A').backgroundColor('#F59E0B') }
    .columnStart(2).columnEnd(4).rowStart(2).rowEnd(3)
  GridItem() { Text('文章B').backgroundColor('#22C55E') }
    .columnStart(4).columnEnd(6).rowStart(2).rowEnd(3)
  GridItem() { Text('通栏广告').backgroundColor('#EC4899') }
    .columnStart(1).columnEnd(6).rowStart(3).rowEnd(4)
}
// 模板定义：左侧 100vp 固定栏 + 4 等分内容列
.columnsTemplate('100vp 1fr 1fr 1fr 1fr')
// 行模板：Banner 较高 120vp + 内容行 auto + 广告条 80vp
.rowsTemplate('120vp auto 80vp')
.columnsGap(8)
.rowsGap(8)

这个 5 列 × 3 行的混合模板，精确地描述了侧边栏固定宽度、内容区弹性分配、Banner 固定高度、广告条固定高度的复杂规则。这就是 Grid 布局在杂志类应用中的杀手级价值。

3.5 rowsTemplate 的 auto 行数超出机制

一个常见的疑问是：如果 rowsTemplate('auto auto') 只声明了 2 行，但 GridItem 中出现了 rowStart(3) 会发生什么？

答案是：Grid 会自动创建第 3 行，使用与最后一个声明行相同的规则（即 auto）。 这是 API Level 24 的人性化设计，意味着你可以只声明前 N 行的特殊尺寸，后续行自动沿用 auto。因此在瀑布流场景中，你甚至可以只写 rowsTemplate('auto') 单行，后续无限行都会自动继承自适应高度。但显式声明足够多行能让代码意图更清晰。

---

第 4 章 自定义 Span 机制的数学原理

4.1 索引体系：从 1 开始的设计选择

GridItem 的四件套属性（columnStart / columnEnd / rowStart / rowEnd）均采用从 1 开始的 1-based 索引，而非程序员熟悉的 0-based。这是 ArkTS 团队在易用性与一致性之间权衡的结果：CSS Grid 的规范同样使用 1-based 索引，与 HTML 表格 <table><tr><td colspan="2"> 的人类直觉一致。

4.2 End 不包含原则：Span 的计算公式

columnEnd 和 rowEnd 遵循"左闭右开区间"的数学惯例——Start 包含，End 不包含。因此，跨越的列数（即 colspan）和行数（rowspan）的计算公式为：

colSpan = columnEnd - columnStart
rowSpan = rowEnd    - rowStart

这一设计初看可能反直觉，但它带来了一个绝佳的工程优势：相邻元素无缝拼接时不需要额外计算偏移。 举个例子，卡片 A 占列 1-2（columnEnd=3），卡片 B 紧挨着卡片 A 的右侧，那么 B 的 columnStart 直接写 3 即可，不需要 “+1”：

// 元素A：占据第 1、2 两列
GridItem() { CardA() }.columnStart(1).columnEnd(3)  // span = 3 - 1 = 2

// 元素B：紧接着 A 的右侧，占据第 3、4 两列
GridItem() { CardB() }.columnStart(3).columnEnd(5)  // span = 5 - 3 = 2

如果改成"闭区间"，那么 B 的 Start 需要写 A.End + 1，频繁的 off-by-one 错误会成为常态。

4.3 四类 Span 模式的标准写法

根据 colSpan 和 rowSpan 的组合，不规则网格中的卡片分为 4 类。以下是每种模式的代码模板：

模式 A：单格卡片（1×1）

最常见的小卡片，colSpan=1，rowSpan=1。

GridItem() { SingleCard() }
  .columnStart(col).columnEnd(col + 1)
  .rowStart(row).rowEnd(row + 1)

模式 B：横向宽卡（N×1）

横跨多列，高度与普通卡一致。典型场景：通栏广告、标题横幅。

// 横跨 4 列（通栏）
GridItem() { WideBanner() }
  .columnStart(1).columnEnd(5)    // span = 5 - 1 = 4
  .rowStart(4).rowEnd(5)          // span = 5 - 4 = 1

模式 C：纵向高卡（1×N）

纵跨多行，宽度与普通卡一致。典型场景：用户画像卡、分类导航高卡。

// 第 1 列纵跨 2 行
GridItem() { TallCard() }
  .columnStart(1).columnEnd(2)    // span = 2 - 1 = 1
  .rowStart(5).rowEnd(7)          // span = 7 - 5 = 2

模式 D：大号展示卡（M×N）

横跨 M 列、纵跨 N 行。典型场景：头条卡片、精选推荐位。

// 2×2 大号卡（左上角锚点在第 1 行第 1 列）
GridItem() { HeroCard() }
  .columnStart(1).columnEnd(3)    // span = 3 - 1 = 2
  .rowStart(1).rowEnd(3)          // span = 3 - 1 = 2

4.4 7 × 4 网格的完整坐标图

为了让读者建立直观的空间感，下图展示了本文实战案例的完整坐标系统，横轴 1-5 为列边界（4 列），纵轴 1-8 为行边界（7 行）：

        col 1    col 2    col 3    col 4
       ┌────────┬────────┬────────┬────────┐
row 1  │  探索发现 2×2    │今日推荐│热门话题│
       │        │        ├────────┼────────┤
row 2  │ 🚀 大号卡 │      │        │        │
       ├────────┼────────┤ 🎵 音乐 │ 📷 摄影 │
row 3  │ 🍜 美食 │ ✈️ 旅行 │  1×2   │  1×2   │
       ├────────┴────────┴────────┴────────┤
row 4  │      🎉 限时活动（通栏 4×1）        │
       ├────────┬─────────────────┬────────┤
row 5  │        │  🤖 科技前沿    │ 👗 时尚 │
       │ 健康生活 ├─────────────────┼────────┤
row 6  │  1×2   │  🎬 影视推荐    │ 📚 阅读 │
       ├────────┼─────────────────┼────────┤
row 7  │ 🎮 游戏 │  🛒 生活服务    │ ➕ 更多 │
       └────────┴─────────────────┴────────┘
row 8

对照此图，任何一个卡片的四个 Span 参数都能被快速确定。例如"科技前沿"卡片横向占据第 2、3 两列（Start=2, End=4），纵向只占第 5 行（Start=5, End=6），因此：

.columnStart(2).columnEnd(4).rowStart(5).rowEnd(6)

4.5 Span 冲突与自动降级规则

如果两个 GridItem 声明的矩形区域发生重叠，会发生什么？ArkUI 的处理策略是后声明者胜出——在 build() 方法中后出现的 GridItem 会覆盖先前声明的冲突区域。这在调试阶段非常有用，可以通过重叠快速定位问题，但生产代码应避免这种情况，因为被覆盖的卡片会被静默隐藏（不抛异常、不打警告）。

建议的调试手段是在开发阶段给每个 GridItem 加 2px 的彩色边框，并打印每个卡片的 Span 信息：

// 调试用：边框 + 日志
GridItem() { Content() }
  .columnStart(s).columnEnd(e)
  .rowStart(rs).rowEnd(re)
  .border({ width: 2, color: Color.Red })

---

第 5 章 完整实战：杂志风格瀑布流 4×7 不规则网格

本章进入本文的核心实战环节。我们将从零构建一个杂志风格的首页，使用 4 列 × 7 行的不规则网格，包含 16 张不同大小、颜色、主题的卡片。完整的代码可在本文附带的 Index.ets 中找到。

5.1 需求分析与视觉稿还原

功能需求

1. 顶部标题栏：页面标题 + 副标题（技术说明）+ 搜索/设置圆形按钮
2. 网格主体：4 列 × 7 行，16 张卡片，呈现瀑布流杂志感
3. 卡片分类：8 种 Span 模式的组合拳（2×2、1×1、1×2、4×1 等）
4. 卡片内部：分类标签胶囊 + 标题 + 副标题 + 背景装饰图标 + 渐变遮罩
5. 交互：点击任意卡片弹出 Toast 提示；滚动支持边缘弹性效果

视觉设计规范

元素	规范值
网格列数	4 列（1fr × 4）
行数	7 行（auto × 7）
卡片间距（列/行）	10vp
内容外边距	左右 10vp，上下 4vp
卡片圆角	16vp
卡片内边距	14vp
卡片阴影	radius=8, offsetY=4, alpha=0.12
标题栏背景	#FFFFFF
网格背景	#F8FAFC
主文字色（白卡内）	#FFFFFF + 渐变遮罩增强对比度

5.2 数据结构设计：CardItem 类

一个精心设计的数据结构可以让 UI 代码精简 50%。我们将卡片的所有信息——包括 Span 参数——封装进 CardItem 类，配合 @Observed 装饰器支持字段级响应式：

@Observed
class CardItem {
  title: string = '';
  subtitle: string = '';
  bgColor: string = '';
  colStart: number = 1;
  colEnd: number = 2;
  rowStart: number = 1;
  rowEnd: number = 2;
  icon: string = '';
  category: string = '';

  constructor(title: string, subtitle: string, bgColor: string,
              colStart: number, colEnd: number,
              rowStart: number, rowEnd: number,
              icon: string, category: string) {
    this.title = title;
    this.subtitle = subtitle;
    this.bgColor = bgColor;
    this.colStart = colStart;
    this.colEnd = colEnd;
    this.rowStart = rowStart;
    this.rowEnd = rowEnd;
    this.icon = icon;
    this.category = category;
  }
}

注意 ArkTS 的三个语法约束：

1. 禁止使用 ! 断言运算符：所有字段必须在声明时赋默认值，或在构造函数中显式初始化。
2. 禁止使用 any/unknown：所有字段的类型必须显式声明（string、number 等）。
3. 禁止解构赋值：构造函数参数不允许使用 { title, subtitle } 形式的对象解构，只能使用位置参数列表。

5.3 卡片数据源：16 张卡片的 Span 分配

根据 4.4 节的坐标图，我们逐一分配 16 张卡片：

@State cardList: CardItem[] = [
  // ===== 第 1-2 行：头部区域 =====
  new CardItem('探索发现', '发现更多精彩内容', '#6366F1',
    1, 3, 1, 3, '🚀', '精选'),       // 2×2
  new CardItem('今日推荐', '编辑精心挑选', '#F59E0B',
    3, 4, 1, 2, '⭐', '推荐'),       // 1×1
  new CardItem('热门话题', '实时热搜榜单', '#EF4444',
    4, 5, 1, 2, '🔥', '热门'),       // 1×1

  // ===== 第 2-3 行右侧：两张高卡 =====
  new CardItem('音乐电台', '沉浸式听觉体验', '#10B981',
    3, 4, 2, 4, '🎵', '音乐'),       // 1×2
  new CardItem('摄影作品', '精选视觉大片', '#EC4899',
    4, 5, 2, 4, '📷', '影像'),       // 1×2

  // ===== 第 3 行左侧 =====
  new CardItem('美食地图', '探寻城市味道', '#F97316',
    1, 2, 3, 4, '🍜', '美食'),       // 1×1
  new CardItem('旅行攻略', '带你环游世界', '#06B6D4',
    2, 3, 3, 4, '✈️', '旅行'),       // 1×1

  // ===== 第 4 行：通栏横幅 =====
  new CardItem('限时活动', '新人专享福利 立即参与 →', '#8B5CF6',
    1, 5, 4, 5, '🎉', '活动'),       // 4×1

  // ===== 第 5-6 行：不规则混合区 =====
  new CardItem('健康生活', '科学运动指南', '#22C55E',
    1, 2, 5, 7, '🏃', '健康'),       // 1×2
  new CardItem('科技前沿', 'AI改变世界', '#3B82F6',
    2, 4, 5, 6, '🤖', '科技'),       // 2×1
  new CardItem('时尚穿搭', '潮流风向标', '#F43F5E',
    4, 5, 5, 6, '👗', '时尚'),       // 1×1

  // ===== 第 6 行右侧 =====
  new CardItem('影视推荐', '高分好剧不停', '#A855F7',
    2, 4, 6, 7, '🎬', '影视'),       // 2×1
  new CardItem('阅读时间', '静心品味书香', '#14B8A6',
    4, 5, 6, 7, '📚', '阅读'),       // 1×1

  // ===== 第 7 行：底部入口 =====
  new CardItem('游戏中心', '精彩游戏推荐', '#0EA5E9',
    1, 2, 7, 8, '🎮', '游戏'),       // 1×1
  new CardItem('生活服务', '便捷生活助手', '#84CC16',
    2, 4, 7, 8, '🛒', '生活'),       // 2×1
  new CardItem('更多', '发现更多精彩', '#64748B',
    4, 5, 7, 8, '➕', '更多'),       // 1×1
];

这 16 条数据涵盖了所有的 Span 模式：2×2、1×1、1×2、2×1、4×1。后续如需新增卡片，只需要追加一条数据即可，无需修改任何布局代码。

5.4 卡片 UI 组件：@Builder CardBuilder

我们使用 @Builder 装饰器将卡片的构建逻辑抽离为可复用方法。为了实现杂志风格的视觉层次，单个卡片内部使用 Stack 双层叠加：底层是半透明装饰大图标 + 纯色背景，顶层是从底部升起的渐变遮罩 + 文字内容区。

@Builder
CardBuilder(item: CardItem) {
  Stack({ alignContent: Alignment.BottomStart }) {
    // 第一层：背景装饰图标（右上角，大号半透明）
    Stack() {
      Text(item.icon)
        .fontSize(64)
        .opacity(0.2)
    }
    .width('100%')
    .height('100%')
    .alignContent(Alignment.TopEnd)
    .padding({ right: 8, top: 8 })

    // 第二层：文字内容 + 底部渐变遮罩
    Column({ space: 4 }) {
      // 分类胶囊标签
      Row() {
        Text(item.category)
          .fontSize(11)
          .fontColor('#FFFFFF')
          .fontWeight(FontWeight.Medium)
      }
      .padding({ left: 8, right: 8, top: 3, bottom: 3 })
      .backgroundColor('rgba(255, 255, 255, 0.25)')
      .borderRadius(10)

      // 标题 + 副标题
      Column({ space: 2 }) {
        Text(item.title)
          .fontSize(this.getTitleSize(item))
          .fontColor('#FFFFFF')
          .fontWeight(FontWeight.Bold)
          .maxLines(1)
          .textOverflow({ overflow: TextOverflow.Ellipsis })

        if (this.isLargeCard(item)) {
          Text(item.subtitle)
            .fontSize(12)
            .fontColor('rgba(255, 255, 255, 0.85)')
            .maxLines(1)
            .textOverflow({ overflow: TextOverflow.Ellipsis })
        }
      }
      .alignItems(HorizontalAlign.Start)

      if (this.isLargeCard(item)) {
        Row() { Blank(); Text(item.icon).fontSize(28) }
        .width('100%')
        .margin({ top: 4 })
      }
    }
    .width('100%')
    .alignItems(HorizontalAlign.Start)
    .padding({ left: 14, right: 14, top: 14, bottom: 14 })
    // 关键：底部向顶部的渐变遮罩，增强文字对比度
    .linearGradient({
      direction: GradientDirection.Top,
      colors: [
        ['rgba(0, 0, 0, 0.45)', 0.0],
        ['rgba(0, 0, 0, 0.15)', 0.5],
        ['rgba(0, 0, 0, 0)',    1.0]
      ]
    })
  }
  .width('100%')
  .height('100%')
  .backgroundColor(item.bgColor)
  .borderRadius(16)
  .shadow({ radius: 8, color: 'rgba(0, 0, 0, 0.12)', offsetX: 0, offsetY: 4 })
  .onClick(() => { this.onCardClick(item); })
}

这里有两个值得注意的辅助方法：

• isLargeCard(item)：判断一张卡片是否"足够大"（colSpan ≥ 2 或 rowSpan ≥ 2），只有大卡片才显示副标题和底部主图标，防止小卡片内容拥挤。
• getTitleSize(item)：根据卡片大小动态返回 16 / 18 / 20 / 22 四种字号，通栏卡片使用最大字号，视觉层次自然形成。

5.5 渐变遮罩的方向选择（踩坑点）

本小节是本文特有的"踩坑实录"。在初次编写代码时，我本能地写了：

direction: GradientDirection.BottomTop

结果编译报错：

Property 'BottomTop' does not exist on type 'typeof GradientDirection'.
Did you mean 'Bottom'?

根本原因：ArkUI 的 GradientDirection 枚举采用"指向目标方向"命名法，而非 CSS 风格的"起-止组合"命名法。正确的映射表是：

想要的渐变方向	正确枚举值	含义
从下往上（Bottom → Top）	GradientDirection.Top	渐变终止于顶部
从上往下（Top → Bottom）	GradientDirection.Bottom	渐变终止于底部
从左往右（Left → Right）	GradientDirection.Right	渐变终止于右侧
从右往左（Right → Left）	GradientDirection.Left	渐变终止于左侧
左上→右下	GradientDirection.RightBottom	终止于右下角
右下→左上	GradientDirection.LeftTop	终止于左上角

因此，"从底部深色向顶部透明过渡"的正确写法是 GradientDirection.Top，而 colors 数组的第一个元素（0.0 位置）对应渐变的起点（容器的底部）。

5.6 页面主结构：Column + Scroll + Grid

最终的页面骨架使用三段式结构：顶部标题栏（Row）+ 可滚动网格区（Scroll + Grid）。外层 Column 保证整体垂直排列：

build() {
  Column({ space: 0 }) {
    // === 顶部标题栏 ===
    Row() { /* 标题 + 副标题 + 搜索/设置按钮 */ }
    .width('100%')
    .padding({ left: 16, right: 16, top: 12, bottom: 16 })
    .backgroundColor('#FFFFFF')

    // === Grid 主内容（可滚动） ===
    Scroll() {
      Grid() {
        ForEach(this.cardList, (item: CardItem): void => {
          GridItem() { this.CardBuilder(item) }
            .columnStart(item.colStart)
            .columnEnd(item.colEnd)
            .rowStart(item.rowStart)
            .rowEnd(item.rowEnd)
        }, (item: CardItem): string =>
          `${item.title}_${item.colStart}_${item.rowStart}`)
      }
      .columnsTemplate('1fr 1fr 1fr 1fr')
      .rowsTemplate('auto auto auto auto auto auto auto')
      .columnsGap(10)
      .rowsGap(10)
      .padding({ left: 10, right: 10, top: 4, bottom: 20 })
      .backgroundColor('#F8FAFC')
    }
    .scrollBar(BarState.Off)
    .width('100%')
    .height('100%')
    .backgroundColor('#F8FAFC')
    .edgeEffect(EdgeEffect.Spring)
  }
  .width('100%')
  .height('100%')
  .backgroundColor('#FFFFFF')
}

ForEach 的第二个参数（键生成函数）至关重要。我们使用 标题_列开始_行开始 三元组作为唯一键，确保框架在列表重排时能精准复用 GridItem 的渲染节点，避免不必要的销毁重建。

5.7 验证与运行

将完整代码粘贴到 Index.ets 后，在 DevEco Studio 中：

1. 点击右上角的 Previewer 按钮（闪电图标）启动 Preview。
2. 或连接真机 / 模拟器，按 Shift + F10 运行应用。

预览界面将呈现一个精美的杂志风格瀑布流首页。滚动时可以感受到边缘弹性效果，点击任意卡片会弹出对应的 Toast 提示。

---

第 6 章 高级技巧：动态网格与多端响应式

6.1 动态列数：根据屏幕宽度自适应

手机竖屏 4 列、平板横屏 8 列、折叠屏展开态 6 列——这是杂志类应用的典型需求。实现方案：通过 @ohos.window 获取应用可见区域宽度，动态计算列数：

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

@Component
struct ResponsiveGrid {
  @State columnCount: number = 4;

  aboutToAppear(): void {
    window.getLastWindow(getContext(this))
      .then((win: window.Window): void => {
        let size: window.Size = win.getWindowProperties().windowRect;
        // 阈值 < 500vp: 3 列；500~840vp: 4 列；840~1200vp: 6 列；> 1200vp: 8 列
        let widthVp: number = px2vp(size.width);
        if (widthVp < 500) this.columnCount = 3;
        else if (widthVp < 840) this.columnCount = 4;
        else if (widthVp < 1200) this.columnCount = 6;
        else this.columnCount = 8;
      });
  }

  private buildTemplate(count: number): string {
    return new Array(count).fill('1fr').join(' ');
  }

  build() {
    Grid() { /* GridItem 列表保持不变 */ }
      .columnsTemplate(this.buildTemplate(this.columnCount))
  }
}

注意：当列数动态变化时，所有 GridItem 的 columnStart/End 也需要同步更新，否则会出现越界或重叠。建议将"响应式列数 + 卡片重新布局"的逻辑封装成一个 ViewModel，对外只暴露 cardList 状态。

6.2 动态 Span：根据内容类型智能排版

在真实的业务场景中，卡片的大小不应硬编码，而应根据内容的"重要性权重"动态分配。例如：

• 广告权重 5 → 分配 2×2 或 4×1
• 编辑精选权重 4 → 分配 1×2 或 2×1
• 普通内容权重 2 → 分配 1×1

封装一个自动布局算法：

class GridLayoutEngine {
  private cols: number = 4;
  private grid: boolean[][];  // 占用矩阵

  constructor(cols: number) {
    this.cols = cols;
    this.grid = [];
  }

  // 分配一个指定 colSpan × rowSpan 的空位
  allocate(colSpan: number, rowSpan: number): { col: number, row: number } | null {
    // 逐行扫描，寻找第一个可以放下 colSpan × rowSpan 的连续空区域
    for (let r: number = 0; ; r++) {
      this.ensureRow(r + rowSpan);
      for (let c: number = 0; c <= this.cols - colSpan; c++) {
        if (this.isFree(c, r, colSpan, rowSpan)) {
          this.mark(c, r, colSpan, rowSpan);
          return { col: c + 1, row: r + 1 };  // 转为 1-based
        }
      }
    }
  }
  // ... 辅助方法 ensureRow / isFree / mark
}

这就是瀑布流 App（如小红书、Pinterest）后台的核心布局算法。它让不规则网格从"手动编排"升级为"自动布局"，同时保证不会出现空位和重叠。

6.3 嵌套 Grid：仪表盘布局

复杂的管理后台或数据仪表盘，常常需要"大网格中套小网格"。例如主界面是 2×2 的 4 个看板，每个看板内部又是 3×3 的小指标卡。Grid 支持无限层嵌套：

Grid() {
  // 4 个大看板，每个都是 1×1
  GridItem() { this.DashboardPanelA() }
    .columnStart(1).columnEnd(2).rowStart(1).rowEnd(2)
  GridItem() { this.DashboardPanelB() }
    .columnStart(2).columnEnd(3).rowStart(1).rowEnd(2)
  GridItem() { this.DashboardPanelC() }
    .columnStart(1).columnEnd(2).rowStart(2).rowEnd(3)
  GridItem() { this.DashboardPanelD() }
    .columnStart(2).columnEnd(3).rowStart(2).rowEnd(3)
}
.columnsTemplate('1fr 1fr')
.rowsTemplate('auto auto')

// 每个看板内部又是一个子 Grid
@Builder
DashboardPanelA() {
  Grid() {
    GridItem() { Text('销售总额').fontSize(14) }
      .columnStart(1).columnEnd(4).rowStart(1).rowEnd(2)
    GridItem() { Text('¥ 128万').fontSize(28).fontWeight(FontWeight.Bold) }
      .columnStart(1).columnEnd(4).rowStart(2).rowEnd(4)
    // ... 更多指标
  }
  .columnsTemplate('1fr 1fr 1fr')
  .rowsTemplate('auto auto auto')
  .width('100%')
  .height(220)
  .backgroundColor('#FFFFFF')
  .borderRadius(12)
}

嵌套 Grid 的性能注意事项：子 Grid 的高度必须确定（固定数值或父容器传入），否则内层 auto 行与外层 auto 行的高度计算会相互依赖，引发"无限循环测量"的性能退化。

6.4 Grid + 动画：animateTo 的正确姿势

在 Grid 中为卡片添加动画（如展开/折叠、淡入/淡出）时，务必遵循 ArkUI 动画的核心铁律：

动画只能改变被 @State 标记的状态变量，不能直接在动画闭包中修改布局属性。

正确示例（切换卡片 Span 带动画）：

@State heroColEnd: number = 3;  // 默认 2 列宽

GridItem() { HeroCard() }
  .columnStart(1).columnEnd(this.heroColEnd)
  .rowStart(1).rowEnd(3)
  .onClick(() => {
    animateTo({ duration: 350, curve: Curve.FastOutSlowIn }, () => {
      this.heroColEnd = (this.heroColEnd === 3) ? 5 : 3;  // 2列 ↔ 4列
    })
  })

⚠️ 严禁在动画闭包中直接调用 .columnEnd(5) 这类链式 API，动画作用的对象是状态变量，不是属性调用。此外，对于包含复杂子组件的 GridItem，建议调用 .renderGroup(true) 将其标记为独立的渲染组，减少动画过程中兄弟节点的重绘开销。

---

第 7 章 性能优化：Grid 渲染瓶颈与突破

7.1 性能测量的基准方法

在讨论优化手段之前，必须先建立测量体系。HarmonyOS NEXT 提供了两个官方工具：

• DevEco Profiler：菜单栏 → View → Tool Windows → Profiler，可实时查看 FPS、CPU 占用、GPU 渲染耗时。
• @ohos.performance 框架：在代码中埋点打印耗时：

import { performance } from '@kit.PerformanceStatisticsKit';

let t0: number = performance.now();
// 执行 Grid 构建或滚动操作
let t1: number = performance.now();
console.info(`Grid render cost: ${(t1 - t0).toFixed(2)}ms`);

我们的优化目标是：滚动帧率稳定在 58~60 FPS，单次 build() 执行时间 < 16ms。

7.2 核心优化一：ForEach 键值的唯一性

ForEach 的第三个参数（键生成器）是 Grid 性能的第一道关卡。如果使用索引 idx 作为键，当在列表头部插入一张卡片时，所有后续卡片的键都会改变，引发框架对全部 GridItem 的销毁重建——这是 50% 性能问题的根源。

❌ 错误写法：

ForEach(this.cardList, (item: CardItem): void => { /* 渲染 */ },
  (item: CardItem, idx: number): string => `${idx}`)

✅ 正确写法（使用稳定且唯一的业务键）：

ForEach(this.cardList, (item: CardItem): void => { /* 渲染 */ },
  (item: CardItem): string => `${item.id}_${item.colStart}_${item.rowStart}`)

7.3 核心优化二：renderGroup(true) 隔离渲染树

对于卡片内部包含多张图片、多层嵌套 Column/Stack 的"重量级 GridItem"，调用 .renderGroup(true) 可以获得 20%~40% 的性能提升。它的作用是告诉渲染引擎：这个子树的绘制是独立的，可以单独缓存为一张 GPU 纹理。 当父容器发生重排时，已缓存的 renderGroup 不需要重新遍历绘制。

GridItem() { HeavyCardContent() }
  .columnStart(1).columnEnd(3).rowStart(1).rowEnd(3)
  .renderGroup(true)

注意事项：

• 仅对内部复杂的大卡片启用，简单的 1×1 小卡不需要。
• 启用后会占用额外的 GPU 显存，建议单次启用数量 < 20 个。
• 动画期间的 GridItem 强制开启 renderGroup。

7.4 核心优化三：cachedCount 虚拟化预加载

当 Grid 中的卡片数量超过 100 张时（例如电商首页的无限瀑布流），应当启用 cachedCount 属性，它会预加载"即将进入视口"的 N 个 GridItem，减少滑动时的白屏闪烁：

Grid() { /* 100+ GridItem */ }
  .columnsTemplate('1fr 1fr')
  .rowsTemplate('auto')
  .cachedCount(8)   // 视口外各预加载 8 个

cachedCount 的推荐值是"单行/单列格子数 × 2"。2 列布局推荐 8，4 列布局推荐 12，过大会增加首帧内存压力。

7.5 核心优化四：图片异步加载与采样

卡片中的图片资源往往占据了 80% 的渲染耗时。图片优化三板斧：

1. 使用 Image 的 autoResize 属性，自动按显示尺寸下采样解码，避免 4K 图片被完整加载到 100×100 的卡片中。
2. 使用 placeholder 占位图，在图片解码期间显示纯色或骨架屏，避免布局抖动。
3. 使用 @ohos.multimedia.image 的 PixelMap API，在业务层统一管理图片缓存池，同一 URL 的图片不重复解码。

7.6 常见性能陷阱清单

反模式	危害	修复方案
在 build() 中动态生成 Template 字符串	每次重建都触发字符串拼接 + 模板解析	缓存到 @State 变量，仅在列数变化时更新
GridItem 混用固定高度 + auto 行高	触发无限次重新测量	统一使用 auto，或统一使用固定高度
滚动监听中更新 @State	每帧触发 build()，帧率暴跌	使用 Throttle（节流），间隔 ≥ 100ms
在 ForEach 回调内声明函数	每次 build 创建新闭包实例	抽离为 @Builder 方法或组件

---

第 8 章 API Level 24 新特性全景

HarmonyOS NEXT API Level 24（对应 HarmonyOS 5.0 及以上版本）对 Grid 组件做了三轮重要增强，本章节做一个系统性梳理。

8.1 模板系统增强：minmax() 支持

API Level 24 在 Template 字符串中新增了对 minmax(min, max) 语法的支持，可以限制列/行的最小/最大尺寸：

// 第 1 列：最小 100vp，最大不超过 200vp，默认取 1fr
.columnsTemplate('minmax(100vp, 200vp) 1fr 1fr 1fr')

这使得 Grid 可以优雅地处理内容极端的场景：当内容很少时列不会塌缩到看不见，当内容极多时列不会无限撑大破坏布局。

8.2 layoutDirection 与 RTL 国际化

新增 layoutDirection 属性，支持三种值：

• GridDirection.Row（默认）：横向优先填充，第 1 行填满后换行到第 2 行
• GridDirection.Column：纵向优先填充，第 1 列填满后换列到第 2 列
• GridDirection.RowReverse / ColumnReverse：反向填充，用于阿拉伯语、希伯来语等 RTL 语言

Grid() { /* 子元素顺序不变，框架自动反转视觉坐标 */ }
  .layoutDirection(this.isRTL ? GridDirection.RowReverse : GridDirection.Row)

8.3 GridItem 的动态 Span 性能优化

在 API Level 23 及以前，修改 GridItem 的任意一个 Span 属性（columnStart 等）会触发整个 Grid 的完全重新布局。API Level 24 引入了增量布局算法，只对受影响的区域重新计算，布局速度提升了 3~5 倍。这使得 animateTo 动画的流畅度大幅提升。

8.4 multiSelectable 多选模式

新增的 multiSelectable(true) 属性允许用户长按进入多选模式，配合 onItemClick 回调可以实现批量删除、批量导出等操作：

Grid() { /* ... */ }
  .multiSelectable(true)
  .onItemClick((event: ItemClickEvent): void => {
    console.info(`选中第 ${event.index} 项，当前选中: ${event.selected}`);
  })

8.5 版本兼容性矩阵

特性	API 20	API 22	API 24
基本 Grid/GridItem	✅	✅	✅
columnsTemplate / rowsTemplate	✅	✅	✅
fr/vp/%/auto 混合单位	❌ 仅 fr/vp	✅	✅
minmax() 语法	❌	❌	✅
layoutDirection	❌	✅ 仅 Row/Column	✅ 含 Reverse
cachedCount 虚拟化	❌	✅	✅ 算法优化
multiSelectable 多选	❌	❌	✅
增量 Span 布局	❌	❌	✅（3-5× 加速）

如果你的应用需要兼容 API Level < 24 的设备，应避免使用 minmax() 和 RowReverse 等新特性，或使用 canIUse() 做运行时降级。

---

第 9 章 常见问题 FAQ 与踩坑记录

Q1. GradientDirection.BottomTop 报错

现象：编译提示 Property 'BottomTop' does not exist on type 'typeof GradientDirection'。

根因：ArkUI 使用"目标方向"命名法，不是"起止组合"命名法。

修复：

// ❌ 错误
direction: GradientDirection.BottomTop

// ✅ 正确（指向顶部 = 从下往上渐变）
direction: GradientDirection.Top

对应关系：TopToBottom → Bottom，LeftToRight → Right，RightToLeft → Left，BottomToTop → Top。

Q2. GridItem 设置了高度但不生效

现象：给 GridItem 写 .height(100) 后，实际渲染高度不是 100vp。

根因：当 rowsTemplate 中指定的行高（如 80vp）与 GridItem 的 height 冲突时，Template 的优先级更高。Template 定义的是"格子容器"的高度，GridItem 只能在格子内部通过 .width('100%').height('100%') 填满。

修复：要么修改 rowsTemplate 中的行高，要么在 GridItem 外层包一个 Stack 控制内部内容的高度。

Q3. Grid 中出现空白单元格

现象：明明分配了 16 张卡片，渲染后只看到 14 张，有 2 格空白。

排查步骤：

1. 检查是否存在 Span 重叠（后声明的卡片覆盖了先声明的）。
2. 检查 columnEnd > columnsTemplate 列数 + 1 或 rowEnd > rowsTemplate 行数 + 1 是否越界（越界的 GridItem 会被裁剪不显示）。
3. 检查 ForEach 的键值是否有重复（相同键会导致只渲染其中一个）。

Q4. Scroll 包裹 Grid 后无法滚动

现象：Grid 内容超出视口，但 Scroll 拖动无反应。

根因：Scroll 的子元素（Grid）必须有明确的高度。必须给 Grid 设置 .height('100%') 或固定数值，否则 Grid 高度 = 内容高度，Scroll 检测不到溢出。

修复：确保 Scroll → Grid 的高度链完整：

Scroll() {
  Grid() { /* ... */ }
    .width('100%')
    .height('100%')   // ✅ 必须显式声明
}
.height('100%')        // ✅ Scroll 也必须有高度

Q5. @Observed 类修改字段后 UI 不刷新

现象：点击卡片修改 card.title，ForEach 渲染的文本没有更新。

根因：@Observed + @State 的联动要求：数组本身是引用类型，@State 只监听"数组引用的变化"（push、splice、重新赋值），默认不监听"数组元素内部字段"的变化。

修复方案：

1. 方案 A（推荐）：将 @State cardList: CardItem[] 改为 @State cardList: @Observed CardItem[]（嵌套装饰器）。
2. 方案 B：修改字段后手动触发数组的引用变化：

   item.title = '新标题';
   this.cardList = [...this.cardList];  // 浅拷贝，触发 @State 刷新
   

Q6. ArkTS 语法：不支持解构赋值、as const、any

现象：编译报错 arkts-no-destructuring 或 arkts-no-any-unknown。

修复：遵循 ArkTS 的语法约束：

// ❌ 解构参数（JS/TS 常用写法）
function foo({ title, subtitle }: CardItem) {}

// ✅ 位置参数 + 手动赋值
function foo(item: CardItem): void {
  let title: string = item.title;
  let subtitle: string = item.subtitle;
}

// ❌ as const 断言
const SIZES = [1, 2, 3] as const;

// ✅ 显式类型标注
const SIZES: number[] = [1, 2, 3];

更多语法约束可查阅本文开头的"ArkTS 语法约束"清单。

Q7. 折叠屏展开/折叠后 Grid 布局错乱

现象：从折叠态（小屏）展开到大屏，或从大屏折叠到小屏，Grid 的卡片出现重叠或空白。

根因：折叠屏状态切换会触发 Window 尺寸变化事件，但 Grid 内部的 Template 和 Span 未同步更新。

修复方案：监听 @ohos.window 的 onWindowSizeChange 回调，在回调中重新计算 columnCount 并重新分配所有卡片的 Span：

aboutToAppear(): void {
  window.getLastWindow(getContext(this))
    .then((win: window.Window): void => {
      win.on('windowSizeChange', (size: window.Size): void => {
        this.handleOrientation(size);  // 重新布局
      });
    });
}

---

第 10 章 总结与展望

10.1 回顾：Grid 布局的三大核心价值

本文从基础概念到完整实战，系统介绍了 HarmonyOS NEXT 中 Grid 不规则网格布局的全套技术栈。回顾全文，Grid 布局为移动端 UI 开发带来了三大不可替代的价值：

第一，布局语义的本质提升。 Grid 让"二维排版"成为原生能力，不再需要 Row/Column 的层层嵌套模拟。杂志封面、仪表盘、瀑布流这些复杂场景的代码量可以下降 50% 以上，可读性、可维护性同步提升。

第二，Span 机制的精确控制。 columnStart/End + rowStart/End 四件套构成了一个二维坐标系，开发者可以在不修改父容器的前提下，独立声明每个子元素的位置和跨度。这种"自描述"的设计使得大型团队的并行开发成本大幅降低——视觉设计师负责分配 16 张卡片的坐标图，工程师只需要按图填写四个数字。

第三，性能与灵活性的平衡。 API Level 24 的增量布局算法、renderGroup 渲染隔离、cachedCount 虚拟化预加载，使 Grid 在数百张卡片量级下仍能保持 60FPS 的滚动帧率。配合动态模板、响应式列数、自动布局算法，Grid 足以支撑从小型工具 App 到亿级用户内容平台的全场景需求。

10.2 与跨平台方案的对比

今天的开发者面临着 ArkUI、Flutter、React Native、Compose Multiplatform 等多种技术栈的选择。Grid 布局作为一项"标准特性"，在各平台中的完成度对比可以作为选型参考：

维度	ArkUI Grid（本文）	Flutter GridView	CSS Grid（Web/React Native）	Jetpack Compose LazyVerticalGrid
自定义 Span 支持	✅ 原生 4 属性	❌ 需要 SliverGridDelegateWithMaxCrossAxisExtent 扩展	✅ grid-column / grid-row	✅ span 修饰器
混合单位模板	✅ fr + vp + px + % + auto + minmax	❌ 仅支持子元素 aspectRatio	✅ fr + px + % + minmax + auto	❌ 无 Template 概念
虚拟化长列表	✅ cachedCount	✅ 原生支持	❌ 需自行实现	✅ Lazy 前缀
增量布局算法	✅ API 24+	✅	视浏览器实现而定	✅
RTL 国际化	✅ layoutDirection	✅	✅ direction: rtl	✅

ArkUI 的 Grid 在模板系统的表达力和 Span 控制精度上，已经达到甚至部分超越了 CSS Grid 的体验，配合原生 120Hz 刷新率和 GPU 渲染缓存，在 HarmonyOS NEXT 设备上可以达到"丝滑不发烫"的表现。

10.3 未来展望：Grid 布局的演进方向

展望 HarmonyOS NEXT 的后续版本（API Level 25~28），我们有理由期待 Grid 布局获得以下增强：

1. subgrid 子网格特性：让嵌套 Grid 的行列与父 Grid 自动对齐，消除嵌套场景下父子孙三层手动对齐的代码。
2. 命名网格区域 grid-template-areas：使用字符串矩阵（如 "hero hero side" "main main side"）语义化声明布局，进一步降低设计师与工程师的沟通成本。
3. Masonry 原生瀑布流模式：通过 layoutMode: Masonry 让 Grid 自动进行"不规整高度"的紧凑排列，不再需要开发者手动分配 rowSpan。
4. AI 辅助布局：接入端侧大模型，根据内容文本自动推荐最优 Span 分配方案（"头条"→ 2×2，"广告"→ 4×1，"次要"→ 1×1）。

无论技术如何演进，Grid 布局的核心思想——关注点分离、二维表达、自描述定位——将始终成立。

10.4 写在最后

本文以"杂志风格瀑布流"为实战主线，从 Grid 的基础概念讲起，深入模板系统与 Span 机制的数学原理，再到完整的 4×7 不规则网格代码、响应式适配、性能优化、API 24 新特性、常见问题 FAQ。读者可以将 Index.ets 中的代码直接复制到 DevEco Studio 中运行，验证每一个知识点。

Grid 布局的学习曲线略高于 Row/Column，但掌握之后的回报是永久性的——你将永远告别"5 层嵌套模拟一个杂志首页"的痛苦，进入"声明式二维排版"的新境界。

下一步行动建议：

1. 打开 DevEco Studio，新建一个空白项目，把本文的完整代码粘贴进去运行。
2. 尝试修改 cardList 中的某张卡片的 colStart/End/rowStart/End，观察布局变化。
3. 尝试新增一张 3×1 或 2×3 模式的卡片，验证布局引擎的灵活性。
4. 根据第 7 章的性能优化清单，为你的真实业务项目逐项对照优化。

全文完。
字数统计：约 11,800 字
适用版本：HarmonyOS NEXT API Level 24 + DevEco Studio 5.0+

---