鸿蒙ArkTS Text组件全解析：全属性详解+富文本实战

在鸿蒙原生应用开发中，Text组件是最基础、最常用的UI组件之一，承担着文本展示、信息传递的核心作用。无论是简单的文字提示、复杂的文章内容，还是带样式的图文混排，都离不开Text组件的灵活运用。本文将全面梳理鸿蒙Text组件的所有核心属性，结合大量实战示例，讲解基础文本样式配置、富文本实现、图文混排等技巧，帮助开发者快速掌握Text组件的全场景用法，轻松实现多样化的文本展示需求。

核心要点：鸿蒙Text组件支持丰富的样式配置（字体、颜色、对齐、间距等），通过Span子组件可实现富文本效果，结合ImageSpan还能完成图文混排，完全满足日常开发中的文本展示需求。

一、Text组件基础概述

Text组件用于在鸿蒙应用界面中展示文本内容，支持单行、多行文本显示，可通过属性配置文本样式、布局方式，同时支持嵌套Span组件实现富文本效果，适配鸿蒙全设备（手机、平板、智慧屏等）的展示需求。

基础用法：直接在Text组件中传入字符串，即可实现文本展示，默认样式为黑色、16vp字体、左对齐，示例如下：

// 基础文本展示
@Entry
@Component
struct TextBasicDemo {
  build() {
    Column() {
      // 直接传入字符串
      Text('Hello HarmonyOS!')
      // 传入资源文件中的字符串（推荐，便于多语言适配）
      Text($r('app.string.hello_harmony'))
    }
    .padding(20)
    .width('100%')
    .height('100%')
  }
}

接下来，我们将详细拆解Text组件的所有核心属性，结合示例讲解每个属性的使用场景和效果。

二、Text组件全属性详解（附实战示例）

Text组件的属性可分为文本样式属性 、布局属性 、交互属性三大类，下面逐一讲解每个属性的用法、参数及实战示例，覆盖开发中所有常用场景。

1. 文本样式属性（核心，控制文本外观）

文本样式属性用于控制文本的字体、颜色、大小、粗细等外观效果，是Text组件最常用的属性，所有样式属性均可单独使用，也可组合搭配。

（1）fontSize：设置字体大小

作用：控制文本的字体大小，单位支持vp（虚拟像素，推荐）、fp（字体像素）、px（物理像素），默认值为16vp。

示例：不同字体大小的文本展示，适配标题、正文、说明文字等场景。

Text('大标题（24vp）')
  .fontSize(24) // 等价于24vp
Text('正文内容（16vp）')
  .fontSize(16)
Text('说明文字（12vp）')
  .fontSize(12)
Text('使用fp单位（18fp）')
  .fontSize(18)

（2）fontColor：设置文本颜色

作用：控制文本的字体颜色，支持十六进制颜色、rgb/rgba、颜色资源、系统颜色，默认值为黑色（#FF000000）。

示例：多种颜色配置方式，适配不同场景的文本配色。

Text('十六进制颜色（红色）')
  .fontColor('#FF0000') // 支持6位（#FF0000）、8位（#FFFF0000，含透明度）
Text('rgb颜色（绿色）')
  .fontColor('rgb(0, 255, 0)')
Text('rgba颜色（半透明蓝色）')
  .fontColor('rgba(0, 0, 255, 0.5)')
Text('颜色资源（推荐，便于统一管理）')
  .fontColor($r('app.color.primary_color'))
Text('系统颜色（灰色）')
  .fontColor(Color.Grey)

（3）fontWeight：设置字体粗细

作用：控制文本的字体粗细，支持数值（100~900）和预设值（Thin、Light、Normal、Medium、Bold、Black等），默认值为Normal（400）。

示例：不同粗细的文本，适配标题、重点强调等场景。

Text('细体（100）')
  .fontWeight(100)
Text('常规（400，默认）')
  .fontWeight(FontWeight.Normal) // 等价于400
Text('中等粗细（500）')
  .fontWeight(500)
Text('加粗（700）')
  .fontWeight(FontWeight.Bold) // 等价于700
Text('粗体（900）')
  .fontWeight(900)

