输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API
高级筛选
Created with Pixso.
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
指南与API参考API参考应用框架ArkUI（方舟UI框架）ArkTS组件文本与输入Text

Text

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
更新时间: 2026-09-09 06:54
本文导读
子组件
接口
属性
baselineOffset
bindSelectionMenu11+
caretColor14+
contentTransition20+
copyOption9+
dataDetectorConfig11+
decoration
draggable9+
editMenuOptions12+
ellipsisMode11+
enableAutoSpacing20+
enableDataDetector11+
enableHapticFeedback13+
enableSelectedDataDetector22+
font10+
font12+
fontColor
fontFamily
fontFeature12+
fontSize
fontStyle
fontWeight
fontWeight12+
fontVariations
halfLeading12+
heightAdaptivePolicy10+
incrementalUpdatePolicy
letterSpacing
lineBreakStrategy12+
lineHeight
lineHeightMultiple22+
lineSpacing12+
lineSpacing20+
marqueeOptions18+
maxFontScale12+
maxFontSize
maxLineHeight22+
selectedDragPreviewStyle23+
maxLines
minFontScale12+
minFontSize
minLineHeight22+
minLines22+
includeFontPadding23+
fallbackLineSpacing23+
optimizeTrailingSpace20+
compressLeadingPunctuation23+
orphanCharOptimization
privacySensitive12+
punctuationOverflow
selectedBackgroundColor14+
selection11+
shaderStyle20+
textAlign
textCase
textContentAlign21+
textDirection23+
textIndent10+
tailIndents
textOverflow
textSelectable12+
textShadow10+
textVerticalAlign20+
wordBreak11+
TextSpanType枚举说明11+
TextResponseType枚举说明11+
TextOverflowOptions对象说明18+
事件
onCopy11+
onWillCopy
onTextSelectionChange11+
onMarqueeStateChange18+
TextOptions11+
TextController11+
导入对象
closeSelectionMenu11+
setStyledString12+
getLayoutManager12+
setTextSelection23+
TextMarqueeOptions对象说明18+
MarqueeStartPolicy枚举说明18+
MarqueeUpdatePolicy枚举说明23+
MarqueeState枚举说明18+
示例
示例1（设置文本布局）
示例2（设置文本样式）
示例3（设置文本超长省略）
示例4（设置文本断行及折行）
示例5（设置文本选中和复制）
示例6（设置文本自适应和缩放倍数限制范围）
示例7（设置文本识别）
示例8（文本绑定自定义菜单）
示例9（设置文本特性与行间距）
示例10（获取文本信息）
示例11（实现键盘框选文本）
示例12（文本扩展自定义菜单）
示例13（配置隐私隐藏）
示例14（设置中西文自动间距）
示例15（文本颜色按线性或径向渐变）
示例16（配置除去行尾空格）
示例17（文本垂直对齐）
示例18（文本翻牌动效）
示例19（文本内容区垂直对齐）
示例20（倍数行高和最大最小行高）
示例21（文本设置显示最小行数）
示例22（设置文本选择区域并高亮显示）
示例23（设置行首标点符号压缩和行尾标点符号悬挂）
示例24（设置自适应间距）
示例25（设置文本拖拽时的背板样式）
示例26（设置文本排版方向）
示例27（获取指定坐标和范围对应的文本信息）
示例28（设置文本排版时是否使能孤字优化）
示例29（设置可变字体的属性）
示例30（设置图片预览菜单）
示例31（设置属性字符串段落缓存策略）
示例32（设置文本尾部缩进）
示例33（设置文本选择的AI菜单）
示例34（长按含表情符号文本绘制渐变高亮背景）
展开章节

Text组件用于显示文本内容，支持设置字体样式、文本对齐、行高、装饰线等属性，支持图文混排、文本选择、文本识别等功能，适用于需要展示文本信息的各类应用场景。

说明

  • 该组件从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

  • 如需设置触摸文本组件外部时是否清除文本选中和手柄，可使用setTextSelectionClearPolicy接口。

文本在组件区域显示效果与字体资源相关，默认字体排印可见字体排印视觉指引。

子组件

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

说明

使用子组件实现图文混排场景。

接口

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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 否

文本组件初始化选项，用于配置文本控制器。当需要使用TextController的功能控制文本内容和选择时，传入此参数。

默认值：不设置时，不使用文本控制器。

模型约束： 此接口仅可在Stage模型下使用。

属性

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

布局与对齐

展开
属性 说明
baselineOffset 设置文本基线的偏移量。
halfLeading12+ 设置文本是否垂直居中。与textVerticalAlign同时配置时，halfLeading不生效。
textAlign 设置文本段落在水平方向的对齐方式。当textOverflow设置为TextOverflow.MARQUEE且文本可滚动时，textAlign属性不生效。
textContentAlign21+ 设置文本内容区在组件内的垂直对齐方式。
textVerticalAlign20+ 设置文本段落在垂直方向的对齐方式。

字体样式

展开
属性 说明
decoration 设置文本装饰线样式及其颜色。
font10+ 设置文本样式。
font12+ 设置文本样式，支持设置字体配置项。
fontColor 设置字体颜色。
fontFamily 设置字体族。
fontFeature12+ 设置文字特性效果，比如数字等宽的特性。
fontSize 设置字体大小。自适应字号生效时，fontSize设置不生效。
fontStyle 设置字体样式。
fontWeight 设置文本的字体粗细。
fontWeight12+ 设置文本字重，支持设置字体配置项。
fontVariations 设置可变字体的属性。起始版本： 26.0.0
letterSpacing 设置文本字符间距。
shaderStyle20+ 设置文本渐变或纯色效果。
textCase 设置文本大小写。
textShadow10+ 设置文字阴影效果。

文本溢出、断行与折行

展开
属性 说明
ellipsisMode11+ 设置省略位置。
lineBreakStrategy12+ 设置折行规则。
marqueeOptions18+ 设置文本跑马灯模式的配置项。
textOverflow 设置文本超长时的显示方式。
wordBreak11+ 设置断行规则。
punctuationOverflow

设置是否启用行尾标点符号悬挂。

起始版本： 26.0.0

行与段落

展开
属性 说明
enableAutoSpacing20+ 设置是否开启中文与西文的自动间距。
lineHeight 设置文本的行高。
lineHeightMultiple22+ 设置文本的行高倍数。
lineSpacing12+ 设置文本的行间距。
lineSpacing20+ 设置文本的行间距。当不配置LineSpacingOptions时，首行上方和尾行下方默认会有行间距。当与lineHeightMultiple同时设置且lineHeightMultiple使用有效值时，仅lineHeightMultiple生效。
maxLineHeight22+ 设置文本的最大行高。
maxLines 设置文本的最大行数。
minLineHeight22+ 设置文本的最小行高。
minLines22+ 设置文本显示的最小行数。
optimizeTrailingSpace20+ 优化行尾空格。
textIndent10+ 设置首行文本缩进。
tailIndents

设置文本尾部缩进。

起始版本： 26.0.0

字体自适应

展开
属性 说明
heightAdaptivePolicy10+ 设置文本自适应布局调整字号的方式。
maxFontScale12+ 设置文本最大的字体缩放倍数。
maxFontSize 设置文本最大显示字号。
minFontScale12+ 设置文本最小的字体缩放倍数。
minFontSize 设置文本最小显示字号。

文本选择与复制

展开
属性 说明
caretColor14+ 设置文本组件选中区域手柄颜色。
copyOption9+ 设置组件是否支持文本可复制粘贴。
draggable9+ 设置选中文本拖拽效果。
selectedBackgroundColor14+ 设置文本选中高亮颜色。
selection11+ 设置选中区域。
textSelectable12+ 设置是否支持文本可选择、可获焦。

文本识别

展开
属性 说明
dataDetectorConfig11+ 设置文本识别配置。
enableDataDetector11+ 设置是否进行文本实体识别，可自动识别电话号码、网址、邮箱、地址、日期等。
enableSelectedDataDetector22+ 设置是否对选中文本进行实体识别。

自定义菜单

展开
属性 说明
bindSelectionMenu11+ 设置自定义选择菜单。
editMenuOptions12+ 设置自定义菜单扩展项。

其他功能

展开
属性 说明
contentTransition20+ 文本动效属性。
enableHapticFeedback13+ 设置是否开启触控反馈。
incrementalUpdatePolicy

设置文本渲染的增量更新策略。

起始版本： 26.0.0
privacySensitive12+ 设置是否支持卡片敏感隐私信息。

以下是详细的接口说明：

baselineOffset

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

baselineOffset(value: number | ResourceStr)

设置文本基线的偏移量，可用于调整文本与其他元素（如图片、图标）的基线对齐，或在图文混排、数学公式、化学公式等需要精确垂直对齐的特殊排版场景中使用。未通过该接口设置时，默认偏移量为0。

正数内容向上偏移，负数向下偏移。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | ResourceStr 是

文本基线的偏移量。设置该值为百分比时，按0显示。

单位：fp

从API version 20开始，支持Resource类型。

bindSelectionMenu11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

bindSelectionMenu(spanType: TextSpanType, content: CustomBuilder, responseType: TextResponseType, options?: SelectionMenuOptions)

设置自定义选择菜单。未通过该接口设置时，默认菜单类型为TextSpanType.TEXT，响应类型为TextResponseType.LONG_PRESS。

bindSelectionMenu的长按响应时长为600ms，bindContextMenu的长按响应时长为800ms，当两者同时绑定且触发方式均为长按时，优先响应bindSelectionMenu。

自定义菜单超长时，建议内部嵌套使用Scroll组件，避免键盘被遮挡。

从API版本26.0.0开始，文本组件调用该接口时，options中的menuType属性传入MenuType.PREVIEW_MENU，设置图片预览菜单的能力生效。

如果要使用图片预览菜单，需要同时把spanType设置为TextSpanType.IMAGE，responseType设置为TextResponseType.LONG_PRESS，options中的menuType设置为MenuType.PREVIEW_MENU才会生效。

当copyOption为CopyOptions.None时，设置图片预览菜单将不会生效。

说明

该接口不支持在attributeModifier中调用。

通过editMenuOptions设置文本选择菜单时，保留系统默认的风格，触发菜单弹出的条件不变。

通过bindSelectionMenu设置文本选择菜单时，风格由开发者定义，触发菜单弹出的条件由开发者定义。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
spanType TextSpanType 是 选择菜单的类型。
content CustomBuilder 是 选择菜单的内容。
responseType TextResponseType 是 选择菜单的响应类型。
options SelectionMenuOptions 否

选择菜单的配置选项，用于自定义选择菜单的行为。包含菜单出现、消失、显示、隐藏等回调配置项。

默认值：不设置时，使用系统默认的选择菜单配置。

caretColor14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

caretColor(color: ResourceColor)

设置文本组件选中区域手柄颜色。未通过该接口设置时，默认选中手柄颜色为'#007DFF'（蓝色）。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
color ResourceColor 是 文本选中手柄颜色。

contentTransition20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

contentTransition(transition: Optional<ContentTransition>)

可以设置为数字翻牌动效NumericTextTransition。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
transition Optional<ContentTransition> 是

文本动效属性，用于配置文本内容变化时的过渡动画效果。可设置为数字翻牌动效NumericTextTransition，实现数字变化时的翻牌动画效果。

值为undefined时，无翻牌效果。

copyOption9+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

copyOption(value: CopyOptions)

设置组件是否支持文本可复制粘贴。未通过该接口设置时，默认值为CopyOptions.None，不支持文本可复制粘贴。

多个属性的功能依赖copyOption的设置，包括selection、setTextSelection、draggable、enableSelectedDataDetector、textSelectable等，具体依赖条件请参考各属性说明。

从API version 20开始，当Text组件执行复制操作时，会将HTML格式的内容添加到剪贴板中。

  • 当Text组件包含子组件时，仅支持Span和ImageSpan子组件向剪贴板中添加HTML格式的内容。

  • 设置Text组件的属性字符串时，请参考属性字符串toHtml接口文档，以了解支持转换为HTML的范围。

设置copyOption为CopyOptions.InApp或者CopyOptions.LocalDevice时：

  • 长按文本，会弹出文本选择菜单，可选中文本并进行复制、全选操作。

  • 默认情况下，长按选中文本可拖拽。若要取消此功能，可将 draggable 设置为 false。

  • 若需要支持Ctrl+C复制，需同时设置textSelectable为TextSelectableMode.SELECTABLE_FOCUSABLE。

此时Text会监听onClick事件，手势事件为非冒泡事件，若需要点击Text组件区域响应父组件的点击手势事件，建议在父组件上使用parallelGesture绑定手势识别，也可参考示例7（设置文本识别）。

由于卡片没有长按事件，此场景下长按文本，不会弹出文本选择菜单。

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

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

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

参数：

展开
参数名 类型 必填 说明
value CopyOptions 是 组件是否支持文本可复制粘贴。

dataDetectorConfig11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

dataDetectorConfig(config: TextDataDetectorConfig)

设置文本识别配置，可配置识别类型、实体显示样式，以及是否开启长按预览等。

需配合enableDataDetector一起使用，设置enableDataDetector为true时，dataDetectorConfig的配置才能生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
config TextDataDetectorConfig 是 文本识别配置对象，用于配置文本识别的具体行为。可配置识别类型（如电话号码、网址、邮箱、地址、日期等）、实体显示样式，以及是否开启长按预览等。需配合enableDataDetector一起使用。

decoration

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

decoration(value: DecorationStyleInterface)

设置文本装饰线样式及其颜色。未通过该接口设置时，默认文本装饰线样式为：

{

type: TextDecorationType.None,

color: Color.Black,

style: TextDecorationStyle.SOLID

}

说明

当文字的下边缘轮廓与装饰线位置相交时，会触发下划线避让规则，下划线将在这些字符处避让文字。常见"gjyqp"等英文字符。

当装饰线颜色设置为Color.Transparent时，装饰线会显示为每行第一个字的字体颜色。设置为透明色16进制值"#00FFFFFF"时，装饰线会显示为透明色。

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

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

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

参数：

展开
参数名 类型 必填 说明
value DecorationStyleInterface12+ 是

文本装饰线样式对象。

说明：

style参数不支持卡片能力。

draggable9+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

draggable(value: boolean)

设置选中文本拖拽效果。未通过该接口设置时，默认选中文本不可拖拽。

不能和onDragStart事件同时使用。

当draggable设置为true时，需配合CopyOptions使用，设置copyOptions为CopyOptions.InApp或者CopyOptions.LocalDevice，支持对选中文本的拖拽及复制到输入框。

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

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

参数：

展开
参数名 类型 必填 说明
value boolean 是

选中文本拖拽效果。

true表示选中文本可拖拽，false表示不可拖拽。

editMenuOptions12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

editMenuOptions(editMenu: EditMenuOptions)

设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。

调用disableMenuItems或disableSystemServiceMenuItems接口屏蔽文本选择菜单内的系统服务菜单项时，editMenuOptions接口内回调方法onCreateMenu的入参列表中不包含被屏蔽的菜单选项。

说明

通过editMenuOptions设置文本选择菜单时，保留系统默认的风格，触发菜单弹出的条件不变。

通过bindSelectionMenu设置文本选择菜单时，风格由开发者定义，触发菜单弹出的条件由开发者定义。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
editMenu EditMenuOptions 是 扩展菜单选项，用于自定义文本选择菜单的扩展项。可设置扩展项的文本内容、图标、回调方法等配置，允许开发者添加自定义菜单项。

ellipsisMode11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

ellipsisMode(value: EllipsisMode)

设置省略位置。未通过该接口设置时，默认在行尾省略（EllipsisMode.END）。

ellipsisMode属性需要与overflow设置为TextOverflow.Ellipsis以及maxLines属性一起使用，单独设置ellipsisMode属性不生效。

EllipsisMode.START和EllipsisMode.CENTER仅在单行文本超长时生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value EllipsisMode 是 省略位置。

enableAutoSpacing20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

enableAutoSpacing(enabled: Optional<boolean>)

设置是否开启中文与西文的自动间距。未通过该接口设置时，默认不开启中文与西文的自动间距。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enabled Optional<boolean> 是

是否开启中文与西文的自动间距。

true为开启自动间距，false为不开启。

值为undefined时，不开启中文与西文的自动间距。

enableDataDetector11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

enableDataDetector(enable: boolean)

设置是否进行文本特殊实体识别，可自动识别文本中的电话号码、网址、邮箱、地址、日期等实体信息，适用于聊天消息、评论内容、文章正文等需要智能识别和交互的场景。未通过该接口设置时，默认不进行文本特殊实体识别。当enableDataDetector设置为true时，识别特殊实体。

所识别实体的样式如下，即字体颜色改为蓝色、并添加蓝色下划线。

收起
自动换行
深色代码主题
复制
  1. color: '#ff007dff'
  2. decoration:{
  3.   type: TextDecorationType.Underline,
  4.   color: '#ff007dff',
  5.   style: TextDecorationStyle.SOLID
  6. }
