大网数据广告活动
OpenHarmony 设备与应用开发

输入框类组件通用接口

· 52CE 我爱测

为TextInput、TextArea组件提供获取文本和光标信息、插入和删除文本、设置计数器以及文本装饰线的能力。

输入框类组件通用接口

为TextInput、TextArea组件提供获取文本和光标信息、插入和删除文本、设置计数器以及文本装饰线的能力。

为Search组件提供获取文本和光标信息、插入和删除文本以及设置文本装饰线的能力。

说明:

  • 从API version 10开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

  • 本模块接口仅可在Stage模型下使用。

TextContentControllerBase

TextInput、TextArea、Search的基础控制器。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

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

getTextContentRect

getTextContentRect(): RectResult

获取已编辑文本内容区域相对于组件的位置和大小,返回值的单位为像素。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

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

返回值:

类型 说明
RectResult 获取已编辑文本内容区域相对组件的位置和大小。
当controller未绑定组件或绑定controller的组件被释放时,返回undefined。

说明:

  • 初始不输入文本时,返回值中有相对组件的位置信息,大小为0。
  • 返回值中的位置信息是第一个字符相对于可编辑组件的位置。
  • 在Search组件中,返回的位置信息是相对Search组件中搜索图标的偏移值。
  • 有输入时,返回信息中的宽度是组件编辑区域的固定宽度。

getTextContentLineCount

getTextContentLineCount(): number

获取已编辑文本内容的行数。

原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。

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

返回值:

类型 说明
number 已编辑文本内容行数。
当controller未绑定组件或绑定controller的组件被释放时,返回undefined。

getCaretOffset11+

getCaretOffset(): CaretOffset

返回当前光标所在位置信息。

说明:

  • 在当前帧更新光标位置同时调用该接口,该接口不生效。
  • 在Search组件中,返回的位置信息是相对Search组件中搜索图标的偏移值。
  • 在Search组件中,不输入文本时,返回值中有相对Search组件的位置信息。
  • 返回值中的位置信息是光标相对于可编辑组件的位置。
  • 当无法获取光标位置时(例如TextInputController未与TextInput组件绑定时),该接口返回null。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

返回值:

类型 说明
CaretOffset 光标相对输入框的位置。
当controller未绑定组件或绑定controller的组件被释放时,返回undefined。

addText15+

addText(text: string, textOperationOptions?: TextContentControllerOptions): number

在已编辑文本的指定位置插入文本,默认插入至文本末尾。

拖拽文本的状态下不生效。

addText仅影响应用内部的UI表现,不影响输入法应用的内部逻辑,不推荐在预上屏状态下调用。

原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。

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

参数:

参数名 类型 必填 说明
text string 是 插入的文本内容。
textOperationOptions TextContentControllerOptions 否 插入文本的配置选项,不设置时默认插入文本至末尾。

返回值:

类型 说明
number 插入文本后光标的位置。

setStyledPlaceholder22+

setStyledPlaceholder(styledString: StyledString): void

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

原子化服务API: 从API version 22开始,该接口支持在原子化服务中使用。

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

参数:

参数名 类型 必填 说明
styledString StyledString 是 设置属性字符串样式的Placeholder,其优先级高于纯文本的placeholder属性。
Placeholder不支持属性字符串事件手势,超链接跳转。

deleteText15+

deleteText(range?: TextRange): void

删除已编辑文本的指定区域的内容。

说明:

  • 拖拽文本的状态下不生效。
  • deleteText仅影响应用内部的UI表现,不影响输入法应用的内部逻辑,不推荐在预上屏状态下调用。

原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。

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

参数:

参数名 类型 必填 说明
range TextRange 否 删除文本的范围,包括删除文本的起始位置和终止位置。
未指定删除范围时,默认将删除全部文本。未指定删除文本的起始位置,则默认从下标0开始删除;未指定删除文本的终止位置,则默认以文本末尾作为删除的结束点。

getSelection15+

getSelection(): TextRange

返回当前文本的选择范围。

原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。

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

返回值:

类型 说明
TextRange 文本当前的选择范围,未选中返回光标位置。
当controller未绑定组件或绑定controller的组件被释放时,返回undefined。

clearPreviewText17+

clearPreviewText(): void

通知输入法清除当前的预上屏文本内容。

原子化服务API: 从API version 17开始,该接口支持在原子化服务中使用。

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

deleteBackward23+

deleteBackward(): void

删除基础控制器controller绑定的文本输入框内文本光标前的一个字符。如果在调用此功能前已用鼠标或键盘选中了部分文本,则会删除被选中的文本。

该接口不支持预上屏场景使用。

原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。

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

scrollToVisible23+

scrollToVisible(range?: TextRange): void