（4）fontStyle：设置字体样式（斜体/正常）

作用：控制文本是否为斜体，支持两个值：Normal（正常，默认）、Italic（斜体）。

示例：斜体文本与正常文本对比。

Text('正常文本（默认）')
  .fontStyle(FontStyle.Normal)
Text('斜体文本')
  .fontStyle(FontStyle.Italic)

（5）fontFamily：设置字体

作用：控制文本的字体，支持系统字体、自定义字体，默认使用系统默认字体。

示例：系统字体与自定义字体配置（需先将自定义字体文件放入resources/fonts目录）。

// 系统字体
Text('系统默认字体')
  .fontFamily('HarmonyOS Sans SC')
Text('思源黑体')
  .fontFamily('思源黑体')
// 自定义字体（需将字体文件放入resources/fonts目录，命名为my_font.ttf）
Text('自定义字体')
  .fontFamily('my_font')

（6）decoration：设置文本装饰线（下划线/删除线）

作用：为文本添加装饰线，支持Underline（下划线）、LineThrough（删除线）、None（无装饰线，默认），可同时设置装饰线颜色。

示例：下划线、删除线的使用场景（如链接、优惠价）。

Text('下划线文本（链接样式）')
  .decoration({ type: TextDecorationType.Underline, color: '#007AFF' })
Text('删除线文本（优惠价原价）')
  .decoration({ type: TextDecorationType.LineThrough, color: '#999999' })
Text('无装饰线文本（默认）')
  .decoration({ type: TextDecorationType.None })

（7）letterSpacing：设置字间距

作用：控制文本中每个字符之间的间距，单位为vp，支持正数（增大间距）、负数（减小间距），默认值为0。

示例：不同字间距的文本，适配标题、标语等场景。

Text('正常字间距（0）')
  .letterSpacing(0)
Text('增大字间距（2）')
  .letterSpacing(2)
Text('减小字间距（-1）')
  .letterSpacing(-1)
Text('标语（字间距5）')
  .fontSize(20)
  .letterSpacing(5)
  .fontWeight(700)

（8）lineHeight：设置行间距

作用：控制多行文本的行间距，支持固定值（vp）、百分比（基于字体大小），默认值为字体大小的1.2倍。

示例：不同行间距的多行文本，适配文章、说明等场景。

Text('默认行间距\n这是第二行文本，默认行间距为字体大小的1.2倍，阅读体验适中')
  .fontSize(16)
Text('固定行间距（24vp）\n这是第二行文本，固定行间距，适合需要严格控制行高的场景')
  .fontSize(16)
  .lineHeight(24)
Text('百分比行间距（1.5倍）\n这是第二行文本，基于字体大小的1.5倍行间距，阅读体验更舒适')
  .fontSize(16)
  .lineHeight(1.5)

（9）textCase：设置文本大小写

作用：控制英文字母的大小写，支持Normal（正常，默认）、UpperCase（全部大写）、LowerCase（全部小写），仅对英文字符有效。

示例：英文字母大小写转换。

Text('Hello HarmonyOS（正常）')
  .textCase(TextCase.Normal)
Text('Hello HarmonyOS（全部大写）')
  .textCase(TextCase.UpperCase)
Text('Hello HarmonyOS（全部小写）')
  .textCase(TextCase.LowerCase)

2. 布局属性（控制文本布局、换行）

布局属性用于控制Text组件的对齐方式、换行规则、文本溢出处理等，适配不同的页面布局需求。

（1）textAlign：设置文本对齐方式

作用：控制文本在Text组件内的水平对齐方式，支持Left（左对齐，默认）、Right（右对齐）、Center（居中对齐）、Justify（两端对齐，仅多行文本生效）。

示例：不同对齐方式的文本展示。

Text('左对齐（默认），这是一段较长的文本，用于演示对齐效果')
  .fontSize(16)
  .textAlign(TextAlign.Left)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('居中对齐，这是一段较长的文本，用于演示对齐效果')
  .fontSize(16)
  .textAlign(TextAlign.Center)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('右对齐，这是一段较长的文本，用于演示对齐效果')
  .fontSize(16)
  .textAlign(TextAlign.Right)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('两端对齐，这是一段较长的文本，用于演示对齐效果，两端对齐仅在多行文本时生效，可让文本左右两侧都对齐')
  .fontSize(16)
  .textAlign(TextAlign.Justify)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')