说明

  • 设备底层需要具备文本识别能力，该接口才能生效。

  • 当textOverflow设置为TextOverflow.MARQUEE时，不进行文本特殊实体识别。

  • 当copyOption设置不为CopyOptions.None且textSelectable设置为TextSelectableMode.UNSELECTABLE时，仍然具有通过菜单复制特殊实体的能力，但不具备选择文本的能力。

  • 手势点击和鼠标右键点击实体，会根据实体类型弹出对应的实体操作菜单，鼠标左键点击实体会直接响应菜单的第一个选项。

  • 当copyOption设置为CopyOptions.None时，点击实体弹出的菜单不包含翻译、分享和搜索选项。

  • 从API version 20开始，支持选中文本后识别实体，在文本选择菜单与鼠标右键菜单中显示对应菜单选项。菜单选项包括TextMenuItemId中的url（打开链接）、email（新建邮件）、phoneNumber（呼叫）、address（导航至该位置）、dateTime（新建日程提醒）。选中文本后识别实体弹出对应菜单选项，要求在选中范围内包括一个完整的AI实体，才能展示对应的选项。例如，实体是https://developer.huawei.com时，只选中com，菜单不会显示打开链接选项。

  • 从API version 20开始，支持在文本选择菜单中显示“问问小艺”选项。当copyOption设置为CopyOptions.LocalDevice或CopyOptions.CROSS_DEVICE(deprecated)时，选中文本后：

    • 如果enableDataDetector设置为false，显示问问小艺选项。
    • 如果enableDataDetector设置为true，此时选中范围内，没有一个AI实体，显示问问小艺选项。
    • 如果enableDataDetector设置为true，此时选中范围内，有一个以上的AI实体，显示问问小艺选项。
    • 如果enableDataDetector设置为true，此时选中范围内，恰好有一个AI实体，展示TextMenuItemId中的对应的选项，此时不显示问问小艺选项。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enable boolean 是

是否可进行文本特殊实体识别。

true表示可识别，false表示不可识别。

enableHapticFeedback13+

Phone13+PC/2in113+Tablet13+TV19+Wearable18+

enableHapticFeedback(isEnabled: boolean)

设置是否开启触控反馈。未通过该接口设置时，默认开启触控反馈。

开启触控反馈时，需要在工程的module.json5配置文件中配置requestPermissions字段开启振动权限，配置如下：

收起
自动换行
深色代码主题
复制
  1. "requestPermissions": [
  2.   {
  3.     "name": "ohos.permission.VIBRATE"
  4.   }
  5. ]
说明

从API version 18开始，该接口支持在attributeModifier中调用。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
isEnabled boolean 是

是否开启触控反馈。

true表示开启，false表示不开启。

enableSelectedDataDetector22+

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

enableSelectedDataDetector(enable: boolean | undefined)

设置是否对选中文本进行实体识别。该接口依赖设备底层应具有文本识别能力，否则设置不会生效。未通过该接口设置时，默认对选中文本进行实体识别。

启用后可识别选区中的邮件、电话、网址、日期、地址等，并在文本选择菜单中展示对应的AI菜单项。默认启用AI菜单功能。

AI菜单功能启用时，在组件中选中文本后，文本选择菜单能够展示对应的AI菜单项，包括TextMenuItemId中的url（打开链接）、email（新建邮件）、phoneNumber（呼叫）、address（导航前往）、dateTime（新建日程）。

AI菜单生效时，选中范围内需包括且仅包括一个完整的AI实体，才能展示对应的选项。该菜单项与TextMenuItemId中的askAI菜单项不同时出现。

需要CopyOptions为CopyOptions.LocalDevice或CopyOptions.CROSS_DEVICE时，本功能生效。

在SelectionContainer跨节点选中场景中该属性无效，在文本选择菜单中不会展示对应的AI菜单项。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enable boolean | undefined 是

是否对选中文本进行实体识别。

true：开启识别，false：关闭识别。默认值为：true。

取值为undefined时，按默认值处理。

font10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

font(value: Font)

设置文本样式。未通过该接口设置时，使用系统默认字体样式配置。

包括字体大小、字体粗细、字体族和字体风格。

仅Text组件生效，其子组件不生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value Font 是 文本样式。

font12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

font(fontValue: Font, options?: FontSettingOptions)

设置文本样式，支持设置字体配置项。

仅Text组件生效，其子组件不生效。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
fontValue Font 是 设置文本样式。
options FontSettingOptions 否

设置字体配置项。

默认值：不设置时，使用默认字体配置，详见FontSettingOptions。

fontColor

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontColor(value: ResourceColor)

设置字体颜色。未通过该接口设置时，默认字体颜色为'#e6182431'（深灰色，不透明度为90%）。Wearable设备上默认字体颜色为'#c5ffffff'（白色，不透明度为77%）。

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

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

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

参数：

展开
参数名 类型 必填 说明
value ResourceColor 是 字体颜色。

fontFamily

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontFamily(value: string | Resource)

设置字体族。未通过该接口设置时，默认字体为'HarmonyOS Sans'。Wearable设备上默认字体也为'HarmonyOS Sans'。

说明

可以使用loadFontSync注册自定义字体。

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

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

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

参数：

展开
参数名 类型 必填 说明
value string | Resource 是 字体族。使用多个字体时，请用逗号','分隔，字体的优先级按顺序生效。例如：'Arial,HarmonyOS Sans'。

fontFeature12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontFeature(value: string)

设置文字特性效果，比如数字等宽的特性。

格式为：normal | <feature-tag-value>

<feature-tag-value>的格式为：<string> [ <integer> | on | off ]

<feature-tag-value>的个数可以有多个，中间用','隔开。

例如，使用等宽数字的输入格式为："ss01" on。

说明

不支持Text内同时存在文本内容和Span或ImageSpan子组件。如果同时存在，只显示Span或ImageSpan内的内容。

字体排版引擎会对开发者传入的宽度width进行向下取整，保证是整型像素后进行排版。如果向上取整，可能会出现文字右侧被截断。

当多个Text组件在Row容器内布局且没有设置具体的布局分配信息时，Text会以Row的最大尺寸进行布局。如果需要子组件主轴累加的尺寸不超过Row容器主轴的尺寸，可以设置layoutWeight或者是以Flex布局来约束子组件的主轴尺寸。

系统默认字体支持的liga连字：Th fb ff fb ffb ffh ffi ffk ffl fh fi fk fl rf rt rv rx ry。常导致Span、属性字符串的效果不符合预期，关闭liga连字特性可以规避。

文字特性效果与使用的字体文件密切相关。例如，8标点挤压功能需要字体文件中字符支持"ss08"特性，否则无法压缩，在当前系统默认字体中右侧标点符号及感叹号、顿号、问号均不生效。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value string 是 文字特性效果，格式为：normal | <feature-tag-value>。<feature-tag-value>的格式为：<string> [<integer> | on | off]，多个之间用','隔开。例如："ss01" on。

fontFeature属性列表：

设置fontFeature属性，fontFeature是OpenType字体的高级排版能力，如支持连字、数字等宽等特性，一般用在自定义字体中，其能力需要字体本身支持。

更多fontFeature能力介绍可参考font-feature-settings property和OpenType Features。

fontSize

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontSize(value: number | string | Resource)

设置字体大小。未通过该接口设置时，默认字体大小为16fp。Wearable设备上默认字体大小为15fp。

说明

自适应字号生效时，fontSize设置不生效。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | string | Resource 是 字体大小。fontSize为number类型时，使用fp单位。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。不支持设置百分比字符串。

fontStyle

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontStyle(value: FontStyle)

设置字体样式。未通过该接口设置时，默认字体样式为FontStyle.Normal。Wearable设备上默认字体样式也为FontStyle.Normal。

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

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

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

参数：

展开
参数名 类型 必填 说明
value FontStyle 是 字体样式。

fontWeight

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontWeight(value: number | FontWeight | ResourceStr)

设置文本的字体粗细，设置过大可能会在不同字体下有截断。未通过该接口设置时，默认字体粗细为FontWeight.Normal。Wearable设备上默认字体粗细为FontWeight.Regular。

仅Text组件生效，其子组件不生效。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | FontWeight | ResourceStr 是

文本的字体粗细。

number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular”、“medium”，分别对应FontWeight中相应的枚举值。设置过大可能会在不同字体下有截断。传入超出取值范围或不符合间隔要求的值时取默认值。

从API version 20开始，支持Resource类型。

fontWeight12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontWeight(weight: number | FontWeight | ResourceStr, options?: FontSettingOptions)

设置文本字重，支持设置字体配置项。设置过大可能会在不同字体下有截断。fontVariations属性的优先级高于本属性，同时设置时以fontVariations的值为准。未通过该接口设置时，默认文本字重为FontWeight.Normal。Wearable设备上默认文本字重为FontWeight.Regular。

仅Text组件生效，其子组件不生效。常见问题参考设置enableVariableFontWeight为true后字重不能跟随设置调节。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
weight number | FontWeight | ResourceStr 是

设置文本字重

number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如“400”，以及“bold”、“bolder”、“lighter”、“regular”、“medium”，分别对应FontWeight中相应的枚举值。设置过大可能会在不同字体下有截断。

传入超出取值范围的值时取默认值。传入不符合间隔要求的值时，若设置fontWeightConfigs的enableVariableFontWeight为true，使用传入值；若设置为false，使用默认值。

从API version 20开始，支持Resource类型。
options FontSettingOptions 否

设置字体配置项，用于启用可变字重调节功能。当需要使用可变字体的字重属性进行精细调节时传入此参数（设置enableVariableFontWeight为true）。不传入时使用默认字体配置（禁用可变字重调节，仅支持整百字重值）。

enableVariableFontWeight为false时禁用可变字重调节，weight取整百值时字重为weight，非整百值时字重为400；enableVariableFontWeight为true时启用可变字重调节，weight取任意整数时字重为weight。

fontVariations

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

fontVariations(fontVariations: Array<FontVariation>)

设置可变字体的属性。

起始版本： 26.0.0

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
fontVariations Array<FontVariation> 是 可变字体的属性数组，数组成员为可变字体的各种属性。fontVariations属性的优先级高于fontWeight。

halfLeading12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

halfLeading(halfLeading: boolean)

设置文本是否垂直居中。未通过该接口设置时，默认文本不平分至行的顶部与底部。

说明

与textVerticalAlign同时配置时，halfLeading不生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
halfLeading boolean 是

设置文本是否垂直居中。与textVerticalAlign同时配置时，halfLeading不生效。

true表示将行间距平分至行的顶部与底部，false则不平分。

heightAdaptivePolicy10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

heightAdaptivePolicy(value: TextHeightAdaptivePolicy)

设置文本自适应布局调整字号的方式。未通过该接口设置时，默认文本自适应高度的方式为TextHeightAdaptivePolicy.MAX_LINES_FIRST。

规则如下：

收起
自动换行
深色代码主题
复制
  1. graph TD
  2.   A[文本自适应布局] --> B{模式选择}
  3.   B -->|MAX_LINES_FIRST| C[优先用maxLines调整高度]
  4.   C --> D{布局是否超过约束?}
  5.   D -->|是| E[在minFontSize~maxFontSize范围内缩小字体以显示更多文本]
  6.   D -->|否| F[保持当前布局]
  7.   B -->|MIN_FONT_SIZE_FIRST| G[优先用minFontSize调整高度]
  8.   G --> H{能否一行显示?}
  9.   H -->|是| I[在minFontSize~maxFontSize范围内增大字体至最大]
  10.   H -->|否| J[按minFontSize显示]
  11.   B -->|LAYOUT_CONSTRAINT_FIRST| K[优先用布局约束调整高度]
  12.   K --> L{布局是否超过约束?}
  13.   L -->|是| M[缩小字体以满足约束]
  14.   M --> N{缩小到minFontSize后仍超约束?}
  15.   N -->|是| O[删除超过布局约束的行]
  16.   N -->|否| F
  17.   L -->|否| F

  • MAX_LINES_FIRST模式：优先使用maxLines属性来调整文本高度。如果使用maxLines属性的布局大小超过了布局约束，则尝试在minFontSize和maxFontSize的范围内缩小字体以显示更多文本。

  • MIN_FONT_SIZE_FIRST模式：优先使用minFontSize属性来调整文本高度。如果使用minFontSize属性可以将文本布局在一行中，则尝试在minFontSize和maxFontSize的范围内增大字体并使用最大限度的字体大小在一行内显示，否则按minFontSize显示。

  • LAYOUT_CONSTRAINT_FIRST模式：优先使用布局约束来调整文本高度。如果布局大小超过布局约束，则尝试在minFontSize和maxFontSize的范围内缩小字体以满足布局约束。如果将字体大小缩小到minFontSize后，布局大小仍然超过布局约束，则删除超过布局约束的行。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value TextHeightAdaptivePolicy 是 文本自适应高度的方式。

incrementalUpdatePolicy

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

incrementalUpdatePolicy(policy: IncrementalUpdatePolicy | undefined)

设置文本渲染的增量更新策略。未通过该接口设置时，默认为IncrementalUpdatePolicy.NONE。

该接口仅在Text内容包含属性字符串（StyledString）时生效。

起始版本： 26.0.0

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
policy IncrementalUpdatePolicy | undefined 是

文本渲染的增量更新策略。

设置为undefined时，按IncrementalUpdatePolicy.NONE处理。

letterSpacing

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

letterSpacing(value: number | ResourceStr)

设置文本字符间距。未通过该接口设置时，默认文本字符间距为0。

设置该值为百分比时，按默认值显示。设置该值为0时，按默认值显示。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

当取值为负值时，文字会被压缩。负值过小时会将组件内容区大小压缩为0，导致内容无法显示。

对每个字符生效，包括行尾字符。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | ResourceStr 是

文本字符间距。

单位：fp

从API version 20开始，支持Resource类型。

lineBreakStrategy12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

lineBreakStrategy(strategy: LineBreakStrategy)

设置折行规则。该属性在wordBreak不等于WordBreak.BREAK_ALL的时候生效，且不支持连词符。未通过该接口设置时，默认折行规则为LineBreakStrategy.GREEDY。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
strategy LineBreakStrategy 是 文本的折行规则。具体值及其说明请参考LineBreakStrategy。

lineHeight

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

lineHeight(value: number | string | Resource)

设置文本行高。

当与lineHeightMultiple同时设置且lineHeightMultiple使用有效值时，lineHeight的设置不生效，以lineHeightMultiple为准。

设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

说明

特殊字符字体高度远超出同行的其他字符高度时，文本框出现截断、遮挡、内容相对位置发生变化等不符合预期的显示异常，需要开发者调整组件高度、行高等属性，修改对应的页面布局。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | string | Resource 是 文本行高。number类型时单位为fp。

lineHeightMultiple22+

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

lineHeightMultiple(value: number | undefined)

使用倍数模式设置文本的行高。

设置行高为入参（value）与字高（fontHeight）的乘积。

说明

当lineHeightMultiple使用有效值和lineHeight或lineSpacing同时设置时，仅lineHeightMultiple生效。lineHeightMultiple小于0时，lineHeightMultiple不生效，使用lineHeight和lineSpacing设置行高和行间距。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value number | undefined 是

使用行高的倍数数值。

取值范围：[0, +∞)

说明：

- 设置的值小于0时，lineHeightMultiple不生效。

- 设置的值等于0时，等效于设置为1，表现为行高没有变化。

- 支持小数输入。

- 值为undefined时，使用默认行高高度。

lineSpacing12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

lineSpacing(value: LengthMetrics)

设置文本的行间距，设置值小于0时，取默认值0。未通过该接口设置时，默认行间距为0。

当与lineHeightMultiple同时设置且lineHeightMultiple使用有效值时，lineSpacing的设置不生效，以lineHeightMultiple为准。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value LengthMetrics 是

文本的行间距。

取值范围：[0, +∞)。设置值小于0时，取默认值0。

lineSpacing20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

lineSpacing(value: LengthMetrics, options?: LineSpacingOptions)

设置文本的行间距。当不配置LineSpacingOptions时，首行上方和尾行下方默认会有行间距。

当与lineHeightMultiple同时设置且lineHeightMultiple使用有效值时，lineSpacing的设置不生效，以lineHeightMultiple为准。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value LengthMetrics 是 文本的行间距。设置值不大于0时，取默认值0。
options LineSpacingOptions 否

设置行间距配置项。

默认值：{ onlyBetweenLines: false }

marqueeOptions18+

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

marqueeOptions(options: Optional<TextMarqueeOptions>)

设置文本跑马灯模式的配置项。

当textOverflow设置为TextOverflow.MARQUEE时，marqueeOptions的设置才能生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
options Optional<TextMarqueeOptions> 是

当Text组件的textOverflow属性设置为MARQUEE时，可通过marqueeOptions设置跑马灯动效具体的属性，如开关、步长、循环次数、方向等。

取值为undefined时，按TextMarqueeOptions中的默认值处理。

maxFontScale12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

maxFontScale(scale: number | Resource)

设置文本最大的字体缩放倍数。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
scale number | Resource 是

文本最大的字体缩放倍数。

取值范围：[1, +∞)

说明：

设置的值小于1时，按值为1处理，其余异常值默认不生效。

maxFontSize

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

maxFontSize(value: number | string | Resource)

设置文本最大显示字号。

string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

需配合minFontSize以及maxLines或布局大小限制使用，单独设置不生效。

自适应字号生效时，fontSize设置不生效。

maxFontSize小于等于0或者maxFontSize小于minFontSize时，自适应字号不生效，此时按照fontSize属性的值生效，未设置时按照其默认值生效。

从API version 18开始支持在子组件和属性字符串上生效，未设置字号的部分会自适应。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | string | Resource 是

