输入框类组件通用接口
为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 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
