1# TextArea 2 3多行文本输入框组件，当输入的文本内容超过组件宽度时会自动换行显示。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12无 13 14 15## 接口 16 17TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController}) 18 19**参数：** 20 21| 参数名 | 参数类型 | 必填 | 参数描述 | 22| ----------------------- | ---------------------------------------- | ---- | -------------- | 23| placeholder | [ResourceStr](ts-types.md#resourcestr) | 否 | 设置无输入时的提示文本。输入内容后，提示文本不显示。 | 24| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 设置输入框当前的文本内容。</br>当组件设置[stateStyles](ts-universal-attributes-polymorphic-style.md)等刷新属性时，建议通过onChange事件将状态变量与文本实时绑定，</br>避免组件刷新时TextArea中的文本内容异常。 | 25| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | 否 | 设置TextArea控制器。 | 26 27 28## 属性 29 30除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 31 32| 名称 | 参数类型 | 描述 | 33| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 34| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | 设置placeholder文本颜色。 | 35| placeholderFont | [Font](ts-types.md#font) | 设置placeholder文本样式，包括字体大小，字体粗细，字体族，字体风格。目前仅支持默认字体族。 | 36| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | 设置文本在输入框中的水平对齐式。<br/>默认值：TextAlign.Start | 37| caretColor | [ResourceColor](ts-types.md#resourcecolor) | 设置输入框光标颜色。 | 38| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](ts-types.md#resourcestr),<br/>error?: (value: string) => void<br/>} | 通过正则表达式设置输入过滤器。匹配表达式的输入允许显示，不匹配的输入将被过滤。仅支持单个字符匹配，不支持字符串匹配。<br/>- value：设置正则表达式。<br/>- error：正则匹配失败时，返回被过滤的内容。 | 39| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 设置输入的文本是否可复制。<br>设置CopyOptions.None时，当前TextArea中的文字无法被复制或剪切，仅支持粘贴。 | 40 41> **说明：** 42> 43> [通用属性padding](ts-universal-attributes-size.md)的默认值为：<br>{<br> top: 8 vp,<br> right: 16 vp,<br> bottom: 8 vp,<br> left: 16 vp<br> } 44 45 46## 事件 47 48除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 49 50| 名称 | 功能描述 | 51| ------------------------------------------------------------ | ------------------------------------------------------------ | 52| onChange(callback: (value: string) => void) | 输入内容发生变化时，触发该回调。<br/>- value：当前输入的文本内容。 | 53| onCopy<sup>8+</sup>(callback:(value: string) => void) | 长按输入框内部区域弹出剪贴板后，点击剪切板复制按钮，触发该回调。<br/>- value：复制的文本内容。 | 54| onCut<sup>8+</sup>(callback:(value: string) => void) | 长按输入框内部区域弹出剪贴板后，点击剪切板剪切按钮，触发该回调。<br/>- value：剪切的文本内容。 | 55| onPaste<sup>8+</sup>(callback:(value: string) => void) | 长按输入框内部区域弹出剪贴板后，点击剪切板粘贴按钮，触发该回调。<br/>- value：粘贴的文本内容。 | 56 57## TextAreaController<sup>8+</sup> 58 59TextArea组件的控制器，目前可通过它设置TextArea组件的光标位置。 60 61### 导入对象 62 63``` 64controller: TextAreaController = new TextAreaController() 65``` 66 67### caretPosition<sup>8+</sup> 68 69caretPosition(value: number): void 70 71设置输入光标的位置。 72 73**参数：** 74 75| 参数名 | 参数类型 | 必填 | 参数描述 | 76| ------ | -------- | ---- | -------------------------------------- | 77| value | number | 是 | 从字符串开始到光标所在位置的字符长度。 | 78 79 80## 示例 81 82```ts 83// xxx.ets 84@Entry 85@Component 86struct TextAreaExample { 87 @State text: string = '' 88 controller: TextAreaController = new TextAreaController() 89 90 build() { 91 Column() { 92 TextArea({ 93 text: this.text, 94 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 95 controller: this.controller 96 }) 97 .placeholderFont({ size: 16, weight: 400 }) 98 .width(336) 99 .height(56) 100 .margin(20) 101 .fontSize(16) 102 .fontColor('#182431') 103 .backgroundColor('#FFFFFF') 104 .onChange((value: string) => { 105 this.text = value 106 }) 107 Text(this.text) 108 Button('Set caretPosition 1') 109 .backgroundColor('#007DFF') 110 .margin(15) 111 .onClick(() => { 112 // 设置光标位置到第一个字符后 113 this.controller.caretPosition(1) 114 }) 115 }.width('100%').height('100%').backgroundColor('#F1F3F5') 116 } 117} 118``` 119 120