（2）maxLines：设置最大行数

作用：控制文本的最大显示行数，超过最大行数的文本将被隐藏，常与textOverflow配合使用。

示例：限制文本最大行数，适配列表、卡片等场景。

Text('这是一段超过两行的文本，用于演示maxLines属性的效果，设置最大行数为2，超过的部分将被隐藏')
  .fontSize(16)
  .maxLines(2)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('这是一段超过一行的文本，设置最大行数为1，用于演示单行文本溢出效果')
  .fontSize(16)
  .maxLines(1)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')

（3）textOverflow：设置文本溢出处理方式

作用：控制文本超过最大行数时的溢出处理方式，支持Clip（直接截断，默认）、Ellipsis（末尾显示省略号）、None（不处理），需与maxLines配合使用。

示例：文本溢出时显示省略号，适配列表标题、摘要等场景。

Text('这是一段超过两行的文本，用于演示textOverflow属性的效果，设置最大行数为2，溢出部分显示省略号')
  .fontSize(16)
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('这是一段超过一行的文本，设置最大行数为1，溢出部分直接截断，不显示省略号')
  .fontSize(16)
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Clip })
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')

（4）wrap：设置文本是否换行

作用：控制文本是否自动换行，支持true（自动换行，默认）、false（不换行，文本将横向溢出）。

示例：换行与不换行的对比效果。

Text('自动换行（默认），这是一段较长的文本，会自动换行显示，适配多行文展示场景')
  .fontSize(16)
  .wrap(true)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('不自动换行，这是一段较长的文本，不会自动换行，会横向溢出Text组件的范围')
  .fontSize(16)
  .wrap(false)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')

（5）padding/margin：内边距/外边距

作用：控制Text组件的内边距（文本与组件边框的间距）和外边距（组件与其他元素的间距），单位为vp，支持单独设置上下左右，也可统一设置。

示例：内边距与外边距的配置。

Text('统一内边距（10vp）')
  .fontSize(16)
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('单独设置上下左右内边距')
  .fontSize(16)
  .padding({ top: 5, right: 10, bottom: 5, left: 10 })
  .backgroundColor('#F5F5F5')
Text('外边距（10vp），与上方组件拉开间距')
  .fontSize(16)
  .margin(10)
  .padding(10)
  .backgroundColor('#F5F5F5')

3. 交互属性（控制文本交互行为）

交互属性用于为Text组件添加交互能力，如点击事件、长按事件、文本选择等，提升用户体验。

（1）onClick：点击事件

作用：为Text组件添加点击事件，点击文本时触发指定的回调函数，适配链接、按钮式文本等场景。

示例：点击文本触发回调，模拟链接跳转。

Text('点击我跳转到详情页（模拟）')
  .fontSize(16)
  .fontColor('#007AFF')
  .decoration({ type: TextDecorationType.Underline })
  .onClick(() => {
    console.log('文本被点击，触发详情页跳转');
    // 实际开发中可添加页面跳转逻辑
  })

（2）onLongPress：长按事件

作用：为Text组件添加长按事件，长按文本时触发指定的回调函数，适配复制、分享等场景。

示例：长按文本触发复制操作。

Text('长按我复制文本内容')
  .fontSize(16)
  .onLongPress(() => {
    console.log('文本被长按，触发复制操作');
    // 实际开发中可添加复制文本到剪贴板的逻辑
  })

（3）selectable：设置文本是否可选择

作用：控制文本是否可被用户选中，支持true（可选中）、false（不可选中，默认），选中后可进行复制、粘贴等操作，适配文章、说明等可复制文本场景。

示例：可选择文本与不可选择文本的对比。

Text('可选择文本，长按可选中并复制内容，适配文章、说明等场景')
  .fontSize(16)
  .selectable(true)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')