文本最大显示字号。

取值范围：大于0且大于等于minFontSize。

单位：fp

说明：

设置的值≤0或小于minFontSize时，自适应字号不生效，此时按照fontSize属性的值生效。

maxLineHeight22+

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

maxLineHeight(value: LengthMetrics | undefined)

设置文本的最大行高，设置值不大于0时，最大行高不受限制。未通过该接口设置时，最大行高不受限制（值为undefined）。

maxLineHeight小于minLineHeight时，maxLineHeight按照minLineHeight属性的值生效。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value LengthMetrics | undefined 是

文本的最大行高，不支持百分比。

设置的值不大于0时按0处理，设置为0时，最大行高不受限制。

取值为undefined时，不生效。

selectedDragPreviewStyle23+

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

selectedDragPreviewStyle(value: SelectedDragPreviewStyle | undefined)

设置文本拖拽时的背板样式。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value SelectedDragPreviewStyle | undefined 是

文本拖拽时的背板样式。

设置为undefined时：背板颜色跟随主题，浅色模式显示白色，深色模式显示黑色。

maxLines

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

maxLines(value: number)

设置文本的最大行数。与minLines同时配置时，最小行数显示范围不会超过maxLines设置的限制。

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

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

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

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

参数：

展开
参数名 类型 必填 说明
value number 是

文本的最大行数。

说明：

取值范围：[0, INT32_MAX]

设置为0时，不显示文本内容。

minFontScale12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

minFontScale(scale: number | Resource)

设置文本最小的字体缩放倍数。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
scale number | Resource 是

文本最小的字体缩放倍数。

取值范围：[0, 1]

说明：

设置的值小于0时按0处理，大于1时按1处理，其余异常值默认不生效。

minFontSize

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

minFontSize(value: number | string | Resource)

设置文本最小显示字号。

string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

需配合maxFontSize以及maxLines或布局大小限制使用，单独设置不生效。

自适应字号生效时，fontSize设置不生效。

minFontSize小于或等于0时，自适应字号不生效，此时按照fontSize属性的值生效，未设置时按照其默认值生效。

从API version 18开始，支持在子组件和属性字符串上生效，未设置字号的部分会自适应。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | string | Resource 是

文本最小显示字号。

取值范围：大于0。

单位：fp

说明：

设置的值≤0时，自适应字号不生效，此时按照fontSize属性的值生效。

minLineHeight22+

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

minLineHeight(value: LengthMetrics | undefined)

设置文本的最小行高，设置值不大于0时，取默认值0。当maxLineHeight的设置值小于minLineHeight时，maxLineHeight会按照minLineHeight的值生效。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value LengthMetrics | undefined 是

文本的最小行高，不支持百分比。

设置的值不大于0时按0处理。

取值为undefined时，不生效。

minLines22+

Phone22+PC/2in122+Tablet22+TV22+Wearable22+

minLines(minLines: Optional<number>)

设置文本显示的最小行数。

如果实际文本高度小于最小行数对应的高度，最后显示高度为最小行数对应的高度。

与maxLines同时配置时，最小行数对应的显示高度不会超过最大行数对应的高度限制。

如果文本设置了constraintSize，那么组件最后显示高度会在constraintSize约束内。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
minLines Optional<number> 是

文本最小行数。

取值范围：[0, INT32_MAX]

设置的值小于0时按0处理。

值为undefined时，最小行数无限制。

说明：

与maxLines同时配置时，最小行数对应的显示高度不会超过最大行数对应的高度限制。

includeFontPadding23+

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

includeFontPadding(include: Optional<boolean>)

设置是否在首行和尾行增加间距以避免文字截断。不通过该接口设置，默认不增加间距。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
include Optional<boolean> 是

是否在首行和尾行增加间距以避免文字截断。

true表示在首行和尾行增加间距；false表示在首行和尾行不增加间距。

undefined表示在首行和尾行不增加间距。

fallbackLineSpacing23+

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

fallbackLineSpacing(enabled: Optional<boolean>)

针对多行文字叠加，支持行高基于文字实际高度自适应。此接口仅当行高小于文字实际高度时生效。不通过该接口设置，默认行高不基于文字实际高度自适应。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enabled Optional<boolean> 是

行高是否基于文字实际高度自适应。

true表示行高基于文字实际高度自适应；false表示行高不基于文字实际高度自适应。

undefined表示行高不基于文字实际高度自适应。

optimizeTrailingSpace20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

optimizeTrailingSpace(optimize: Optional<boolean>)

设置是否在文本布局过程中优化每行末尾的空格，可解决行尾空格影响对齐显示效果问题。未通过该接口设置时，默认不优化每行末尾的空格。

设置Text.optimizeTrailingSpace为true时：

  • 多行、单行、图文混排等多种情况下均会优化行尾空格（TextAlign.Center或TextAlign.End时，优化效果明显）；

  • 纯空格文本时，修饰线、阴影、背景色跟随空格文本显示；

  • 行首空格不在优化范围内，行尾文本强制换行，每行行尾空格根据组件宽度优化行尾空格。

当纯空格文本设置优化行尾空格optimizeTrailingSpace为true时，不允许同时设置文本背景色backgroundColor、空格装饰线decoration和对齐textAlign三个属性。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
optimize Optional<boolean> 是

是否优化每行末尾的空格。

true表示优化末尾空格，false则不优化。

值为undefined时，不优化末尾空格。

compressLeadingPunctuation23+

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

compressLeadingPunctuation(enabled: Optional<boolean>)

设置是否开启行首标点符号压缩。

说明

  • 行首标点符号默认不压缩。

  • 支持压缩的标点符号，请参考ParagraphStyle的行首压缩的标点范围。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enabled Optional<boolean> 是

是否开启行首标点符号压缩。

true表示开启行首标点符号压缩；false表示不开启行首标点符号压缩；undefined表示不开启。

orphanCharOptimization

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

orphanCharOptimization(enabled: Optional<boolean>)

设置文本排版时是否使能孤字优化。不通过该接口设置，默认不使能孤字优化。

孤字优化通过更高效地处理孤立字符（段落尾行首字符）来改善文本布局。使能后，它会调整换行点以尽可能避免孤立字符。孤字优化特性需在wordBreak为非BREAK_ALL并且待排版文本首个TextStyle的locale为“zh-Hans”或“zh-Hant”时生效。

起始版本： 26.0.0

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enabled Optional<boolean> 是

段落最后一行是否使能孤字优化。

true表示使能孤字优化，false表示不使能孤字优化。

值为undefined或null时，不使能孤字优化。

privacySensitive12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

privacySensitive(supported: boolean)

设置是否支持卡片敏感隐私信息。未通过该接口设置时，默认不支持卡片敏感隐私信息。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
supported boolean 是

是否支持卡片敏感隐私信息。

true表示支持卡片敏感隐私信息，隐私模式下文字将被遮罩为横杠"-"样式；false表示不支持卡片敏感隐私信息，隐私模式下文字正常显示。

说明：

设置为null则表示不敏感。

进入隐私模式需要卡片框架支持。隐私遮罩的类型可以通过obscured配置。

punctuationOverflow

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

punctuationOverflow(enabled: Optional<boolean>)

设置是否启用行尾标点符号悬挂。不通过该接口设置，默认标点符号不悬挂。

起始版本： 26.0.0

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
enabled Optional<boolean> 是

是否启用行尾标点符号悬挂。

true表示启用行尾标点符号悬挂，false表示不启用行尾标点符号悬挂。设置为undefined或null时，不启用标点符号悬挂。

selectedBackgroundColor14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

selectedBackgroundColor(color: ResourceColor)

设置文本选中高亮颜色。如果未设置不透明度或设置为完全不透明，默认使用20%不透明度。未通过该接口设置时，默认文本选中高亮颜色为'#007DFF'（蓝色）。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
color ResourceColor 是 文本选中高亮颜色。

selection11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

selection(selectionStart: number, selectionEnd: number)

设置选中区域。未通过该接口设置时，默认不设置选中区域（selectionStart和selectionEnd均为-1）。

选中区域高亮且显示手柄和文本选择菜单。

当copyOption设置为CopyOptions.None时，设置selection属性不生效。

当textOverflow设置为TextOverflow.MARQUEE时，设置selection属性不生效。

当selectionStart大于等于selectionEnd时不选中。可选范围为[0, textSize]，其中textSize为文本内容最大字符数，入参小于0时处理为0，大于textSize时处理为textSize。

当selectionStart或selectionEnd位于截断的不可见区域时，文本不选中。当clip设置为false时，超出父组件的文本可以被选中。

可通过onTextSelectionChange接口获取选中区域位置变化结果。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
selectionStart number 是

所选文本的起始位置。

取值范围：[0, textSize]，其中textSize为文本内容最大字符数。入参小于0时处理为0，大于textSize时处理为textSize。
selectionEnd number 是

所选文本的结束位置。

取值范围：[0, textSize]，其中textSize为文本内容最大字符数。入参小于0时处理为0，大于textSize时处理为textSize。

shaderStyle20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

shaderStyle(shader: ShaderStyle)

可以显示为径向渐变RadialGradientStyle或线性渐变LinearGradientStyle或纯色ColorShaderStyle的效果，shaderStyle的优先级高于fontColor和AI识别，纯色建议使用fontColor。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
shader ShaderStyle 是

径向渐变或线性渐变或纯色。

根据传入的参数区分处理径向渐变RadialGradientStyle或线性渐变LinearGradientStyle或纯色ColorShaderStyle，最终设置到Text文本上显示为渐变色效果。

说明：

当设置为径向渐变RadialGradientStyle时，若RadialGradientOptions的center参数设置到组件范围外时，可将repeating参数设置为true，此时渐变效果会更明显。

textAlign

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textAlign(value: TextAlign)

设置文本段落在水平方向的对齐方式。未通过该接口设置时，默认文本段落在水平方向的对齐方式为TextAlign.Start。Wearable设备上默认为TextAlign.Center。

当textOverflow设置为TextOverflow.MARQUEE且文本可滚动时，textAlign属性不生效。

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

可通过align属性控制文本段落在垂直方向上的位置，此组件中不可通过align属性控制文本段落在水平方向上的位置，具体效果如下：

  • Alignment.TopStart、Alignment.Top、Alignment.TopEnd：内容顶部对齐。

  • Alignment.Start、Alignment.Center、Alignment.End：内容垂直居中。

  • Alignment.BottomStart、Alignment.Bottom、Alignment.BottomEnd：内容底部对齐。

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

说明

textAlign只能调整文本整体的布局，不影响字符的显示顺序。若需要调整字符的显示顺序，请参考镜像状态字符对齐。

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

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

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

参数：

展开
参数名 类型 必填 说明
value TextAlign 是

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

说明：

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

textCase

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textCase(value: TextCase)

设置文本大小写。未通过该接口设置时，默认文本大小写行为为TextCase.Normal。

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

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

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

参数：

展开
参数名 类型 必填 说明
value TextCase 是 文本大小写。

textContentAlign21+

Phone21+PC/2in121+Tablet21+TV21+Wearable21+

textContentAlign(textContentAlign: Optional<TextContentAlign>)

设置文本内容区在组件内的垂直对齐方式。

此接口可以在文本内容区高度大于组件高度时生效，确保文本内容区的对齐方式正确显示。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
textContentAlign Optional<TextContentAlign> 是

文本内容区在组件内的垂直对齐方式。

默认(undefined和异常值情况下)和align属性设置为Center效果一致。

textDirection23+

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

textDirection(direction: TextDirection | undefined)

指定文本排版方向，未通过该接口设置时，默认文本排版方向遵循组件布局方向。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
direction TextDirection | undefined 是

文本排版方向。

设置为undefined时，按照TextDirection.DEFAULT处理，表现为文本排版方向遵循组件布局方向。

textIndent10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textIndent(value: Length)

设置首行文本缩进。未通过该接口设置时，默认首行文本缩进为0。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value Length 是

首行文本缩进。

单位：fp

取值范围：大于等于0。设置负数时，按默认值处理。

tailIndents

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

tailIndents(value: Optional<LengthMetrics | Array<LengthMetrics>>)

设置文本尾部缩进。未通过该接口设置时，文本尾部缩进为0fp。

起始版本： 26.0.0

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value Optional<LengthMetrics | Array<LengthMetrics>> 是

指定文本每一行尾部缩进。当提供一个单独的LengthMetrics值时，所有行共享相同的尾部缩进；当提供一个数组时，第i个元素指定第i行的尾部缩进；如果文本行数超过数组长度，则数组中的最后一个元素将用于剩余的行。不支持百分比。

取值范围：大于等于0。设置负数时，按默认值处理。

textOverflow

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textOverflow(options: TextOverflowOptions)

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

当TextOverflowOptions设置为TextOverflow.None、TextOverflow.Clip或TextOverflow.Ellipsis时：

当TextOverflowOptions设置为TextOverflow.MARQUEE时：

  • 文本在一行内滚动显示。

  • 设置maxLines、copyOption、selection属性均不生效，且不能进行文本特殊实体识别（即enableDataDetector设置enable为true时不生效）。

  • Text组件clip属性默认为true。

  • 属性字符串的CustomSpan不支持跑马灯模式。

  • textAlign属性的生效规则：当文本不可滚动时，textAlign属性生效；当文本可滚动时，textAlign属性不生效。

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

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

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

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

参数：

展开
参数名 类型 必填 说明
options TextOverflowOptions 是 文本超长显示方式配置对象，用于配置文本超长时的显示方式，包含overflow属性指定截断、省略号或跑马灯等显示行为。

textSelectable12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textSelectable(mode: TextSelectableMode)

设置是否支持文本可选择、可获焦。未通过该接口设置时，默认文本可选择、不可获焦（TextSelectableMode.SELECTABLE_UNFOCUSABLE）。

需配合copyOption使用。当copyOption设置为CopyOptions.None时，设置textSelectable属性不生效。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
mode TextSelectableMode 是 文本是否支持可选择、可获焦。

textShadow10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

textShadow(value: ShadowOptions | Array<ShadowOptions>)

设置文字阴影效果。

不支持ShadowOptions对象中的type、fill字段和color字段的智能取色模式。

从API version 11开始，该接口支持以数组形式入参，实现多重文字阴影。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value ShadowOptions | Array<ShadowOptions>11+ 是 文字阴影效果，用于配置文字阴影的视觉表现。ShadowOptions包含radius（阴影半径）、color（阴影颜色）、offsetX（水平偏移）、offsetY（垂直偏移）等配置项。不支持type、fill字段和color字段的智能取色模式。从API version 11开始支持以数组形式入参，实现多重文字阴影。

textVerticalAlign20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

textVerticalAlign(textVerticalAlign: Optional<TextVerticalAlign>)

设置文本段落在垂直方向的对齐方式。未通过该接口设置时，默认文本段落在垂直方向的对齐方式为TextVerticalAlign.BASELINE。

说明
  • 与halfLeading同时配置时，halfLeading不生效。
  • 一个段落下使用同一字号必须同时设置行高lineHeight或者同一个段落不同字号文本混排时才有效果差异，否则设置了该属性任意枚举值和未设置该属性都是一样的排版效果。属性字符串TextStyle中的SuperscriptStyle上下角标样式仅在TextVerticalAlign属性值为TextVerticalAlign.BASELINE时生效，其余垂直对齐方式下上下角标文本和普通文本表现一致，无上下角标效果。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
textVerticalAlign Optional<TextVerticalAlign> 是

文本段落在垂直方向的对齐方式。

默认值：TextVerticalAlign.BASELINE

取值为undefined时，按照TextVerticalAlign.BASELINE处理，对齐文本基线。

wordBreak11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

wordBreak(value: WordBreak)

设置断行规则。未通过该接口设置时，默认断行规则为WordBreak.BREAK_WORD。

默认情况下，不调用wordBreak或者设置WordBreak.BREAK_WORD时，文本截断按字进行。例如，英文以单词为最小单位进行截断。

WordBreak.BREAK_ALL与{overflow: TextOverflow.Ellipsis}、maxLines组合使用，可实现英文单词按字母截断，超出部分以省略号显示。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value WordBreak 是 断行规则。

TextSpanType11+枚举说明

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Span类型信息。

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 值 说明
TEXT 0

Span为文字类型。

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

Span为图像类型。

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

Span为图文混合类型。

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

注册此类型菜单但未注册TEXT、IMAGE、MIXED菜单时，文字类型、图片类型、图文混合类型都会触发并显示此类型对应的菜单。

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

菜单类型的匹配顺序如下。例如，用户长按文本时，根据以下规则查找：

  1. 查找是否注册了TextSpanType.TEXT、TextResponseType.LONG_PRESS菜单
  2. 查找是否注册了TextSpanType.TEXT、TextResponseType.DEFAULT菜单
  3. 查找是否注册了TextSpanType.DEFAULT、TextResponseType.LONG_PRESS菜单
  4. 查找是否注册了TextSpanType.DEFAULT、TextResponseType.DEFAULT菜单

TextResponseType11+枚举说明

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

选择菜单的响应类型。

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 值 说明
RIGHT_CLICK 0

通过鼠标右键触发菜单弹出。

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

通过长按触发菜单弹出。

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

通过鼠标选中触发菜单弹出。

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

注册此类型的菜单，但未注册RIGHT_CLICK、LONG_PRESS、SELECT时，右键、长按、鼠标、selection选中均会触发并显示此类型对应的菜单。

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

