HarmonyOS NEXT 开发实战ArkUI Text 文本组件完全指南效果一、前言Text是 ArkUI 框架中最基础也最常用的组件之一用于在界面上显示文字内容。无论是简单的标签文案还是复杂的富文本排版Text组件都能胜任。本文将从基础用法出发逐步深入讲解Text组件的核心属性、样式控制、文本装饰、事件交互等知识点并通过多个实战示例帮助你全面掌握 Text 组件的使用技巧。二、基本用法2.1 创建文本Text组件接受三种类型的参数// 方式一直接传入字符串Text(Hello HarmonyOS)// 方式二传入资源引用支持多语言Text($r(app.string.hello))// 方式三无参创建通过子组件 Span 组合内容Text(){Span(Hello )Span(HarmonyOS).fontColor(#FF6B35)}2.2 基础属性速查Text(示例文本).fontSize(16)// 字体大小单位fp默认值 16fp.fontWeight(FontWeight.Normal)// 字体粗细.fontColor(#333333)// 字体颜色.fontFamily(sans-serif)// 字体族.fontStyle(FontStyle.Normal)// 字体风格正常/斜体.letterSpacing(2)// 字符间距.lineHeight(24)// 行高.textAlign(TextAlign.Start)// 文本对齐方式.maxLines(3)// 最大显示行数.textOverflow({overflow:TextOverflow.Ellipsis})// 文本溢出处理三、核心属性详解3.1 字体大小fontSizeText(标题文本).fontSize(28)// 数字类型单位 fpText(正文文本).fontSize(14fp)// 字符串类型Text(说明文本).fontSize($r(app.float.text_size))// 资源引用提示fpfont point是字体专用单位当用户调整系统字体大小时fp单位的字体会随之缩放vp单位则不会。推荐在文本场景使用fp。3.2 字体粗细fontWeightText(正常).fontWeight(FontWeight.Normal)// 400Text(加粗).fontWeight(FontWeight.Bold)// 700Text(中等).fontWeight(FontWeight.Medium)// 500Text(细体).fontWeight(FontWeight.Lighter)// 300Text(自定义).fontWeight(600)// 数字 100-900常用 FontWeight 枚举值枚举值对应数值适用场景FontWeight.Lighter300次要信息、辅助说明FontWeight.Normal400正文内容FontWeight.Medium500副标题、列表标题FontWeight.Bold700大标题、重点强调3.3 字体颜色fontColorText(十六进制颜色).fontColor(#FF6B35)Text(命名颜色).fontColor(Color.Blue)Text(RGBA颜色).fontColor(rgba(255, 107, 53, 0.8))Text(资源引用).fontColor($r(app.color.primary_text))3.4 文本对齐textAlignText(左对齐文本).textAlign(TextAlign.Start)// 左对齐默认.width(100%)Text(居中文本).textAlign(TextAlign.Center)// 居中对齐Text(右对齐文本).textAlign(TextAlign.End)// 右对齐注意textAlign生效需要父容器或自身有足够的宽度否则文本宽度等于内容宽度时对齐方式看不出效果。3.5 字符间距letterSpacingText(标准间距).letterSpacing(0)Text(宽松间距).letterSpacing(4)// 古诗词排版常用Text(紧凑间距).letterSpacing(-0.5)// 英文排版优化3.6 行高lineHeightText(标准行高).fontSize(16).lineHeight(24)// 1.5倍行高阅读体验最佳Text(宽松行高).fontSize(14).lineHeight(26)// 长文本阅读推荐经验值中文正文推荐行高 字号 × 1.5~1.8 倍英文正文推荐行高 字号 × 1.4~1.6 倍。3.7 文本溢出处理当文本内容超出显示区域时可以通过textOverflow和maxLines控制溢出行为Text(这是一段非常长的文本内容超出了显示区域需要截断处理...).maxLines(2)// 最多显示2行.textOverflow({overflow:TextOverflow.Ellipsis})// 超出部分显示省略号.width(300)TextOverflow 枚举值效果说明TextOverflow.None正常换行不截断可能溢出容器TextOverflow.Clip直接截断超出部分被裁切TextOverflow.Ellipsis省略号截断超出部分显示 “…”四、文本装饰4.1 文本装饰线decorationText(下划线文本).decoration({type:TextDecorationType.Underline,color:#FF6B35})Text(删除线文本).decoration({type:TextDecorationType.LineThrough,color:#999999})Text(上划线文本).decoration({type:TextDecorationType.Overline,color:#666666})4.2 文本阴影textShadowText(带阴影的文本).fontSize(24).fontWeight(FontWeight.Bold).textShadow({radius:8,color:rgba(0,0,0,0.3),offsetX:2,offsetY:2})4.3 文本渐变填充gradient通过foregroundLinearGradient实现渐变文字效果Text(渐变文字).fontSize(32).fontWeight(FontWeight.Bold).foregroundLinearGradient({direction:GradientDirection.Right,colors:[[#FF6B35,0.0],[#FF1744,0.5],[#D500F9,1.0]]})五、富文本组合SpanText组件可以包含Span子组件实现同一行内不同文字不同样式的富文本效果Text(){Span(作者).fontSize(14).fontColor(#999999)Span(李白).fontSize(16).fontColor(#333333).fontWeight(FontWeight.Medium)Span(唐代).fontSize(13).fontColor(#AAAAAA)}Span 支持的样式属性属性说明fontSize字体大小fontColor字体颜色fontWeight字体粗细fontFamily字体族fontStyle字体风格decoration文本装饰线letterSpacing字符间距backgroundColor文字背景色六、完整实战示例6.1 示例诗词卡片排版EntryComponentV2struct TextDemo{build(){Column(){// 标题 Text(静夜思).fontSize(30).fontWeight(FontWeight.Bold).fontColor(#1a1a2e).letterSpacing(10).margin({top:40})// 作者信息Span 组合Text(){Span([).fontColor(#999999)Span(唐代).fontColor(#666666).fontWeight(FontWeight.Medium)Span(] ).fontColor(#999999)Span(李白).fontColor(#1a1a2e).fontSize(18).fontWeight(FontWeight.Medium)}.fontSize(16).margin({top:12})// 诗句正文 Column({space:16}){Text(床前明月光).fontSize(20).fontColor(#333333).letterSpacing(4).lineHeight(32)Text(疑是地上霜。).fontSize(20).fontColor(#333333).letterSpacing(4).lineHeight(32)Text(举头望明月).fontSize(20).fontColor(#333333).letterSpacing(4).lineHeight(32)Text(低头思故乡。).fontSize(20).fontColor(#333333).letterSpacing(4).lineHeight(32)}.margin({top:30}).alignItems(HorizontalAlign.Center).width(100%)// 分隔线 Divider().color(#EEEEEE).strokeWidth(1).margin({top:30,bottom:30}).width(60%)// 诗意赏析 Column(){Text(诗意赏析).fontSize(15).fontWeight(FontWeight.Medium).fontColor(#FF6B35).margin({bottom:8})Text(这首诗写的是在寂静的月夜思念家乡的感受。诗人通过描写月光照射在床前的景象联想到秋天的白霜进而抬头望月低头思念远方的故乡。全诗语言朴素自然意境深远是李白的代表作之一。).fontSize(14).fontColor(#666666).lineHeight(24).textAlign(TextAlign.Start)}.width(85%).padding(20).borderRadius(16).backgroundColor(#F8F8F8).alignItems(HorizontalAlign.Start)Blank()}.width(100%).height(100%).backgroundColor(#FFFFFF).alignItems(HorizontalAlign.Center)}}七、Text 组件与交互事件7.1 点击事件Text(点击查看详情).fontSize(16).fontColor(#1976D2).onClick((){// 处理点击事件console.info(文本被点击)})7.2 长按事件Text(长按复制).fontSize(16).gesture(LongPressGesture().onAction((){console.info(触发长按)}))7.3 可复制文本Text(可以长按复制的文本).fontSize(16).copyOption(CopyOptions.LocalDevice)// 允许复制到本地剪贴板八、常用排版场景速查表场景推荐配置页面大标题fontSize(28),fontWeight(Bold),fontColor(#1a1a2e)列表标题fontSize(16),fontWeight(Medium),maxLines(1)Ellipsis正文段落fontSize(14),lineHeight(22),fontColor(#333333)辅助说明fontSize(12),fontColor(#999999)古诗词fontSize(20),letterSpacing(4~8),textAlign(Center)价格数字fontSize(24),fontWeight(Bold),fontColor(#FF4444)链接文本fontColor(#1976D2),decoration(Underline)九、常见问题与最佳实践9.1 fp 与 vp 的区别fpfont point字体专用单位跟随系统字体大小设置缩放vpvirtual pixel虚拟像素单位不跟随系统字体设置推荐文本内容使用fp单位默认即为 fp确保应用支持系统级字体大小调整提升无障碍体验。9.2 多行文本居中Text(第一行\n第二行\n第三行).textAlign(TextAlign.Center)// 行内居中对齐.multilineTextAlignment(TextAlign.Center)// 多行文本整体居中API 79.3 文本自适应缩放当文本可能超出容器宽度时可以使用autoSize让文本自动缩小字号以适应容器Text(这段文本可能很长需要自适应缩放显示).fontSize(20).autoSize({minSize:12,maxSize:20}).width(200)十、总结Text组件是 ArkUI 中最基础且使用频率最高的组件。掌握以下核心要点即可应对大多数文本排版需求知识点关键要点基本创建字符串 / 资源引用 / Span 子组件字体控制fontSize、fontWeight、fontColor、fontFamily排版控制textAlign、letterSpacing、lineHeight溢出处理maxLinestextOverflow装饰效果decoration、textShadow、foregroundLinearGradient富文本Span子组件实现混合样式交互能力onClick、copyOption、gesture参考文档Text - 华为开发者文档