【共创季稿事节】鸿蒙原生 ArkTS 布局深度解析：一行代码实现 Row 内垂直居中

zjxcq520

226人浏览 · 2026-06-17 13:17:50

zjxcq520 · 2026-06-17 13:17:50 发布

鸿蒙原生 ArkTS 布局深度解析：一行代码实现 Row 内垂直居中（经典居中对齐方案）

一、引言

在鸿蒙原生应用开发中，布局是最基础也最核心的技能之一。无论是新手入门还是资深开发者，垂直居中 这个需求几乎每天都在出现。特别是在 Row 组件中，如何让不同高度的子元素在垂直方向上漂亮地居中，是每一位 ArkTS 开发者必须掌握的技能。

HarmonyOS NEXT（API 24）提供了 ArkTS 声明式 UI 框架，其布局模型简洁而强大。本文将围绕 Row 组件的垂直居中展开深度讲解，通过一个完整的示例应用，带你吃透 alignItems: VerticalAlign.Center 这一经典居中对齐方案。

全文将涵盖：

Row 布局模型的核心原理
一行代码实现垂直居中的技术细节
与顶部对齐、底部对齐的对比分析
真实业务场景中的实战应用
常见陷阱与最佳实践

二、Row 布局模型核心原理

2.1 主轴与交叉轴

在 ArkTS 的布局体系中，Row 是一个水平排列容器。理解 Row 的布局，首先要理解两个核心概念：

主轴（Main Axis）： 水平方向，即子组件的排列方向，从左到右依次摆放。
交叉轴（Cross Axis）： 垂直方向，即与排列方向垂直的轴。

         ← 主轴（水平） →
    ┌──────────────────────┐
    │  ┌──┐ ┌──┐ ┌──┐ ┌──┐ │
  ╭  │  │A │ │B │ │C │ │D │ │  ← 交叉轴（垂直）
  ↑  │  └──┘ └──┘ └──┘ └──┘ │
  │  └──────────────────────┘

alignItems 控制的就是交叉轴方向的对齐方式。对于 Row 而言，交叉轴是垂直方向，因此 alignItems 接受 VerticalAlign 枚举值。

2.2 Row 的高度行为

这是很多初学者最容易踩坑的地方。Row 的高度行为遵循以下规则：

默认高度 = 最高子组件的高度：如果 Row 不显式设置 height，它的高度会自动由内部最高的子组件撑开。此时所有子组件已经紧贴 Row 的上下边界，垂直居中效果不明显。
显式设置高度：只有当 Row.height 大于内部最高子组件的高度时，才会产生额外的垂直空间，alignItems 的居中效果才直观可见。
子组件高度差异越大，居中效果越明显：当子组件高度各不相同时，VerticalAlign.Center 会让所有子组件的垂直中线对齐，形成整齐划一的视觉效果。

2.3 alignItems 的取值

在 HarmonyOS NEXT（API 24）中，Row 的 alignItems 方法接受 VerticalAlign 枚举，共有三个取值：

枚举值	效果	适用场景
`VerticalAlign.Center`	垂直居中对齐	最常用，绝大多数 UI 需求
`VerticalAlign.Top`	顶部对齐	顶部导航栏、标签页标题栏
`VerticalAlign.Bottom`	底部对齐	底部操作栏、底部导航标签

三、完整示例应用详解

我们创建了一个完整的 ArkTS 页面，包含 4 个示例，全方位展示 alignItems 的用法。

3.1 项目结构

entry/src/main/ets/pages/Index.ets

这个文件是应用的入口页面，使用 @Entry 和 @Component 装饰器构建。在 HarmonyOS NEXT API 24 中，@Entry 和 @Component 是 ArkTS 的全局装饰器，无需额外 import。

3.2 整体架构

最外层使用 Scroll 组件包裹 Column，实现整个页面的垂直滚动，确保内容超出屏幕高度时可以滚动查看。内部 Column 依次排列 4 个示例，每个示例由一个标题和对应的 Row 演示组成。