菜单类型的匹配顺序如下。例如，用户长按文本时，根据以下规则查找：

  1. 查找是否注册了TextSpanType.TEXT、TextResponseType.LONG_PRESS菜单
  2. 查找是否注册了TextSpanType.TEXT、TextResponseType.DEFAULT菜单
  3. 查找是否注册了TextSpanType.DEFAULT、TextResponseType.LONG_PRESS菜单
  4. 查找是否注册了TextSpanType.DEFAULT、TextResponseType.DEFAULT菜单

TextOverflowOptions18+对象说明

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

文本超长显示方式对象。

说明

为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。

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

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
overflow7+ TextOverflow 否 否

文本超长时的显示方式。

默认值：TextOverflow.Clip

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

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

事件

除支持通用事件外，还支持以下事件：

onCopy11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onCopy(callback:(value: string) => void)

长按文本内部区域弹出剪贴板后，点击剪贴板复制按钮，触发该回调。目前只有文本可以复制。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value string 是 复制的文本内容。

onWillCopy

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

onWillCopy(callback: Callback<string, boolean>)

在进行复制操作前，触发该回调。

说明

onWillCopy和onCopy形成will/did时序模式：

  • onWillCopy在复制操作前触发，可通过返回false拦截复制操作；返回true则允许复制，随后触发onCopy。
  • onCopy在复制操作完成后触发，无法拦截。
  • 两者可以同时使用，onWillCopy用于拦截控制，onCopy用于获取复制结果。

起始版本： 26.0.0

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
callback Callback<string, boolean> 是 string为将要被复制的文本内容；boolean表示当前文本是否允许被复制，true：允许文本被复制；false：不允许文本被复制。

onTextSelectionChange11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void)

文本选择的位置发生变化时，触发该回调。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
selectionStart number 是 所选文本的起始位置。
selectionEnd number 是 所选文本的结束位置。

onMarqueeStateChange18+

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

onMarqueeStateChange(callback: Callback<MarqueeState>)

跑马灯动画进行到特定的阶段时，触发该回调。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
callback Callback<MarqueeState> 是 通过callback参数指定触发回调的状态，状态由MarqueeState枚举定义，例如开始滚动、完成一次滚动、滚动完成或停止滚动。

TextOptions11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Text初始化参数。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
controller TextController 否 否 文本控制器。

TextController11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Text组件的控制器。

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

模型约束： 此接口仅可在Stage模型下使用。

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

导入对象

收起
自动换行
深色代码主题
复制
  1. controller: TextController = new TextController()

closeSelectionMenu11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

closeSelectionMenu(): void

关闭自定义选择菜单或系统默认选择菜单。

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

模型约束： 此接口仅可在Stage模型下使用。

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

setStyledString12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

setStyledString(value: StyledString): void

触发绑定或更新属性字符串。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
value StyledString 是

属性字符串。

说明：

StyledString的子类MutableStyledString也可以作为入参值。
说明

多次调用setStyledString，会用新的入参覆盖已绑定的属性字符串，而不是叠加新的入参。

属性字符串通过controller绑定时，需要等待布局完成后，绑定生效。当measure和setStyledString同时使用，开发者需要通过@ohos.arkui.inspector (布局回调)判断布局完成，再绑定属性字符串。

在API version 14及以下版本，开发者调用TextController的setStyledString接口设置属性字符串，如果调用时TextController还未绑定对应的Text，则此次设置无效。

从API version 15开始，TextController会保存设置的属性字符串。当TextController已经和Text绑定，则Text会自动设置属性字符串，显示对应的样式。

这一区别体现在aboutToAppear中设置属性字符串，API 14及以下版本不生效，API 15及以上版本生效，推荐用法请参考创建并应用StyledString和MutableStyledString。

getLayoutManager12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

getLayoutManager(): LayoutManager

获取布局管理器对象。

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

模型约束： 此接口仅可在Stage模型下使用。

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

返回值：

展开
类型 说明
LayoutManager

布局管理器对象，用于获取文本布局信息，包括行数、字形位置、行信息、字符绘制区域等。

说明：

当TextController还未绑定Text组件，或绑定的Text组件已被销毁/卸载时，会返回undefined。

setTextSelection23+

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

setTextSelection(selectionStart: number | undefined, selectionEnd: number | undefined, options?: SelectionOptions): void

设置文本选择区域并高亮显示。

说明

当copyOption设置为CopyOptions.None时，设置setTextSelection不生效。

当textOverflow设置为TextOverflow.MARQUEE时，设置setTextSelection不生效。

当selectionStart大于等于selectionEnd时不选中。可选范围为[0, textSize]，其中textSize为文本内容最大字符数，入参小于0时处理为0，大于textSize时处理为textSize。

当selectionStart或selectionEnd位于截断的不可见区域时，文本不选中。clip设置为false时，超出父组件的文本选中区域生效。

如果设备为PC/2in1，即使options被赋值为MenuPolicy.SHOW，调用setTextSelection也不弹出菜单。

当emoji表情被选中区域截断时，若表情的起始位置包含在设置的文本选中区域内，该表情就会被选中。

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

模型约束： 此接口仅可在Stage模型下使用。

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

参数：

展开
参数名 类型 必填 说明
selectionStart number | undefined 是

文本选择区域起始位置。

取值范围：[0, +∞），值为负数或undefined时按0处理。
selectionEnd number | undefined 是

文本选择区域结束位置。

取值范围：[0, +∞），值为负数或undefined时按0处理。
options SelectionOptions 否

选中文字时的配置。

默认值：SelectionOptions中MenuPolicy.DEFAULT

TextMarqueeOptions18+对象说明

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

Marquee初始化参数。

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
start boolean 否 否

控制跑马灯进入播放状态。

true表示播放，false表示不播放。

元服务API： 从API version 18开始，该接口支持在元服务中使用。
step number 否 是

滚动动画文本滚动步长。

单位：vp

取值范围：(0, 文本宽度]。设置小于等于0的值时按默认值处理。

默认值：4.0vp

元服务API： 从API version 18开始，该接口支持在元服务中使用。
spacing23+ LengthMetrics 否 是

两轮跑马灯之间的间距。单位：vp。当LengthMetrics对象的unit属性为LengthUnit.PERCENT时，当前设置不生效，按默认值处理。

默认值：48.0vp

元服务API： 从API version 23开始，该接口支持在元服务中使用。
loop number 否 是

设置重复滚动的次数，小于等于零时无限循环。

默认值：-1

元服务API： 从API version 18开始，该接口支持在元服务中使用。
fromStart boolean 否 是

设置文本从头开始滚动或反向滚动。

true表示从头开始滚动，false表示反向滚动。

默认值：true

元服务API： 从API version 18开始，该接口支持在元服务中使用。
delay number 否 是

设置每次滚动的时间间隔。

取值范围：[0, +∞)。设置负数时按默认值处理。

默认值：0

单位：毫秒

元服务API： 从API version 18开始，该接口支持在元服务中使用。
fadeout boolean 否 是

设置文字超长时的渐隐效果。

true表示支持渐隐效果，false表示不支持渐隐效果。

当Text内容超出显示范围时，未完全展现的文字边缘将应用渐隐效果。若两端均有文字未完全显示，则两端同时应用渐隐效果。在渐隐效果开启状态下，clip属性将自动锁定为true，不允许设置为false。

默认值：false

元服务API： 从API version 18开始，该接口支持在元服务中使用。
marqueeStartPolicy MarqueeStartPolicy 否 是

设置跑马灯启动策略，该属性值生效需将start设置为true。

默认值：TV设备上默认值为MarqueeStartPolicy.ON_FOCUS，其他设备默认值为MarqueeStartPolicy.DEFAULT

元服务API： 从API version 18开始，该接口支持在元服务中使用。
marqueeUpdatePolicy23+ MarqueeUpdatePolicy 否 是

跑马灯组件属性更新后，跑马灯的滚动策略。

当跑马灯为播放状态，且文本内容宽度超过跑马灯组件宽度时，该属性生效。

默认值：MarqueeUpdatePolicy.DEFAULT

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

MarqueeStartPolicy18+枚举说明

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

Marquee的滚动方式，可选择默认持续滚动或条件触发滚动。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 值 说明
DEFAULT 0 默认持续滚动。
ON_FOCUS 1 获焦以及鼠标悬浮时开始滚动。

MarqueeUpdatePolicy23+枚举说明

Phone23+PC/2in123+Tablet23+TV23+Wearable23+

跑马灯组件属性更新后，跑马灯的滚动策略。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 值 说明
DEFAULT 0 跑马灯组件属性更新后，从开始位置，运行跑马灯效果。
PRESERVE_POSITION 1 跑马灯组件属性更新后，保持当前位置，运行跑马灯效果。

MarqueeState18+枚举说明

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

Marquee状态回调的返回值。

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

模型约束： 此接口仅可在Stage模型下使用。

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

展开
名称 值 说明
START 0 跑马灯滚动开始。
BOUNCE 1 完成一次跑马灯滚动，如果循环次数不是1，将会多次返回。
FINISH 2 跑马灯全部循环次数完成或跑马灯停止滚动（例如TextMarqueeOptions中start被设置为false）。

示例

示例1（设置文本布局）

该示例通过textAlign、lineHeight、baselineOffset、halfLeading（从API version 12开始）属性展示了文本布局的效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Extend(Text)
  3. function style(textAlign: TextAlign) {
  4.   .textAlign(textAlign)
  5.   .fontSize(12)
  6.   .border({ width: 1 })
  7.   .padding(10)
  8.   .width('100%')
  9.   .margin(5)
  10. }
  11. 

  12. @Entry
  13. @Component
  14. struct TextExample1 {
  15.   @State changeTextAlignIndex: number = 0;
  16.   @State textAlign: TextAlign[] = [TextAlign.Start, TextAlign.Center, TextAlign.End];
  17.   @State textAlignStr: string[] = ['Start', 'Center', 'End'];
  18. 

  19.   build() {
  20.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
  21.       // 设置文本水平方向对齐方式
  22.       // 单行文本
  23.       Text('textAlign').fontSize(9).fontColor(0xCCCCCC)
  24.       Text(`TextAlign set to ${this.textAlignStr[this.changeTextAlignIndex]}.`)
  25.         .style(this.textAlign[this.changeTextAlignIndex])
  26. 

  27.       // 多行文本
  28.       Text(`This is the text content with textAlign set to ${this.textAlignStr[this.changeTextAlignIndex]}.`)
  29.         .style(this.textAlign[this.changeTextAlignIndex])
  30.         .margin(5)
  31. 

  32.       Row() {
  33.         Button('当前TextAlign类型：' + this.textAlignStr[this.changeTextAlignIndex]).onClick(() => {
  34.           this.changeTextAlignIndex++;
  35.           if (this.changeTextAlignIndex > (this.textAlignStr.length - 1)) {
  36.             this.changeTextAlignIndex = 0;
  37.           }
  38.         })
  39.       }.justifyContent(FlexAlign.Center).width('100%')
  40. 

  41.       // 设置文本行高
  42.       Text('lineHeight').fontSize(9).fontColor(0xCCCCCC)
  43.       Text('This is the text with the line height set. This is the text with the line height set.')
  44.         .style(TextAlign.Start)
  45.       Text('This is the text with the line height set. This is the text with the line height set.')
  46.         .style(TextAlign.Start)
  47.         .lineHeight(20)
  48. 

  49.       // 设置文本基线偏移
  50.       Text('baselineOffset').fontSize(9).fontColor(0xCCCCCC)
  51.       Text('This is the text content with baselineOffset 0.')
  52.         .baselineOffset(0)
  53.         .style(TextAlign.Start)
  54.       Text('This is the text content with baselineOffset 30.')
  55.         .baselineOffset(30)
  56.         .style(TextAlign.Start)
  57.       Text('This is the text content with baselineOffset -20.')
  58.         .baselineOffset(-20)
  59.         .style(TextAlign.Start)
  60. 

  61.       // 设置文本是否居中对齐
  62.       Text('halfLeading').fontSize(9).fontColor(0xCCCCCC)
  63.       Text('This is the text with the halfLeading set.')
  64.         .lineHeight(60)
  65.         .halfLeading(true)
  66.         .style(TextAlign.Start)
  67.       Text('This is the text without the halfLeading set.')
  68.         .lineHeight(60)
  69.         .halfLeading(false)
  70.         .style(TextAlign.Start)
  71.     }.height(600).width('100%').padding({ left: 35, right: 35, top: 35 })
  72.   }
  73. }

示例2（设置文本样式）

该示例通过decoration、letterSpacing、textCase、fontFamily、textShadow（从API version 10开始）、fontStyle、textIndent（从API version 10开始）、fontWeight（从API version 12开始，支持设置字重无极调节配置项）属性展示了不同样式的文本效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Extend(Text)
  3. function style() {
  4.   .font({ size: 12 }, { enableVariableFontWeight: true })
  5.   .border({ width: 1 })
  6.   .padding(10)
  7.   .width('100%')
  8.   .margin(5)
  9. }
  10. 

  11. @Entry
  12. @Component
  13. struct TextExample2 {
  14.   @State changeDecorationIndex: number = 0;
  15.   @State textDecorationType: TextDecorationType[] =
  16.     [TextDecorationType.LineThrough, TextDecorationType.Overline, TextDecorationType.Underline];
  17.   @State textDecorationTypeStr: string[] = ['LineThrough', 'Overline', 'Underline'];
  18.   @State textDecorationStyle: TextDecorationStyle[] =
  19.     [TextDecorationStyle.SOLID, TextDecorationStyle.DOTTED, TextDecorationStyle.WAVY];
  20.   @State textDecorationStyleStr: string[] = ['SOLID', 'DOTTED', 'WAVY'];
  21. 

  22.   build() {
  23.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
  24.       Text('decoration').fontSize(9).fontColor(0xCCCCCC)
  25.       Text('This is the text content with the decoration set to LineThrough and the color set to Red.')
  26.         .decoration({
  27.           type: this.textDecorationType[this.changeDecorationIndex],
  28.           color: Color.Red,
  29.           style: this.textDecorationStyle[this.changeDecorationIndex]
  30.         })
  31.         .style()
  32.         .margin(5)
  33. 

  34.       Row() {
  35.         Button('decoration type：' + this.textDecorationTypeStr[this.changeDecorationIndex] + ' & ' +
  36.         this.textDecorationStyleStr[this.changeDecorationIndex]).onClick(() => {
  37.           this.changeDecorationIndex++;
  38.           if (this.changeDecorationIndex > (this.textDecorationTypeStr.length - 1)) {
  39.             this.changeDecorationIndex = 0;
  40.           }
  41.         })
  42.       }.justifyContent(FlexAlign.Center).width('100%')
  43. 

  44.       // 文本字符间距
  45.       Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC)
  46.       Text('This is the text content with letterSpacing 0.')
  47.         .letterSpacing(0)
  48.         .style()
  49.       Text('This is the text content with letterSpacing 3.')
  50.         .letterSpacing(3)
  51.         .style()
  52.       Text('This is the text content with letterSpacing -1.')
  53.         .letterSpacing(-1)
  54.         .style()
  55. 

  56.       Text('textCase').fontSize(9).fontColor(0xCCCCCC)
  57.       Text('This is the text content with textCase set to Normal.')
  58.         .textCase(TextCase.Normal)
  59.         .style()
  60.       // 文本全小写展示
  61.       Text('This is the text content with textCase set to LowerCase.')
  62.         .textCase(TextCase.LowerCase)
  63.         .style()
  64.       // 文本全大写展示
  65.       Text('This is the text content with textCase set to UpperCase.')
  66.         .textCase(TextCase.UpperCase)
  67.         .style()
  68. 

  69.       Text('fontFamily').fontSize(9).fontColor(0xCCCCCC)
  70.       // 设置字体列表
  71.       Text('This is the text content with fontFamily')
  72.         .style()
  73.         .fontFamily('HarmonyOS Sans')
  74. 

  75.       Text('textShadow').fontSize(9).fontColor(0xCCCCCC)
  76.       // 设置文字阴影效果
  77.       Text('textShadow')
  78.         .style()
  79.         .textAlign(TextAlign.Center)
  80.         .fontSize(40)
  81.         .textShadow({
  82.           radius: 10,
  83.           color: Color.Black,
  84.           offsetX: 0,
  85.           offsetY: 0
  86.         })
  87. 

  88.       Text('fontStyle').fontSize(9).fontColor(0xCCCCCC)
  89.       // 设置字体样式
  90.       Text('This is the text content with fontStyle set to Italic')
  91.         .style()
  92.         .fontStyle(FontStyle.Italic)
  93.       Text('This is the text content with fontStyle set to Normal')
  94.         .style()
  95.         .fontStyle(FontStyle.Normal)
  96. 

  97.       Text('textIndent').fontSize(9).fontColor(0xCCCCCC)
  98.       // 设置文字缩进
  99.       Text('This is the text content with textIndent 30')
  100.         .style()
  101.         .textIndent(30)
  102. 

  103.       Text('fontWeight').fontSize(9).fontColor(0xCCCCCC)
  104.       // 设置文本的字体粗细
  105.       Text('This is the text content with fontWeight 800')
  106.         .style()
  107.         .fontWeight('800', { enableVariableFontWeight: true })
  108. 

  109.     }.width('100%').padding({ left: 35, right: 35 })
  110.   }
  111. }

