TextInput

The <TextInput> component provides single-line text input.

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

TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})

Parameters

Name Type Mandatory Description
placeholder ResourceStr No Text displayed when there is no input.
text ResourceStr No Current text input.
controller8+ TextInputController No Text input controller.

Attributes

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

Name Type Description
type InputType Input box type.
Default value: InputType.Normal
placeholderColor ResourceColor Placeholder text color.
placeholderFont Font Placeholder text style.
enterKeyType EnterKeyType How the Enter key is labeled.
Default value: EnterKeyType.Done
caretColor ResourceColor Color of the caret in the text box.
maxLength number Maximum number of characters in the text input.
inputFilter8+ {
value: value: ResourceStr8+,
error?: (value: string) => void
}		 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.
- value: regular expression to set.
- error: ignored content to return when regular expression matching fails.

EnterKeyType

Name Description
Go The Enter key is labeled "Go."
Search The Enter key is labeled "Search."
Send The Enter key is labeled "Send."
Next The Enter key is labeled "Next."
Done The Enter key is labeled "Done."

InputType enums

Name Description
Normal Normal input mode.
Password Password input mode.
Email Email address input mode.
Number Digit input mode.

Event

Name Description
onChange(callback: (value: string) => void) Triggered when the input changes.
onSubmit(callback: (enterKey: EnterKeyType) => void) Triggered when the Enter key on the physical or soft keyboard is pressed.
onEditChanged(callback: (isEditing: boolean) => void)(deprecated) Triggered when the input status changes.
onEditChange(callback: (isEditing: boolean) => void) 8+ Triggered when the input status changes.
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.

TextInputController8+

Implements the controller of the <TextInput> component.

Objects to Import

controller: TextInputController = new TextInputController()

caretPosition

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

Single-line Text Input

// xxx.ets
@Entry
@Component
struct TextInputExample1 {
  @State text: string = ''

  build() {
    Column() {
      TextInput({ placeholder: 'input your word' })
        .placeholderColor("rgb(0,0,225)")
        .placeholderFont({ size: 30, weight: 100, family: 'cursive', style: FontStyle.Italic })
        .caretColor(Color.Blue)
        .height(50)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .fontFamily("sans-serif")
        .fontStyle(FontStyle.Normal)
        .fontColor(Color.Red)
        .onChange((value: string) => {
          this.text = value
        })
      Text(this.text).width('90%')
    }
  }
}

en-us_image_0000001212378402

Setting the Caret

// xxx.ets
@Entry
@Component
struct TextInputExample2 {
    @State text: string = ''
    controller: TextInputController = new TextInputController()
    build() {
        Column() {
            TextInput({ placeholder: 'Please input your words.', controller:this.controller})
            Button('caretPosition')
                .onClick(() => {
                this.controller.caretPosition(4)
            })
        }
    }
}

en-us_image_0000001212058468