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