ArkTS 文本显示组件（Text / Span）详解
— HarmonyOS 常用基础组件开发指南
在 UI 开发里，文本永远是最基础也是最关键的组成部分。ArkTS 提供的文本显示组件不仅仅用于展示文字，它还支持样式控制、对齐、溢出处理、行数限制等能力，是做界面时必须熟练掌握的基础之一。 developer.huawei.com
一、什么是 Text / Span
Text
Text 是最基础的文本显示组件，用于在屏幕上展示一段文字，它本身支持多种样式属性。官方文档指出：它用于展示用户视图中的文字内容，是最基本的文本显示方式。 developer.huawei.com+1
示例结构：
Text('Hello HarmonyOS')
Span
Span 是 Text 的内联文本子组件，用于在同一段 Text 中对不同片段指定不同样式（比如一个句子部分加粗、部分变色）。它本质上也是一个文本单元，但更灵活。 CSDN博客
二、Text 常用属性与用法（逐条解读）
1) 基本显示属性
文本内容
Text('欢迎来到 HarmonyOS')
就是这样直接写出一段显示文本。
2) 字体大小与颜色
fontSize()调整字体大小fontColor()改变字体颜色
Text('主标题')
.fontSize(18)
.fontColor(0xFF333333)
文本大小与颜色是最基础的视觉控制，可以用 vp/数字/资源引用设置。 developer.huawei.com
3) 字体粗细
使用 fontWeight() 控制字体粗细：
Text('加粗文字')
.fontWeight(FontWeight.Bold)
常见值包括：Normal, Medium, Bold 等。 腾讯云
4) 文本对齐
默认 Text 的对齐方式由父容器决定，但当你显式设置宽度时，可以用 textAlign() 控制水平对齐：
Text('居中显示')
.width('100%')
.textAlign(TextAlign.Center)
对齐属性要在组件有宽度的时候才生效，否则不会产生视觉变化。 腾讯云
5) 溢出与最大行数控制
在卡片、摘要等 UI 场景中，我们经常需要控制文本行数：
Text('这是一个很长的文本...')
.maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })
搭配 maxLines() 和 textOverflow() 使用，可以控制文本最多显示多少行，并在溢出时显示省略号（Ellipsis）。 腾讯云
6) 行高、字间距等进阶样式
lineHeight()控制行间距letterSpacing()调整字母间距
在做段落排版、标题层级区分时非常有用（支持视觉一致性）。 腾讯云
7) 自定义字体
你可以通过 fontFamily() 引用指定字体：
Text('自定义字体')
.fontFamily('HarmonyOS Sans')
默认字体是系统自带的 HarmonyOS Sans。 腾讯云
三、Span：同一 Text 内不同样式的利器
如果你想在同一句话里让一部分文字变色、加粗、或者改变大小，而不想拆成多个 Text、Row，那就用 Span。
例如：
Text() {
Span('普通文字')
Span('强调文字').fontColor(0xFFFF3B30).fontWeight(FontWeight.Bold)
Span('结束语')
}
Span 作为 Text 的子组件，可以继承父 Text 的一些样式，也可以自己覆盖设置，非常适合做“局部样式”处理。 CSDN博客
四、实战场景示例（像项目里写的）
下面是三种常见的 Text/Span 组合写法，你在真实 UI 上非常会用到：
1) 标题 + 副标题 卡片区
Column({ space: 4 }) {
Text('商品名称可能很长，会自动换行')
.fontSize(16)
.fontWeight(FontWeight.Medium)
.maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })
Text('商品副标题/描述')
.fontSize(13)
.fontColor(0xFF888888)
.maxLines(1)
.textOverflow({ overflow: TextOverflow.Ellipsis })
}
这种写法常用于商品卡片、动态流中的文本布局。 腾讯云
2) 混合文本提示（颜色 + 加粗 +普通）
Text() {
Span('总计 ')
Span('¥299.00').fontColor(0xFFFF3B30).fontWeight(FontWeight.Bold)
Span('，含税费')
}
用 Span 分段实现局部强调比拆成多个 Text 更干净。 CSDN博客
3) 小提示 + 图标内联（通过容器组合）
Row({ space: 6, alignItems: ItemAlign.Center }) {
Image($r('icon_info'))
.width(14).height(14)
Text('数据最后更新时间：2025-12-01')
.fontSize(12)
.fontColor(0xFF666666)
}
虽然图标是 Image，但文本与图标组合的场景非常常见。 Medium
五、推荐写法与常见误区
建议 1 — 统一样式组件化
如果多个页面里有“统一的段落标题样式”，建议封装成一个小组件（比如 SectionTitle），避免重复代码。
误区 1 — 不给 Text 限制宽度就设置对齐
如果 Text 没有明确宽度，textAlign() 看不出效果；这时要配合容器布局或者显式 width。 腾讯云
误区 2 — 长文本不控制 MaxLines
长文本如果不加行数限制，在卡片、网格等布局里会一行占满整个高度，视觉会不自然。 腾讯云
六、版本 & API 说明
Text从 API 7 开始支持，该组件用于显示文本。 developer.huawei.com- 更多扩展如 Span 的继承属性、不同版本支持情况，可以在官方 API 参考中查阅（比如继承父 Text 属性如字体、大小等支持情况详见相关文档）。 CSDN博客
七、小结（像人写的总结）
| 特性 | 你何时用 |
|---|---|
Text 基础显示 | 标题 / 段落 / 标签 |
| 颜色 / 大小 / 粗细 | 平衡视觉层级 |
maxLines + textOverflow | 控制长文本空间 |
textAlign | 对齐视觉规范 |
Span 局部样式 | 同一行内强调/变色 |
文本显示不是“写文字而已”，正确的样式控制和排版策略能让 UI 更专业、更易读、更符合设计规范。掌握这些属性，几乎所有文本场景你就能稳稳拿下。 developer.huawei.com+1