示例3（设置文本超长省略）

该示例通过maxLines、textOverflow、ellipsisMode属性展示了文本超长省略以及调整省略位置的效果，通过MULTILINE_START和MULTILINE_CENTER两种类型实现了单行文本和多行文本场景下的省略号在行首和行中的效果。同时，可以通过marqueeOptions配置跑马灯模式下的配置项以及跑马灯动画进行到特定的阶段时，触发的回调onMarqueeStateChange。

从API version 11开始，通过ellipsisMode属性设置文本超长时的显示方式。

从API version 18开始，新增marqueeOptions属性设置跑马灯模式下的配置项，同时新增回调onMarqueeStateChange。

从API version 24开始，EllipsisMode新增了MULTILINE_START和MULTILINE_CENTER枚举。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { LengthMetrics } from '@kit.ArkUI';
  3. 

  4. @Extend(Text)
  5. function style() {
  6.   .textAlign(TextAlign.Center)
  7.   .fontSize(15)
  8.   .border({ width: 1 })
  9.   .padding(10)
  10.   .width('100%')
  11.   .margin(5)
  12. }
  13. 

  14. @Entry
  15. @Component
  16. struct TextExample3 {
  17.   @State text: string =
  18.     'The text component is used to display a piece of textual information.' +
  19.       'Support universal attributes and universal text attributes.' +
  20.       'The text component is used to display a piece of textual information.' +
  21.       'Support universal attributes and universal text attributes.';
  22.   @State ellipsisModeIndex: number = 0;
  23.   @State ellipsisMode: EllipsisMode[] =
  24.     [EllipsisMode.START, EllipsisMode.CENTER, EllipsisMode.END, EllipsisMode.MULTILINE_START,
  25.       EllipsisMode.MULTILINE_CENTER]; // 从API version 24开始新增MULTILINE_START和MULTILINE_CENTER
  26.   @State ellipsisModeStr: string[] = ['START', 'CENTER', 'END', 'MULTILINE_START',
  27.     'MULTILINE_CENTER'];
  28. 

  29.   build() {
  30.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
  31.       // 文本超长时显示方式
  32.       Text('TextOverflow+maxLines').fontSize(12).fontColor(Color.Black)
  33.       // 超出maxLines截断内容展示
  34.       Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content. This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content.')
  35.         .textOverflow({ overflow: TextOverflow.Clip })
  36.         .maxLines(1)
  37.         .style()
  38. 

  39.       // 超出maxLines展示省略号
  40.       Text('This is set textOverflow to Ellipsis text content This is set textOverflow to Ellipsis text content.')
  41.         .textOverflow({ overflow: TextOverflow.Ellipsis })
  42.         .maxLines(1)
  43.         .style()
  44. 

  45.       Text('marquee').fontSize(12).fontColor(Color.Black)
  46.       // 设置文本超长时以跑马灯的方式展示
  47.       Text('This is the text with the text overflow set marquee')
  48.         .textOverflow({ overflow: TextOverflow.MARQUEE })
  49.         .style()
  50.         .marqueeOptions({
  51.           start: true,
  52.           fromStart: true,
  53.           step: 6,
  54.           spacing: LengthMetrics.vp(48), // 从API version 23开始新增
  55.           loop: -1,
  56.           delay: 0,
  57.           fadeout: false,
  58.           marqueeStartPolicy: MarqueeStartPolicy.DEFAULT,
  59.           marqueeUpdatePolicy: MarqueeUpdatePolicy.DEFAULT // 从API version 23开始新增
  60.         })
  61.         .onMarqueeStateChange((state: MarqueeState) => {
  62.           if (state == MarqueeState.START) {
  63.             // "收到状态: START";
  64.           } else if (state == MarqueeState.BOUNCE) {
  65.             // "收到状态: BOUNCE";
  66.           } else if (state == MarqueeState.FINISH) {
  67.             // "收到状态: FINISH";
  68.           }
  69.         })
  70. 

  71.       // 设置文本超长时省略号的位置
  72.       Text('ellipsisMode(单行文本)').fontSize(12).fontColor(Color.Black)
  73.       Text(this.text)
  74.         .textOverflow({ overflow: TextOverflow.Ellipsis })
  75.         .ellipsisMode(this.ellipsisMode[this.ellipsisModeIndex])
  76.         .maxLines(1)
  77.         .style()
  78.       Text('ellipsisMode(多行文本)').fontSize(12).fontColor(Color.Black)
  79.       Text(this.text)
  80.         .textOverflow({ overflow: TextOverflow.Ellipsis })
  81.         .ellipsisMode(this.ellipsisMode[this.ellipsisModeIndex])
  82.         .maxLines(3)
  83.         .style()
  84. 

  85.       Row() {
  86.         Button('更改省略号位置：' + this.ellipsisModeStr[this.ellipsisModeIndex]).onClick(() => {
  87.           this.ellipsisModeIndex++;
  88.           if (this.ellipsisModeIndex > (this.ellipsisModeStr.length - 1)) {
  89.             this.ellipsisModeIndex = 0;
  90.           }
  91.         })
  92.       }
  93.     }.height(600).width('100%').padding({ left: 35, right: 35, top: 35 })
  94.   }
  95. }

示例4（设置文本断行及折行）

该示例通过wordBreak（从API version 11开始）、lineBreakStrategy（从API version 12开始）、clip属性展示了文本在不同断行、折行规则下的效果以及文本超长时是否截断。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Extend(Text)
  3. function style() {
  4.   .fontSize(12)
  5.   .border({ width: 1 })
  6.   .padding(10)
  7.   .width('100%')
  8.   .margin(5)
  9. }
  10. 

  11. @Entry
  12. @Component
  13. struct TextExample4 {
  14.   @State text: string =
  15.     'The text component is used to display a piece of textual information.Support universal attributes and universal text attributes.';
  16.   @State longText: string =
  17.     'They can be classified as built-in components–those directly provided by the ArkUI framework and custom components – those defined by developers' +
  18.       'The built-in components include buttons radio buttons progress indicators and text You can set the rendering effect of these components in method chaining mode,' +
  19.       'page components are divided into independent UI units to implement independent creation development and reuse of different units on pages making pages more engineering-oriented.';
  20.   @State textClip: boolean = false;
  21.   @State wordBreakIndex: number = 0;
  22.   @State wordBreak: WordBreak[] = [WordBreak.NORMAL, WordBreak.BREAK_ALL, WordBreak.BREAK_WORD];
  23.   @State wordBreakStr: string[] = ['NORMAL', 'BREAK_ALL', 'BREAK_WORD'];
  24.   @State lineBreakStrategyIndex: number = 0;
  25.   @State lineBreakStrategy: LineBreakStrategy[] =
  26.     [LineBreakStrategy.GREEDY, LineBreakStrategy.HIGH_QUALITY, LineBreakStrategy.BALANCED];
  27.   @State lineBreakStrategyStr: string[] = ['GREEDY', 'HIGH_QUALITY', 'BALANCED'];
  28. 

  29.   build() {
  30.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
  31.       Text('wordBreak').fontSize(9).fontColor(0xCCCCCC)
  32.       // 设置文本断行规则
  33.       Text(this.text)
  34.         .maxLines(2)
  35.         .textOverflow({ overflow: TextOverflow.Ellipsis })
  36.         .wordBreak(this.wordBreak[this.wordBreakIndex])
  37.         .style()
  38. 

  39.       Row() {
  40.         Button('当前wordBreak模式：' + this.wordBreakStr[this.wordBreakIndex]).onClick(() => {
  41.           this.wordBreakIndex++;
  42.           if (this.wordBreakIndex > (this.wordBreakStr.length - 1)) {
  43.             this.wordBreakIndex = 0;
  44.           }
  45.         })
  46.       }
  47. 

  48.       Text('clip').fontSize(9).fontColor(0xCCCCCC)
  49.       // 设置文本是否超长截断
  50.       Text('This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.')
  51.         .wordBreak(WordBreak.NORMAL)
  52.         .maxLines(2)
  53.         .clip(this.textClip)
  54.         .style()
  55.       Row() {
  56.         Button('切换clip：' + this.textClip).onClick(() => {
  57.           this.textClip = !this.textClip;
  58.         })
  59.       }
  60. 

  61.       Text('lineBreakStrategy').fontSize(9).fontColor(0xCCCCCC)
  62.       // 设置文本折行规则
  63.       Text(this.longText)
  64.         .lineBreakStrategy(this.lineBreakStrategy[this.lineBreakStrategyIndex])
  65.         .style()
  66.       Row() {
  67.         Button('当前lineBreakStrategy模式：' + this.lineBreakStrategyStr[this.lineBreakStrategyIndex]).onClick(() => {
  68.           this.lineBreakStrategyIndex++;
  69.           if (this.lineBreakStrategyIndex > (this.lineBreakStrategyStr.length - 1)) {
  70.             this.lineBreakStrategyIndex = 0;
  71.           }
  72.         })
  73.       }
  74.     }.height(600).width('100%').padding({ left: 35, right: 35, top: 35 })
  75.   }
  76. }

示例5（设置文本选中和复制）

该示例通过selection（从API version 11开始）、onCopy（从API version 11开始）、draggable（从API version 9开始）、caretColor（从API version 14开始）、selectedBackgroundColor（从API version 14开始）、onWillCopy接口展示了文本选中、触发复制回调、设置文本选中可拖拽、修改手柄和选中颜色的效果以及如何拦截系统复制。

从API版本26.0.0开始，新增onWillCopy接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample5 {
  5.   @State onCopy: string = '';
  6.   @State text: string =
  7.     'This is set selection to Selection text content This is set selection to Selection text content.';
  8.   @State start: number = 0;
  9.   @State end: number = 20;
  10. 

  11.   build() {
  12.     Column() {
  13.       Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Start }) {
  14.         Text(this.text)
  15.           .fontSize(12)
  16.           .border({ width: 1 })
  17.           .lineHeight(20)
  18.           .margin(30)
  19.           .copyOption(CopyOptions.InApp)
  20.           .selection(this.start, this.end)
  21.           .onCopy((value: string) => {
  22.             this.onCopy = value;
  23.           })
  24.           // 从API版本26.0.0开始支持onWillCopy
  25.           .onWillCopy((value: string) => {
  26.             // 根据业务逻辑判断是否允许复制
  27.             return true; // 允许复制时返回true，随后onCopy会被触发
  28.           })
  29.           .draggable(true)
  30.           .caretColor(Color.Red)
  31.           .selectedBackgroundColor(Color.Grey)
  32.           .enableHapticFeedback(true)
  33.         Button('Set text selection')
  34.           .onClick(() => {
  35.             // 变更文本选中起始点、终点
  36.             this.start = 10;
  37.             this.end = 30;
  38.           })
  39.         Text(this.onCopy).fontSize(12).margin(10).key('copy')
  40.       }.height(600).width(335).padding({ left: 35, right: 35, top: 35 })
  41.     }.width('100%')
  42.   }
  43. }

示例6（设置文本自适应和缩放倍数限制范围）

该示例通过heightAdaptivePolicy（从API version 10开始）属性展示文本自适应效果以及通过minFontScale（从API version 12开始）、maxFontScale（从API version 12开始）展示设置字体缩放倍数限制范围。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Extend(Text)
  3. function style(heightAdaptivePolicy: TextHeightAdaptivePolicy) {
  4.   .width('80%')
  5.   .height(90)
  6.   .borderWidth(1)
  7.   .minFontSize(10)
  8.   .maxFontSize(30)
  9.   .maxLines(2)
  10.   .margin(5)
  11.   .textOverflow({ overflow: TextOverflow.Ellipsis })
  12.   .heightAdaptivePolicy(heightAdaptivePolicy)
  13. }
  14. 

  15. @Entry
  16. @Component
  17. struct TextExample6 {
  18.   build() {
  19.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
  20.       // 设置文本自适应高度的方式
  21.       Text('heightAdaptivePolicy').fontSize(9).fontColor(0xCCCCCC)
  22.       Text('This is the text with the height adaptive policy set.')
  23.         .style(TextHeightAdaptivePolicy.MAX_LINES_FIRST)
  24.       Text('This is the text with the height adaptive policy set.')
  25.         .style(TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST)
  26.       Text('This is the text with the height adaptive policy set.')
  27.         .style(TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST)
  28. 

  29.       Text('fontScale').fontSize(9).fontColor(0xCCCCCC)
  30.       Text('This is the text content with minFontScale set to 1 and maxFontScale set to 1.2')
  31.         .style(TextHeightAdaptivePolicy.MAX_LINES_FIRST)
  32.         .minFontScale(1)
  33.         .maxFontScale(1.2)
  34.     }.height(600).width('100%').padding({ left: 35, right: 35, top: 35 })
  35.   }
  36. }

示例7（设置文本识别）

从API version 11开始，该示例通过enableDataDetector、dataDetectorConfig接口实现了文本识别的功能。当enableDataDetector设为true且不设置dataDetectorConfig时，系统会识别所有实体类型，并将识别实体的字体颜色改为蓝色、添加蓝色下划线。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample7 {
  5.   @State phoneNumber: string = '(86) (755) ********';
  6.   @State url: string = 'www.********.com';
  7.   @State email: string = '***@example.com';
  8.   @State address: string = 'XX省XX市XX区XXXX';
  9.   @State datetime: string = 'XX年XX月XX日XXXX';
  10.   @State enableDataDetector: boolean = true;
  11.   @State types: TextDataDetectorType[] = [];
  12. 

  13.   build() {
  14.     Row() {
  15.       Column() {
  16.         Text(
  17.           '电话号码：' + this.phoneNumber + '\n' +
  18.             '链接：' + this.url + '\n' +
  19.             '邮箱：' + this.email + '\n' +
  20.             '地址：' + this.address + '\n' +
  21.             '时间：' + this.datetime
  22.         )
  23.           .fontSize(16)
  24.           .copyOption(CopyOptions.InApp)
  25.           .enableDataDetector(this.enableDataDetector)
  26.           .dataDetectorConfig({
  27.             types: this.types, onDetectResultUpdate: (result: string) => {
  28.             }
  29.           })
  30.           .textAlign(TextAlign.Center)
  31.           .borderWidth(1)
  32.           .padding(10)
  33.           .width('100%')
  34.       }
  35.       .width('100%')
  36.       // 使用parallelGesture中的TapGesture替代onClick属性，达到非冒泡事件类似冒泡
  37.       // 的效果，点击Text组件区域Column上的点击事件正常响应
  38.       .parallelGesture(TapGesture().onAction((event: GestureEvent) => {
  39.         console.info('test column onClick timestamp:' + event.timestamp);
  40.       }), GestureMask.Normal)
  41.     }
  42.     .height('100%')
  43.   }
  44. }

示例8（文本绑定自定义菜单）

从API version 11开始，该示例通过bindSelectionMenu、onTextSelectionChange、closeSelectionMenu接口实现了文本绑定自定义菜单的功能。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample8 {
  5.   controller: TextController = new TextController();
  6.   options: TextOptions = { controller: this.controller };
  7. 

  8.   build() {
  9.     Column() {
  10.       Column() {
  11.         Text(undefined, this.options) {
  12.           Span('Hello World')
  13.           // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  14.           ImageSpan($r('app.media.startIcon'))
  15.             .width(50)
  16.             .height(50)
  17.             .objectFit(ImageFit.Fill)
  18.             .verticalAlign(ImageSpanAlignment.CENTER)
  19.         }
  20.         .copyOption(CopyOptions.InApp)
  21.         .bindSelectionMenu(TextSpanType.IMAGE, this.LongPressImageCustomMenu, TextResponseType.LONG_PRESS, {
  22.           onDisappear: () => {
  23.             console.info(`自定义选择菜单关闭时回调`);
  24.           },
  25.           onAppear: () => {
  26.             console.info(`自定义选择菜单弹出时回调`);
  27.           },
  28.           onMenuShow: () => {
  29.             console.info(`自定义选择菜单显示时回调`);
  30.           },
  31.           onMenuHide: () => {
  32.             console.info(`自定义选择菜单隐藏时回调`);
  33.           }
  34.         })
  35.         .bindSelectionMenu(TextSpanType.TEXT, this.RightClickTextCustomMenu, TextResponseType.RIGHT_CLICK)
  36.         .bindSelectionMenu(TextSpanType.MIXED, this.SelectMixCustomMenu, TextResponseType.SELECT)
  37.         .onTextSelectionChange((selectionStart: number, selectionEnd: number) => {
  38.           console.info(`文本选中区域变化回调, selectionStart: ${selectionStart}, selectionEnd: ${selectionEnd}`);
  39.         })
  40.         .borderWidth(1)
  41.         .borderColor(Color.Red)
  42.         .width(200)
  43.         .height(100)
  44.       }
  45.       .width('100%')
  46.       .backgroundColor(Color.White)
  47.       .alignItems(HorizontalAlign.Start)
  48.       .padding(25)
  49.     }
  50.     .height('100%')
  51.   }
  52. 

  53.   @Builder
  54.   RightClickTextCustomMenu() {
  55.     Column() {
  56.       Menu() {
  57.         MenuItemGroup() {
  58.           // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  59.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Right Click Menu 1', labelInfo: '' })
  60.             .onClick((event) => {
  61.               this.controller.closeSelectionMenu();
  62.             })
  63.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Right Click Menu 2', labelInfo: '' })
  64.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Right Click Menu 3', labelInfo: '' })
  65.         }
  66.       }
  67.       .MenuStyles()
  68.     }
  69.   }
  70. 

  71.   @Builder
  72.   LongPressImageCustomMenu() {
  73.     Column() {
  74.       Menu() {
  75.         MenuItemGroup() {
  76.           // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  77.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Long Press Image Menu 1', labelInfo: '' })
  78.             .onClick((event) => {
  79.               this.controller.closeSelectionMenu();
  80.             })
  81.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Long Press Image Menu 2', labelInfo: '' })
  82.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Long Press Image Menu 3', labelInfo: '' })
  83.         }
  84.       }
  85.       .MenuStyles()
  86.     }
  87.   }
  88. 

  89.   @Builder
  90.   SelectMixCustomMenu() {
  91.     Column() {
  92.       Menu() {
  93.         MenuItemGroup() {
  94.           // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  95.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Select Mixed Menu 1', labelInfo: '' })
  96.             .onClick((event) => {
  97.               this.controller.closeSelectionMenu();
  98.             })
  99.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Select Mixed Menu 2', labelInfo: '' })
  100.           MenuItem({ startIcon: $r('app.media.startIcon'), content: 'Select Mixed Menu 3', labelInfo: '' })
  101.         }
  102.       }
  103.       .MenuStyles()
  104.     }
  105.   }
  106. }
  107. 

  108. @Extend(Menu)
  109. function MenuStyles() {
  110.   .radius($r('sys.float.ohos_id_corner_radius_card'))
  111.   .clip(true)
  112.   .backgroundColor('#F0F0F0')
  113. }

