在鸿蒙原生应用开发中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组件最常用的属性所有样式属性均可单独使用也可组合搭配。1fontSize设置字体大小作用控制文本的字体大小单位支持vp虚拟像素推荐、fp字体像素、px物理像素默认值为16vp。示例不同字体大小的文本展示适配标题、正文、说明文字等场景。Text(大标题24vp) .fontSize(24) // 等价于24vp Text(正文内容16vp) .fontSize(16) Text(说明文字12vp) .fontSize(12) Text(使用fp单位18fp) .fontSize(18)2fontColor设置文本颜色作用控制文本的字体颜色支持十六进制颜色、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)3fontWeight设置字体粗细作用控制文本的字体粗细支持数值100~900和预设值Thin、Light、Normal、Medium、Bold、Black等默认值为Normal400。示例不同粗细的文本适配标题、重点强调等场景。Text(细体100) .fontWeight(100) Text(常规400默认) .fontWeight(FontWeight.Normal) // 等价于400 Text(中等粗细500) .fontWeight(500) Text(加粗700) .fontWeight(FontWeight.Bold) // 等价于700 Text(粗体900) .fontWeight(900)4fontStyle设置字体样式斜体/正常作用控制文本是否为斜体支持两个值Normal正常默认、Italic斜体。示例斜体文本与正常文本对比。Text(正常文本默认) .fontStyle(FontStyle.Normal) Text(斜体文本) .fontStyle(FontStyle.Italic)5fontFamily设置字体作用控制文本的字体支持系统字体、自定义字体默认使用系统默认字体。示例系统字体与自定义字体配置需先将自定义字体文件放入resources/fonts目录。// 系统字体 Text(系统默认字体) .fontFamily(HarmonyOS Sans SC) Text(思源黑体) .fontFamily(思源黑体) // 自定义字体需将字体文件放入resources/fonts目录命名为my_font.ttf Text(自定义字体) .fontFamily(my_font)6decoration设置文本装饰线下划线/删除线作用为文本添加装饰线支持Underline下划线、LineThrough删除线、None无装饰线默认可同时设置装饰线颜色。示例下划线、删除线的使用场景如链接、优惠价。Text(下划线文本链接样式) .decoration({ type: TextDecorationType.Underline, color: #007AFF }) Text(删除线文本优惠价原价) .decoration({ type: TextDecorationType.LineThrough, color: #999999 }) Text(无装饰线文本默认) .decoration({ type: TextDecorationType.None })7letterSpacing设置字间距作用控制文本中每个字符之间的间距单位为vp支持正数增大间距、负数减小间距默认值为0。示例不同字间距的文本适配标题、标语等场景。Text(正常字间距0) .letterSpacing(0) Text(增大字间距2) .letterSpacing(2) Text(减小字间距-1) .letterSpacing(-1) Text(标语字间距5) .fontSize(20) .letterSpacing(5) .fontWeight(700)8lineHeight设置行间距作用控制多行文本的行间距支持固定值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)9textCase设置文本大小写作用控制英文字母的大小写支持Normal正常默认、UpperCase全部大写、LowerCase全部小写仅对英文字符有效。示例英文字母大小写转换。Text(Hello HarmonyOS正常) .textCase(TextCase.Normal) Text(Hello HarmonyOS全部大写) .textCase(TextCase.UpperCase) Text(Hello HarmonyOS全部小写) .textCase(TextCase.LowerCase)2. 布局属性控制文本布局、换行布局属性用于控制Text组件的对齐方式、换行规则、文本溢出处理等适配不同的页面布局需求。1textAlign设置文本对齐方式作用控制文本在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)2maxLines设置最大行数作用控制文本的最大显示行数超过最大行数的文本将被隐藏常与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)3textOverflow设置文本溢出处理方式作用控制文本超过最大行数时的溢出处理方式支持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)4wrap设置文本是否换行作用控制文本是否自动换行支持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)5padding/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组件添加交互能力如点击事件、长按事件、文本选择等提升用户体验。1onClick点击事件作用为Text组件添加点击事件点击文本时触发指定的回调函数适配链接、按钮式文本等场景。示例点击文本触发回调模拟链接跳转。Text(点击我跳转到详情页模拟) .fontSize(16) .fontColor(#007AFF) .decoration({ type: TextDecorationType.Underline }) .onClick(() { console.log(文本被点击触发详情页跳转); // 实际开发中可添加页面跳转逻辑 })2onLongPress长按事件作用为Text组件添加长按事件长按文本时触发指定的回调函数适配复制、分享等场景。示例长按文本触发复制操作。Text(长按我复制文本内容) .fontSize(16) .onLongPress(() { console.log(文本被长按触发复制操作); // 实际开发中可添加复制文本到剪贴板的逻辑 })3selectable设置文本是否可选择作用控制文本是否可被用户选中支持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坑点1textAlign属性不生效原因Text组件的宽度未设置默认宽度为内容宽度此时对齐方式无法体现或justify对齐方式用于单行文本。避坑方案为Text组件设置固定宽度或百分比宽度justify对齐方式仅用于多行文本确保文本超过一行。2坑点2文本溢出省略号不显示原因未设置maxLines属性或textOverflow属性未与maxLines配合使用或文本未超过maxLines设置的行数。避坑方案同时设置maxLines和textOverflow属性确保文本超过maxLines设置的行数才能显示省略号。3坑点3ImageSpan图片不显示原因图片资源路径错误、图片文件损坏或网络图片未配置网络权限ohos.permission.INTERNET。避坑方案检查图片资源路径是否正确确保图片文件可用网络图片需在module.json5中配置网络权限。4坑点4字间距、行间距设置不生效原因字间距letterSpacing仅对单行文本生效行间距lineHeight仅对多行文本生效或属性值设置错误如使用非数值类型。避坑方案字间距用于单行文本行间距用于多行文本确保属性值为数值类型如16、1.5避免使用字符串。5坑点5文本可选择但无法复制原因selectable属性设置为true但未适配鸿蒙系统的剪贴板权限或文本内容为资源文件中的字符串需确保字符串可被复制。避坑方案确保selectable属性为true复杂场景下可通过长按事件手动实现复制逻辑调用剪贴板API。