Text('不可选择文本（默认），无法被选中，适配普通提示文本')
  .fontSize(16)
  .selectable(false)
  .width('80%')
  .padding(10)
  .backgroundColor('#F5F5F5')

三、富文本实战：嵌套Span组件实现多样化样式

在实际开发中，经常需要对一段文本中的不同部分设置不同的样式（如不同颜色、大小、粗细），此时仅靠Text组件的属性无法实现，需要通过嵌套Span组件来实现富文本效果。

核心原理：Text组件支持嵌套多个Span子组件，每个Span组件可单独设置样式，从而实现同一段文本中不同部分的样式差异化，同时支持嵌套ImageSpan实现图文混排。

1. 基础富文本：多样式文本组合

通过嵌套多个Span组件，为不同文本片段设置不同的样式，适配重点强调、混合配色等场景。

示例1：重点内容加粗、变色，适配通知、提示等场景。

Text() {
  Span('温馨提示：')
    .fontSize(16)
    .fontColor('#FF0000')
    .fontWeight(700)
  Span('请在')
    .fontSize(16)
    .fontColor('#333333')
  Span('24小时内')
    .fontSize(16)
    .fontColor('#007AFF')
    .fontWeight(700)
  Span('完成支付，逾期订单将自动取消，感谢您的配合！')
    .fontSize(16)
    .fontColor('#333333')
}
.padding(10)
.width('90%')
.backgroundColor('#FFF5E6')
.borderRadius(8)

示例2：混合字体大小、颜色、斜体，适配文章标题、摘要等场景。

Text() {
  Span('鸿蒙开发实战：')
    .fontSize(20)
    .fontColor('#000000')
    .fontWeight(700)
  Span('Text组件全解析')
    .fontSize(20)
    .fontColor('#007AFF')
    .fontWeight(700)
  Span('（附富文本示例）')
    .fontSize(16)
    .fontColor('#666666')
    .fontStyle(FontStyle.Italic)
}
.padding(10)

2. 进阶富文本：图文混排（ImageSpan）

通过在Text组件中嵌套ImageSpan组件，可实现图文混排效果，适配表情、图标搭配文本等场景，让文本展示更生动。

注意：使用ImageSpan时，需确保图片资源已放入resources/images目录，支持本地图片和网络图片（需配置网络权限）。

示例1：文本中插入表情图标，适配聊天、提示等场景。

Text() {
  Span('今天天气很好，适合出门游玩')
    .fontSize(16)
    .fontColor('#333333')
  ImageSpan($r('app.media.sun'), { width: 24, height: 24, verticalAlign: VerticalAlign.Middle })
  Span('，记得做好防晒哦！')
    .fontSize(16)
    .fontColor('#333333')
}
.padding(10)

示例2：文本中插入图标，适配操作提示、功能说明等场景。

Text() {
  ImageSpan($r('app.media.tips'), { width: 20, height: 20, verticalAlign: VerticalAlign.Middle })
  Span(' 操作说明：')
    .fontSize(16)
    .fontWeight(700)
    .fontColor('#333333')
  Span('点击')
    .fontSize(16)
    .fontColor('#333333')
  Span('确认按钮')
    .fontSize(16)
    .fontColor('#007AFF')
    .fontWeight(700)
  Span('即可提交表单，提交后无法修改，请仔细核对信息。')
    .fontSize(16)
    .fontColor('#333333')
}
.padding(10)
.width('90%')
.backgroundColor('#F5F5F5')
.borderRadius(8)

3. 高级富文本：Span组件组合使用（多样式+图文混排）

结合Span组件的样式配置和ImageSpan组件，实现复杂的富文本效果，适配文章内容、商品介绍等场景。

