HarmonyOS ArkUI 布局详解：相对布局与栅格布局

sm（小型设备，4 列）

当屏幕宽度落入 sm 断点范围（通常 < 520vp），栅格被划分为 4 列，每个 GridCol 默认占满整行（若未指定 span）。

md（中型设备，8 列）

在中等屏幕（如平板横屏，520vp ~ 840vp），栅格扩展为 8 列，可容纳更多并排内容，提升信息密度。

布局的总列数（columns）

GridRow 的 columns 属性决定了每个断点下栅格系统的总列数，其默认值随 API 版本变化：

• API version < 20： columns = 12（全局统一 12 列，不区分设备）；
• API version ≥ 20： columns = { xs: 2, sm: 4, md: 8, lg: 12, xl: 12, xxl: 12 }（响应式默认值）。

🔍 注意： 当前环境使用的是 API version 17，因此默认为 12 列，且不随设备变化。

这意味着即使在小屏设备上，栅格仍按 12 列划分，若 GridCol 未指定 span，则默认 span=12，表现为单列全宽布局。

可以看到，所有子项一行排布（因 span=12 占满整行）：

属性详解

columns：number（固定列数）

直接指定所有断点下的总列数为固定值。

GridRow({ columns:2}){/* ... */}// 全局 2 列

2 列效果：

3 列效果：

✅ 适用场景：简单两栏/三栏布局，无需响应式。

columns：GridRowColumnOption（响应式列数）

通过对象形式为不同断点设置独立列数，实现真正的响应式设计。

GridRow({ columns:{ sm:4, md:8, lg:12}}){/* ... */}

此配置下，小屏 4 列、中屏 8 列、大屏 12 列，内容密度随屏幕增大而提升。

direction: GridRowDirection.Row（默认）

子项从左到右排列，符合常规阅读习惯。

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

direction: GridRowDirection.RowReverse

子项从右到左排列，适用于 RTL 语言或特殊视觉动效。

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

⚠️ 注意：仅改变布局顺序，不影响文本方向。

gutter：number（统一间距）

设置所有 GridCol 之间的水平与垂直间距（单位：vp）。

GridRow({ gutter:10}){/* ... */}// 间距 10vp

gutter: GutterOption（分向间距）

通过对象分别设置水平（x）和垂直（y）间距。

GridRow({ gutter:{ x:8, y:16}// 水平 8vp，垂直 16vp}){/* ... */}

🎯 设计价值：实现卡片式布局的经典'内边距 + 外间距'效果。

子组件 GridCol

GridCol 必须作为 GridRow 的直接子组件，用于定义单个栅格单元的行为。它通过三大核心属性控制布局：

span（占用列数）

决定该单元占据多少栅格列。

span: number（固定值）

GridCol({ span:6}){Text('占 6 列')}

在 12 列系统中，span=6 表示占据一半宽度。

span: GridColColumnOption（响应式）

为不同断点设置不同 span，实现内容自适应。

GridCol({ span:{ sm:4,// 小屏占满（4/4）
  md:4,// 中屏占一半（4/8）
  lg:3 // 大屏占 1/4（3/12）
}}){/* ... */}

✅ 最佳实践：小屏 span=断点列数 → 单列；大屏 span=较小值 → 多列并排。

offset（偏移列数）

在 span 之前跳过指定列数，实现留白或居中效果。

offset: number

GridCol({ span:6, offset:3})// 从第 4 列开始（跳过 3 列）

offset: GridColColumnOption（响应式偏移）

GridCol({ span:{ sm:4, md:6}, offset:{ sm:0, md:1}})

小屏无偏移，中屏向右偏移 1 列。

order（显示顺序）

控制 GridCol 在视觉上的渲染顺序，不改变 DOM 结构，可用于 SEO 或无障碍优化。

order: number

GridCol({ order:2})// 第二个显示
GridCol({ order:1})// 第一个显示

order: GridColColumnOption（响应式排序）

GridCol({ order:{ sm:2,// 小屏第二
  md:1 // 中屏第一
}})

实现'小屏主次颠倒，大屏正常顺序'的交互策略。

总结与工程建议

最佳实践：

1. 优先使用响应式配置（GridColColumnOption），而非固定值；
2. 总 span 不要超过 columns，否则会换行或溢出；
3. 结合 @Watch 监听屏幕尺寸，动态调整复杂布局；
4. 避免过度嵌套：GridRow 内不应再嵌套 GridRow，可改用 Flex；
5. 性能考量：大量 GridCol 时，确保 span/offset 计算高效。

通过合理运用 GridRow 与 GridCol，开发者可轻松构建出专业级响应式界面，真正实现'一次开发，多端部署'的鸿蒙愿景。