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)

这种写法能保证：

• 主标题最多两行
• 摘要始终一行

在布局里弹性好、对齐规范。

---

🏁 八、总结与建议（项目里必读）

✔ 不管界面多复杂，Text 都是基础
✔ 控制行数 / 超出方式 是最重要的两个属性
✔ 结合布局（Row/Column/Flex） 使用能写出优雅结构
✔ 别直接写硬编码颜色/大小，用设计规范或主题更易维护