示例9（设置文本特性与行间距）

从API version 12开始，该示例通过fontFeature、lineSpacing接口展示了设置文本特性与行间距的效果，同时，配置LineSpacingOptions中的onlyBetweenLines（从API version 20开始）属性，可以设置文本的行间距，是否仅在行与行之间生效。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { LengthMetrics } from '@kit.ArkUI';
  3. 

  4. @Extend(Text)
  5. function style() {
  6.   .fontSize(12)
  7.   .border({ width: 1 })
  8.   .width('100%')
  9. }
  10. 

  11. @Entry
  12. @Component
  13. struct TextExample9 {
  14.   build() {
  15.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
  16.       Text('lineSpacing').fontSize(9).fontColor(0xCCCCCC)
  17.       // 设置文本行间距
  18.       Text('This is a context with no lineSpacing set.')
  19.         .lineSpacing(undefined)
  20.         .style()
  21.       Text('This is a context with lineSpacing set to 20_px.')
  22.         .lineSpacing(LengthMetrics.px(20))
  23.         .style()
  24.       Text('This is the context with lineSpacing set to 20_vp.')
  25.         .lineSpacing(LengthMetrics.vp(20))
  26.         .style()
  27.       Text('This is the context with lineSpacing set to 20_fp.')
  28.         .lineSpacing(LengthMetrics.fp(20))
  29.         .style()
  30.       Text('This is the context with lineSpacing set to 20_lpx.')
  31.         .lineSpacing(LengthMetrics.lpx(20))
  32.         .style()
  33.       Text('This is the context with lineSpacing set to 100%.')
  34.         .lineSpacing(LengthMetrics.percent(1))
  35.         .style()
  36.       Text('The line spacing of this context is set to 20_px, and the spacing is effective only between the lines.')
  37.         .lineSpacing(LengthMetrics.px(20), { onlyBetweenLines: true })
  38.         .style()
  39. 

  40.       Text('fontFeature').fontSize(9).fontColor(0xCCCCCC)
  41.       // 设置文本特性
  42.       Text('This is frac on : 1/2 2/3 3/4')
  43.         .fontFeature('"frac" on')
  44.         .style()
  45.       Text('This is frac off: 1/2 2/3 3/4')
  46.         .fontFeature('"frac" off')
  47.         .style()
  48.     }.height(300).width(350).padding({ left: 35, right: 35, top: 35 })
  49.   }
  50. }

示例10（获取文本信息）

从API version 12开始，该示例通过getLayoutManager接口调用文本的布局管理对象获取文本信息，同时，LayoutManager中的getRectsForRange（从API version 14开始）接口可以获取指定矩形宽度样式和高度样式下，文本中任意区间范围内字符或占位符的绘制区域信息。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { text } from '@kit.ArkGraphics2D';
  3. 

  4. @Entry
  5. @Component
  6. struct TextExample10 {
  7.   @State lineCount: string = "";
  8.   @State glyphPositionAtCoordinate: string = "";
  9.   @State lineMetrics: string = "";
  10.   @State rectsForRangeStr: string = "";
  11.   controller: TextController = new TextController();
  12.   @State textStr: string =
  13.     'Hello World! 您好，世界！';
  14. 

  15.   build() {
  16.     Scroll() {
  17.       Column() {
  18.         Text('Text组件getLayoutManager接口获取段落相对组件的信息')
  19.           .fontSize(15)
  20.           .fontColor(0xCCCCCC)
  21.           .width('90%')
  22.           .padding(10)
  23.         Text(this.textStr, { controller: this.controller })
  24.           .fontSize(25)
  25.           .borderWidth(1)
  26.           .onAreaChange(() => {
  27.             // getLayoutManager在TextController未绑定Text或Text被销毁时会返回undefined，使用时需做判空处理
  28.             let layoutManager: LayoutManager = this.controller.getLayoutManager();
  29.             if (!layoutManager) {
  30.               return;
  31.             }
  32.             this.lineCount = 'LineCount: ' + layoutManager.getLineCount();
  33.           })
  34. 

  35.         Text('LineCount').fontSize(15).fontColor(0xCCCCCC).width('90%').padding(10)
  36.         Text(this.lineCount)
  37. 

  38.         Text('GlyphPositionAtCoordinate').fontSize(15).fontColor(0xCCCCCC).width('90%').padding(10)
  39.         Button("相对组件坐标[150,50]字形信息")
  40.           .onClick(() => {
  41.             let layoutManager: LayoutManager = this.controller.getLayoutManager();
  42.             if (!layoutManager) {
  43.               return;
  44.             }
  45.             let position: PositionWithAffinity = layoutManager.getGlyphPositionAtCoordinate(150, 50);
  46.             this.glyphPositionAtCoordinate =
  47.               '相对组件坐标[150,50] glyphPositionAtCoordinate position: ' + position.position + ' affinity: ' +
  48.               position.affinity;
  49.           })
  50.           .margin({ bottom: 20, top: 10 })
  51.         Text(this.glyphPositionAtCoordinate)
  52. 

  53.         Text('LineMetrics').fontSize(15).fontColor(0xCCCCCC).width('90%').padding(10)
  54.         Button('首行行信息、文本样式信息、以及字体属性信息')
  55.           .onClick(() => {
  56.             let layoutManager: LayoutManager = this.controller.getLayoutManager();
  57.             if (!layoutManager) {
  58.               return;
  59.             }
  60.             let lineMetrics: LineMetrics = layoutManager.getLineMetrics(0);
  61.             this.lineMetrics = 'lineMetrics is ' + JSON.stringify(lineMetrics) + '\n\n';
  62.             let runMetrics = lineMetrics.runMetrics;
  63.             runMetrics.forEach((value, key) => {
  64.               this.lineMetrics += 'runMetrics key is ' + key + ' ' + JSON.stringify(value) + '\n\n';
  65.             })
  66.           })
  67.           .margin({ bottom: 20, top: 10 })
  68.         Text(this.lineMetrics)
  69. 

  70.         Text('getRectsForRange').fontSize(15).fontColor(0xCCCCCC).width('90%').padding(10)
  71.         Button('获取指定矩形宽度样式和高度样式下，文本中任意区间范围内字符或占位符的绘制区域信息')
  72.           .onClick(() => {
  73.             let layoutManager: LayoutManager = this.controller.getLayoutManager();
  74.             if (!layoutManager) {
  75.               return;
  76.             }
  77.             let range: TextRange = { start: 0, end: 1 };
  78.             let rectsForRangeInfo: text.TextBox[] =
  79.               layoutManager.getRectsForRange(range, text.RectWidthStyle.TIGHT, text.RectHeightStyle.TIGHT);
  80.             this.rectsForRangeStr = 'getRectsForRange result is ' + '\n\n';
  81.             rectsForRangeInfo.forEach((value, key) => {
  82.               this.rectsForRangeStr += 'rectsForRange key is ' + key + ' ' + JSON.stringify(value) + '\n\n';
  83.             })
  84.           })
  85.           .margin({ bottom: 20, top: 10 })
  86.         Text(this.rectsForRangeStr)
  87.       }
  88.       .margin({ top: 100, left: 8, right: 8 })
  89.     }
  90.   }
  91. }

示例11（实现键盘框选文本）

从API version 12开始，该示例通过textSelectable属性实现了设置TextSelectMode.SELECTABLE_FOCUSABLE时能够触发键盘框选文本功能。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample11 {
  5.   @State message: string =
  6.     'TextTextTextTextTextTextTextText' + 'TextTextTextTextTextTextTextTextTextTextTextTextTextTextTextText';
  7. 

  8.   build() {
  9.     Column() {
  10.       Text(this.message)
  11.         .width(300)
  12.         .height(100)
  13.         .maxLines(5)
  14.         .fontColor(Color.Black)
  15.         .copyOption(CopyOptions.InApp)
  16.         .selection(3, 8)
  17.         .textSelectable(TextSelectableMode.SELECTABLE_FOCUSABLE)
  18.     }.width('100%').margin({ top: 100 })
  19.   }
  20. }

示例12（文本扩展自定义菜单）

从API version 12开始，该示例通过editMenuOptions接口实现了文本设置自定义菜单扩展项的文本内容、图标以及回调的功能，同时，可以在onPrepareMenu（从API version 20开始）回调中，进行菜单数据的设置。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample12 {
  5.   @State text: string = 'Text editMenuOptions'
  6.   @State endIndex: number = 0;
  7.   onCreateMenu = (menuItems: Array<TextMenuItem>) => {
  8.     // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  9.     let item1: TextMenuItem = {
  10.       content: 'create1',
  11.       icon: $r('app.media.startIcon'),
  12.       id: TextMenuItemId.of('create1'),
  13.     };
  14.     let item2: TextMenuItem = {
  15.       content: 'create2',
  16.       id: TextMenuItemId.of('create2'),
  17.       icon: $r('app.media.startIcon'),
  18.     };
  19.     menuItems.push(item1);
  20.     menuItems.unshift(item2);
  21.     let targetIndex = menuItems.findIndex(item => item.id.equals(TextMenuItemId.askAI));
  22.     if (targetIndex !== -1) {
  23.       menuItems.splice(targetIndex, 1); // 从目标索引删除1个元素
  24.     }
  25.     targetIndex = menuItems.findIndex(item => item.id.equals(TextMenuItemId.TRANSLATE));
  26.     if (targetIndex !== -1) {
  27.       menuItems.splice(targetIndex, 1);
  28.     }
  29.     return menuItems;
  30.   }
  31.   onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => {
  32.     if (menuItem.id.equals(TextMenuItemId.of("create2"))) {
  33.       console.info('拦截 id: create2 start:' + textRange.start + '; end:' + textRange.end);
  34.       return true;
  35.     }
  36.     if (menuItem.id.equals(TextMenuItemId.of("prepare1"))) {
  37.       console.info('拦截 id: prepare1 start:' + textRange.start + '; end:' + textRange.end);
  38.       return true;
  39.     }
  40.     if (menuItem.id.equals(TextMenuItemId.COPY)) {
  41.       console.info('拦截 COPY start:' + textRange.start + '; end:' + textRange.end);
  42.       return true;
  43.     }
  44.     if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) {
  45.       console.info('不拦截 SELECT_ALL start:' + textRange.start + '; end:' + textRange.end);
  46.       return false;
  47.     }
  48.     return false;
  49.   }
  50.   // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  51.   onPrepareMenu = (menuItems: Array<TextMenuItem>) => {
  52.     let item1: TextMenuItem = {
  53.       content: 'prepare1_' + this.endIndex,
  54.       icon: $r('app.media.startIcon'),
  55.       id: TextMenuItemId.of('prepare1'),
  56.     };
  57.     menuItems.unshift(item1);
  58.     return menuItems;
  59.   }
  60.   @State editMenuOptions: EditMenuOptions = {
  61.     onCreateMenu: this.onCreateMenu,
  62.     onMenuItemClick: this.onMenuItemClick,
  63.     onPrepareMenu: this.onPrepareMenu
  64.   };
  65. 

  66.   build() {
  67.     Column() {
  68.       Text(this.text)
  69.         .fontSize(20)
  70.         .copyOption(CopyOptions.LocalDevice)
  71.         .editMenuOptions(this.editMenuOptions)
  72.         .margin({ top: 100 })
  73.         .onTextSelectionChange((selectionStart: number, selectionEnd: number) => {
  74.           this.endIndex = selectionEnd;
  75.         })
  76.     }
  77.     .width('90%')
  78.     .margin('5%')
  79.   }
  80. }

示例13（配置隐私隐藏）

从API version 12开始，该示例通过privacySensitive属性展示了文本如何配置隐私隐藏的效果，实际显示需要卡片框架支持。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample13 {
  5.   build() {
  6.     Column({ space: 10 }) {
  7.       Text('privacySensitive')
  8.         .privacySensitive(true)
  9.         .margin({ top: 30 })
  10.     }
  11.     .alignItems(HorizontalAlign.Center)
  12.     .width('100%')
  13.   }
  14. }

示例14（设置中西文自动间距）

从API version 20开始，该示例通过enableAutoSpacing属性设置中西文自动间距。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample {
  5.   build() {
  6.     Row() {
  7.       Column() {
  8.         Text('开启中西文自动间距').margin(5)
  9.         Text('中西文Auto Spacing自动间距')
  10.           .enableAutoSpacing(true)
  11.         Text('关闭中西文自动间距').margin(5)
  12.         Text('中西文Auto Spacing自动间距')
  13.           .enableAutoSpacing(false)
  14.       }.height('100%')
  15.     }
  16.     .width('60%')
  17.   }
  18. }

示例15（文本颜色按线性或径向渐变）

从API version 20开始，该示例通过shaderStyle接口实现了对Text组件显示为渐变色和纯色的功能。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct ShaderColorStyle {
  4.   @State message: string = 'Hello World';
  5.   @State linearGradientOptionsAngle: LinearGradientOptions =
  6.     {
  7.       angle: 45,
  8.       colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]]
  9.     };
  10.   @State linearGradientOptionsDirection: LinearGradientOptions =
  11.     {
  12.       direction: GradientDirection.LeftTop,
  13.       colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]],
  14.       repeating: true,
  15.     };
  16.   @State radialGradientOptions: RadialGradientOptions =
  17.     {
  18.       center: [50, 50],
  19.       radius: 20,
  20.       colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]],
  21.       repeating: true,
  22.     };
  23.   @State colorShaderStyle: ColorShaderStyle =
  24.     {
  25.       color: Color.Blue
  26.     };
  27.   build() {
  28.     Column({ space: 5 }) {
  29.       Text('angle为45°的线性渐变').fontSize(18).width('90%').fontColor(0xCCCCCC)
  30.         .margin({ top: 40, left: 40 })
  31.       Text(this.message)
  32.         .fontSize(50)
  33.         .width('80%')
  34.         .height(50)
  35.         .shaderStyle(this.linearGradientOptionsAngle)
  36.       Text('direction为LeftTop的线性渐变').fontSize(18).width('90%').fontColor(0xCCCCCC)
  37.         .margin({ top: 40, left: 40 })
  38.       Text(this.message)
  39.         .fontSize(50)
  40.         .width('80%')
  41.         .height(50)
  42.         .shaderStyle(this.linearGradientOptionsDirection)
  43.       Text('径向渐变').fontSize(18).width('90%').fontColor(0xCCCCCC)
  44.         .margin({ top: 40, left: 40 })
  45.       Text(this.message)
  46.         .fontSize(50)
  47.         .width('80%')
  48.         .height(50)
  49.         .shaderStyle(this.radialGradientOptions)
  50.       Text('纯色').fontSize(18).width('90%').fontColor(0xCCCCCC)
  51.         .margin({ top: 40, left: 40 })
  52.       Text(this.message)
  53.         .fontSize(50)
  54.         .width('80%')
  55.         .height(50)
  56.         .shaderStyle(this.colorShaderStyle)
  57.     }
  58.   }
  59. }

示例16（配置除去行尾空格）

从API version 20开始，该示例通过optimizeTrailingSpace属性展示了文本如何配置除去行尾空格的效果，一般需要与对齐功能搭配使用，实际显示需要字体引擎支持。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample16 {
  5.   build() {
  6.     Column() {
  7.       Text('Trimmed space enabled     ')
  8.         .fontSize(30)
  9.         .fontWeight(FontWeight.Bold)
  10.         .margin({ top: 20 })
  11.         .optimizeTrailingSpace(true)
  12.         .textAlign(TextAlign.Center)
  13.       Text('Trimmed space disabled     ')
  14.         .fontSize(30)
  15.         .fontWeight(FontWeight.Bold)
  16.         .margin({ top: 20 })
  17.         .optimizeTrailingSpace(false)
  18.         .textAlign(TextAlign.Center)
  19.     }
  20.     .width("100%")
  21.   }
  22. }

