TextArea

The <TextArea> component provides multi-line text input and automatically wraps text so that each line does not have more than the width of the component.

NOTE

This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

Not supported

APIs

TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController})

Parameters

Name Type Mandatory Description
placeholder ResourceStr No Placeholder text displayed when there is no input. It is not displayed once there is any input.
text ResourceStr No Current text input.
If the component has stateStyles or any other attribute that may trigger updating configured, you are advised to bind the state variable to the text in real time through the onChange event,
so as to prevent display errors when the component is updated.
controller8+ TextAreaController No Text area controller.

Attributes

In addition to the universal attributes, the following attributes are supported.

Name Type Description
placeholderColor ResourceColor Placeholder text color.
placeholderFont Font Placeholder text style, including the font size, font width, font family, and font style. Currently, only the default font family is supported.
textAlign TextAlign Horizontal alignment of the text.
Default value: TextAlign.Start
caretColor ResourceColor Color of the caret in the text box.
inputFilter8+ {
value: ResourceStr,
error?: (value: string) => void
}		 Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The specified regular expression can match single characters, but not strings.
- value: regular expression to set.
- error: filtered-out content to return when regular expression matching fails.
copyOption9+ CopyOptions Whether copy and paste is allowed.
If this attribute is set to CopyOptions.None, the paste operation is allowed, but not the copy or cut operation.

NOTE

The default value of the universal attribute padding is as follows:
{
top: 8 vp,
right: 16 vp,
bottom: 8 vp,
left: 16 vp
}

Events

In addition to the universal events, the following events are supported.

Name Description
onChange(callback: (value: string) => void) Triggered when the input in the text box changes.
- value: text entered.
onCopy8+(callback:(value: string) => void) Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.
- value: text to be copied.
onCut8+(callback:(value: string) => void) Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.
- value: text to be cut.
onPaste8+(callback:(value: string) => void) Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.
- value: text to be pasted.

TextAreaController8+

Defines the controller for controlling the <TextArea> component. Currently, the controller can be used to control the caret position.

Objects to Import

controller: TextAreaController = new TextAreaController()

caretPosition8+

caretPosition(value: number): void

Sets the position of the caret.

Parameters

Name Type Mandatory Description
value number Yes Length from the start of the string to the position where the caret is located.

Example

// xxx.ets
@Entry
@Component
struct TextAreaExample {
  @State text: string = ''
  controller: TextAreaController = new TextAreaController()

  build() {
    Column() {
      TextArea({
        text: this.text,
        placeholder: 'The text area can hold an unlimited amount of text. input your word...',
        controller: this.controller
      })
        .placeholderFont({ size: 16, weight: 400 })
        .width(336)
        .height(56)
        .margin(20)
        .fontSize(16)
        .fontColor('#182431')
        .backgroundColor('#FFFFFF')
        .onChange((value: string) => {
          this.text = value
        })
      Text(this.text)
      Button('Set caretPosition 1')
        .backgroundColor('#007DFF')
        .margin(15)
        .onClick(() => {
          // Move the caret to after the first entered character.
          this.controller.caretPosition(1)
        })
    }.width('100%').height('100%').backgroundColor('#F1F3F5')
  }
}

textArea