HarmonyOS NEXT鸿蒙开发：TextArea 多行文本输入组件

作者：马育民 • • 阅读：10052

介绍

TextArea 是用于接收多行文本输入的组件，适用于需要用户输入长文本的场景（如备注、评论、反馈等），相比单行的 TextInput 支持换行和更多的文本内容。

基本特性

  • 支持 多行文本输入，自动换行
  • 可设置最大输入长度、提示文本
  • 支持获取焦点、失去焦点等事件
  • 可配置文本对齐方式、字体样式等

应用场景

  • 评论
  • 外卖备注
  • 笔记、记事本
  • 个人介绍

基本用法

TextArea 的核心是通过 value 属性绑定文本数据，并通过 onChange 事件实时监听输入变化，基本示例如下：

@State inputValue: string = ""
build() {
  Column() {
    TextArea({
      text: $$this.inputValue, // 绑定文本内容
      placeholder:"请输入个人介绍" //提示文本（占位符）
    })
      .height(150) // 设置输入框高度，否则是单行输入框
      .border({ width: 1, color: "#cccccc" })
      .margin(10)
    // 按钮
    Button("获取内容")
      .onClick(()=>{
        console.log("获取内容：",this.inputValue)
      })
    Button("修改内容")
      .onClick(()=>{
        this.inputValue = "123"
        console.log("修改内容")
      })

  }
}

常用属性

属性 说明
maxLength 最大输入长度限制，如 maxLength(500) 限制最多输入500个字符
textAlign 文本对齐方式，可选 TextAlign.Left（左对齐）、TextAlign.Center（居中）、TextAlign.Right（右对齐）
fontSize 文本字体大小，如 fontSize(16)
fontColor 文本颜色，如 fontColor("#333333")
placeholderColor 提示文本（hint）的颜色，如 placeholderColor("#999999")
enabled 是否允许输入，false 时为禁用状态（灰显，不可编辑）
border 边框样式，如 border({ width: 1, radius: 4, color: "#ddd" })（宽度、圆角、颜色）
width/height 组件宽高，建议设置固定高度或使用 minHeight 适应内容
padding 内边距，调整文本与边框的距离，如 padding(10)

常用事件

事件 说明
onChange 文本内容变化时触发，返回当前输入的完整文本，用于同步数据
onFocus 输入框获取焦点时触发（如用户点击输入框），可用于弹出提示或调整样式
onBlur 输入框失去焦点时触发（如用户点击其他区域），可用于校验输入内容
onSubmit 点击软键盘的“完成”按钮时触发，通常用于提交输入内容

例子

带长度限制

TextArea({
        text: $$this.inputValue, // 绑定文本内容
        placeholder:"最多输入10字" //提示文本（占位符）
      })
        .maxLength(10) // 限制最大长度
        .height(120)
        .border({ width: 1, radius: 4 })
        .margin(10)

禁用状态的文本区域

TextArea({
        text: $$this.inputValue, // 绑定文本内容
        placeholder:"这是一段不可编辑的文本内容" //提示文本（占位符）
      })
  .enabled(false) // 禁用输入
  .height(120)
  .border({ width: 1, radius: 4 })
  .margin(10)

带焦点监听的文本输入

import { promptAction } from '@kit.ArkUI';

TextArea({
        text: $$this.inputValue, // 绑定文本内容
        placeholder:"点击输入" //提示文本（占位符）
      })
        .onFocus(() => {
          console.log("文本框获取焦点");
          // 可在此处执行准备逻辑，如加载历史记录
        })
        .onBlur(() => {
          console.log("文本框失去焦点");
          // 可在此处执行校验，如检查内容是否为空
          if (this.inputValue.length === 0) {
            promptAction.showToast({
              message: "内容不能为空"
            })
            // AlertDialog.show({ message: "内容不能为空" });
          }
        })
        .height(120)
        .border({ width: 1})
        .margin(10)

注意

  • 高度设置：TextArea 需设置合适的 height 或 minHeight，避免因内容过多导致显示不全

  • 性能优化：当 maxLength 较大时，避免在 onChange 中执行复杂逻辑（如实时过滤），可在 onBlur 或 onSubmit 中处理

  • 与 TextInput 区别：TextArea 适用于多行输入，TextInput 适用于单行输入（如用户名、密码）

通过 TextArea 组件，可轻松实现多行文本输入功能，结合属性配置和事件处理，能满足各类长文本输入场景的需求。

原文出处：/show_1GW1y1gv36kc.html

吉ICP备15003043号