将起始索引与结束索引传递给与其绑定的输入框(TextInput、TextArea、Search)组件,并将此范围内的文字滚动到可视区域。

原子化服务API: 从API version 23开始,该接口支持在原子化服务中使用。

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

参数:

参数名 类型 必填 说明
range TextRange 否 滚动到可视区域的文本范围,包括文本起始位置和终止位置。
起始位置应小于等于结束位置,否则接口调用无效。起始位置小于0视为0,结束位置大于全文长度视为全文长度。
未指定范围时,默认为全部文本。未指定起始位置,默认起始位置为0;未指定结束位置,默认结束位置为全文长度。

InputCounterOptions11+对象说明

计数器的配置项。

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

名称 类型 只读 可选 说明
thresholdPercentage number 否 是 thresholdPercentage是可输入字符数占最大字符限制的百分比值。字符计数器显示的样式为当前输入字符数/最大字符数。当输入字符数大于最大字符数乘百分比值时,显示字符计数器。thresholdPercentage值的有效值区间为[1,100],数值为小数时,向下取整,如果设置的number超出有效值区间内,不显示字符计数器。thresholdPercentage设置为undefined,显示字符计数器,但此参数不生效。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
highlightBorder boolean 否 是 如果用户设置计数器时不设置InputCounterOptions,那么当前输入字符数达到最大字符数时,边框和计数器下标将变为红色。如果用户设置显示字符计数器同时thresholdPercentage参数数值在有效区间内,那么当输入字符数超过最大字符数时,边框和计数器下标将变成红色。如果此参数为true,则显示红色边框,参数为false则不显示。
默认值:true
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
counterTextColor22+ ColorMetrics 否 是 设置组件中字符计数器的文本颜色。当用户输入字符数大于最大字符数乘百分比值时,计数器会显示当前输入的字符数,并且计数器的文本颜色为counterTextColor指定的颜色。如果不设置counterTextColor,则计数器的文本颜色为默认颜色,默认颜色为灰色。
原子化服务API: 从API version 22开始,该接口支持在原子化服务中使用。
counterTextOverflowColor22+ ColorMetrics 否 是 设置组件中字符计数器在溢出时的文本颜色。当用户输入的字符数超过计数器最大长度时,计数器的文本颜色和边框的颜色会切换为counterTextOverflowColor指定的颜色,以提醒用户输入已超出限制。如果不设置counterTextOverflowColor,则计数器和边框在溢出时的文本颜色为默认颜色,默认颜色为红色。
说明:
当设置了InputCounterOptions的highlightBorder属性时,边框颜色才会被同步更改。
原子化服务API: 从API version 22开始,该接口支持在原子化服务中使用。

CaretOffset11+对象说明

光标相对输入框的位置信息。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

名称 类型 只读 可选 说明
index number 否 否 光标所在位置的索引值。
x number 否 否 光标相对输入框的x坐标值,单位px。
y number 否 否 光标相对输入框的y坐标值,单位px。

TextDecorationOptions12+对象说明

文本装饰线的配置项。

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

名称 类型 只读 可选 说明
type TextDecorationType 否 否 设置文本装饰线类型。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
color  ResourceColor 否 是 设置文本装饰线颜色。
默认值:Color.Black。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
style TextDecorationStyle 否 是 设置文本装饰线样式。
默认值:TextDecorationStyle.SOLID。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
thicknessScale number 否 是 设置文本装饰线的粗细缩放比例。
默认值:1.0
取值范围:[0, +∞)
说明: 负值按默认值处理。
起始版本: 26.0.0
原子化服务API: 从API版本26.0.0开始,该接口支持在原子化服务中使用。
模型约束: 此接口仅可在Stage模型下使用。

SelectionOptions12+对象说明

setTextSelection选中文字时的配置。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

名称 类型 只读 可选 说明
menuPolicy MenuPolicy 否 是 菜单弹出的策略。 默认值:MenuPolicy.DEFAULT。

MenuPolicy12+

菜单弹出的策略。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

名称 值 说明
DEFAULT 0 按照底层默认逻辑决定是否弹出菜单。
HIDE 1 始终不弹出菜单。
SHOW 2 始终弹出菜单。

SymbolGlyphModifier12+

type SymbolGlyphModifier = SymbolGlyphModifier

SymbolGlyphModifier类型,用于设置自定义图标小符号。

原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。

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

类型 说明
SymbolGlyphModifier 返回当前的SymbolGlyphModifier。

TextContentControllerOptions15+

用于设置输入框插入字符时的配置选项。

原子化服务API: 从API version 15开始,该接口支持在原子化服务中使用。

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

名称 类型 只读 可选 说明
offset number 否 是 插入文本的位置。
说明:
当需要在指定位置(而非末尾)插入文本时传入此参数。不传入时默认插入到文本末尾。

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。