@Entry
@Component
struct Index {
  build() {
    Scroll() {                    // 外层滚动容器
      Column() {                  // 垂直排列所有示例
        // ... 标题
        // ... 示例一
        // ... 示例二
        // ... 示例三
        // ... 示例四
        // ... 底部代码提示
      }
      .width('100%')
      .padding({ top: 8, bottom: 16 })
      .backgroundColor('#FFF5F5F5')
    }
    .width('100%')
    .height('100%')
    .scrollable(ScrollDirection.Vertical)
  }
}

3.3 示例一：不同高度元素垂直居中（核心演示）

这是本文的核心示例。我们创建了一个 Row，内部包含 4 个高度各不相同的 Text 组件：

子组件	高度	颜色	寓意
A	40vp	蓝色 `#4A90D9`	较矮元素
B	70vp	绿色 `#50C878`	最高元素
C	50vp	橙色 `#E67E22`	中等元素
D	30vp	紫色 `#9B59B6`	最矮元素

Row() {
  Text('A').width(50).height(40).backgroundColor('#FF4A90D9')
  Text('B').width(50).height(70).backgroundColor('#FF50C878')
  Text('C').width(50).height(50).backgroundColor('#FFE67E22')
  Text('D').width(50).height(30).backgroundColor('#FF9B59B6')
}
.width('90%')
.height(120)                              // 关键：固定高度大于最高子组件
.backgroundColor('#FFF0F0F0')
.borderRadius(12)
.padding({ left: 12, right: 12 })
.alignItems(VerticalAlign.Center)         // ★ 一行代码实现垂直居中

运行效果： 4 个颜色各异的色块在浅灰色背景的 Row 中，它们的垂直中线完美对齐。尽管 D 只有 30vp 高度而 B 高达 70vp，但它们的中线在同一条水平线上，视觉上整齐划一。

3.4 示例二与示例三：对比呈现

为了帮助读者直观理解不同对齐方式的差异，我们设计了两个对比示例：

示例二 — 顶部对齐（VerticalAlign.Top）：

.alignItems(VerticalAlign.Top)

效果：所有子组件紧贴 Row 的顶部边缘排列。最高元素 B 的上沿与 Row 顶部对齐，其他元素则悬空在下方。

示例三 — 底部对齐（VerticalAlign.Bottom）：

.alignItems(VerticalAlign.Bottom)

效果：所有子组件紧贴 Row 的底部边缘排列。最高元素 B 的下沿与 Row 底部对齐，其他元素悬空在上方。

对比意义： 三个示例使用完全相同的子组件，仅改变 alignItems 的参数，便获得三种截然不同的视觉效果。这种"所见即所得"的特性正是声明式 UI 的魅力所在。

3.5 示例四：真实业务场景

理论讲完了，我们来看实际开发中的常见场景：图标 + 文字 + 箭头 的列表项布局。

Row() {
  Circle()              // 左侧图标
    .width(32).height(32)
    .fill('#FF4A90D9')

  Text('我的收藏')       // 中间标题
    .fontSize(16)
    .fontColor('#FF333333')
    .margin({ left: 10 })

  Blank()               // 弹性空白，将箭头推到最右侧

  Text('>')             // 右侧箭头
    .fontSize(20)
    .fontColor('#FFCCCCCC')
}
.width('90%')
.height(60)                               // 固定行高
.backgroundColor(Color.White)
.borderRadius(12)
.padding({ left: 16, right: 16 })
.alignItems(VerticalAlign.Center)         // ★ 图标、文字、箭头全部垂直居中
.shadow({ radius: 4, color: '#11000000' })

这个模式在设置页面、列表页面、个人中心等场景中非常常见。关键洞察在于：

Circle（圆形图标）高度 32vp
Text（文字）高度由字号自动决定，约 22vp 左右
Text('>')（箭头）高度约 28vp

三者高度不同，但一行 VerticalAlign.Center 即可让它们的中线完美对齐。无需为每个元素单独计算 margin 或 padding 偏移量，极大简化了代码。

我们在示例中连续展示了三个业务条目（我的收藏、我的订单、设置），每个条目的逻辑完全相同，只需更换图标颜色和文字内容，体现了 Row 垂直居中方案的可复用性。

四、HarmonyOS NEXT API 24 中的 API 变化

在编写本文示例时，我们实际遇到了 API 版本适配的问题，这些经验值得分享：

4.1 装饰器无需导入