Text() {
  Span('商品名称：')
    .fontSize(16)
    .fontColor('#666666')
  Span('鸿蒙原生开发实战教程（全册）')
    .fontSize(18)
    .fontColor('#000000')
    .fontWeight(700)
  Span('\n') // 换行
  Span('原价：')
    .fontSize(14)
    .fontColor('#999999')
  Span('¥199')
    .fontSize(14)
    .fontColor('#999999')
    .decoration({ type: TextDecorationType.LineThrough })
  Span('  优惠价：')
    .fontSize(14)
    .fontColor('#999999')
  Span('¥129')
    .fontSize(18)
    .fontColor('#FF0000')
    .fontWeight(700)
  ImageSpan($r('app.media.hot'), { width: 24, height: 24, verticalAlign: VerticalAlign.Middle })
  Span('\n') // 换行
  Span('商品简介：')
    .fontSize(14)
    .fontColor('#666666')
  Span('涵盖Text组件、富文本、布局等核心知识点，搭配100+实战示例，零基础也能快速上手鸿蒙开发，适合初学者和进阶开发者学习。')
    .fontSize(14)
    .fontColor('#333333')
    .lineHeight(1.5)
}
.padding(15)
.width('90%')
.backgroundColor('#FFFFFF')
.border({ width: 1, color: '#EEEEEE' })
.borderRadius(8)

四、Text组件使用最佳实践与避坑指南

掌握Text组件的属性和富文本用法后，结合开发中的常见场景，遵循以下最佳实践，规避常见坑点，提升开发效率和页面体验。

1. 最佳实践

（1）优先使用资源文件管理文本内容

将文本内容放入resources/strings.json文件中，通过$r('app.string.xxx')引用，便于多语言适配、统一管理和修改，避免硬编码字符串。

示例：strings.json配置与引用。

// strings.json
{
  "hello_harmony": "Hello HarmonyOS!",
  "tips_pay": "请在24小时内完成支付，逾期订单将自动取消"
}
// 引用
Text($r('app.string.hello_harmony'))
Text($r('app.string.tips_pay'))

（2）合理设置行间距和字间距，提升阅读体验

正文文本建议设置1.4~1.5倍的行间距，字间距设置为0或1，避免行间距过大或过小导致阅读疲劳；标题文本可适当增大字间距，提升视觉效果。

（3）文本溢出时优先使用省略号，提升页面整洁度

在列表、卡片等场景中，文本超过最大行数时，建议使用textOverflow: Ellipsis显示省略号，避免文本溢出或截断，提升页面整洁度。

（4）富文本中合理搭配样式，避免过度花哨

富文本的核心是突出重点，避免同一文本中使用过多不同颜色、大小的样式，建议重点内容使用加粗、变色，普通内容保持统一样式，确保视觉协调。

（5）图文混排时控制图片大小，保持与文本对齐

使用ImageSpan时，建议将图片大小设置为与文本字体大小相近，通过verticalAlign属性设置垂直对齐（推荐VerticalAlign.Middle），确保图文排版协调。

2. 常见坑点与避坑方案

（1）坑点1：textAlign属性不生效

原因：Text组件的宽度未设置，默认宽度为内容宽度，此时对齐方式无法体现；或justify对齐方式用于单行文本。

避坑方案：为Text组件设置固定宽度或百分比宽度；justify对齐方式仅用于多行文本，确保文本超过一行。

（2）坑点2：文本溢出省略号不显示

原因：未设置maxLines属性，或textOverflow属性未与maxLines配合使用；或文本未超过maxLines设置的行数。

避坑方案：同时设置maxLines和textOverflow属性，确保文本超过maxLines设置的行数，才能显示省略号。

（3）坑点3：ImageSpan图片不显示

原因：图片资源路径错误、图片文件损坏，或网络图片未配置网络权限（ohos.permission.INTERNET）。

避坑方案：检查图片资源路径是否正确，确保图片文件可用；网络图片需在module.json5中配置网络权限。

（4）坑点4：字间距、行间距设置不生效

原因：字间距（letterSpacing）仅对单行文本生效，行间距（lineHeight）仅对多行文本生效；或属性值设置错误（如使用非数值类型）。

避坑方案：字间距用于单行文本，行间距用于多行文本；确保属性值为数值类型（如16、1.5），避免使用字符串。

（5）坑点5：文本可选择但无法复制

原因：selectable属性设置为true，但未适配鸿蒙系统的剪贴板权限，或文本内容为资源文件中的字符串（需确保字符串可被复制）。

避坑方案：确保selectable属性为true；复杂场景下，可通过长按事件手动实现复制逻辑（调用剪贴板API）。