ts-basic-components-textarea.md 5.3 KB
Newer Older
Z
zengyawen 已提交
1
# TextArea
Z
zengyawen 已提交
2 3


E
esterzhou 已提交
4
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
Z
zengyawen 已提交
5
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
Z
zengyawen 已提交
6

Z
zengyawen 已提交
7 8 9 10 11

The **<TextArea>** component provides multi-line text input.


## Required Permissions
Z
zengyawen 已提交
12 13 14

None

Z
zengyawen 已提交
15

E
esterzhou 已提交
16
## Child Components
Z
zengyawen 已提交
17

E
esterzhou 已提交
18
None
Z
zengyawen 已提交
19

Z
zengyawen 已提交
20 21 22 23 24 25

## APIs

TextArea(value?:{placeholder?: string controller?: TextAreaController})

- Parameters
E
esterzhou 已提交
26
    | Name | Type | Mandatory | Default Value | Description |
Z
zengyawen 已提交
27
  | -------- | -------- | -------- | -------- | -------- |
E
esterzhou 已提交
28 29
  | placeholder | string | No | - | Text displayed when there is no input. |
  | controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | - | Text area controller. |
Z
zengyawen 已提交
30 31 32 33


## Attributes

E
ester.zhou 已提交
34
In addition to universal attributes, the following attributes are supported.
Z
zengyawen 已提交
35

E
esterzhou 已提交
36
| Name | Type | Default Value | Description |
Z
zengyawen 已提交
37
| -------- | -------- | -------- | -------- |
E
esterzhou 已提交
38 39 40 41 42
| placeholderColor | Color | - | Placeholder text color. |
| placeholderFont | {<br/>size?: number,<br/>weight?:number \| [FontWeight](ts-universal-attributes-text-style.md),<br/>family?: string,<br/>style?: [FontStyle](ts-universal-attributes-text-style.md)<br/>} | - | Placeholder text style.<br/>- **size**: font size. If the value is of the number type, the unit fp is used.<br/>- **weight**: font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.<br/>- **family**: font family. Use commas (,) to separate multiple fonts, for example, **'Arial, sans-serif'**. The priority of the fonts is the sequence in which they are placed.<br/>- **style**: font style. |
| textAlign | TextAlign | Start | Sets the text horizontal alignment mode. |
| caretColor | Color | - | Sets the color of the cursor in the text box. |
| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](../../ui/ts-types.md),<br/>error?: (value: string)<br/>} | - | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are ignored. The specified regular expression can match single characters, but not strings. Example: ^(? =.\*\d)(? =.\*[a-z])(? =.\*[A-Z]).{8,10}$. Strong passwords containing 8 to 10 characters cannot be filtered.<br/>- **value**: indicates the regular expression to set.<br/>- **error**: returns the ignored content when regular expression matching fails. |
Z
zengyawen 已提交
43 44

- TextAlign enums
E
esterzhou 已提交
45
    | Name | Description |
Z
zengyawen 已提交
46
  | -------- | -------- |
E
esterzhou 已提交
47 48 49
  | Start | Aligns the header horizontally. |
  | Center | Horizontal center alignment. |
  | End | Align the tail horizontally. |
Z
zengyawen 已提交
50 51 52 53


## Events

E
esterzhou 已提交
54
| Name | Description |
Z
zengyawen 已提交
55
| -------- | -------- |
E
esterzhou 已提交
56 57 58 59
| onChange(callback: (value: string) =&gt; void) | Triggered when the input changes. |
| onCopy<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br/>**value**: text to be copied. |
| onCut<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br/>**value**: text to be cut. |
| onPaste<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br/>**value**: text to be pasted. |
Z
zengyawen 已提交
60

E
ester.zhou 已提交
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
## TextAreaController<sup>8+</sup>

Defines the controller for controlling the **&lt;TextArea&gt;** component.

### Objects to Import

```
controller: TextAreaController = new TextAreaController()

```

### caretPosition<sup>8+</sup>

caretPosition(value: number): void

Sets the position of the caret.

- Parameters
  | Name   | Type | Mandatory | Default Value | Description     |
  | ----- | ------ | ---- | ---- | ------------------- |
  | value | number | Yes  | -    | Length from the start of the string to the position where the input cursor is located. |

Z
zengyawen 已提交
83 84 85 86 87 88

## Example


### Multi-line Text Input

Z
zengyawen 已提交
89 90 91 92

```
@Entry
@Component
Z
zengyawen 已提交
93
struct TextAreaExample2 {
Z
zengyawen 已提交
94 95 96
  @State text: string = ''
  build() {
    Column() {
Z
zengyawen 已提交
97
      TextArea({ placeholder: 'input your word'})
Z
zengyawen 已提交
98 99 100 101 102 103 104 105 106 107
        .placeholderColor("rgb(0,0,225)")
        .placeholderFont({ size: 30, weight: 100, family: 'cursive', style: FontStyle.Italic })
        .textAlign(TextAlign.Center)
        .caretColor(Color.Blue)
        .height(50)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .fontFamily("sans-serif")
        .fontStyle(FontStyle.Normal)
        .fontColor(Color.Red)
Z
zengyawen 已提交
108 109 110
        .inputFilter('^[\u4E00-\u9FA5A-Za-z0-9_]+$',(value: string) => {
          console.info("hyb"+value)
        })
Z
zengyawen 已提交
111 112 113 114 115 116 117 118 119
        .onChange((value: string) => {
          this.text = value
        })
      Text(this.text).width('90%')
    }
  }
}
```

Z
zengyawen 已提交
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
![en-us_image_0000001256858399](figures/en-us_image_0000001256858399.gif)


### Setting the Input Cursor


```
@Entry
@Component
struct TextAreaTest {
    controller: TextAreaController = new TextAreaController()
    build() {
        Column() {
            TextArea({ placeholder: 'input your word',controller:this.controller })
            Button('caretPosition')
                .onClick(() => {
                    this.controller.caretPosition(4)
                })
          }
    }
}
```
Z
zengyawen 已提交
142

Z
zengyawen 已提交
143
![en-us_image_0000001212058476](figures/en-us_image_0000001212058476.png)