1# TextArea 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @kangshihui--> 5<!--Designer: @pssea--> 6<!--Tester: @jiaoaozihao--> 7<!--Adviser: @HelloCrease--> 8 9多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。 10 11高度未设置时，组件无默认高度，自适应内容高度。宽度未设置时，默认撑满最大宽度。 12 13> **说明：** 14> 15> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16 17 18## 子组件 19 20无 21 22 23## 接口 24 25TextArea(value?: TextAreaOptions) 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ----- | ----- | ---- | ---- | 35| value | [TextAreaOptions](#textareaoptions对象说明) | 否 | TextArea组件参数。 | 36 37## TextAreaOptions对象说明 38 39TextArea初始化参数。 40 41**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.ArkUI.ArkUI.Full 44 45| 名称 | 类型 | 只读 | 可选 | 说明 | 46| ---- | ----- | ---- | ---- | ---- | 47| placeholder | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 设置无输入时的提示文本。输入内容后，提示文本不显示。<br/>仅设置placeholder属性时，手柄依然跟随拖动，手柄松开后光标停留在文字开头位置。 | 48| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 设置输入框当前的文本内容。</br>建议通过onChange事件将状态变量与文本实时绑定，</br>避免组件刷新时TextArea中的文本内容异常。<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。<br />从API version 18开始，该参数支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。| 49| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | 否 | 是 | 设置TextArea控制器。 | 50 51 52## 属性 53 54除支持[通用属性](ts-component-general-attributes.md)，还支持以下属性： 55 56> **说明：** 57> 58> [通用属性padding](ts-universal-attributes-size.md#padding)的默认值为：<br>{<br> top: '8vp',<br> right: '16vp',<br> bottom: '8vp',<br> left: '16vp'<br> } 59> 60> 从API version 11开始，多行输入框可设置.width('auto')使组件宽度自适应文本宽度，自适应时组件宽度受constraintSize属性以及父容器传递的最大最小宽度限制，其余使用方式参考[尺寸设置](ts-universal-attributes-size.md)。 61 62### placeholderColor 63 64placeholderColor(value: ResourceColor) 65 66设置placeholder文本颜色。 67 68**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| ------ | ------------------------------------------ | ---- | -------------------------------------------- | 76| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | placeholder文本颜色。<br/>默认值：跟随主题。 | 77 78### placeholderFont 79 80placeholderFont(value: Font) 81 82设置placeholder文本样式，包括字体大小、字体粗细、字体族、字体风格。当前支持'HarmonyOS Sans'字体和注册自定义字体[loadFontSync](../../apis-arkgraphics2d/js-apis-graphics-text.md#loadfontsync)。 83 84**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 85 86**系统能力：** SystemCapability.ArkUI.ArkUI.Full 87 88**参数：** 89 90| 参数名 | 类型 | 必填 | 说明 | 91| ------ | ------------------------ | ---- | --------------------- | 92| value | [Font](ts-types.md#font) | 是 | placeholder文本样式。 | 93 94### textAlign 95 96textAlign(value: TextAlign) 97 98设置文本在输入框中的水平对齐方式。 99 100支持TextAlign.Start、TextAlign.Center和TextAlign.End。 101 102可通过[align](ts-universal-attributes-location.md)属性控制文本段落在垂直方向上的位置，此组件中不可通过align属性控制文本段落在水平方向上的位置，即align属性中Alignment.TopStart、Alignment.Top、Alignment.TopEnd效果相同，控制内容在顶部，Alignment.Start、Alignment.Center、Alignment.End效果相同，控制内容垂直居中，Alignment.BottomStart、Alignment.Bottom、Alignment.BottomEnd效果相同，控制内容在底部。 103 104当textAlign属性设置为TextAlign.JUSTIFY时，最后一行文本不参与两端对齐，为水平对齐首部效果。 105 106从API version 11开始，textAlign可设置TextAlign.JUSTIFY 107 108**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| ------ | ------------------------------------------- | ---- | ---------------------------------------------------------- | 116| value | [TextAlign](ts-appendix-enums.md#textalign) | 是 | 文本在输入框中的水平对齐方式。<br/>默认值：TextAlign.Start | 117 118> **说明：** 119> 120> textAlign只能调整文本整体的布局，不影响字符的显示顺序。若需要调整字符的显示顺序，请参考[镜像状态字符对齐](../../../ui/arkts-internationalization.md#镜像状态字符对齐)。 121 122### caretColor 123 124caretColor(value: ResourceColor) 125 126设置输入框光标颜色。 127 128**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 129 130**系统能力：** SystemCapability.ArkUI.ArkUI.Full 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| ------ | ------------------------------------------ | ---- | -------------------------------------- | 136| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 输入框光标颜色。<br/>默认值：'#007DFF' | 137 138> **说明：** 139> 从API version 12开始，此接口支持设置文本手柄颜色，光标和文本手柄颜色保持一致。 140 141### fontColor 142 143fontColor(value: ResourceColor) 144 145设置字体颜色。 146 147**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 148 149**系统能力：** SystemCapability.ArkUI.ArkUI.Full 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 说明 | 154| ------ | ------------------------------------------ | ---- | ---------- | 155| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 字体颜色。 | 156 157### fontSize 158 159fontSize(value: Length) 160 161设置字体大小。 162 163**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 164 165**系统能力：** SystemCapability.ArkUI.ArkUI.Full 166 167**参数：** 168 169| 参数名 | 类型 | 必填 | 说明 | 170| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 171| value | [Length](ts-types.md#length) | 是 | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp，Wearable设备上默认值为：18fp。不支持设置百分比字符串。 | 172 173### fontStyle 174 175fontStyle(value: FontStyle) 176 177设置字体样式。 178 179**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.ArkUI.ArkUI.Full 182 183**参数：** 184 185| 参数名 | 类型 | 必填 | 说明 | 186| ------ | ------------------------------------------- | ---- | --------------------------------------- | 187| value | [FontStyle](ts-appendix-enums.md#fontstyle) | 是 | 字体样式。<br/>默认值：FontStyle.Normal | 188 189### fontWeight 190 191fontWeight(value: number | FontWeight | ResourceStr) 192 193设置文本的字体粗细，设置过大可能会在不同字体下有截断。 194 195**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 196 197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 198 199**参数：** 200 201| 参数名 | 类型 | 必填 | 说明 | 202| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 203| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| [ResourceStr](ts-types.md#resourcestr) | 是 | 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal <br>从API version 20开始，支持Resource类型。| 204 205### fontFamily 206 207fontFamily(value: ResourceStr) 208 209设置字体列表。 210 211**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215**参数：** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 219| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 字体列表。默认字体'HarmonyOS Sans'。<br>使用多个字体时，请用逗号','分隔，字体的优先级按顺序生效。例如：'Arial, HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和注册自定义字体[loadFontSync](../../apis-arkgraphics2d/js-apis-graphics-text.md#loadfontsync)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 | 220 221### inputFilter<sup>8+</sup> 222 223inputFilter(value: ResourceStr, error?: (value: string) => void) 224 225通过正则表达式设置输入过滤器。匹配表达式的输入允许显示，不匹配的输入将被过滤。 226 227单字符输入场景仅支持单字符匹配，多字符输入场景支持字符串匹配，例如粘贴。 228 229**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 230 231**系统能力：** SystemCapability.ArkUI.ArkUI.Full 232 233**参数：** 234 235| 参数名 | 类型 | 必填 | 说明 | 236| ------ | -------------------------------------- | ---- | ---------------------------------- | 237| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 正则表达式。 | 238| error | (value: string) => void | 否 | 正则匹配失败时，返回被过滤的内容。 | 239 240### copyOption<sup>9+</sup> 241 242copyOption(value: CopyOptions) 243 244设置输入的文本是否可复制。设置CopyOptions.None时，当前TextArea中的文字无法被复制、剪切、翻译、分享、搜索和帮写，支持粘贴和全选。 245 246设置CopyOptions.None时，不支持拖拽操作。 247 248**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 249 250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| ------ | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 256| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 是 | 输入的文本是否可复制。<br/>默认值：CopyOptions.LocalDevice，支持设备内复制。 | 257 258### maxLength<sup>10+</sup> 259 260maxLength(value: number) 261 262设置文本的最大输入字符数。默认不设置最大输入字符数限制。到达文本最大字符限制，将无法继续输入字符，同时边框变为红色。 263 264**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| ------ | ------ | ---- | ---------------------- | 272| value | number | 是 | 文本的最大输入字符数。 | 273 274### showCounter<sup>10+</sup> 275 276showCounter(value: boolean, options?: InputCounterOptions) 277 278设置当通过InputCounterOptions输入的字符数超过阈值时显示计数器。 279 280参数value为true时，才能设置options，文本框开启计数器功能，需要配合maxLength（设置最大字符限制）一起使用。字符计数器显示的效果是当前输入字符数/最大可输入字符数。 281 282当输入字符数大于最大字符数乘百分比值时，显示字符计数器。如果用户设置计数器时不设置InputCounterOptions，那么当前输入字符数达到最大字符数时，边框和计数器下标将变为红色。用户同时设置参数value为true和InputCounterOptions，当thresholdPercentage数值在有效区间内，且输入字符数超过最大字符数时，边框和计数器下标将变为红色，框体抖动。highlightBorder设置为false，则不显示红色边框，计数器默认显示红色边框。内联模式下字符计数器不显示。 283 284**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 285 286**系统能力：** SystemCapability.ArkUI.ArkUI.Full 287 288**参数：** 289 290| 参数名 | 类型 | 必填 | 说明 | 291| --------------------- | ------------------------------------------------------------ | ---- | ---------------- | 292| value | boolean | 是 | 是否显示计数器。<br/>true表示显示计时器，false表示不显示。 | 293| options<sup>11+</sup> | [InputCounterOptions](ts-universal-attributes-text-style.md#inputcounteroptions11对象说明) | 否 | 计数器的配置项。 | 294 295### style<sup>10+</sup> 296 297style(value: TextContentStyle) 298 299设置文本框多态样式，内联输入风格只支持TextAreaType.Normal类型。 300 301**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 302 303**系统能力：** SystemCapability.ArkUI.ArkUI.Full 304 305**参数：** 306 307| 参数名 | 类型 | 必填 | 说明 | 308| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 309| value | [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | 是 | 文本框多态样式。<br/>默认值：TextContentStyle.DEFAULT | 310 311### enableKeyboardOnFocus<sup>10+</sup> 312 313enableKeyboardOnFocus(value: boolean) 314 315设置TextArea通过点击以外的方式获焦时，是否主动拉起软键盘。 316 317从API version 10开始，获焦默认绑定输入法。 318 319**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 320 321**系统能力：** SystemCapability.ArkUI.ArkUI.Full 322 323**参数：** 324 325| 参数名 | 类型 | 必填 | 说明 | 326| ------ | ------- | ---- | ----------------------------------------------------------- | 327| value | boolean | 是 | 通过点击以外的方式获焦时，是否主动拉起软键盘。<br/>true表示主动拉起，false表示不主动拉起。<br/>默认值：true | 328 329### selectionMenuHidden<sup>10+</sup> 330 331selectionMenuHidden(value: boolean) 332 333设置是否不弹出系统文本选择菜单。 334 335**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 336 337**系统能力：** SystemCapability.ArkUI.ArkUI.Full 338 339**参数：** 340 341| 参数名 | 类型 | 必填 | 说明 | 342| ------ | ------- | ---- | ------------------------------------------------------------ | 343| value | boolean | 是 | 是否不弹出系统文本选择菜单。<br />设置为true时，单击输入框光标、长按输入框、双击输入框、三击输入框或者右键输入框，不弹出系统文本选择菜单。<br />设置为false时，弹出系统文本选择菜单。<br />默认值：false | 344 345### barState<sup>10+</sup> 346 347barState(value: BarState) 348 349设置输入框滚动条的显示模式。 350 351**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 352 353**系统能力：** SystemCapability.ArkUI.ArkUI.Full 354 355**参数：** 356 357| 参数名 | 类型 | 必填 | 说明 | 358| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 359| value | [BarState](ts-appendix-enums.md#barstate) | 是 | 输入框滚动条的显示模式。<br/>默认值：BarState.Auto | 360 361### maxLines<sup>10+</sup> 362 363maxLines(value: number) 364 365配置textOverflow一起使用时，maxLines为可显示行数，超出截断；未配置textOverflow时，内联模式获焦状态下内容超出maxLines时，文本可滚动显示，内联模式非获焦状态下不生效maxLines，非内联模式按行截断。 366 367**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 368 369**系统能力：** SystemCapability.ArkUI.ArkUI.Full 370 371**参数：** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 375| value | number | 是 | 内联输入风格编辑态时文本可显示的最大行数。<br/>默认值：3，非内联模式下，默认值为+∞，不限制最大行数。 <br/>取值范围：(0, +∞) | 376 377### maxLines<sup>20+</sup> 378 379maxLines(lines: number, options: MaxLinesOptions) 380 381配置[textOverflow](#textoverflow12)一起使用时，maxLines为可显示行数，超出可配置为截断或滚动。未配置textOverflow时，内联模式获焦状态下内容超出maxLines时，文本可滚动显示。内联模式非获焦状态下，maxLines不生效。 382 383**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 384 385**系统能力：** SystemCapability.ArkUI.ArkUI.Full 386 387**参数：** 388 389| 参数名 | 类型 | 必填 | 说明 | 390| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 391| lines | number | 是 | 内联输入风格编辑态时文本可显示的最大行数。<br/>默认值：3，非内联模式下，默认值为+∞，不限制最大行数。 <br/>取值范围：(0, +∞) | 392|options | [MaxLinesOptions](ts-text-common.md#maxlinesoptions20对象说明) | 是 | 文本超长时显示效果。<br/>默认值：MaxLinesMode.CLIP | 393 394### minLines<sup>20+</sup> 395 396minLines(lines: Optional\<number>) 397 398设置节点显示的最小行数，若传入值小于1，则自动取值为1。如果节点设置了[constraintSize](ts-universal-attributes-size.md#constraintsize)，那么组件最后显示高度会在[constraintSize](ts-universal-attributes-size.md#constraintsize)约束内。 399 400**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 401 402**系统能力：** SystemCapability.ArkUI.ArkUI.Full 403 404**参数：** 405 406| 参数名 | 类型 | 必填 | 说明 | 407| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 408| lines | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<number> | 是 | 节点最小行数。 | 409 410### customKeyboard<sup>10+</sup> 411 412customKeyboard(value: CustomBuilder, options?: KeyboardOptions) 413 414设置自定义键盘。 415 416当设置自定义键盘时，输入框激活后不会打开系统输入法，而是加载指定的自定义组件。 417 418自定义键盘的高度可以通过自定义组件根节点的height属性设置，宽度则使用系统默认值。 419 420自定义键盘采用覆盖原始界面的方式呈现，当没有开启避让模式或者输入框不需要避让的场景，不会对应用原始界面产生压缩或者上提。 421 422自定义键盘无法获取焦点，但是会拦截手势事件。 423 424默认在输入控件失去焦点时，关闭自定义键盘，开发者也可以通过[TextAreaController](#textareacontroller8).[stopEditing](#stopediting10)方法控制键盘关闭。 425 426如果设备支持拍摄输入，设置自定义键盘后，输入框将不再支持拍摄输入。 427 428当设置自定义键盘时，可以通过绑定[onKeyPrelme](ts-universal-events-key.md#onkeypreime12)事件规避物理键盘的输入。 429 430**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 431 432**系统能力：** SystemCapability.ArkUI.ArkUI.Full 433 434**参数：** 435 436| 参数名 | 类型 | 必填 | 说明 | 437| --------------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 438| value | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 自定义键盘。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 439| options<sup>12+</sup> | [KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12) | 否 | 设置自定义键盘是否支持避让功能。 | 440 441### type<sup>11+</sup> 442 443type(value: TextAreaType) 444 445设置输入框类型。 446 447**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 448 449**系统能力：** SystemCapability.ArkUI.ArkUI.Full 450 451**参数：** 452 453| 参数名 | 类型 | 必填 | 说明 | 454| ------ | --------------------------------------- | ---- | -------------------------------------------- | 455| value | [TextAreaType](#textareatype11枚举说明) | 是 | 输入框类型。<br/>默认值：TextAreaType.Normal | 456 457### enterKeyType<sup>11+</sup> 458 459enterKeyType(value: EnterKeyType) 460 461设置输入法回车键类型。 462 463**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 464 465**系统能力：** SystemCapability.ArkUI.ArkUI.Full 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| ------ | ------------------------------------------------ | ---- | ---------------------------------------------------- | 471| value | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype枚举说明) | 是 | 输入法回车键类型。<br/>默认值：EnterKeyType.NEW_LINE | 472 473### enableAutoFill<sup>12+</sup> 474 475enableAutoFill(value: boolean) 476 477设置是否启用自动填充。 478 479**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 480 481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| ------ | ------- | ---- | ------------------------------------------------------------ | 487| value | boolean | 是 | 是否启用自动填充。<br/>true表示启用，false表示不启用。<br/>默认值：true | 488 489### contentType<sup>12+</sup> 490 491contentType(contentType: ContentType) 492 493设置自动填充类型。 494 495**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 496 497**系统能力：** SystemCapability.ArkUI.ArkUI.Full 498 499**参数：** 500 501| 参数名 | 类型 | 必填 | 说明 | 502| ----------- | ------------------------------------- | ---- | -------------- | 503| contentType | [ContentType](ts-basic-components-textinput.md#contenttype12枚举说明) | 是 | 自动填充类型。 | 504 505### lineHeight<sup>12+</sup> 506 507lineHeight(value: number | string | Resource) 508 509设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。 510 511**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 512 513**系统能力：** SystemCapability.ArkUI.ArkUI.Full 514 515**参数：** 516 517| 参数名 | 类型 | 必填 | 说明 | 518| ------ | ------------------------------------------------------------ | ---- | ---------------- | 519| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本的文本行高。 | 520 521> **说明：** 522> 523> 特殊字符字体高度远超出同行的其他字符高度时，文本框出现截断、遮挡、内容相对位置发生变化等不符合预期的显示异常，需要开发者调整组件高度、行高等属性，修改对应的页面布局。 524 525### decoration<sup>12+</sup> 526 527decoration(value: TextDecorationOptions) 528 529设置文本装饰线类型样式及其颜色。 530 531**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 532 533**系统能力：** SystemCapability.ArkUI.ArkUI.Full 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 539| value | [TextDecorationOptions](ts-universal-attributes-text-style.md#textdecorationoptions12对象说明) | 是 | 文本装饰线对象。<br />默认值：{<br/> type: TextDecorationType.None,<br/> color: Color.Black,<br/> style: TextDecorationStyle.SOLID <br/>} | 540 541### letterSpacing<sup>12+</sup> 542 543letterSpacing(value: number | string | Resource) 544 545设置文本字符间距。设置该值为百分比时，按默认值显示。当设置该值为0时，使用默认值。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 546 547当取值为负值时，文字会发生压缩，负值过小时会将组件内容区大小压缩为0，导致无内容显示。 548 549对每个字符生效，包括行尾字符。 550 551**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 552 553**系统能力：** SystemCapability.ArkUI.ArkUI.Full 554 555**参数：** 556 557| 参数名 | 类型 | 必填 | 说明 | 558| ------ | -------------------------- | ---- | -------------- | 559| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本字符间距。<br/>单位：[fp](ts-pixel-units.md) | 560 561### fontFeature<sup>12+</sup> 562 563fontFeature(value: string) 564 565设置文字特性效果，比如数字等宽的特性。 566 567格式为：normal \| \<feature-tag-value\> 568 569\<feature-tag-value\>的格式为：\<string\> \[ \<integer\> \| on \| off ] 570 571\<feature-tag-value\>的个数可以有多个，中间用','隔开。 572 573例如，使用等宽数字的输入格式为："ss01" on。 574 575**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 576 577**系统能力：** SystemCapability.ArkUI.ArkUI.Full 578 579**参数：** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| ------ | ------ | ---- | -------------- | 583| value | string | 是 | 文字特性效果。 | 584 585Font Feature当前支持的属性见 [fontFeature属性列表](ts-basic-components-text.md#fontfeature12)。 586设置 Font Feature 属性，Font Feature 是 OpenType 字体的高级排版能力，如支持连字、数字等宽等特性，一般用在自定义字体中，其能力需要字体本身支持。 587更多 Font Feature 能力介绍可参考 https://www.w3.org/TR/css-fonts-3/#font-feature-settings-prop 和 https://sparanoid.com/lab/opentype-features/ 588### wordBreak<sup>12+</sup> 589 590wordBreak(value: WordBreak) 591 592设置文本断行规则。该属性对placeholder文本无效。 593 594**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 595 596**系统能力：** SystemCapability.ArkUI.ArkUI.Full 597 598**参数：** 599 600| 参数名 | 类型 | 必填 | 说明 | 601| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 602| value | [WordBreak](ts-appendix-enums.md#wordbreak11) | 是 | 文本断行规则。 <br />默认值：WordBreak.BREAK_WORD | 603 604> **说明：** 605> 606> 组件不支持clip属性设置，设置该属性任意枚举值对组件文本截断无影响。 607 608### selectedBackgroundColor<sup>12+</sup> 609 610selectedBackgroundColor(value: ResourceColor) 611 612设置文本选中底板颜色。如果未设置不透明度，默认为20%不透明度。 613 614**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 615 616**系统能力：** SystemCapability.ArkUI.ArkUI.Full 617 618**参数：** 619 620| 参数名 | 类型 | 必填 | 说明 | 621| ------ | ------------------------------------------ | ---- | ------------------------------------------ | 622| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 文本选中底板颜色。 | 623 624### caretStyle<sup>12+</sup> 625 626caretStyle(value: CaretStyle) 627 628设置光标风格。 629 630**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 631 632**系统能力：** SystemCapability.ArkUI.ArkUI.Full 633 634**参数：** 635 636| 参数名 | 类型 | 必填 | 说明 | 637| ------ | ----------------------------------- | ---- | ------------ | 638| value | [CaretStyle](ts-text-common.md#caretstyle10) | 是 | 光标的风格。 | 639 640> **说明：** 641> 642> 当同时设置caretColor属性和caretStyle属性中的color参数时，遵循后设置生效原则。 643> 644> 从API version 12开始，此接口支持设置文本手柄颜色，光标和文本手柄颜色保持一致。 645 646### textIndent<sup>12+</sup> 647 648textIndent(value: Dimension) 649 650设置首行文本缩进。 651 652**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 653 654**系统能力：** SystemCapability.ArkUI.ArkUI.Full 655 656**参数：** 657 658| 参数名 | 类型 | 必填 | 说明 | 659| ------ | ----------------------------------- | ---- | ---------------------------- | 660| value | [Dimension](ts-types.md#dimension10)| 是 | 首行文本缩进。<br/>默认值：0 | 661 662### textOverflow<sup>12+</sup> 663 664textOverflow(value: TextOverflow) 665 666设置文本超长时的显示方式。 667 668内联模式，主动配置textOverflow才会生效按[maxLines](#maxlines10)截断效果，不配置时，默认不截断。 669 670文本截断是按字截断。例如，英文以单词为最小单位进行截断，若需要以字母为单位进行截断，[wordBreak](ts-appendix-enums.md#wordbreak11)属性可设置为WordBreak.BREAK_ALL。 671 672当textOverflow设置为TextOverflow.None、TextOverflow.Clip、TextOverflow.Ellipsis时，需配合[maxLines](#maxlines10)使用，单独设置不生效。设置TextOverflow.None与TextOverflow.Clip效果一样。 673 674**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 675 676**系统能力：** SystemCapability.ArkUI.ArkUI.Full 677 678**参数：** 679 680| 参数名 | 类型 | 必填 | 说明 | 681| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 682| value | [TextOverflow](ts-appendix-enums.md#textoverflow) | 是 | 文本超长时的显示方式。<br/>默认值：TextOverflow.Clip | 683 684> **说明：** 685> TextArea组件不支持设置TextOverflow.MARQUEE模式,当设置为TextOverflow.MARQUEE模式时 显示为TextOverflow.Clip 686 687### minFontSize<sup>12+</sup> 688 689minFontSize(value: number | string | Resource) 690 691设置文本最小显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 692 693需配合[maxFontSize](#maxfontsize12)以及[maxLines](#maxlines10)或布局大小限制使用，单独设置不生效。 694 695自适应字号生效时，fontSize设置不生效。 696 697minFontSize小于或等于0时，自适应字号不生效，此时按照[fontSize](#fontsize)属性的值生效，未设置时按照其默认值生效。 698 699**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 700 701**系统能力：** SystemCapability.ArkUI.ArkUI.Full 702 703**参数：** 704 705| 参数名 | 类型 | 必填 | 说明 | 706| ------ | ------------------------------------------------------------ | ---- | ------------------ | 707| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本最小显示字号。<br/>单位：[fp](ts-pixel-units.md) | 708 709### maxFontSize<sup>12+</sup> 710 711maxFontSize(value: number | string | Resource) 712 713设置文本最大显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 714 715需配合[minFontSize](#minfontsize12)以及[maxLines](#maxlines10)或布局大小限制使用，单独设置不生效。 716 717自适应字号生效时，fontSize设置不生效。 718 719maxFontSize小于等于0或者maxFontSize小于minFontSize时，自适应字号不生效，此时按照[fontSize](#fontsize)属性的值生效，未设置时按照其默认值生效。 720 721**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 722 723**系统能力：** SystemCapability.ArkUI.ArkUI.Full 724 725**参数：** 726 727| 参数名 | 类型 | 必填 | 说明 | 728| ------ | ------------------------------------------------------------ | ---- | ------------------ | 729| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 文本最大显示字号。<br/>单位：[fp](ts-pixel-units.md) | 730 731### heightAdaptivePolicy<sup>12+</sup> 732 733heightAdaptivePolicy(value: TextHeightAdaptivePolicy) 734 735设置文本自适应高度的方式。 736 737当设置为TextHeightAdaptivePolicy.MAX_LINES_FIRST时，优先使用[maxLines](#maxlines10)属性来调整文本高度。如果使用maxLines属性的布局大小超过了布局约束，则尝试在[minFontSize](#minfontsize12)和[maxFontSize](#maxfontsize12)的范围内缩小字体以显示更多文本。 738组件设置为内联输入风格，编辑态与非编辑态存在字体大小不一致情况。 739 740当设置为TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST时，优先使用minFontSize属性来调整文本高度。如果使用minFontSize属性可以将文本布局在一行中，则尝试在minFontSize和maxFontSize的范围内增大字体并使用最大可能的字体大小。 741 742当设置为TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST时，优先使用布局约束来调整文本高度。如果布局大小超过布局约束，则尝试在minFontSize和maxFontSize的范围内缩小字体以满足布局约束。 743 744**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 745 746**系统能力：** SystemCapability.ArkUI.ArkUI.Full 747 748**参数：** 749 750| 参数名 | 类型 | 必填 | 说明 | 751| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 752| value | [TextHeightAdaptivePolicy](ts-appendix-enums.md#textheightadaptivepolicy10) | 是 | 文本自适应高度的方式。<br/>默认值：TextHeightAdaptivePolicy.MAX_LINES_FIRST | 753 754### lineSpacing<sup>12+</sup> 755 756lineSpacing(value: LengthMetrics) 757 758设置文本的行间距，设置值不大于0时，取默认值0。 759 760**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 761 762**系统能力：** SystemCapability.ArkUI.ArkUI.Full 763 764**参数：** 765 766| 参数名 | 类型 | 必填 | 说明 | 767| ------ | ------------------------------------------------------------ | ---- | ---------------- | 768| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 文本的行间距。默认值：0 | 769 770### lineSpacing<sup>20+</sup> 771 772lineSpacing(value: LengthMetrics, options?: LineSpacingOptions) 773 774设置文本的行间距。当不配置LineSpacingOptions时，首行上方和尾行下方默认会有行间距。 775 776**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 777 778**系统能力：** SystemCapability.ArkUI.ArkUI.Full 779 780**参数：** 781 782| 参数名 | 类型 | 必填 | 说明 | 783| ------ | ------------------------------------------------------------ | ---- | ---------------- | 784| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 文本的行间距。设置值不大于0时，取默认值0。 | 785| options | [LineSpacingOptions](ts-text-common.md#linespacingoptions20对象说明) | 否 | 设置行间距配置项。<br/>默认值：{ onlyBetweenLines: false } | 786 787### lineBreakStrategy<sup>12+</sup> 788 789lineBreakStrategy(strategy: LineBreakStrategy) 790 791设置折行规则。该属性在[wordBreak](#wordbreak12)不等于WordBreak.BREAK_ALL的时候生效，不支持连词符。 792 793**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 794 795**系统能力：** SystemCapability.ArkUI.ArkUI.Full 796 797**参数：** 798 799| 参数名 | 类型 | 必填 | 说明 | 800| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------- | 801| strategy | [LineBreakStrategy](ts-appendix-enums.md#linebreakstrategy12) | 是 | 文本的折行规则。 <br />默认值：LineBreakStrategy.GREEDY | 802 803### editMenuOptions<sup>12+</sup> 804 805editMenuOptions(editMenu: EditMenuOptions) 806 807设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。 808 809调用[disableMenuItems](../arkts-apis-uicontext-textmenucontroller.md#disablemenuitems20)或[disableSystemServiceMenuItems](../arkts-apis-uicontext-textmenucontroller.md#disablesystemservicemenuitems20)接口屏蔽文本选择菜单内的系统服务菜单项时，editMenuOptions接口内回调方法[onCreateMenu](./ts-text-common.md#oncreatemenu12)的入参列表中不包含被屏蔽的菜单选项。 810 811**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 812 813**系统能力：** SystemCapability.ArkUI.ArkUI.Full 814 815**参数：** 816 817| 参数名 | 类型 | 必填 | 说明 | 818| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 819| editMenu | [EditMenuOptions](ts-text-common.md#editmenuoptions) | 是 | 扩展菜单选项。 | 820 821### enablePreviewText<sup>12+</sup> 822 823enablePreviewText(enable: boolean) 824 825设置是否开启输入预上屏。 826 827预上屏内容定义为文字暂存态，目前不支持文字拦截功能，因此不触发[onWillInsert](#onwillinsert12)、[onDidInsert](#ondidinsert12)、[onWillDelete](#onwilldelete12)、[onDidDelete](#ondiddelete12)回调。 828 829**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 830 831**系统能力：** SystemCapability.ArkUI.ArkUI.Full 832 833**参数：** 834 835| 参数名 | 类型 | 必填 | 说明 | 836| ------ | ------- | ---- | ---------------------------------- | 837| enable | boolean | 是 | 是否开启输入预上屏。<br/>true表示开启，false表示不开启。<br/>默认值：true | 838 839> **说明：** 840> 841> “预上屏”描述的是一种文字暂存状态。需要在输入法中开启预上屏功能，在输入文本过程中，未确认输入候选词时，文本框中显示标记文本。例如，通过拼音输入中文时，未确定候选词之前，在输入框中显示拼音字母，该状态称为文字预上屏。 842 843### enableHapticFeedback<sup>13+</sup> 844 845enableHapticFeedback(isEnabled: boolean) 846 847设置是否开启触控反馈。 848 849**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 850 851**系统能力：** SystemCapability.ArkUI.ArkUI.Full 852 853**参数：** 854 855| 参数名 | 类型 | 必填 | 说明 | 856| ------ | ------- | ---- | ---------------------------------- | 857| isEnabled | boolean | 是 | 是否开启触控反馈。<br/>true表示开启，false表示不开启。<br/>默认值：true | 858 859> **说明：** 860> 861> 开启触控反馈时，需要在工程的module.json5中配置requestPermissions字段以开启振动权限，配置如下： 862> ```json 863> "requestPermissions": [ 864> { 865> "name": "ohos.permission.VIBRATE", 866> } 867> ] 868> ``` 869 870### autoCapitalizationMode<sup>20+</sup> 871 872autoCapitalizationMode(mode: AutoCapitalizationMode) 873 874设置自动大小写模式的文本模式，只提供接口能力，具体实现以输入法应用为主。 875 876**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 877 878**系统能力：** SystemCapability.ArkUI.ArkUI.Full 879 880**参数：** 881 882| 参数名 | 类型 | 必填 | 说明 | 883| -------- | ----------------------------------------- | ---- | -------------------------- | 884| mode | [AutoCapitalizationMode](ts-text-common.md#autocapitalizationmode20枚举说明) | 是 | 自动大小写模式，默认状态无效。 | 885 886### keyboardAppearance<sup>15+</sup> 887 888keyboardAppearance(appearance: Optional\<KeyboardAppearance>) 889 890设置输入框拉起的键盘样式。 891 892**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 893 894**系统能力：** SystemCapability.ArkUI.ArkUI.Full 895 896**参数：** 897 898| 参数名 | 类型 | 必填 | 说明 | 899| ------ | ----------------------------------------- | ---- | ------------------------------------------------------ | 900| appearance | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[KeyboardAppearance](ts-text-common.md#keyboardappearance15枚举说明)> | 是 | 键盘样式。<br/>默认值：KeyboardAppearance.NONE_IMMERSIVE | 901 902### strokeWidth<sup>20+</sup> 903 904strokeWidth(width: Optional\<LengthMetrics>) 905 906设置文本描边的宽度。 907 908**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 909 910**系统能力：** SystemCapability.ArkUI.ArkUI.Full 911 912**参数：** 913 914| 参数名 | 类型 | 必填 | 说明 | 915| ------ | ------------------------------------------------------------ | ---- | ---------------- | 916| width | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12)> | 是 | 文本描边的宽度。当LengthMetrics的单位为px时，<br/>若设置值小于0，显示实心字；若大于0，显示空心字。<br/>默认值为0，不做描边处理。 | 917 918### strokeColor<sup>20+</sup> 919 920strokeColor(color: Optional\<ResourceColor>) 921 922设置文本描边的颜色。 923 924**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 925 926**系统能力：** SystemCapability.ArkUI.ArkUI.Full 927 928**参数：** 929 930| 参数名 | 类型 | 必填 | 说明 | 931| ------ | ------------------------------------------ | ---- | ---------- | 932| color | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 描边颜色。默认值为字体颜色，设置异常值时取默认值。| 933 934### stopBackPress<sup>15+</sup> 935 936stopBackPress(isStopped: Optional\<boolean>) 937 938设置是否阻止返回键向其它组件或应用侧传递。 939 940**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 941 942**系统能力：** SystemCapability.ArkUI.ArkUI.Full 943 944**参数：** 945 946| 参数名 | 类型 | 必填 | 说明 | 947| ------ | --------------------------------------------------- | ---- | ----------------------------------------- | 948| isStopped | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 是否阻止返回键。<br/>true表示阻止返回键向其它组件或应用侧传递，false表示不阻止。<br />默认值：true | 949 950### halfLeading<sup>18+</sup> 951 952halfLeading(halfLeading: Optional\<boolean>) 953 954设置文本是否将行间距平分至行的顶部与底部。 955 956**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 957 958**系统能力：** SystemCapability.ArkUI.ArkUI.Full 959 960**参数：** 961 962| 参数名 | 类型 | 必填 | 说明 | 963| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 964| halfLeading | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 文本是否将行间距平分至行的顶部与底部。<br/>true表示将行间距平分至行的顶部与底部，false则不平分。<br/>默认值：false | 965 966### minFontScale<sup>18+</sup> 967 968minFontScale(scale: Optional\<number | Resource>) 969 970设置文本最小的字体缩放倍数。 971 972**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 973 974**系统能力：** SystemCapability.ArkUI.ArkUI.Full 975 976**参数：** 977 978| 参数名 | 类型 | 必填 | 说明 | 979| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 980| scale | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<number \| [Resource](ts-types.md#resource)> | 是 | 文本最小的字体缩放倍数，支持undefined类型。<br/>取值范围：[0, 1]<br/>**说明：** <br/>设置的值小于0时，按值为0处理。设置的值大于1，按值为1处理。异常值默认不生效。<br/>使用前需在工程中配置configuration.json文件和app.json5文件，具体详见[示例17设置最小字体范围与最大字体范围](#示例17设置最小字体范围与最大字体范围)。 | 981 982### maxFontScale<sup>18+</sup> 983 984maxFontScale(scale: Optional\<number | Resource>) 985 986设置文本最大的字体缩放倍数。 987 988**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 989 990**系统能力：** SystemCapability.ArkUI.ArkUI.Full 991 992**参数：** 993 994| 参数名 | 类型 | 必填 | 说明 | 995| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 996| scale | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<number \| [Resource](ts-types.md#resource)> | 是 | 文本最大的字体缩放倍数，支持undefined类型。<br/>取值范围：[1, +∞)<br/>**说明：** <br/>设置的值小于1时，按值为1处理。异常值默认不生效。<br/>使用前需在工程中配置configuration.json文件和app.json5文件，具体详见[示例17设置最小字体范围与最大字体范围](#示例17设置最小字体范围与最大字体范围)。 | 997 998### ellipsisMode<sup>18+</sup> 999 1000ellipsisMode(mode: Optional\<EllipsisMode>) 1001 1002设置省略位置。ellipsisMode属性需要配合[textOverflow](#textoverflow12)设置为TextOverflow.Ellipsis以及[maxLines](#maxlines10)使用，单独设置ellipsisMode属性不生效。 1003 1004EllipsisMode.START和EllipsisMode.CENTER仅在[maxLines](#maxlines10)设置为1生效。 1005 1006**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1007 1008**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1009 1010**参数：** 1011 1012| 参数名 | 类型 | 必填 | 说明 | 1013| ------ | --------------------------------------------------- | ---- | ----------------------------------------- | 1014| mode | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[EllipsisMode](ts-appendix-enums.md#ellipsismode11)> | 是 | 省略位置。 <br />默认值：EllipsisMode.END | 1015 1016### enableAutoSpacing<sup>20+</sup> 1017 1018enableAutoSpacing(enabled: Optional\<boolean>) 1019 1020设置是否开启中文与西文的自动间距。 1021 1022**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1023 1024**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1025 1026**参数：** 1027 1028| 参数名 | 类型 | 必填 | 说明 | 1029| ------ | ------- | ---- | ---------------------------------- | 1030| enabled | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 是否开启中文与西文的自动间距。<br/>true为开启自动间距，false为不开启。<br />默认值：false | 1031 1032## 事件 1033 1034除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 1035 1036### onChange 1037 1038onChange(callback: EditableTextOnChangeCallback) 1039 1040输入内容发生变化时，触发该回调。 1041 1042在本回调中，若执行了光标操作，需要开发者在预上屏场景下依据previewText参数调整光标逻辑，以适应预上屏场景。 1043 1044**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1045 1046**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1047 1048**参数：** 1049 1050| 参数名 | 类型 | 必填 | 说明 | 1051| ------ | ------ | ---- | -------------------- | 1052| callback | [EditableTextOnChangeCallback](ts-text-common.md#editabletextonchangecallback12) | 是 | 当前输入文本内容变化时的回调。 | 1053 1054### onEditChange<sup>10+</sup> 1055 1056onEditChange(callback: (isEditing: boolean) => void) 1057 1058输入状态变化时，触发该回调。有光标时为编辑态，无光标时为非编辑态。 1059 1060**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1061 1062**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1063 1064**参数：** 1065 1066| 参数名 | 类型 | 必填 | 说明 | 1067| --------- | ------- | ---- | -------------------- | 1068| isEditing | boolean | 是 | 为true表示正在输入。 | 1069 1070### onCopy<sup>8+</sup> 1071 1072onCopy(callback: (value: string) => void) 1073 1074进行复制操作时，触发该回调。 1075 1076**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1077 1078**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1079 1080**参数：** 1081 1082| 参数名 | 类型 | 必填 | 说明 | 1083| ------ | ------ | ---- | ---------------- | 1084| value | string | 是 | 复制的文本内容。 | 1085 1086### onCut<sup>8+</sup> 1087 1088onCut(callback: (value: string) => void) 1089 1090进行剪切操作时，触发该回调。 1091 1092**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1093 1094**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1095 1096**参数：** 1097 1098| 参数名 | 类型 | 必填 | 说明 | 1099| ------ | ------ | ---- | ---------------- | 1100| value | string | 是 | 剪切的文本内容。 | 1101 1102### onPaste 1103 1104onPaste(callback: (value: string, event: PasteEvent) => void) 1105 1106进行粘贴操作时，触发该回调。 1107 1108**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1109 1110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1111 1112**参数：** 1113 1114| 参数名 | 类型 | 必填 | 说明 | 1115| ------------------- | ------------------------------------------------------------ | ---- | ---------------------- | 1116| value | string | 是 | 粘贴的文本内容。 | 1117| event<sup>11+</sup> | [PasteEvent](ts-basic-components-richeditor.md#pasteevent11) | 是 | 用户自定义的粘贴事件。 | 1118 1119### onTextSelectionChange<sup>10+</sup> 1120 1121onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void) 1122 1123文本选择的位置或编辑状态下光标位置发生变化时，触发该回调。 1124 1125**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1126 1127**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1128 1129**参数：** 1130 1131| 参数名 | 类型 | 必填 | 说明 | 1132| -------------- | ------ | ---- | --------------------------------------- | 1133| selectionStart | number | 是 | 所选文本的起始位置，文字的起始位置为0。 | 1134| selectionEnd | number | 是 | 所选文本的结束位置。 | 1135 1136### onContentScroll<sup>10+</sup> 1137 1138onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void) 1139 1140文本内容滚动时，触发该回调。 1141 1142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1143 1144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1145 1146**参数：** 1147 1148| 参数名 | 类型 | 必填 | 说明 | 1149| ------------ | ------ | ---- | ---------------------------------- | 1150| totalOffsetX | number | 是 | 文本在内容区的横坐标偏移。<br/>单位：[px](ts-pixel-units.md) | 1151| totalOffsetY | number | 是 | 文本在内容区的纵坐标偏移。<br/>单位：[px](ts-pixel-units.md) | 1152 1153### onSubmit<sup>11+</sup> 1154 1155onSubmit(callback: (enterKey: EnterKeyType) => void) 1156 1157按下软键盘输入法回车键时，触发该回调。 1158 1159**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1160 1161**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1162 1163**参数：** 1164 1165| 参数名 | 类型 | 必填 | 说明 | 1166| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 1167| enterKey | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype枚举说明) | 是 | 输入法回车键类型，类型为EnterKeyType.NEW_LINE时不触发onSubmit。 | 1168 1169### onSubmit<sup>14+</sup> 1170 1171onSubmit(callback: TextAreaSubmitCallback) 1172 1173按下软键盘输入法回车键触发该回调事件，提交事件时提供保持TextArea编辑状态的方法。 1174 1175**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1176 1177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1178 1179**参数：** 1180 1181| 参数名 | 类型 | 必填 | 说明 | 1182| ------ | ------- | ---- | ----------------------------- | 1183| callback | [TextAreaSubmitCallback](#textareasubmitcallback14) | 是 | 按下软键盘输入法回车键时的回调事件。 | 1184 1185### onWillInsert<sup>12+</sup> 1186 1187onWillInsert(callback: Callback\<InsertValue, boolean>) 1188 1189在将要输入时，触发该回调。 1190 1191**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1192 1193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1194 1195**参数：** 1196 1197| 参数名 | 类型 | 必填 | 说明 | 1198| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1199| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12对象说明), boolean> | 是 | 在将要输入时调用的回调。<br/>在返回true时，表示正常插入，返回false时，表示不插入。<br/>在预上屏和候选词操作时，该回调不触发。<br/>仅支持系统输入法输入的场景。 | 1200 1201### onDidInsert<sup>12+</sup> 1202 1203onDidInsert(callback: Callback\<InsertValue>) 1204 1205在输入完成时，触发该回调。 1206 1207**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1208 1209**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1210 1211**参数：** 1212 1213| 参数名 | 类型 | 必填 | 说明 | 1214| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1215| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12对象说明)> | 是 | 在输入完成时调用的回调。<br/>仅支持系统输入法输入的场景。 | 1216 1217### onWillDelete<sup>12+</sup> 1218 1219onWillDelete(callback: Callback\<DeleteValue, boolean>) 1220 1221在将要删除时，触发该回调。 1222 1223**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1224 1225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1226 1227**参数：** 1228 1229| 参数名 | 类型 | 必填 | 说明 | 1230| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1231| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12对象说明), boolean> | 是 | 在将要删除时调用的回调。<br/>在返回true时，表示正常删除，返回false时，表示不删除。<br/>在预上屏删除操作时，该回调不触发。<br/>仅支持系统输入法输入的场景。 | 1232 1233### onDidDelete<sup>12+</sup> 1234 1235onDidDelete(callback: Callback\<DeleteValue>) 1236 1237在删除完成时，触发该回调。 1238 1239**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1240 1241**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1242 1243**参数：** 1244 1245| 参数名 | 类型 | 必填 | 说明 | 1246| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1247| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12对象说明)> | 是 | 在删除完成时调用的回调。<br/>仅支持系统输入法输入的场景。 | 1248 1249> **说明：** 1250> 1251> 点击清除按钮不触发onDidDelete回调。 1252 1253### onWillChange<sup>15+</sup> 1254 1255onWillChange(callback: Callback\<EditableTextChangeValue, boolean>) 1256 1257在文本内容将要发生变化时，触发该回调。 1258 1259onWillChange的回调时序晚于onWillInsert、onWillDelete，早于onDidInsert、onDidDelete。 1260 1261**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1262 1263**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1264 1265**参数：** 1266 1267| 参数名 | 类型 | 必填 | 说明 | 1268| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1269| callback | Callback\<[EditableTextChangeValue](ts-text-common.md#editabletextchangevalue15), boolean> | 是 | 在文本内容将要发生变化时的回调。<br/>返回true时，表示正常修改。返回false时，表示拦截此次触发。 | 1270 1271## TextAreaController<sup>8+</sup> 1272 1273TextArea组件的控制器继承自[TextContentControllerBase](ts-universal-attributes-text-style.md#textcontentcontrollerbase)，涉及的接口有[getTextContentRect](ts-universal-attributes-text-style.md#gettextcontentrect)、[getTextContentLineCount](ts-universal-attributes-text-style.md#gettextcontentlinecount)、[getCaretOffset](ts-universal-attributes-text-style.md#getcaretoffset11)、[addText](ts-universal-attributes-text-style.md#addtext15)、[deleteText](ts-universal-attributes-text-style.md#deletetext15)、[getSelection](ts-universal-attributes-text-style.md#getselection15)、[clearPreviewText](ts-universal-attributes-text-style.md#clearpreviewtext17)<!--Del-->以及系统接口[getText](ts-text-common-sys.md#gettext19)<!--DelEnd-->。 1274 1275**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1276 1277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1278 1279### 导入对象 1280 1281``` 1282controller: TextAreaController = new TextAreaController() 1283``` 1284 1285### constructor<sup>8+</sup> 1286 1287constructor() 1288 1289TextAreaController的构造函数。 1290 1291**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1292 1293**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1294 1295### caretPosition<sup>8+</sup> 1296 1297caretPosition(value: number): void 1298 1299设置输入光标的位置。 1300 1301**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1302 1303**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1304 1305**参数：** 1306 1307| 参数名 | 类型 | 必填 | 说明 | 1308| ------ | ---- | ---- | ---- | 1309| value | number | 是 | 从字符串开始到光标所在位置的字符长度。 | 1310 1311### setTextSelection<sup>10+</sup> 1312 1313setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void 1314 1315组件在获焦状态下，调用该接口设置文本选择区域并高亮显示，且只有在selectionStart小于selectionEnd时，文字才会被选取、高亮显示。 1316 1317**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1318 1319**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1320 1321**参数：** 1322 1323| 参数名 | 类型 | 必填 | 说明 | 1324| ------ | ---- | ---- | ---- | 1325| selectionStart | number | 是 | 文本选择区域起始位置，文本框中文字的起始位置为0。<br/>当selectionStart小于0时，按0处理；当selectionStart大于文字最大长度时，按照文字最大长度处理。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1326| selectionEnd | number | 是 | 文本选择区域结束位置。<br/>当selectionEnd小于0时，按0处理；当selectionEnd大于文字最大长度时，按照文字最大长度处理。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1327| options<sup>12+</sup> | [SelectionOptions](ts-universal-attributes-text-style.md#selectionoptions12对象说明) | 否 | 选中文字时的配置。<br />默认值：MenuPolicy.DEFAULT<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1328 1329> **说明：** 1330> 1331> 如果selectionMenuHidden被赋值为true或设备为2in1时，即使options被赋值为MenuPolicy.SHOW，调用setTextSelection也不弹出菜单。 1332> 1333> 如果选中的文本含有emoji表情时，表情的起始位置包含在设置的文本选中区域内就会被选中。 1334 1335### stopEditing<sup>10+</sup> 1336 1337stopEditing(): void 1338 1339退出编辑态。 1340 1341**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1342 1343**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1344 1345## TextAreaType<sup>11+</sup>枚举说明 1346 1347**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1348 1349| 名称 | 值 | 说明 | 1350| ------ | ----- | ------ | 1351| NORMAL | 0 | 基本输入模式。<br/>支持输入数字、字母、下划线、空格、特殊字符。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1352| NUMBER | 2 | 纯数字输入模式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1353| PHONE_NUMBER | 3 | 电话号码输入模式。<br/>支持输入数字、空格、+ 、-、*、#、(、)，长度不限。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1354| EMAIL | 5 | 邮箱地址输入模式。<br/>支持数字，字母，下划线、小数点、!、#、$、%、&、'、*、+、-、/、=、?、^、`、\{、\|、\}、~，以及@字符（只能存在一个@字符）。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1355| NUMBER_DECIMAL<sup>12+</sup> | 12 | 带小数点的数字输入模式。<br/>支持数字，小数点（只能存在一个小数点）。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 1356| URL<sup>12+</sup> | 13 | 带URL的输入模式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1357| ONE_TIME_CODE<sup>20+</sup> | 14 | 验证码输入模式。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 1358 1359## TextAreaSubmitCallback<sup>14+</sup> 1360 1361type TextAreaSubmitCallback = (enterKeyType: EnterKeyType, event?: SubmitEvent) => void 1362 1363软键盘按下回车键时的回调事件。 1364 1365**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1366 1367**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1368 1369**参数：** 1370 1371| 参数名 | 类型 | 必填 | 说明 | 1372| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 1373| enterKeyType | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype枚举说明) | 是 | 软键盘输入法回车键类型。<br>类型为EnterKeyType.NEW_LINE时不触发onSubmit。 | 1374| event | [SubmitEvent](ts-basic-components-textinput.md#submitevent11) | 否 | 提交事件。 | 1375 1376## 示例 1377 1378### 示例1（设置与获取光标位置） 1379 1380从API version 8开始，该示例通过[controller](#textareacontroller8)实现了光标位置的设置与获取。 1381 1382```ts 1383// xxx.ets 1384@Entry 1385@Component 1386struct TextAreaExample { 1387 @State text: string = ''; 1388 @State positionInfo: CaretOffset = { index: 0, x: 0, y: 0 }; 1389 controller: TextAreaController = new TextAreaController(); 1390 1391 build() { 1392 Column() { 1393 TextArea({ 1394 text: this.text, 1395 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1396 controller: this.controller 1397 }) 1398 .placeholderFont({ size: 16, weight: 400 }) 1399 .width(336) 1400 .height(56) 1401 .margin(20) 1402 .fontSize(16) 1403 .fontColor('#182431') 1404 .backgroundColor('#FFFFFF') 1405 .onChange((value: string) => { 1406 this.text = value; 1407 }) 1408 Text(this.text) 1409 Button('Set caretPosition 1') 1410 .backgroundColor('#007DFF') 1411 .margin(15) 1412 .onClick(() => { 1413 // 设置光标位置到第一个字符后 1414 this.controller.caretPosition(1); 1415 }) 1416 Button('Get CaretOffset') 1417 .backgroundColor('#007DFF') 1418 .margin(15) 1419 .onClick(() => { 1420 this.positionInfo = this.controller.getCaretOffset(); 1421 }) 1422 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1423 } 1424} 1425``` 1426 1427 1428 1429### 示例2（设置计数器） 1430 1431从API version 10开始，该示例通过[maxLength](#maxlength10)、[showCounter](#showcounter10)属性实现了计数器的功能。 1432 1433```ts 1434// xxx.ets 1435@Entry 1436@Component 1437struct TextAreaExample { 1438 @State text: string = ''; 1439 controller: TextAreaController = new TextAreaController(); 1440 1441 build() { 1442 Column() { 1443 TextArea({ 1444 text: this.text, 1445 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1446 controller: this.controller 1447 }) 1448 .placeholderFont({ size: 16, weight: 400 }) 1449 .width(336) 1450 .height(56) 1451 .margin(20) 1452 .fontSize(16) 1453 .fontColor('#182431') 1454 .backgroundColor('#FFFFFF') 1455 .maxLength(4) 1456 .showCounter(true, { thresholdPercentage: 50, highlightBorder: true }) 1457 //计数器显示效果为用户当前输入字符数/最大字符限制数。最大字符限制数通过maxLength()接口设置。 1458 //如果用户当前输入字符数达到最大字符限制乘50%（thresholdPercentage）。字符计数器显示。 1459 //用户设置highlightBorder为false时，配置取消红色边框。不设置此参数时，默认为true。 1460 .onChange((value: string) => { 1461 this.text = value; 1462 }) 1463 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1464 } 1465} 1466``` 1467 1468 1469 1470 1471### 示例3（设置自定义键盘） 1472 1473从API version 10开始，该示例通过[customKeyboard](#customkeyboard10)属性实现了自定义键盘的功能。 1474 1475```ts 1476// xxx.ets 1477@Entry 1478@Component 1479struct TextAreaExample { 1480 controller: TextAreaController = new TextAreaController(); 1481 @State inputValue: string = ""; 1482 1483 // 自定义键盘组件 1484 @Builder CustomKeyboardBuilder() { 1485 Column() { 1486 Button('x').onClick(() => { 1487 // 关闭自定义键盘 1488 this.controller.stopEditing(); 1489 }) 1490 Grid() { 1491 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1492 GridItem() { 1493 Button(item + "") 1494 .width(110).onClick(() => { 1495 this.inputValue += item; 1496 }) 1497 } 1498 }) 1499 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1500 }.backgroundColor(Color.Gray) 1501 } 1502 1503 build() { 1504 Column() { 1505 TextArea({ controller: this.controller, text: this.inputValue }) 1506 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 })// 绑定自定义键盘 1507 .height(200) 1508 } 1509 } 1510} 1511``` 1512 1513 1514 1515### 示例4（设置输入法回车键类型） 1516 1517从API version 11开始，该示例通过[enterKeyType](#enterkeytype11)属性实现了动态切换输入法回车键的效果。 1518 1519```ts 1520// xxx.ets 1521@Entry 1522@Component 1523struct TextAreaExample { 1524 @State text: string = ''; 1525 @State enterTypes: Array<EnterKeyType> = 1526 [EnterKeyType.Go, EnterKeyType.Search, EnterKeyType.Send, EnterKeyType.Done, EnterKeyType.Next, 1527 EnterKeyType.PREVIOUS, EnterKeyType.NEW_LINE]; 1528 @State index: number = 0; 1529 1530 build() { 1531 Column({ space: 20 }) { 1532 TextArea({ placeholder: '请输入用户名', text: this.text }) 1533 .width(380) 1534 .enterKeyType(this.enterTypes[this.index]) 1535 .onChange((value: string) => { 1536 this.text = value; 1537 }) 1538 .onSubmit((enterKey: EnterKeyType) => { 1539 console.info("trigger area onSubmit" + enterKey); 1540 }) 1541 Button('改变EnterKeyType').onClick(() => { 1542 this.index = (this.index + 1) % this.enterTypes.length; 1543 }) 1544 1545 }.width('100%') 1546 } 1547} 1548``` 1549 1550 1551 1552 1553### 示例5（设置文本断行规则） 1554 1555从API version 12开始，该示例通过[wordBreak](#wordbreak12)属性实现了TextArea不同断行规则下的效果。 1556 1557```ts 1558// xxx.ets 1559@Entry 1560@Component 1561struct TextAreaExample { 1562 build() { 1563 Column() { 1564 Text("属性WordBreakType为NORMAL的样式：").fontSize(16).fontColor(0xFF0000) 1565 TextArea({ 1566 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1567 }) 1568 .fontSize(16) 1569 .border({ width: 1 }) 1570 .wordBreak(WordBreak.NORMAL) 1571 Text("英文文本，属性WordBreakType为BREAK_ALL的样式：").fontSize(16).fontColor(0xFF0000) 1572 TextArea({ 1573 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1574 }) 1575 .fontSize(16) 1576 .border({ width: 1 }) 1577 .wordBreak(WordBreak.BREAK_ALL) 1578 Text("中文文本，属性WordBreakType为BREAK_ALL的样式：").fontSize(16).fontColor(0xFF0000) 1579 TextArea({ 1580 text: '多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。\n高度未设置时，组件无默认高度，自适应内容高度。宽度未设置时，默认撑满最大宽度。' 1581 }) 1582 .fontSize(16) 1583 .border({ width: 1 }) 1584 .wordBreak(WordBreak.BREAK_ALL) 1585 Text("属性WordBreakType为BREAK_WORD的样式：").fontSize(16).fontColor(0xFF0000) 1586 TextArea({ 1587 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1588 }) 1589 .fontSize(16) 1590 .border({ width: 1 }) 1591 .wordBreak(WordBreak.BREAK_WORD) 1592 } 1593 } 1594} 1595``` 1596 1597 1598 1599### 示例6（设置文本样式） 1600 1601从API version 12开始，该示例通过[lineHeight](#lineheight12)、[letterSpacing](#letterspacing12)、[decoration](#decoration12)属性展示了不同样式的文本效果。 1602 1603```ts 1604// xxx.ets 1605@Entry 1606@Component 1607struct TextAreaExample { 1608 build() { 1609 Row() { 1610 Column() { 1611 Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) 1612 TextArea({ text: 'lineHeight unset' }) 1613 .border({ width: 1 }).padding(10).margin(5) 1614 TextArea({ text: 'lineHeight 15' }) 1615 .border({ width: 1 }).padding(10).margin(5).lineHeight(15) 1616 TextArea({ text: 'lineHeight 30' }) 1617 .border({ width: 1 }).padding(10).margin(5).lineHeight(30) 1618 1619 Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC) 1620 TextArea({ text: 'letterSpacing 0' }) 1621 .border({ width: 1 }).padding(5).margin(5).letterSpacing(0) 1622 TextArea({ text: 'letterSpacing 3' }) 1623 .border({ width: 1 }).padding(5).margin(5).letterSpacing(3) 1624 TextArea({ text: 'letterSpacing -1' }) 1625 .border({ width: 1 }).padding(5).margin(5).letterSpacing(-1) 1626 1627 Text('decoration').fontSize(9).fontColor(0xCCCCCC) 1628 TextArea({ text: 'LineThrough, Red\nsecond line' }) 1629 .border({ width: 1 }).padding(5).margin(5) 1630 .decoration({ type: TextDecorationType.LineThrough, color: Color.Red }) 1631 TextArea({ text: 'Overline, Red, DOTTED\nsecond line' }) 1632 .border({ width: 1 }).padding(5).margin(5) 1633 .decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DOTTED }) 1634 TextArea({ text: 'Underline, Red, WAVY\nsecond line' }) 1635 .border({ width: 1 }).padding(5).margin(5) 1636 .decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY }) 1637 }.height('90%') 1638 } 1639 .width('90%') 1640 .margin(10) 1641 } 1642} 1643``` 1644 1645 1646 1647### 示例7（设置文字特性效果） 1648 1649从API version 12开始，该示例通过[fontFeature](#fontfeature12)属性实现了文本在不同文字特性下的展示效果。 1650 1651```ts 1652// xxx.ets 1653@Entry 1654@Component 1655struct TextAreaExample { 1656 @State text1: string = 'This is ss01 on : 0123456789'; 1657 @State text2: string = 'This is ss01 off: 0123456789'; 1658 1659 build() { 1660 Column() { 1661 TextArea({ text: this.text1 }) 1662 .fontSize(20) 1663 .margin({ top: 200 }) 1664 .fontFeature("\"ss01\" on") 1665 TextArea({ text: this.text2 }) 1666 .margin({ top: 10 }) 1667 .fontSize(20) 1668 .fontFeature("\"ss01\" off") 1669 } 1670 .width("90%") 1671 .margin("5%") 1672 } 1673} 1674``` 1675 1676 1677### 示例8（自定义键盘避让） 1678 1679该示例通过[customKeyboard](#customkeyboard10)（从API version 10开始）属性配置[KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12)（从API version 12开始）接口实现了自定义键盘避让的效果。 1680 1681```ts 1682// xxx.ets 1683@Entry 1684@Component 1685struct TextAreaExample { 1686 controller: TextAreaController = new TextAreaController(); 1687 @State inputValue: string = ""; 1688 @State height1: string | number = '80%'; 1689 @State height2: number = 100; 1690 @State supportAvoidance: boolean = true; 1691 1692 // 自定义键盘组件 1693 @Builder 1694 CustomKeyboardBuilder() { 1695 Column() { 1696 Row() { 1697 Button('x').onClick(() => { 1698 // 关闭自定义键盘 1699 this.controller.stopEditing(); 1700 }).margin(10) 1701 } 1702 1703 Grid() { 1704 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1705 GridItem() { 1706 Button(item + "") 1707 .width(110).onClick(() => { 1708 this.inputValue += item; 1709 }) 1710 } 1711 }) 1712 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1713 }.backgroundColor(Color.Gray) 1714 } 1715 1716 build() { 1717 Column() { 1718 Row() { 1719 Button("20%") 1720 .fontSize(24) 1721 .onClick(() => { 1722 this.height1 = "20%"; 1723 }) 1724 Button("80%") 1725 .fontSize(24) 1726 .margin({ left: 20 }) 1727 .onClick(() => { 1728 this.height1 = "80%"; 1729 }) 1730 } 1731 .justifyContent(FlexAlign.Center) 1732 .alignItems(VerticalAlign.Bottom) 1733 .height(this.height1) 1734 .width("100%") 1735 .padding({ bottom: 50 }) 1736 1737 TextArea({ controller: this.controller, text: this.inputValue })// 绑定自定义键盘 1738 .height(100) 1739 .customKeyboard(this.CustomKeyboardBuilder(), { supportAvoidance: this.supportAvoidance }) 1740 .margin(10) 1741 .border({ width: 1 }) 1742 } 1743 } 1744} 1745``` 1746 1747 1748### 示例9（设置文本自适应） 1749 1750从API version 12开始，该示例通过[minFontSize](#minfontsize12)、[maxFontSize](#maxfontsize12)、[heightAdaptivePolicy](#heightadaptivepolicy12)属性展示了文本自适应字号的效果。 1751 1752```ts 1753// xxx.ets 1754@Entry 1755@Component 1756struct TextAreaExample { 1757 build() { 1758 Row() { 1759 Column() { 1760 Text('heightAdaptivePolicy').fontSize(9).fontColor(0xCCCCCC) 1761 TextArea({text: 'This is the text with the height adaptive policy set'}) 1762 .width('80%').height(90).borderWidth(1).margin(1) 1763 .minFontSize(4) 1764 .maxFontSize(40) 1765 .maxLines(3) 1766 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MAX_LINES_FIRST) 1767 TextArea({text: 'This is the text with the height adaptive policy set'}) 1768 .width('80%').height(90).borderWidth(1).margin(1) 1769 .minFontSize(4) 1770 .maxFontSize(40) 1771 .maxLines(3) 1772 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST) 1773 TextArea({text: 'This is the text with the height adaptive policy set'}) 1774 .width('80%').height(90).borderWidth(1).margin(1) 1775 .minFontSize(4) 1776 .maxFontSize(40) 1777 .maxLines(3) 1778 .heightAdaptivePolicy(TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST) 1779 }.height('90%') 1780 } 1781 .width('90%') 1782 .margin(10) 1783 } 1784} 1785``` 1786 1787 1788 1789### 示例10（设置文本行间距） 1790 1791从API version 12开始，该示例通过[lineSpacing](#linespacing12)属性展示了文本在不同行间距下的展示效果，同时，配置[LineSpacingOptions](ts-text-common.md#linespacingoptions20对象说明)中的onlyBetweenLines（从API version 20开始）属性，可以设置文本的行间距，是否仅在行与行之间生效。 1792 1793```ts 1794// xxx.ets 1795import { LengthMetrics } from '@kit.ArkUI'; 1796 1797@Entry 1798@Component 1799struct TextAreaExample { 1800 build() { 1801 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 1802 Text('TextArea lineSpacing.').fontSize(9).fontColor(0xCCCCCC) 1803 TextArea({ text: 'This is the TextArea with no lineSpacing set.' }) 1804 .fontSize(12) 1805 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_px.' }) 1806 .fontSize(12) 1807 .lineSpacing(LengthMetrics.px(20)) 1808 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_vp.' }) 1809 .fontSize(12) 1810 .lineSpacing(LengthMetrics.vp(20)) 1811 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_fp.' }) 1812 .fontSize(12) 1813 .lineSpacing(LengthMetrics.fp(20)) 1814 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_lpx.' }) 1815 .fontSize(12) 1816 .lineSpacing(LengthMetrics.lpx(20)) 1817 TextArea({ text: 'This is the TextArea with lineSpacing set to 100%.' }) 1818 .fontSize(12) 1819 .lineSpacing(LengthMetrics.percent(1)) 1820 TextArea({ text: 'The line spacing of this TextArea is set to 20_px, and the spacing is effective only between the lines.' }) 1821 .fontSize(12) 1822 .lineSpacing(LengthMetrics.px(20), { onlyBetweenLines: true }) 1823 }.height(600).width(350).padding({ left: 35, right: 35, top: 35 }) 1824 } 1825} 1826``` 1827 1828 1829 1830### 示例11（设置自动填充） 1831 1832从API version 12开始，该示例通过[contentType](#contenttype12)、[enableAutoFill](#enableautofill12)属性实现了文本自动填充的功能。 1833 1834```ts 1835// xxx.ets 1836@Entry 1837@Component 1838struct TextAreaExample { 1839 @State text: string = ''; 1840 1841 build() { 1842 Column() { 1843 // 邮箱地址自动填充类型 1844 TextArea({ placeholder: 'input your email...' }) 1845 .width('95%') 1846 .height(40) 1847 .margin(20) 1848 .contentType(ContentType.EMAIL_ADDRESS) 1849 .enableAutoFill(true) 1850 .maxLength(20) 1851 // 街道地址自动填充类型 1852 TextArea({ placeholder: 'input your street address...' }) 1853 .width('95%') 1854 .height(40) 1855 .margin(20) 1856 .contentType(ContentType.FULL_STREET_ADDRESS) 1857 .enableAutoFill(true) 1858 .maxLength(20) 1859 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1860 } 1861} 1862``` 1863 1864 1865 1866### 示例12（设置折行规则） 1867 1868从API version 12开始，该示例通过[lineBreakStrategy](#linebreakstrategy12)属性实现了TextArea不同折行规则下的效果。 1869 1870```ts 1871// xxx.ets 1872@Entry 1873@Component 1874struct TextAreaExample { 1875 @State message1: string = 1876 "They can be classified as built-in components–those directly provided by the ArkUI framework and custom components – those defined by developers" + 1877 "The built-in components include buttons radio buttonsprogress indicators and text You can set the rendering effect of these components in method chaining mode," + 1878 "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."; 1879 @State lineBreakStrategyIndex: number = 0; 1880 @State lineBreakStrategy: LineBreakStrategy[] = 1881 [LineBreakStrategy.GREEDY, LineBreakStrategy.HIGH_QUALITY, LineBreakStrategy.BALANCED]; 1882 @State lineBreakStrategyStr: string[] = ['GREEDY', 'HIGH_QUALITY', 'BALANCED']; 1883 1884 build() { 1885 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 1886 Text('lineBreakStrategy').fontSize(9).fontColor(0xCCCCCC) 1887 TextArea({ text: this.message1 }) 1888 .fontSize(12) 1889 .border({ width: 1 }) 1890 .padding(10) 1891 .width('100%') 1892 .lineBreakStrategy(this.lineBreakStrategy[this.lineBreakStrategyIndex]) 1893 Row() { 1894 Button('当前lineBreakStrategy模式：' + this.lineBreakStrategyStr[this.lineBreakStrategyIndex]).onClick(() => { 1895 this.lineBreakStrategyIndex++; 1896 if (this.lineBreakStrategyIndex > (this.lineBreakStrategyStr.length - 1)) { 1897 this.lineBreakStrategyIndex = 0; 1898 } 1899 }) 1900 }.padding({ top: 10 }) 1901 }.height(700).width(370).padding({ left: 35, right: 35, top: 35 }) 1902 } 1903} 1904``` 1905 1906 1907 1908### 示例13（支持插入和删除回调） 1909 1910从API version 12开始，该示例通过[onWillInsert](#onwillinsert12)、[onDidInsert](#ondidinsert12)、[onWillDelete](#onwilldelete12)、[onDidDelete](#ondiddelete12)接口实现了插入和删除的功能。 1911 1912```ts 1913// xxx.ets 1914@Entry 1915@Component 1916struct TextAreaExample { 1917 @State insertValue: string = ""; 1918 @State deleteValue: string = ""; 1919 @State insertOffset: number = 0; 1920 @State deleteOffset: number = 0; 1921 @State deleteDirection: number = 0; 1922 1923 build() { 1924 Row() { 1925 Column() { 1926 TextArea({ text: "TextArea支持插入回调文本" }) 1927 .width(300) 1928 .height(60) 1929 .onWillInsert((info: InsertValue) => { 1930 this.insertValue = info.insertValue; 1931 return true; 1932 }) 1933 .onDidInsert((info: InsertValue) => { 1934 this.insertOffset = info.insertOffset; 1935 }) 1936 1937 Text("insertValue:" + this.insertValue + " insertOffset:" + this.insertOffset).height(30) 1938 1939 TextArea({ text: "TextArea支持删除回调文本b" }) 1940 .width(300) 1941 .height(60) 1942 .onWillDelete((info: DeleteValue) => { 1943 this.deleteValue = info.deleteValue; 1944 this.deleteDirection = info.direction; 1945 return true; 1946 }) 1947 .onDidDelete((info: DeleteValue) => { 1948 this.deleteOffset = info.deleteOffset; 1949 this.deleteDirection = info.direction; 1950 }) 1951 1952 Text("deleteValue:" + this.deleteValue + " deleteOffset:" + this.deleteOffset).height(30) 1953 Text("deleteDirection:" + (this.deleteDirection == 0 ? "BACKWARD" : "FORWARD")).height(30) 1954 1955 }.width('100%') 1956 } 1957 .height('100%') 1958 } 1959} 1960``` 1961 1962 1963 1964### 示例14（文本扩展自定义菜单） 1965 1966从API version 12开始，该示例通过[editMenuOptions](#editmenuoptions12)接口实现了文本设置自定义菜单扩展项的文本内容、图标以及回调的功能，同时，可以在[onPrepareMenu](ts-text-common.md#onpreparemenu20)（从API version 20开始）回调中，进行菜单数据的设置。 1967 1968```ts 1969// xxx.ets 1970@Entry 1971@Component 1972struct TextAreaExample { 1973 @State text: string = 'TextArea editMenuOptions'; 1974 @State endIndex: number = 0; 1975 onCreateMenu = (menuItems: Array<TextMenuItem>) => { 1976 // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。 1977 let item1: TextMenuItem = { 1978 content: 'create1', 1979 icon: $r('app.media.startIcon'), 1980 id: TextMenuItemId.of('create1'), 1981 }; 1982 let item2: TextMenuItem = { 1983 content: 'create2', 1984 id: TextMenuItemId.of('create2'), 1985 icon: $r('app.media.startIcon'), 1986 }; 1987 menuItems.push(item1); 1988 menuItems.unshift(item2); 1989 return menuItems; 1990 } 1991 onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => { 1992 if (menuItem.id.equals(TextMenuItemId.of("create2"))) { 1993 console.info("拦截 id: create2 start:" + textRange.start + "; end:" + textRange.end); 1994 return true; 1995 } 1996 if (menuItem.id.equals(TextMenuItemId.of("prepare1"))) { 1997 console.info("拦截 id: prepare1 start:" + textRange.start + "; end:" + textRange.end); 1998 return true; 1999 } 2000 if (menuItem.id.equals(TextMenuItemId.COPY)) { 2001 console.info("拦截 COPY start:" + textRange.start + "; end:" + textRange.end); 2002 return true; 2003 } 2004 if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) { 2005 console.info("不拦截 SELECT_ALL start:" + textRange.start + "; end:" + textRange.end); 2006 return false; 2007 } 2008 return false; 2009 } 2010 onPrepareMenu = (menuItems: Array<TextMenuItem>) => { 2011 // $r('app.media.startIcon')需要替换为开发者所需的图像资源文件。 2012 let item1: TextMenuItem = { 2013 content: 'prepare1_' + this.endIndex, 2014 icon: $r('app.media.startIcon'), 2015 id: TextMenuItemId.of('prepare1'), 2016 }; 2017 menuItems.unshift(item1); 2018 return menuItems; 2019 } 2020 @State editMenuOptions: EditMenuOptions = { 2021 onCreateMenu: this.onCreateMenu, 2022 onMenuItemClick: this.onMenuItemClick, 2023 onPrepareMenu: this.onPrepareMenu 2024 }; 2025 2026 build() { 2027 Column() { 2028 TextArea({ text: this.text }) 2029 .width('95%') 2030 .height(56) 2031 .editMenuOptions(this.editMenuOptions) 2032 .margin({ top: 100 }) 2033 .onTextSelectionChange((selectionStart: number, selectionEnd: number) => { 2034 this.endIndex = selectionEnd; 2035 }) 2036 } 2037 .width("90%") 2038 .margin("5%") 2039 } 2040} 2041``` 2042 2043 2044 2045### 示例15（文本设置省略模式） 2046 2047该示例通过[textOverflow](#textoverflow12)（从API version 12开始）、[ellipsisMode](#ellipsismode18)（从API version 18开始）、[maxLines](#maxlines10)（从API version 10开始）属性展示了文本超长省略以及调整省略位置的效果。 2048 2049```ts 2050// xxx.ets 2051@Entry 2052@Component 2053struct EllipsisModeExample { 2054 @State textIndex: number = 0; 2055 @State text: string = "As the sun begins to set, casting a warm golden hue across the sky," + 2056 "the world seems to slow down and breathe a sigh of relief. The sky is painted with hues of orange, " + 2057 " pink, and lavender, creating a breath taking tapestry that stretches as far as the eye can see." + 2058 "The air is filled with the sweet scent of blooming flowers, mingling with the earthy aroma of freshly turned soil."; 2059 @State ellipsisModeIndex: number = 0; 2060 @State ellipsisMode: (EllipsisMode | undefined | null)[] = 2061 [EllipsisMode.START, EllipsisMode.END, EllipsisMode.CENTER, undefined, null]; 2062 @State ellipsisModeStr: string[] = ['START ', 'END', 'CENTER', 'undefined', 'null']; 2063 @State textOverflowIndex: number = 0; 2064 @State textOverflow: TextOverflow[] = [TextOverflow.Ellipsis, TextOverflow.Clip]; 2065 @State textOverflowStr: string[] = ['Ellipsis', 'Clip']; 2066 @State maxLinesIndex: number = 0; 2067 @State maxLines: number[] = [1, 2, 3]; 2068 @State maxLinesStr: string[] = ['1', '2', '3']; 2069 @State styleAreaIndex: number = 0; 2070 @State styleArea: TextContentStyle[] = [TextContentStyle.INLINE, TextContentStyle.DEFAULT]; 2071 @State styleAreaStr: string[] = ['INLINE', 'DEFAULT']; 2072 2073 build() { 2074 Column({ space: 20 }) { 2075 TextArea({ text: this.text }) 2076 .textOverflow(this.textOverflow[this.textOverflowIndex]) 2077 .ellipsisMode(this.ellipsisMode[this.ellipsisModeIndex]) 2078 .maxLines(this.maxLines[this.maxLinesIndex]) 2079 .style(this.styleArea[this.styleAreaIndex]) 2080 .fontSize(30) 2081 .margin(30) 2082 2083 Button('更改ellipsisMode模式：' + this.ellipsisModeStr[this.ellipsisModeIndex]).onClick(() => { 2084 this.ellipsisModeIndex++; 2085 if (this.ellipsisModeIndex > (this.ellipsisModeStr.length - 1)) { 2086 this.ellipsisModeIndex = 0; 2087 } 2088 }).fontSize(20) 2089 Button('更改textOverflow模式：' + this.textOverflowStr[this.textOverflowIndex]).onClick(() => { 2090 this.textOverflowIndex++; 2091 if (this.textOverflowIndex > (this.textOverflowStr.length - 1)) { 2092 this.textOverflowIndex = 0; 2093 } 2094 }).fontSize(20) 2095 Button('更改maxLines大小：' + this.maxLinesStr[this.maxLinesIndex]).onClick(() => { 2096 this.maxLinesIndex++; 2097 if (this.maxLinesIndex > (this.maxLinesStr.length - 1)) { 2098 this.maxLinesIndex = 0; 2099 } 2100 }).fontSize(20) 2101 Button('更改Style大小：' + this.styleAreaStr[this.styleAreaIndex]).onClick(() => { 2102 this.styleAreaIndex++; 2103 if (this.styleAreaIndex > (this.styleAreaStr.length - 1)) { 2104 this.styleAreaIndex = 0; 2105 } 2106 }).fontSize(20) 2107 }.height(600).width('100%') 2108 } 2109} 2110``` 2111 2112 2113 2114### 示例16（自定义复制、剪切、粘贴） 2115 2116该示例通过[onCopy](#oncopy8)、[onCut](#oncut8)、[onPaste](#onpaste)展示如何监听文本选择菜单的复制、剪切、粘贴按钮，以及如何屏蔽系统粘贴功能并实现自定义的粘贴能力，同时，可以通过[maxFontScale](#maxfontscale18)、[minFontScale](#minfontscale18)属性设置文本最大和最小的字体缩放倍数。 2117 2118```ts 2119// xxx.ets 2120@Entry 2121@Component 2122struct TextAreaExample { 2123 @State text: string = ''; 2124 controller: TextAreaController = new TextAreaController(); 2125 2126 build() { 2127 Column() { 2128 TextArea({ 2129 text: this.text, 2130 placeholder: 'placeholder', 2131 controller: this.controller 2132 }) 2133 .placeholderColor(Color.Red) 2134 .textAlign(TextAlign.Center) 2135 .caretColor(Color.Green) 2136 .caretStyle({ width: '2vp' }) 2137 .fontStyle(FontStyle.Italic) 2138 .fontWeight(FontWeight.Bold) 2139 .fontFamily('HarmonyOS Sans') 2140 .inputFilter('[a-zA-Z]+', (value) => { // 只允许字母输入 2141 console.error(`unsupport char ${value}`); 2142 }) 2143 .copyOption(CopyOptions.LocalDevice) 2144 .enableKeyboardOnFocus(false) 2145 .selectionMenuHidden(false) 2146 .barState(BarState.On) 2147 .type(TextAreaType.NORMAL) 2148 .selectedBackgroundColor(Color.Orange) 2149 .textIndent(2) 2150 .halfLeading(true) 2151 .minFontScale(1) 2152 .maxFontScale(2) 2153 .enablePreviewText(true) 2154 .enableHapticFeedback(true) 2155 .stopBackPress(false)// 返回键交给其他组件处理 2156 .width(336) 2157 .height(56) 2158 .margin(20) 2159 .fontSize(16) 2160 .onEditChange((isEditing: boolean) => { 2161 console.info(`isEditing ${isEditing}`); 2162 }) 2163 .onCopy((value) => { 2164 console.info(`copy ${value}`); 2165 }) 2166 .onCut((value) => { 2167 console.info(`cut ${value}`); 2168 }) 2169 .onPaste((value, event) => { 2170 // 阻止系统粘贴功能，开发者可自行实现 2171 if (event.preventDefault) { 2172 event.preventDefault(); 2173 } 2174 console.info(`paste:${value}`); 2175 this.text = value; 2176 }) 2177 .onTextSelectionChange((start: number, end: number) => { 2178 console.info(`onTextSelectionChange start ${start}, end ${end}`); 2179 }) 2180 .onContentScroll((totalOffsetX: number, totalOffsetY: number) => { 2181 console.info(`onContentScroll offsetX ${totalOffsetX}, offsetY ${totalOffsetY}`); 2182 }) 2183 }.width('100%').height('100%').backgroundColor('#F1F3F5') 2184 } 2185} 2186``` 2187 2188 2189### 示例17（设置最小字体范围与最大字体范围） 2190 2191从API version 18开始，该示例通过[minFontScale](#minfontscale18)、[maxFontScale](#maxfontscale18)设置字体显示最小与最大范围<!--Del-->（该示例使用系统接口，应用类型需调整为系统应用，可参考HarmonyAppProvision的[系统接口说明](../../../reference/development-intro-api.md#系统接口说明)）<!--DelEnd-->。 2192<!--code_no_check--> 2193```json 2194// 开启应用缩放跟随系统 2195// AppScope/resources/base，新建文件夹profile。 2196// AppScope/resources/base/profile，新建文件configuration.json。 2197// AppScope/resources/base/profile/configuration.json，增加如下代码。 2198{ 2199 "configuration": { 2200 "fontSizeScale": "followSystem", 2201 "fontSizeMaxScale": "3.2" 2202 } 2203} 2204``` 2205<!--code_no_check--> 2206```json 2207// AppScope/app.json5，修改如下代码。 2208{ 2209 "app": { 2210 "bundleName": "com.example.myapplication", 2211 "vendor": "example", 2212 "versionCode": 1000000, 2213 "versionName": "1.0.0", 2214 "icon": "$media:app_icon", 2215 "label": "$string:app_name", 2216 "configuration": "$profile:configuration" 2217 } 2218} 2219``` 2220<!--RP1--> 2221<!--code_no_check--> 2222```ts 2223// xxx.ets 2224import { abilityManager, Configuration } from '@kit.AbilityKit'; 2225import { BusinessError } from '@kit.BasicServicesKit'; 2226 2227@Entry 2228@Component 2229struct TextAreaExample { 2230 @State currentFontSizeScale: number = 1; 2231 @State minFontScale: number = 0.85; 2232 @State maxFontScale: number = 2; 2233 2234 // 设置字体大小 2235 async setFontScale(scale: number): Promise<void> { 2236 let configInit: Configuration = { 2237 language: 'zh-Ch', 2238 fontSizeScale: scale, 2239 }; 2240 // 更新配置-字体大小，调用系统接口更新字体配置 2241 // 需在工程的module.json5文件的requestPermissions字段配置权限：ohos.permission.UPDATE_CONFIGURATION 2242 abilityManager.updateConfiguration(configInit, (err: BusinessError) => { 2243 if (err) { 2244 console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`); 2245 } else { 2246 this.currentFontSizeScale = scale; 2247 console.info('updateConfiguration success.'); 2248 } 2249 }); 2250 } 2251 2252 build() { 2253 Column() { 2254 Column({ space: 30 }) { 2255 Text("通过minFontScale、maxFontScale调整文本显示的最大和最小字体缩放倍数。") 2256 TextArea({ 2257 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 2258 text: '通过minFontScale、maxFontScale调整文本显示的最大和最小字体缩放倍数。' 2259 }) 2260 .minFontScale(this.minFontScale)// 设置最小字体缩放倍数，参数为undefined则跟随系统默认倍数缩放 2261 .maxFontScale(this.maxFontScale) // 设置最大字体缩放倍数，参数为undefined则跟随系统默认倍数缩放 2262 }.width('100%') 2263 2264 Column() { 2265 Row() { 2266 Button('1倍').onClick(() => { 2267 this.setFontScale(1) 2268 }).margin(10) 2269 Button('1.75倍').onClick(() => { 2270 this.setFontScale(1.75) 2271 }).margin(10) 2272 } 2273 2274 Row() { 2275 Button('2倍').onClick(() => { 2276 this.setFontScale(2) 2277 }).margin(10) 2278 Button('3.2倍').onClick(() => { 2279 this.setFontScale(3.2) 2280 }).margin(10) 2281 } 2282 }.margin({ top: 50 }) 2283 } 2284 } 2285} 2286``` 2287| 系统字体缩放倍数为2倍 | 系统字体缩放倍数为3.2倍 | 2288| ---------------------------------- | ------------------------------------ | 2289|  |  | 2290<!--RP1End--> 2291### 示例18（设置选中指定区域的文本内容） 2292 2293从API version 10开始，该示例通过[setTextSelection](#settextselection10)方法展示如何设置选中指定区域的文本内容以及菜单的显隐策略。 2294 2295```ts 2296// xxx.ets 2297 2298@Entry 2299@Component 2300struct TextAreaExample { 2301 controller: TextAreaController = new TextAreaController(); 2302 @State startIndex: number = 0; 2303 @State endIndex: number = 0; 2304 2305 build() { 2306 Column({ space: 3 }) { 2307 Text('Selection start:' + this.startIndex + ' end:' + this.endIndex) 2308 TextArea({ text: 'Hello World', controller: this.controller }) 2309 .width('95%') 2310 .height(80) 2311 .margin(10) 2312 .defaultFocus(true) 2313 .enableKeyboardOnFocus(true) 2314 .onTextSelectionChange((selectionStart: number, selectionEnd: number) => { 2315 this.startIndex = selectionStart; 2316 this.endIndex = selectionEnd; 2317 }) 2318 2319 Button('setTextSelection [0,3], set menuPolicy is MenuPolicy.SHOW') 2320 .onClick(() => { 2321 this.controller.setTextSelection(0, 3, { menuPolicy: MenuPolicy.SHOW }); 2322 }) 2323 } 2324 .width('100%') 2325 .height('100%') 2326 } 2327} 2328``` 2329 2330 2331 2332### 示例19（设置文本描边） 2333 2334从API version 20开始，该示例通过[strokeWidth](#strokewidth20)和[strokeColor](#strokecolor20)属性设置文本的描边宽度及颜色。 2335 2336```ts 2337// xxx.ets 2338import { LengthMetrics } from '@kit.ArkUI'; 2339 2340@Entry 2341@Component 2342struct TextAreaExample { 2343 build() { 2344 Row() { 2345 Column() { 2346 Text('stroke feature').fontSize(9).fontColor(0xCCCCCC) 2347 2348 TextArea({ text: 'Text without stroke' }) 2349 .width('100%') 2350 .height(60) 2351 .borderWidth(1) 2352 .fontSize(40) 2353 TextArea({ text: 'Text with stroke' }) 2354 .width('100%') 2355 .height(60) 2356 .borderWidth(1) 2357 .fontSize(40) 2358 .strokeWidth(LengthMetrics.px(-3.0)) 2359 .strokeColor(Color.Red) 2360 TextArea({ text: 'Text with stroke' }) 2361 .width('100%') 2362 .height(60) 2363 .borderWidth(1) 2364 .fontSize(40) 2365 .strokeWidth(LengthMetrics.px(3.0)) 2366 .strokeColor(Color.Red) 2367 }.height('90%') 2368 } 2369 .width('90%') 2370 .margin(10) 2371 } 2372} 2373``` 2374 2375 2376 2377### 示例20（设置中西文自动间距） 2378 2379从API version 20开始，该示例通过[enableAutoSpacing](#enableautospacing20)属性设置中西文自动间距。 2380 2381```ts 2382// xxx.ets 2383@Entry 2384@Component 2385struct TextAreaExample { 2386 build() { 2387 Row() { 2388 Column() { 2389 Text('开启中西文自动间距').margin(5) 2390 TextArea({text: '中西文Auto Spacing自动间距'}) 2391 .enableAutoSpacing(true) 2392 Text('关闭中西文自动间距').margin(5) 2393 TextArea({text: '中西文Auto Spacing自动间距'}) 2394 .enableAutoSpacing(false) 2395 }.height('100%') 2396 } 2397 .width('60%') 2398 } 2399} 2400``` 2401 2402 2403 2404### 示例21（设置最大行数） 2405 2406从API version 20开始，该示例通过[maxLines](#maxlines20)属性设置显示最大行数，超出最大行数后可滚动。 2407 2408```ts 2409// xxx.ets 2410@Entry 2411@Component 2412struct TextAreaExample { 2413 build() { 2414 Row() { 2415 Column() { 2416 TextArea({ text: '1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20' }) 2417 .fontSize(50) 2418 .width('50%') 2419 .borderWidth(1) 2420 .margin(100) 2421 .textOverflow(TextOverflow.Clip) 2422 .maxLines(3, { overflowMode: MaxLinesMode.SCROLL }) 2423 }.height('90%') 2424 } 2425 .width('90%') 2426 .margin(10) 2427 } 2428} 2429 2430``` 2431 2432 2433### 示例22（设置最小行数） 2434 2435从API version 20开始，该示例通过[minLines](#minlines20)属性设置显示的最小行数。 2436 2437```ts 2438// xxx.ets 2439@Entry 2440@Component 2441struct Index { 2442 @State message: string = 'Hello World'; 2443 2444 build() { 2445 Row() { 2446 Column() { 2447 TextArea({ text: this.message }) 2448 .width('95%') 2449 .fontSize(20) 2450 .margin(10) 2451 .minLines(3) 2452 } 2453 } 2454 .width('90%') 2455 .margin(10) 2456 } 2457} 2458``` 2459 2460 2461
