1# 输入框类组件通用接口 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @kangshihui--> 5<!--Designer: @pssea--> 6<!--Tester: @jiaoaozihao--> 7<!--Adviser: @HelloCrease--> 8 9为[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md)组件提供获取文本和光标信息、插入和删除文本、设置计数器以及文本装饰线的能力。 10为[Search](ts-basic-components-search.md)组件提供获取文本和光标信息、插入和删除文本以及设置文本装饰线的能力。 11 12> **说明：** 13> 14> 从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15 16## TextContentControllerBase 17 18TextInput、TextArea、Search的基础控制器。 19 20**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 21 22**系统能力：** SystemCapability.ArkUI.ArkUI.Full 23 24### getTextContentRect 25 26getTextContentRect(): RectResult 27 28获取已编辑文本内容区域相对于组件的位置和大小，返回值的单位为像素。 29 30**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 31 32**系统能力：** SystemCapability.ArkUI.ArkUI.Full 33 34**返回值：** 35 36| 类型 | 说明 | 37| ------------------- | -------- | 38| [RectResult](ts-universal-attributes-on-child-touch-test.md#rectresult) | 获取已编辑文本内容区域相对组件的位置和大小。 | 39 40> **说明：** 41> 42> - 初始不输入文本时，返回值中有相对组件的位置信息，大小为0。 43> - 返回值中的位置信息是第一个字符相对于可编辑组件的位置。 44> - 在Search组件中，返回的位置信息是相对Search组件中搜索图标的偏移值。 45> - 有输入时，返回信息中的宽度是组件编辑区域的固定宽度。 46 47### getTextContentLineCount 48 49getTextContentLineCount(): number 50 51获取已编辑文本内容的行数。 52 53**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 54 55**系统能力：** SystemCapability.ArkUI.ArkUI.Full 56 57**返回值：** 58 59| 类型 | 说明 | 60| ----- | -------- | 61| number| 已编辑文本内容行数。 | 62 63### getCaretOffset<sup>11+</sup> 64 65getCaretOffset(): CaretOffset 66 67返回当前光标所在位置信息。 68 69**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 70 71**系统能力：** SystemCapability.ArkUI.ArkUI.Full 72 73**返回值：** 74 75| 类型 | 说明 | 76| ----------------------- | ---------------- | 77| [CaretOffset](#caretoffset11对象说明) | 光标相对输入框的位置。 | 78 79> **说明：** 80> 81> - 在当前帧更新光标位置同时调用该接口，该接口不生效。 82> - 在Search组件中，返回的位置信息是相对Search组件中搜索图标的偏移值。 83> - 在Search组件中，不输入文本时，返回值中有相对Search组件的位置信息。 84> - 返回值中的位置信息是光标相对于可编辑组件的位置。 85 86### addText<sup>15+</sup> 87 88addText(text: string, textOperationOptions?: TextContentControllerOptions): number 89 90在已编辑文本的指定位置插入文本，默认插入至文本末尾。 91拖拽文本的状态下不生效。 92 93`addText`仅影响应用内部的UI表现，不影响输入法应用的内部逻辑，不推荐在预上屏状态下调用。 94 95**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 96 97**系统能力：** SystemCapability.ArkUI.ArkUI.Full 98 99**参数：** 100 101| 参数名 | 类型 | 必填 | 说明 | 102| ------- | ------ | ---- | ----- | 103| text | string | 是 | 插入的文本内容。 | 104| textOperationOptions | [TextContentControllerOptions](#textcontentcontrolleroptions15) | 否 | 插入文本的配置选项，不设置时默认插入文本至末尾。 | 105 106**返回值：** 107 108| 类型 | 说明 | 109| ----- | -------- | 110| number| 插入文本后光标的位置。 | 111 112### deleteText<sup>15+</sup> 113 114deleteText(range?: TextRange): void 115 116删除已编辑文本的指定区域的内容。 117拖拽文本的状态下不生效。 118 119`deleteText`仅影响应用内部的UI表现，不影响输入法应用的内部逻辑，不推荐在预上屏状态下调用。 120 121**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------- | ------ | ---- | ----- | 129| range | [TextRange](ts-text-common.md#textrange12) | 否 | 删除文本的范围，包括删除文本的起始位置和终止位置。<br>未指定删除范围时，默认将删除全部文本。未指定删除文本的起始位置，则默认从下标0开始删除；未指定删除文本的终止位置，则默认以文本末尾作为删除的结束点。 | 130 131### getSelection<sup>15+</sup> 132 133getSelection(): TextRange 134 135返回当前文本的选择范围。 136 137**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 138 139**系统能力：** SystemCapability.ArkUI.ArkUI.Full 140 141**返回值：** 142 143| 类型 | 说明 | 144| ----------------------- | ---------------- | 145| [TextRange](ts-text-common.md#textrange12) | 文本当前的选择范围，未选中返回光标位置。 | 146 147### clearPreviewText<sup>17+</sup> 148 149clearPreviewText(): void 150 151通知输入法清除当前的预上屏文本内容。 152 153**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 154 155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 156 157## InputCounterOptions<sup>11+</sup>对象说明 158 159计数器的配置项。 160 161**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 162 163**系统能力：** SystemCapability.ArkUI.ArkUI.Full 164 165| 名称 | 类型 | 只读 | 可选 | 说明 | 166| -------- | ------- | ----------- | ----------- | ----------- | 167| thresholdPercentage | number | 否 | 是 | thresholdPercentage是可输入字符数占最大字符限制的百分比值。字符计数器显示的样式为当前输入字符数/最大字符数。当输入字符数大于最大字符数乘百分比值时，显示字符计数器。thresholdPercentage值的有效值区间为[1,100]，数值为小数时，向下取整，如果设置的number超出有效值区间内，不显示字符计数器。thresholdPercentage设置为undefined，显示字符计数器，但此参数不生效。 | 168| highlightBorder | boolean | 否 | 是 | 如果用户设置计数器时不设置InputCounterOptions，那么当前输入字符数达到最大字符数时，边框和计数器下标将变为红色。如果用户设置显示字符计数器同时thresholdPercentage参数数值在有效区间内，那么当输入字符数超过最大字符数时，边框和计数器下标将变成红色。如果此参数为true，则显示红色边框。计数器默认显示红色边框。 | 169 170## CaretOffset<sup>11+</sup>对象说明 171 172光标相对输入框的位置信息。 173 174**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 175 176**系统能力：** SystemCapability.ArkUI.ArkUI.Full 177 178| 名称 | 类型 | 只读 | 可选 | 说明 | 179| -------- | ------- | ----------- | ----------- | ----------- | 180| index | number | 否 | 否 | 光标所在位置的索引值。 | 181| x | number | 否 | 否 | 光标相对输入框的x坐标位值，单位px。 | 182| y | number | 否 | 否 | 光标相对输入框的y坐标位值，单位px。 | 183 184## TextDecorationOptions<sup>12+</sup>对象说明 185 186文本装饰线的配置项。 187 188**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192| 名称 | 类型 | 只读 | 可选 | 说明 | 193| -------- | ------- | ----------- | ----------- | ----------- | 194| type | [TextDecorationType](ts-appendix-enums.md#textdecorationtype) | 否 | 否 | 设置文本装饰线类型。 | 195| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 设置文本装饰线颜色。 | 196| style | [TextDecorationStyle](ts-appendix-enums.md#textdecorationstyle12) | 否 | 是 | 设置文本装饰线样式。 | 197 198## SelectionOptions<sup>12+</sup>对象说明 199 200setTextSelection选中文字时的配置。 201 202**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 203 204**系统能力：** SystemCapability.ArkUI.ArkUI.Full 205 206| 名称 | 类型 | 只读 | 可选 | 说明 | 207| -------- | ------- | ----------- | ----------- | ----------- | 208| menuPolicy | [MenuPolicy](#menupolicy12) | 否 | 是 | 菜单弹出的策略。 | 209 210## MenuPolicy<sup>12+</sup> 211 212菜单弹出的策略。 213 214**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 215 216**系统能力：** SystemCapability.ArkUI.ArkUI.Full 217 218| 名称 | 值 | 说明 | 219| ------- | ---- | ---------------------------------- | 220| DEFAULT | 0 | 按照底层默认逻辑决定是否弹出菜单。 | 221| HIDE | 1 | 始终不弹出菜单。 | 222| SHOW | 2 | 始终弹出菜单。 | 223 224## SymbolGlyphModifier<sup>12+</sup> 225 226type SymbolGlyphModifier = SymbolGlyphModifier 227 228SymbolGlyphModifier类型，用于设置自定义图标小符号。 229 230**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 231 232**系统能力：** SystemCapability.ArkUI.ArkUI.Full 233 234| 类型 | 说明 | 235| ----- | -------- | 236| [SymbolGlyphModifier](ts-universal-attributes-attribute-symbolglyphmodifier.md#symbolglyphmodifier) | 返回当前的SymbolGlyphModifier。 | 237 238## TextContentControllerOptions<sup>15+</sup> 239 240用于设置输入框插入字符时的配置选项。 241 242**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 243 244**系统能力：** SystemCapability.ArkUI.ArkUI.Full 245 246| 名称 | 类型 | 只读 | 可选 | 说明 | 247| --------- | ------ | ---- | ---- | ---------- | 248| offset | number | 否 | 是 | 插入文本的位置。 |