示例17（文本垂直对齐）

从API version 20开始，该示例通过textVerticalAlign属性展示了文本如何设置文本垂直对齐效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample14 {
  5.   build() {
  6.     Column({ space: 10 }) {
  7.       Text() {
  8.         Span('Hello')
  9.           .fontSize(50)
  10.         // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  11.         ImageSpan($r('app.media.startIcon'))
  12.           .width(30).height(30)
  13.           .verticalAlign(ImageSpanAlignment.FOLLOW_PARAGRAPH)// 从API version 20开始，支持ImageSpanAlignment.FOLLOW_PARAGRAPH
  14.         Span('World')
  15.       }
  16.       .textVerticalAlign(TextVerticalAlign.CENTER)
  17.       .borderWidth(1)
  18.     }
  19.     .alignItems(HorizontalAlign.Center)
  20.     .width('100%')
  21.   }
  22. }

示例18（文本翻牌动效）

从API version 20开始，该示例通过contentTransition属性展示了数字翻牌效果。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextNumberTransition {
  5.   @State number: number = 98;
  6.   @State numberTransition: NumericTextTransition =
  7.     new NumericTextTransition({ flipDirection: FlipDirection.DOWN, enableBlur: false });
  8. 

  9.   build() {
  10.     Column() {
  11.       Text(this.number + '')
  12.         .borderWidth(1)
  13.         .fontSize(40)
  14.         .contentTransition(this.numberTransition)
  15.       Button('change number')
  16.         .onClick(() => {
  17.           this.number++;
  18.         })
  19.         .margin(10)
  20.     }
  21.     .justifyContent(FlexAlign.Center)
  22.     .height('100%')
  23.     .width('100%')
  24.   }
  25. }

示例19（文本内容区垂直对齐）

从API version 21开始，该示例通过textContentAlign属性展示了当文本内容区高度大于组件高度时文本内容区的垂直对齐。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct TextContentAlignExample {
  4. 

  5.   build() {
  6.     Column() {
  7.       Row() {
  8.         Text('这是一段展示文字')
  9.           .fontSize(30)
  10.           .backgroundColor(Color.Gray)
  11.           .width('80%')
  12.           .height(20)
  13.           .textContentAlign(TextContentAlign.CENTER)
  14.       }.height('60%')
  15.     }
  16.   }
  17. }

示例20（倍数行高和最大最小行高）

从API version 22开始，该示例通过lineHeightMultiple属性展示了使用倍数模式设置行高，同时通过minLineHeight和maxLineHeight来设置最小和最大行高值。

收起
自动换行
深色代码主题
复制
  1. import { LengthUnit } from '@kit.ArkUI';
  2. 

  3. @Entry
  4. @Component
  5. struct Index {
  6.   @State message: string = 'hello';
  7. 

  8.   build() {
  9.     Scroll() {
  10.       Column() {
  11.         Row() {
  12.           Text(this.message)
  13.             .lineHeight(176)
  14.             .backgroundColor(0xffc0c0c0)
  15.             .fontSize(50)
  16.           Text(this.message)
  17.             .lineHeightMultiple(3)
  18.             .backgroundColor(0xffc0c0c0)
  19.             .fontSize(50)
  20.           Text(this.message)
  21.             .lineHeight(300)
  22.             .maxLineHeight({value:176,unit:LengthUnit.FP})
  23.             .backgroundColor(0xffc0c0c0)
  24.             .fontSize(50)
  25.           Text(this.message)
  26.             .lineHeight(10)
  27.             .minLineHeight({value:176,unit:LengthUnit.FP})
  28.             .backgroundColor(0xffc0c0c0)
  29.             .fontSize(50)
  30.         }
  31.       }
  32.     }.height('100%')
  33.     .width('100%')
  34.   }
  35. }

示例21（文本设置显示最小行数）

从API version 22开始，该示例使用minLines属性设置文本显示的最小行数。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct TextExample1 {
  4.   @State shortMessage: string = 'Hello world!';
  5.   @State longMessage: string = 'The minimum number of lines displayed for this text setting is 1';
  6. 

  7.   build() {
  8.     Column() {
  9.       Text(this.shortMessage)
  10.         .minLines(3)
  11.         .fontSize(20)
  12.         .margin(10)
  13.         .width('95%')
  14.         .border({ width: 1 })
  15.       Text(this.longMessage)
  16.         .minLines(1)
  17.         .fontSize(20)
  18.         .margin(10)
  19.         .width('95%')
  20.         .border({ width: 1 })
  21.     }.height(100).width('90%').margin(10)
  22.   }
  23. }

示例22（设置文本选择区域并高亮显示）

从API version 23开始，该示例使用TextController中的setTextSelection设置文本选择区域并高亮显示。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct Index {
  4.   controller: TextController = new TextController();
  5.   @State textStr: string = 'Hello World! 你好，世界！';
  6. 

  7.   build() {
  8.     Scroll() {
  9.       Column() {
  10.         Text(this.textStr, { controller: this.controller })
  11.           .fontSize(25)
  12.           .borderWidth(1)
  13.           .copyOption(CopyOptions.LocalDevice)
  14.         Button('setTextSelection')
  15.           .onClick(() => {
  16.             this.controller.setTextSelection(1, 6, { menuPolicy: MenuPolicy.HIDE })
  17.           })
  18.           .margin({ bottom: 20, top: 10 } as Margin)
  19.       }
  20.       .margin({ top: 100, left: 8, right: 8 } as Margin)
  21.     }
  22.   }
  23. }

示例23（设置行首标点符号压缩和行尾标点符号悬挂）

本示例通过compressLeadingPunctuation接口设置行首标点符号压缩，通过punctuationOverflow设置行尾标点符号悬挂。

左侧有间距的标点符号位于行首时，标点会直接压缩间距至左侧边界。

文本自动换行后，剩余内容（含标点符号）需要能够放入上一行，标点符号悬挂才生效。

从API版本23开始，新增compressLeadingPunctuation接口。

从API版本26.0.0开始，新增punctuationOverflow接口。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct PunctuationDemo {
  4.   @State compressLeadingPunctuation: boolean = false;
  5.   @State punctuationOverflow: boolean = false;
  6.   @State text: string = '「0123456789！\n『0123456789：\n（0123456789；\n《0123456789）\n〈0123456789】';
  7. 

  8.   build() {
  9.     Column() {
  10.       Text(this.text)
  11.         .compressLeadingPunctuation(this.compressLeadingPunctuation)
  12.         .punctuationOverflow(this.punctuationOverflow)
  13.         .border({ width: 1, color: Color.Black })
  14.         .copyOption(CopyOptions.LocalDevice)
  15.         .fontSize('20fp')
  16.         .align(Alignment.Center)
  17.         .height('35%')
  18.         .width('40%')
  19. 

  20.       Column() {
  21.         Button('开启行首标点符号压缩').onClick(() => {
  22.           this.compressLeadingPunctuation = true
  23.         }).margin(5)
  24.         Button('关闭行首标点符号压缩').onClick(() => {
  25.           this.compressLeadingPunctuation = false
  26.         }).margin(5)
  27.         Button('开启行尾标点符号悬挂').onClick(() => {
  28.           this.punctuationOverflow = true
  29.         }).margin(5)
  30.         Button('关闭行尾标点符号悬挂').onClick(() => {
  31.           this.punctuationOverflow = false
  32.         }).margin(5)
  33.       }
  34.     }.width('100%').padding(20)
  35.   }
  36. }

示例24（设置自适应间距）

该示例通过includeFontPadding接口增加首行尾行间距和fallbackLineSpacing接口设置自适应行间距。

从API version 23开始，新增includeFontPadding和fallbackLineSpacing接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. 

  3. const UYGHUR_TEXT: string = 'ياخشىمۇسەنياخشىمۇسەنياخشىمۇسەنياخشىمۇسەنياخشىمۇسەنياخشىمۇسەنياخشىمۇسەن';
  4. @Entry
  5. @Component
  6. struct Index {
  7.   @State include: boolean | null | undefined = false;
  8.   @State fallback: boolean | null | undefined = false;
  9.   @State displayText: string = UYGHUR_TEXT;
  10. 

  11.   build() {
  12.     Column() {
  13.       Text(this.displayText)
  14.         .includeFontPadding(this.include)
  15.         .fallbackLineSpacing(this.fallback)
  16.         .lineHeight(5)
  17.         .width('100%')
  18.         .height(100)
  19.         .backgroundColor('#eee')
  20.         .borderWidth(1)
  21.         .borderColor('#dddddd')
  22. 

  23.       Scroll() {
  24.         Column() {
  25.           // --- IncludeFontPadding相关按钮 ---
  26.           Button('设置includePadding: ' + this.include)
  27.             .onClick(() => {
  28.               this.include = this.include === false ? true : false;
  29.             })
  30.             .margin({ bottom: 10 })
  31. 

  32.           // --- FallbackLineSpacing相关按钮 ---
  33.           Button('设置fallbackLineSpacing: ' + this.fallback)
  34.             .onClick(() => {
  35.               this.fallback = this.fallback === false ? true : false;
  36.             })
  37.             .margin({ bottom: 10 })
  38. 

  39.         }
  40.         .width('100%')
  41.         .padding(5)
  42.       }
  43.       .height(250)
  44.       .backgroundColor('transparent')
  45.       .scrollBarWidth(2)
  46.       .scrollBarColor('#888')
  47. 

  48.     }
  49.     .width('100%')
  50.     .height('100%')
  51.     .padding(20)
  52.   }
  53. }

示例25（设置文本拖拽时的背板样式）

该示例通过selectedDragPreviewStyle接口设置文本拖拽时的背板样式。

从API version 23开始，新增selectedDragPreviewStyle接口。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct TextTest {
  4.   build() {
  5.     Column() {
  6.       Text('This is drag text')
  7.         .copyOption(CopyOptions.InApp)
  8.         .width(200)
  9.         .height(100)
  10.         .margin(150)
  11.         .draggable(true)
  12.         .selectedDragPreviewStyle({color: 'rgba(227, 248, 249, 1)'})
  13.     }
  14.     .height('100%')
  15.   }
  16. }

示例26（设置文本排版方向）

该示例通过textDirection接口设置文本排版方向。

从API version 23开始，新增textDirection接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample {
  5.   @State text: string = 'Text文本排版方向示例';
  6. 

  7.   build() {
  8.     Column({ space: 3 }) {
  9.       Text('Text文本排版方向DEFAULT')
  10.         .fontSize(12).width('90%').margin(5)
  11.       Text(this.text)
  12.         .width('95%')
  13.         .borderWidth(1)
  14.       Text('Text文本排版方向RTL')
  15.         .fontSize(12).width('90%').margin(5)
  16.       Text(this.text)
  17.         .width('95%')
  18.         .borderWidth(1)
  19.         .textDirection(TextDirection.RTL)
  20.       Text('Text文本排版方向RTL，文本水平方向对齐方式LEFT')
  21.         .fontSize(12).width('90%').margin(5)
  22.       Text(this.text)
  23.         .width('95%')
  24.         .borderWidth(1)
  25.         .textDirection(TextDirection.RTL)
  26.         .textAlign(TextAlign.LEFT)
  27.     }
  28.     .width('100%')
  29.     .height('100%')
  30.   }
  31. }

示例27（获取指定坐标和范围对应的文本信息）

从API version 24开始，支持getCharacterPositionAtCoordinate，getGlyphRangeForCharacterRange，getCharacterRangeForGlyphRange接口。该示例通过getLayoutManager接口调用文本的布局管理对象获取文本信息，通过LayoutManager中的getCharacterPositionAtCoordinate获取坐标字符的位置信息，通过getGlyphRangeForCharacterRange根据字符索引范围获取字形索引范围和实际的字符索引范围，通过getCharacterRangeForGlyphRange根据字形索引范围获取字符索引范围和实际的字形索引范围。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { LengthMetrics } from '@kit.ArkUI';
  3. 

  4. @Entry
  5. @Component
  6. struct TextExample10 {
  7.   @State start: number = 10;
  8.   @State end: number = 20;
  9.   textController: TextController = new TextController();
  10.   textStr: string = 'Hello World! 您好，世界!';
  11.   @State str1: string = ''
  12.   @State str2: string = ''
  13.   @State str3: string = ''
  14.   @State str4: string = ''
  15.   titleParagraphStyleAttr: ParagraphStyle =
  16.     new ParagraphStyle({ paragraphSpacing: LengthMetrics.px(50), textIndent: LengthMetrics.vp(15) });
  17.   mutableStyledString: MutableStyledString =
  18.     new MutableStyledString('属性字符串TextStyle测试\n属性字符串测试\n属性字符串TextStyle测试');
  19. 

  20.   build() {
  21.     Column() {
  22.       Text(this.textStr, { controller: this.textController }) {
  23.         Span('Hello World 123 \n')
  24.         Span('Hello World 456 \n')
  25.         Span('Hello World 789 \n')
  26.       }
  27.       .fontSize(25)
  28.       .borderWidth(1)
  29. 

  30.       Text(this.str1)
  31.       Text(this.str2)
  32.       Text(this.str3)
  33.       Text(this.str4)
  34. 

  35.       Button('点击可增加属性字符串').onClick(() => {
  36.         this.textController.setStyledString(this.mutableStyledString)
  37.       })
  38. 

  39.       Button('相对组件坐标[150,50]字形信息')
  40.         .onClick(() => {
  41.           // getLayoutManager在TextController未绑定Text或Text被销毁时会返回undefined，使用时需做判空处理
  42.           let layoutManager: LayoutManager = this.textController.getLayoutManager();
  43.           if (!layoutManager) {
  44.             return;
  45.           }
  46.           let position1: PositionWithAffinity = layoutManager.getGlyphPositionAtCoordinate(150, 50);
  47.           this.str1 = '相对组件坐标[150,50] glyphPosition position: ' + position1.position +
  48.             ' affinity: ' +
  49.           position1.affinity;
  50. 

  51.           let position2: PositionWithAffinity =
  52.             layoutManager.getCharacterPositionAtCoordinate(150, 50) as PositionWithAffinity;
  53.           this.str2 = '相对组件坐标[150,50] characterPosition position: ' + position2.position +
  54.             ' affinity: ' +
  55.           position2.affinity;
  56. 

  57.           let range1: TextRange = { start: this.start, end: this.end };
  58.           let ranges1: Array<TextRange> = layoutManager.getGlyphRangeForCharacterRange(range1) as Array<TextRange>
  59.           this.str3 = 'getGlyphRangeForCharacterRange 字形数 ' + ranges1[0].start + ' ' + ranges1[0].end + '\n' +
  60.             'getGlyphRangeForCharacterRange 实际字符数 ' + ranges1[1].start + ' ' + ranges1[1].end
  61. 

  62.           let range2: TextRange = { start: this.start, end: this.end };
  63.           let ranges2: Array<TextRange> = layoutManager.getCharacterRangeForGlyphRange(range2) as Array<TextRange>
  64.           this.str4 = 'getCharacterRangeForGlyphRange 字符数 ' + ranges2[0].start + ' ' + ranges2[0].end + '\n' +
  65.             'getCharacterRangeForGlyphRange 实际字形数 ' + ranges2[1].start + ' ' + ranges2[1].end
  66.         })
  67.         .margin({ bottom: 20, top: 10 })
  68.     }.justifyContent(FlexAlign.Center).width('100%').height('100%')
  69.   }
  70. }

示例28（设置文本排版时是否使能孤字优化）

该示例通过orphanCharOptimization接口设置使能孤字优化，确保段落最后一行不出现孤字。

从API版本26.0.0开始，新增orphanCharOptimization接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample {
  5.   @State text: string = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa文本aaaaaaaaaaaaa';
  6. 

  7.   build() {
  8.     Column({ space: 3 }) {
  9.       Text('Text不使能孤字优化')
  10.         .fontSize(12).width('90%').margin(5)
  11.       Text(this.text)
  12.         .fontSize(20)
  13.         .width('456')
  14.         .borderWidth(1)
  15.       Text('Text使能孤字优化')
  16.         .fontSize(12).width('90%').margin(5)
  17.       Text(this.text)
  18.         .fontSize(20)
  19.         .width('456')
  20.         .borderWidth(1)
  21.         .orphanCharOptimization(true)
  22.     }
  23.     .width('100%')
  24.     .height('100%')
  25.   }
  26. }

该效果图会因设备尺寸差异有显示区别，仅供参考。

示例29（设置可变字体的属性）

该示例通过fontVariations接口设置可变字体的属性。

从API版本26.0.0开始，新增fontVariations接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample {
  5.   @State weightValue: number = 400;
  6. 

  7.   build() {
  8.     Column() {
  9.       Text('Hello World !')
  10.         // wght代表可变字体的字重属性
  11.         .fontVariations([{ axis: 'wght', value: this.weightValue }])
  12.       Button('字重: ' + this.weightValue)
  13.         .margin(10)
  14.         .onClick(() => {
  15.           this.weightValue += 100;
  16.         })
  17.     }.width('100%')
  18.   }
  19. }

示例30（设置图片预览菜单）

该示例通过bindSelectionMenu接口实现了文本设置图片预览菜单的功能。

