ArkTS Text 文本组件详细指南

原创已于 2025-12-18 16:22:05 修改 · 451 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #huawei #鸿蒙

于 2025-12-18 16:19:15 首次发布

「鸿蒙心迹」“2025・领航者闯关记“主题征文活动 10w+人浏览 501人参与

ArkTS Text 文本组件详细指南

鸿蒙第四期开发者活动

在任何界面里，最常见、最基础的组件就是 文本（Text）。它看起来简单，但掌握好它的属性、样式、换行、截断等行为，会让你的页面更规范、显示更稳定。

一、Text 是什么？

在 HarmonyOS ArkTS 的声明式 UI 框架里，Text 是一个基础组件，用于在界面上显示一段文本内容。它不是简单的字符串，而是一个可以被样式化、布局控制、事件绑定的 UI 组件。维基百科

在 ArkUI 里和 Row、Column、Image 一样，Text 是最基本的可渲染组件之一。

Text('Hello World')
  .fontSize(18)
  .fontColor(Color.Black)

📍 二、为什么 Text 很重要？

你做任何 UI 页面，文本几乎无处不在：

标题
副标题
按钮标签
错误提示
价格、计数、时间
富文本段落

因此理解 Text 的属性与表现，是构建优雅 UI 的起点。

✨ 三、Text 的常用属性（逐条解释）

下面每个属性我都配了“为什么要用”和“常见写法”。

🔹 1. `.fontSize(size)`

设置字体大小（统一单位 vp 或数字）。

小标题、正文、细节文字常用不同尺寸规范。

Text('标题')
  .fontSize(20)

Text('正文')
  .fontSize(14)

🔹 2. `.fontColor(color)`

控制文本颜色，大多数时候用设计稿给定的色值。

Text('错误提示')
  .fontColor(0xFFFF3B30)  // red 错误色

🔹 3. `.fontWeight(weight)`

控制字体粗细，对比更明显、更易读。

Text('加粗标题')
  .fontWeight(FontWeight.Bold)

🔹 4. `.maxLines(n) 和 .textOverflow(...)`

当文本可能很长时，你可以控制：

最多显示几行
超过行数时如何显示（省略号/截断）

Text('很长的描述内容...')
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

这在卡片标题、段落摘要场景里非常常见。

🔹 5. `.textAlign(...)`

控制水平对齐方式，常见的值有：

TextAlign.Start（靠左）
TextAlign.Center（居中）
TextAlign.End（靠右）

Text('居中标题')
  .textAlign(TextAlign.Center)

🔹 6. 字体系列、装饰等（可选）

根据设计需求，你可能会用到：

fontStyle（斜体）
textDecoration（下划线/删除线）

这些属性在视觉类界面、强调文字效果中非常有用。

🧱 四、Text 在布局里的行为

ArkTS UI 是一个声明式组件体系，Text 会根据父容器的布局规则参与排布，比如：

Row 里：

Row({ space: 10 }) {
  Text('左侧')
  Text('右侧')
}

Column 里：

Column({ space: 6 }) {
  Text('第一行')
  Text('第二行')
}

无论是 Row/Column/Flex/Stack，Text 都像一个“可布局的元素”去占用空间、对齐、伸缩。

⚠️ 五、常见细节问题与解决

下面是我在开发中最常遇到、也最容易犯的小错误：

✔ 问题 1 — 字太长遮挡别的组件

如果你没有设置 maxLines，长文本会占用太多空间，导致布局跑掉。

解决办法：

Text(longText)
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

✔ 问题 2 — 文本内容换行不对

默认情况下，Text 会按单词/字符换行，但有时你希望更精确的行为：

使用 textAlign
或者放在 Flex/Column 里配合布局权重

✔ 问题 3 — 颜色适配暗色模式

在有“亮/暗模式”的界面里，文本颜色不要写固定黑色，而应该用主题色或变量。

🧠 六、进阶写法（项目里真用得上的）

📌 1. 富文本组合（图标与文字在一行）

有时一行里既有图标又有文本，你不会用一个 Text 就搞定，这时配合 Row/Stack 可以写得很干净：

Row({ space: 6 }) {
  Image($r('icon_info'))
    .width(18).height(18)
  Text('提示信息')
    .fontSize(14)
}

📌 2. 状态动态文本

当文本内容和状态关联时，用状态变量驱动文本自动刷新：

@State private count: number = 0

Text(`已选 ${this.count} 项`)

📌 3. 多语言文本

在项目里要支持国际化，多数情况下你会用资源引用，而不是硬编码：

Text($r('strings.hello'))

📋 七、实战示例：一个典型卡片标题与摘要

这个结构在商品页/推荐页/文章页里极常见：

Column({ space: 4 }) {
  Text('这是一个非常长的标题，可能会换行')
    .fontSize(16)
    .fontWeight(FontWeight.Medium)
    .maxLines(2)
    .textOverflow({ overflow: TextOverflow.Ellipsis })

  Text('这是摘要/副标题，较小号字体')
    .fontSize(13)
    .fontColor(0xFF666666)

这种写法能保证：