在较旧的 HarmonyOS 版本中，@Entry、@Component、@State 等装饰器需要从 @kit.ArkUI 导入：

// ❌ API 24 中不需要这样写
import { Component, Entry, State } from '@kit.ArkUI';

在 API 24 中，这些装饰器是 ArkTS 语言的全局关键字，无需任何 import 语句即可直接使用。如果强行导入，编译器会报错：

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

4.2 alignItems 接受 VerticalAlign 而非 ItemAlign

这也是一个重要的 API 调整。在部分文档或早期版本中，Row 的 alignItems 可能接受 ItemAlign 枚举。但在 HarmonyOS NEXT API 24 中，正确的枚举类型是 VerticalAlign：

// ✅ 正确写法
Row() { /* ... */ }
  .alignItems(VerticalAlign.Center)

// ❌ 错误写法（编译不通过）
Row() { /* ... */ }
  .alignItems(ItemAlign.Center)

VerticalAlign 的取值：

VerticalAlign.Center — 垂直居中
VerticalAlign.Top — 顶部对齐
VerticalAlign.Bottom — 底部对齐

4.3 Column 不支持 scrollable 方法

在 API 24 中，Column 组件没有 .scrollable() 方法。如果需要 Column 内容可滚动，必须使用 Scroll 组件包裹：

// ✅ 正确写法
Scroll() {
  Column() {
    // 大量内容...
  }
}
.scrollable(ScrollDirection.Vertical)

// ❌ 错误写法
Column() {
  // 大量内容...
}
.scrollable(ScrollDirection.Vertical)  // Column 没有此方法

五、常见陷阱与最佳实践

5.1 陷阱一：Row 高度未显式设置

问题： 不少开发者写了 alignItems(VerticalAlign.Center) 却发现没有效果。

原因： Row 的默认高度由最高子组件撑开。此时 Row 的上边界紧贴最高元素的顶部，下边界紧贴最高元素的底部，没有多余的垂直空间，居中无从谈起。

解决方案： 显式设置 Row 的 height，确保它大于内部所有子组件的最大高度。

// ✅ 必须设置高度
Row() { /* ... */ }
  .height(120)    // 大于所有子组件的高度
  .alignItems(VerticalAlign.Center)

5.2 陷阱二：父容器未填充满

问题： Row 的父容器高度不够，Row 的高度无法展开。

解决： 确保 Row 的父容器（或根容器）设置了足够的可用空间。通常设置 Column().height('100%') 或使用 .layoutWeight(1)。

5.3 陷阱三：多行文本的高度不确定性

问题： 当 Text 包含多行文本时，其实际高度受 maxLines、文字长度、字体大小等多因素影响，难以精确预知。

解决： 依然使用 VerticalAlign.Center 自动居中，无需手动计算高度。Row 的 height 设置一个足够大的经验值（如 56vp ~ 72vp 适用于大多数列表项）即可。

5.4 最佳实践清单

始终显式设置 Row 的高度：这是垂直居中生效的前提条件。
使用 Blank 实现弹性布局：当需要将部分子元素推到右侧时，Blank() 是最简洁的方案。
优先 VerticalAlign.Center：除非有特殊设计需求（如顶部导航栏用 Top，底部操作栏用 Bottom），否则 Center 是最通用的选择。
合理使用 padding：Row 的 padding 是在容器内部留白，不改变子组件的相对对齐关系。
组合使用 shadow 和 borderRadius：给 Row 添加圆角和阴影，让 UI 更有层次感。

六、垂直居中方案对比

在鸿蒙 ArkTS 中，垂直居中并非只有 alignItems 这一种方式。下表对比了常见的方案：

方案	适用容器	代码	优点	缺点
`alignItems(VerticalAlign.Center)`	Row	`.alignItems(VerticalAlign.Center)`	一行代码，简洁高效	仅适用于 Row
`justifyContent(FlexAlign.Center)`	Column	`.justifyContent(FlexAlign.Center)`	Column 主轴居中	仅适用于 Column
`alignRules`	RelativeContainer	复杂配置	灵活定位	代码量大，可读性差
`position` 绝对定位	Stack	`.position({ x: ..., y: ... })`	精确控制	脱离文档流，需手动计算
`constraintSize` + margin	任意	手动计算	兼容老版本	硬编码，维护困难