从API版本26.0.0开始，文本组件调用该接口时，options中的menuType属性传入MenuType.PREVIEW_MENU，设置图片预览菜单的能力生效。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextExample {
  5.   @Builder
  6.   panel() {
  7.     Column() {
  8.       Text('abc').backgroundColor('#F0F0F0')
  9.     }.width(256)
  10.   }
  11. 

  12.   build() {
  13.     Column() {
  14.       Column() {
  15.         Text() {
  16.           Span('Hello')
  17.             .fontSize(50)
  18.           // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。
  19.           ImageSpan($r('app.media.startIcon'))
  20.             .width(30).height(30)
  21.             .verticalAlign(ImageSpanAlignment.FOLLOW_PARAGRAPH)// 从API version 20开始，支持ImageSpanAlignment.FOLLOW_PARAGRAPH
  22.           Span('World')
  23.         }
  24.         .textVerticalAlign(TextVerticalAlign.CENTER)
  25.         .borderWidth(1)
  26.         .copyOption(CopyOptions.InApp)
  27.         .bindSelectionMenu(TextSpanType.IMAGE, this.panel, TextResponseType.LONG_PRESS, {
  28.           menuType : MenuType.PREVIEW_MENU,
  29.           previewMenuOptions : {
  30.             hapticFeedbackMode : HapticFeedbackMode.ENABLED
  31.           }
  32.         })
  33.       }.width('100%').backgroundColor(Color.White)
  34.     }.height('100%')
  35.   }
  36. }

示例31（设置属性字符串段落缓存策略）

该示例通过incrementalUpdatePolicy接口设置文本渲染的增量更新策略，使用段落级缓存优化渲染性能。

从API版本26.0.0开始，新增incrementalUpdatePolicy属性。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { LengthMetrics } from '@kit.ArkUI';
  3. 

  4. @Entry
  5. @Component
  6. struct StyledStringAppend {
  7.   textController: TextController = new TextController();
  8.   scroller: Scroller = new Scroller();
  9.   @State index: number = 0
  10.   // 段落标题样式：居中、加粗
  11.   titleParagraphStyle: ParagraphStyle = new ParagraphStyle({ textAlign: TextAlign.Center });
  12.   // 第一段落样式：首行缩进20vp
  13.   paragraphStyleAttr1: ParagraphStyle = new ParagraphStyle({ textIndent: LengthMetrics.vp(20) });
  14.   // 第二段落样式：左对齐、首行缩进20vp
  15.   paragraphStyleAttr2: ParagraphStyle =
  16.     new ParagraphStyle({ textAlign: TextAlign.Start, textIndent: LengthMetrics.vp(20) });
  17.   // 行高样式
  18.   lineHeightStyle: LineHeightStyle = new LineHeightStyle(new LengthMetrics(30));
  19.   str: string = '属性字符串段落缓存示例'
  20.   styledString1: MutableStyledString = new MutableStyledString(this.str, [{
  21.     start: 0,
  22.     length: this.str.length,
  23.     styledKey: StyledStringKey.PARAGRAPH_STYLE,
  24.     styledValue: this.titleParagraphStyle
  25.   }, {
  26.     start: 0,
  27.     length: this.str.length,
  28.     styledKey: StyledStringKey.LINE_HEIGHT,
  29.     styledValue: this.lineHeightStyle
  30.   }, {
  31.     start: 0,
  32.     length: this.str.length,
  33.     styledKey: StyledStringKey.FONT,
  34.     styledValue: new TextStyle({
  35.       fontColor: Color.Blue,
  36.       fontWeight: FontWeight.Bolder
  37.     })
  38.   }]);
  39. 

  40.   aboutToAppear() {
  41.     // 追加初始段落内容，设置段落缩进和行高
  42.     let str1: string = '\n首段落：'
  43.     let str2: string = '属性字符串支持段落样式缓存，单击下方按钮追加新段落，验证段落缓存效果。'
  44.     let paragraph1: StyledString =
  45.       new StyledString(str1 + str2, [{
  46.         start: 0,
  47.         length: str1.length,
  48.         styledKey: StyledStringKey.PARAGRAPH_STYLE,
  49.         styledValue: this.paragraphStyleAttr1
  50.       }, {
  51.         start: 0,
  52.         length: str1.length,
  53.         styledKey: StyledStringKey.FONT,
  54.         styledValue: new TextStyle({
  55.           fontColor: Color.Blue,
  56.           fontWeight: FontWeight.Bold
  57.         })
  58.       }, {
  59.         start: 0,
  60.         length: str1.length + str2.length,
  61.         styledKey: StyledStringKey.LINE_HEIGHT,
  62.         styledValue: this.lineHeightStyle
  63.       }]);
  64.     this.styledString1.appendStyledString(paragraph1);
  65.     this.textController.setStyledString(this.styledString1);
  66.   }
  67. 

  68.   build() {
  69.     Column() {
  70.       Scroll(this.scroller) {
  71.         Column() {
  72.           Text('示例：属性字符串段落缓存\n单击"追加文本"追加新段落，后端走段落缓存\n')
  73.             .fontSize(16)
  74.             .fontColor(Color.Gray)
  75.             .margin({ bottom: 5 })
  76.             .width("100%")
  77. 

  78.           Text(undefined, { controller: this.textController })
  79.             .width('100%')
  80.             .borderWidth(1)
  81.             .padding(10)
  82.             .copyOption(CopyOptions.InApp)
  83.             .incrementalUpdatePolicy(IncrementalUpdatePolicy.PARAGRAPH_CACHE)
  84.         }
  85.         .width('100%')
  86.         .padding({ left: 20, right: 20 })
  87.       }
  88.       .width('100%')
  89. 

  90.       Button("追加文本")
  91.         .width('80%')
  92.         .margin({ top: 10, bottom: 15 })
  93.         .onClick(() => {
  94.           this.index++;
  95.           // 追加新段落，每个段落带有段落缩进样式，触发后端段落缓存
  96.           let str1: string = '\n第' + this.index + '段落：'
  97.           let str2: string = '这是追加的文本内容，用于验证段落缓存机制。'
  98.           let newParagraph: StyledString = new StyledString(
  99.             str1 + str2,
  100.             [{
  101.               start: 0,
  102.               length: str1.length,
  103.               styledKey: StyledStringKey.PARAGRAPH_STYLE,
  104.               styledValue: this.paragraphStyleAttr2
  105.             }, {
  106.               start: 0,
  107.               length: str1.length + str2.length,
  108.               styledKey: StyledStringKey.LINE_HEIGHT,
  109.               styledValue: this.lineHeightStyle
  110.             }, {
  111.               start: 0,
  112.               length: str1.length,
  113.               styledKey: StyledStringKey.FONT,
  114.               styledValue: new TextStyle({
  115.                 fontColor: Color.Blue,
  116.                 fontWeight: FontWeight.Bold
  117.               })
  118.             }]);
  119.           this.styledString1.appendStyledString(newParagraph);
  120.           this.textController.setStyledString(this.styledString1);
  121.         })
  122.     }
  123.     .width('100%')
  124.     .height('70%')
  125.   }
  126. }

示例32（设置文本尾部缩进）

该示例通过tailIndents接口实现了文本尾部缩进的功能。

从API版本26.0.0开始，通过tailIndents属性设置文本尾部缩进。

收起
自动换行
深色代码主题
复制
  1. import { LengthMetrics } from '@kit.ArkUI';
  2. 

  3. @Entry
  4. @Component
  5. struct TailIndentsExample {
  6.   build() {
  7.     Column() {
  8.       Text('未设置tailIndents\n未设置tailIndents\n未设置tailIndents\n未设置tailIndents\n未设置tailIndents')
  9.         .fontSize(20)
  10.         .borderWidth(1)
  11.         .borderColor(Color.Blue)
  12.         .textAlign(TextAlign.End)
  13.         .width('100%')
  14. 

  15.       Text('设置tailIndents单值\n设置tailIndents单值\n设置tailIndents单值\n设置tailIndents单值\n设置tailIndents单值')
  16.         .fontSize(20)
  17.         .borderWidth(1)
  18.         .borderColor(Color.Blue)
  19.         .textAlign(TextAlign.End)
  20.         .width('100%')
  21.         .tailIndents(LengthMetrics.vp(100))
  22. 

  23.       Text('设置tailIndents数组\n设置tailIndents数组\n设置tailIndents数组\n设置tailIndents数组\n设置tailIndents数组')
  24.         .fontSize(20)
  25.         .borderWidth(1)
  26.         .borderColor(Color.Blue)
  27.         .textAlign(TextAlign.End)
  28.         .width('100%')
  29.         .tailIndents([LengthMetrics.vp(100), LengthMetrics.vp(50), LengthMetrics.vp(20)])
  30. 

  31.     }
  32.     .height('100%')
  33.     .width('100%')
  34.   }
  35. }

示例33（设置文本选择的AI菜单）

该示例通过enableSelectedDataDetector，配置文本选择AI菜单功能。

从API version 22开始，新增enableSelectedDataDetector。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct DataDetectorDemo {
  4.   exampleText: string = '示例网址：www.example.com';
  5. 

  6.   build() {
  7.     Column() {
  8.       Row(){
  9.         Text(this.exampleText)
  10.           .copyOption(CopyOptions.LocalDevice)
  11.           .enableSelectedDataDetector(true)
  12.           .border({ width: 1, color: Color.Black })
  13.           .padding(10)
  14.           .margin(10)
  15.       }
  16.     }.width('100%')
  17.   }
  18. }

示例34（长按含表情符号文本绘制渐变高亮背景）

该示例通过getLayoutManager接口获取文本的布局管理对象，使用LayoutManager中以UTF-16编码查询的getCharacterPositionAtCoordinate根据长按坐标获取字符位置与亲和性，再通过getGlyphRangeForCharacterRange获取对应的字形索引范围与实际字符范围，最后通过getRectsForRange获取文本矩形区域，并在Canvas上绘制渐变背景，实现对包含表情符号（字形簇）文本的高亮。

从API版本26.0.0开始，新增带编码类型参数的getCharacterPositionAtCoordinate、getGlyphRangeForCharacterRange、getCharacterRangeForGlyphRange接口重载，以及TextEncoding枚举。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { LengthMetrics } from '@kit.ArkUI';
  3. import { text } from '@kit.ArkGraphics2D';
  4. 

  5. const TEXT_CONTENT: string =
  6.   '这是一段包含表情符号的测试文本\u{1F60A}。长按文字可查看渐变高亮效果\u{1F389}。\n' +
  7.   '复杂表情符号\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}也会被正确处理' +
  8.   '\u{1F3F3}\u{FE0F}\u{200D}\u{1F308}，再来一些emoji\u{1F680}\u{1F31F}\u{1F4BB}和中文混排。\n' +
  9.   '第三行：可以长按不同位置试试各种字符\u{1F600}\u{1F431}\u{1F409}。';
  10. 

  11. @Entry
  12. @Component
  13. struct Utf16GlyphHighlightPage {
  14.   private textController: TextController = new TextController();
  15.   private canvasContext: CanvasRenderingContext2D = new CanvasRenderingContext2D(new RenderingContextSettings(true));
  16.   @State isCanvasReady: boolean = false;
  17.   @State resultInfo: string = '长按下方文字（含表情符号）查看渐变背景高亮效果';
  18. 

  19.   aboutToAppear(): void {
  20.     const styledString = new MutableStyledString(TEXT_CONTENT, [{
  21.       start: 0, length: TEXT_CONTENT.length,
  22.       styledKey: StyledStringKey.FONT,
  23.       styledValue: new TextStyle({ fontSize: LengthMetrics.vp(24) })
  24.     }]);
  25.     this.textController.setStyledString(styledString);
  26.   }
  27. 

  28.   build() {
  29.     Column() {
  30.       Text(this.resultInfo)
  31.         .fontSize(13).fontColor('#666666')
  32.         .padding({ left: 16, right: 16, top: 12, bottom: 8 })
  33.         .margin({ left: 12, right: 12, top: 12 })
  34.         .width('100%').height(110)
  35.       Stack({ alignContent: Alignment.TopStart }) {
  36.         Canvas(this.canvasContext).width('100%').height('100%')
  37.           .onReady(() => { this.isCanvasReady = true; })
  38.         Text(undefined, { controller: this.textController })
  39.           .gesture(LongPressGesture({ repeat: false, duration: 500 })
  40.             .onAction((event: GestureEvent) => { this.handleLongPress(event); }))
  41.       }
  42.       .layoutWeight(1).width('100%')
  43.       .padding({ left: 16, right: 16, top: 12 })
  44.       .margin({ left: 12, right: 12, bottom: 12 }).clip(true)
  45.     }.height('100%').width('100%')
  46.   }
  47. 

  48.   private handleLongPress(event: GestureEvent): void {
  49.     // 处理流程：坐标转px -> getCharacterPositionAtCoordinate获取字符位置与亲和性 ->
  50.     //           依亲和性确定字符范围 -> getGlyphRangeForCharacterRange获取字形范围与实际字符范围 ->
  51.     //           getRectsForRange获取矩形区域 -> Canvas绘制渐变背景
  52.     if (!this.isCanvasReady) { this.resultInfo = 'Canvas 尚未就绪，请稍后重试'; return; }
  53.     const uiContext = this.getUIContext();
  54.     // 获取文本布局管理对象，用于后续的字符位置/字形范围/矩形区域查询
  55.     const layoutManager = this.textController.getLayoutManager();
  56.     if (!layoutManager) { this.resultInfo = 'LayoutManager 不可用'; return; }
  57.     const finger = event.fingerList[0];
  58.     if (!finger) { this.resultInfo = '未获取到手指信息'; return; }
  59.     // 将长按坐标从vp转换为px，供布局查询接口使用
  60.     const localXPx = uiContext.vp2px(finger.localX);
  61.     const localYPx = uiContext.vp2px(finger.localY);
  62.     // 以UTF-16编码查询距离长按坐标最近的字符位置及亲和性
  63.     const posAffinity = layoutManager.getCharacterPositionAtCoordinate(localXPx, localYPx, TextEncoding.TEXT_ENCODING_UTF16);
  64.     if (!posAffinity) { this.resultInfo = 'getCharacterPositionAtCoordinate 返回 undefined'; return; }
  65.     const index = posAffinity.position;
  66.     const affinity = posAffinity.affinity;
  67.     let charStart: number, charEnd: number;
  68.     if (affinity === text.Affinity.UPSTREAM) {
  69.       charStart = Math.max(0, index - 1); charEnd = index;
  70.     } else {
  71.       charStart = index; charEnd = index + 1;
  72.     }
  73.     // 根据字符范围查询对应的字形范围与实际字符范围（UTF-16编码）
  74.     const glyphRanges = layoutManager.getGlyphRangeForCharacterRange(
  75.       { start: charStart, end: charEnd }, TextEncoding.TEXT_ENCODING_UTF16);
  76.     if (!glyphRanges || glyphRanges.length === 0) {
  77.       this.resultInfo = `getGlyphRangeForCharacterRange 返回空, index=${index}, affinity=${affinity}`; return;
  78.     }
  79.     const actualRange: TextRange = glyphRanges.length >= 2 ? glyphRanges[1] : { start: charStart, end: charEnd };
  80.     // 根据实际字符范围获取文本矩形区域，用于绘制高亮背景
  81.     const textBoxes = layoutManager.getRectsForRange(actualRange, text.RectWidthStyle.TIGHT, text.RectHeightStyle.TIGHT);
  82.     if (!textBoxes || textBoxes.length === 0) {
  83.       this.resultInfo = `getRectsForRange 返回空, range=[${actualRange.start}, ${actualRange.end}]`; return;
  84.     }
  85.     this.drawGradientBackground(uiContext, textBoxes);
  86.     const affinityStr = affinity === text.Affinity.UPSTREAM ? 'UPSTREAM(0)' : 'DOWNSTREAM(1)';
  87.     this.resultInfo =
  88.       `坐标: (${finger.localX.toFixed(1)}, ${finger.localY.toFixed(1)})vp\n` +
  89.       `UTF16偏移: ${index}, 亲和性: ${affinityStr}\n` +
  90.       `传入范围: [${charStart}, ${charEnd}] -> 实际字符范围: [${actualRange.start}, ${actualRange.end}]\n` +
  91.       `矩形数: ${textBoxes.length}`;
  92.   }
  93. 

  94.   private drawGradientBackground(uiContext: UIContext, textBoxes: TextBox[]): void {
  95.     const ctx = this.canvasContext;
  96.     ctx.clearRect(0, 0, 5000, 5000);
  97.     for (const box of textBoxes) {
  98.       const r = box.rect;
  99.       const l = uiContext.px2vp(r.left), t = uiContext.px2vp(r.top);
  100.       const w = uiContext.px2vp(r.right) - l, h = uiContext.px2vp(r.bottom) - t;
  101.       if (w <= 0 || h <= 0) continue;
  102.       const g = ctx.createLinearGradient(l, t, l + w, t + h);
  103.       g.addColorStop(0, 'rgba(187, 153, 255, 0.66)');
  104.       g.addColorStop(1, 'rgba(129, 229, 255, 0.66)');
  105.       ctx.fillStyle = g;
  106.       ctx.beginPath();
  107.       ctx.roundRect(l, t, w, h, 4);
  108.       ctx.fill();
  109.     }
  110.   }
  111. }

该效果图会因设备尺寸差异有显示区别，仅供参考。

文本与输入
TextArea
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明