鸿蒙5.0开发进阶：UI框架-ArkTS组件（Text）

本文链接：https://blog.youkuaiyun.com/Androidbye/article/details/145114765

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

Text

显示一段文本的组件。

说明

该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

可以包含Span、ImageSpan、SymbolSpan和ContainerSpan子组件。

接口

Text(content?: string | Resource , value?: TextOptions)

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
content	string \| Resource	否	文本内容。包含子组件Span且未设置属性字符串时不生效，显示Span内容，并且此时text组件的样式不生效。默认值：' '
value11+	TextOptions	否	文本组件初始化选项。

参数名

类型

必填

说明

content

string | Resource

否

文本内容。包含子组件Span且未设置属性字符串时不生效，显示Span内容，并且此时text组件的样式不生效。

默认值：' '

value11+

TextOptions

否

文本组件初始化选项。

属性

除支持通用属性，还支持以下属性：

textAlign

textAlign(value: TextAlign)

设置文本段落在水平方向的对齐方式。

文本段落宽度占满Text组件宽度。

可通过align属性控制文本段落在垂直方向上的位置，此组件中不可通过align属性控制文本段落在水平方向上的位置，即align属性中Alignment.TopStart、Alignment.Top、Alignment.TopEnd效果相同，控制内容在顶部，Alignment.Start、Alignment.Center、Alignment.End效果相同，控制内容垂直居中，Alignment.BottomStart、Alignment.Bottom、Alignment.BottomEnd效果相同，控制内容在底部。结合TextAlign属性可控制内容在水平方向的位置。

当textAlign属性设置为TextAlign.JUSTIFY时，需要根据文本内容设置wordBreak属性，且最后一行文本不参与两端对齐，为水平对齐首部效果。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	TextAlign	是	文本段落在水平方向的对齐方式。默认值：TextAlign.Start

参数名

类型

必填

说明

value

TextAlign

是

文本段落在水平方向的对齐方式。

默认值：TextAlign.Start

textOverflow

textOverflow(value: { overflow: TextOverflow })

设置文本超长时的显示方式。

文本截断是按字截断。例如，英文以单词为最小单位进行截断，若需要以字母为单位进行截断，可在字母间添加零宽空格：\u200B。从API version 11开始，建议优先组合wordBreak属性设置为WordBreak.BREAK_ALL方式实现字母为单位进行截断，使用示例4。

当overflow设置为TextOverflow.None、TextOverflow.Clip、TextOverflow.Ellipsis时，需配合maxLines使用，单独设置不生效。设置TextOverflow.None与TextOverflow.Clip效果一样。

当overflow设置为TextOverflow.MARQUEE时，文本在一行内滚动显示，设置maxLines及copyOption属性均不生效。在文本不可滚动时，设置textAlign属性生效；在文本可滚动时，设置textAlign属性不生效。在跑马灯模式下，Text组件clip属性默认为true。属性字符串的CustomSpan不支持跑马灯模式。

从API version 12开始，当overflow设置为TextOverflow.MARQUEE时，支持ImageSpan组件，文本和图片在一行内滚动显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	{overflow: TextOverflow}	是	文本超长时的显示方式。默认值：{overflow: TextOverflow.Clip}

参数名

类型

必填

说明

value

{overflow: TextOverflow}

是

文本超长时的显示方式。

默认值：{overflow: TextOverflow.Clip}

maxLines

maxLines(value: number)

设置文本的最大行数。默认情况下，文本是自动折行的，如果指定此属性，则文本最多不会超过指定的行。如果有多余的文本，可以通过textOverflow来指定截断方式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	文本的最大行数。

lineHeight

lineHeight(value: number | string | Resource)

设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| string \| Resource	是	文本的文本行高。

decoration

decoration(value: DecorationStyleInterface)

设置文本装饰线样式及其颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	DecorationStyleInterface12+	是	文本装饰线样式对象。默认值： { type: TextDecorationType.None, color: Color.Black, style: TextDecorationStyle.SOLID } 说明： style参数不支持卡片能力。

参数名

类型

必填

说明

value

DecorationStyleInterface12+

是

文本装饰线样式对象。

默认值：

{

type: TextDecorationType.None,

color: Color.Black,