鸿蒙PC UI控件库 - TextArea 多行文本输入详解

摘要 TextArea是一个多行文本输入组件，支持自动高度调整、字数统计、长度限制等功能。主要特性包括：支持多行文本输入与自动换行可配置字数统计显示和最大长度限制自动调整高度（3-10行范围）提供标签、提示文本和错误提示功能包含品牌标识和多种尺寸选择支持禁用、只读、必填等状态适用于评论输入、内容编辑等场景，通过API可灵活配置各项参数。组件采用双向绑定机制，所有样式均可通过代码定制，

红目香薰

832人浏览 · 2025-12-14 13:07:20

红目香薰 · 2025-12-14 13:07:20 发布

演示视频地址：

https://www.bilibili.com/video/BV1jomdBBE4H/
在这里插入图片描述

概述

TextArea 是控件库中的多行文本输入组件，支持字数统计、自动调整高度、验证等功能，适用于评论输入、内容编辑、详细描述等需要多行文本输入的场景。

设计理念

多行文本输入框采用灵活易用设计，具有以下特点：

多行输入：支持多行文本输入，自动换行
字数统计：支持显示字数统计，实时反馈
自动调整：支持根据内容自动调整高度
长度限制：支持最大长度限制
品牌标识：左下角自动包含品牌标识（圆圈红字"PC"）
主题统一：所有样式配置都在代码中，方便定制

适用场景

评论输入：用户评论、反馈输入
内容编辑：文章编辑、内容创作
详细描述：产品描述、详情输入
表单输入：多行表单字段

特性

✨ 核心特性

✅ 多行输入：支持多行文本输入，自动换行
✅ 字数统计：支持显示字数统计（可选）
✅ 自动调整高度：支持根据内容自动调整高度
✅ 行数控制：支持设置最小和最大行数
✅ 长度限制：支持最大长度限制
✅ 标签和提示：支持标签、提示文本、错误提示
✅ 多种尺寸：支持 small、medium、large 三种尺寸
✅ 状态管理：支持禁用、只读、必填等状态
✅ 品牌标识：自动包含左下角品牌标识
✅ 主题配置：所有样式都可通过代码配置

🎨 视觉特点

正常状态：白色背景 + 灰色边框
错误状态：红色边框 + 红色错误提示
禁用状态：灰色背景 + 灰色文字 + 灰色边框
只读状态：正常样式但不可编辑
字数统计：显示在右上角，超出限制时变红

快速开始

基础用法

import { TextArea } from '../components/base'

@Entry
@Component
struct MyPage {
  @State content: string = ''

  build() {
    Column({ space: 20 }) {
      // 基础多行文本输入框
      TextArea({
        value: $content,
        placeholder: '请输入内容'
      })
      
      // 带标签的多行文本输入框
      TextArea({
        value: $content,
        placeholder: '请输入内容',
        label: '内容'
      })
      
      // 带字数统计的多行文本输入框
      TextArea({
        value: $content,
        placeholder: '请输入内容',
        label: '内容',
        showCount: true
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

关于双向绑定

TextArea 使用 @Link 实现双向绑定，需要使用 $variableName 语法：

@State content: string = ''

TextArea({
  value: $content  // 使用 $ 创建双向绑定
})

API 参考

Props

属性名	类型	默认值	说明
`value`	`@Link string`	-	文本值（必需，双向绑定）
`placeholder`	`string`	`'请输入内容'`	占位符文本
`label`	`string`	`''`	标签文本
`hint`	`string`	`''`	提示文本（显示在输入框下方）
`errorMessage`	`string`	`''`	错误提示文本（优先级高于 hint）
`inputSize`	`'small' \| 'medium' \| 'large'`	`'medium'`	输入框尺寸
`disabled`	`boolean`	`false`	是否禁用
`readonly`	`boolean`	`false`	是否只读
`required`	`boolean`	`false`	是否必填
`maxLength`	`number`	`0`	最大长度（0表示无限制）
`minRows`	`number`	`3`	最小行数（自动调整高度时）
`maxRows`	`number`	`10`	最大行数（自动调整高度时）
`autoHeight`	`boolean`	`true`	是否自动调整高度
`showCount`	`boolean`	`false`	是否显示字数统计
`showBrand`	`boolean`	`true`	是否显示品牌标识
`inputWidth`	`string \| number`	`'100%'`	输入框宽度
`inputHeight`	`string \| number?`	`undefined`	输入框高度（固定高度时使用）

尺寸规格

尺寸	最小高度	字体大小	行高	内边距（左右）
`small`	80vp	14vp	20vp	12vp
`medium`	100vp	16vp	22vp	14vp
`large`	120vp	18vp	26vp	16vp

使用示例

1. 基础多行文本输入框

@Entry
@Component
struct TextAreaExample1 {
  @State content: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content,
        placeholder: '请输入多行文本内容'
      })
      
      Text(`当前内容长度：${this.content.length} 字符`)
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(20)
  }
}

2. 带标签和提示

@Entry
@Component
struct TextAreaExample2 {
  @State content: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content,
        placeholder: '请输入内容',
        label: '内容',
        hint: '请输入详细内容描述'
      })
      
      TextArea({
        value: $content,
        placeholder: '请输入内容',
        label: '内容',
        errorMessage: '输入内容有误，请重新输入'
      })
    }
    .width('100%')
    .padding(20)
  }
}

3. 字数统计

@Entry
@Component
struct TextAreaExample3 {
  @State content: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content,
        placeholder: '请输入内容',
        label: '内容',
        showCount: true
      })
      
      Text('提示：显示字数统计，不限制最大长度')
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(20)
  }
}

4. 最大长度限制

@Entry
@Component
struct TextAreaExample4 {
  @State content: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content,
        placeholder: '最多输入100个字符',
        label: '内容',
        maxLength: 100,
        showCount: true
      })
      
      Text('提示：达到最大长度时，字数统计会显示为红色')
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(20)
  }
}

5. 自动调整高度

@Entry
@Component
struct TextAreaExample5 {
  @State content: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content,
        placeholder: '输入内容会自动调整高度',
        label: '内容',
        autoHeight: true,
        minRows: 3,
        maxRows: 8,
        showCount: true
      })
      
      Text('提示：输入内容时，高度会根据行数自动调整')
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(20)
  }
}

6. 不同尺寸

@Entry
@Component
struct TextAreaExample6 {
  @State content1: string = ''
  @State content2: string = ''
  @State content3: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content1,
        placeholder: '小尺寸',
        inputSize: 'small'
      })
      
      TextArea({
        value: $content2,
        placeholder: '中等尺寸（默认）',
        inputSize: 'medium'
      })
      
      TextArea({
        value: $content3,
        placeholder: '大尺寸',
        inputSize: 'large'
      })
    }
    .width('100%')
    .padding(20)
  }
}

7. 必填和状态

@Entry
@Component
struct TextAreaExample7 {
  @State content1: string = ''
  @State content2: string = '禁用状态的内容'
  @State content3: string = '只读状态的内容'

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content1,
        placeholder: '请输入内容',
        label: '必填项',
        required: true
      })
      
      TextArea({
        value: $content2,
        placeholder: '请输入内容',
        label: '禁用状态',
        disabled: true
      })
      
      TextArea({
        value: $content3,
        placeholder: '请输入内容',
        label: '只读状态',
        readonly: true
      })
    }
    .width('100%')
    .padding(20)
  }
}

8. 固定高度

@Entry
@Component
struct TextAreaExample8 {
  @State content: string = ''

  build() {
    Column({ space: 15 }) {
      TextArea({
        value: $content,
        placeholder: '固定高度200vp',
        label: '内容',
        autoHeight: false,
        inputHeight: 200,
        showCount: true
      })
      
      Text('提示：关闭自动调整高度，使用固定高度')
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(20)
  }
}

9. 评论输入示例

@Entry
@Component
struct CommentInput {
  @State comment: string = ''

  build() {
    Column({ space: 20 }) {
      Text('发表评论')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
      
      TextArea({
        value: $comment,
        placeholder: '请输入您的评论...',
        label: '评论',
        maxLength: 500,
        showCount: true,
        autoHeight: true,
        minRows: 4,
        maxRows: 10,
        required: true
      })
      
      Button('提交评论')
        .width('100%')
        .height(44)
        .enabled(this.comment.trim().length > 0)
        .onClick(() => {
          // 处理提交逻辑
        })
    }
    .width('100%')
    .padding(30)
  }
}

10. 内容编辑示例

@Entry
@Component
struct ContentEditor {
  @State title: string = ''
  @State content: string = ''

  build() {
    Column({ space: 20 }) {
      Text('内容编辑')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
      
      TextInput({
        value: $title,
        placeholder: '请输入标题',
        label: '标题',
        required: true
      })
      
      TextArea({
        value: $content,
        placeholder: '请输入正文内容...',
        label: '正文',
        maxLength: 5000,
        showCount: true,
        autoHeight: true,
        minRows: 10,
        maxRows: 20,
        required: true
      })
      
      Row({ space: 10 }) {
        Button('保存草稿')
          .layoutWeight(1)
          .height(44)
        
        Button('发布')
          .layoutWeight(1)
          .height(44)
          .enabled(this.title.trim().length > 0 && this.content.trim().length > 0)
      }
      .width('100%')
    }
    .width('100%')
    .padding(30)
  }
}

主题配置

TextArea 的所有样式都通过 ComponentTheme 配置，所有配置都在代码中，不依赖JSON文件。

修改默认颜色

import { ComponentTheme } from '../theme/ComponentTheme'

// 修改主色（影响聚焦状态的边框颜色）
ComponentTheme.PRIMARY_COLOR = '#007AFF'

// 修改错误色（影响错误状态的边框和提示颜色）
ComponentTheme.ERROR_COLOR = '#FF3B30'

// 修改边框颜色
ComponentTheme.BORDER_COLOR = '#E5E5E5'

// 修改圆角
ComponentTheme.BORDER_RADIUS = 8

批量配置

import { ComponentTheme } from '../theme/ComponentTheme'

// 使用 setTheme 方法批量配置
ComponentTheme.setTheme({
  primaryColor: '#007AFF',
  errorColor: '#FF3B30',
  borderRadius: 8,
  spacing: 16
})

最佳实践

1. 尺寸选择

2. 字数统计

默认关闭：showCount: false，适用于大多数场景
需要反馈：需要实时反馈时，开启字数统计
长度限制：设置 maxLength 时，建议开启字数统计

3. 自动调整高度

默认开启：autoHeight: true，提供更好的用户体验
固定高度：需要固定高度时，设置 autoHeight: false 和 inputHeight
行数控制：使用 minRows 和 maxRows 控制自动调整范围

4. 长度限制

合理设置：根据业务需求设置合理的 maxLength
用户提示：使用 hint 说明长度要求
实时反馈：开启字数统计，提供实时反馈

5. 行数设置

最小行数：minRows: 3 适用于大多数场景
最大行数：maxRows: 10 适用于一般内容输入
长文本：长文本编辑时，可以设置更大的 maxRows

6. 用户体验

占位符：提供清晰的占位符文本
提示信息：使用 hint 提供输入指导
错误提示：使用 errorMessage 显示明确的错误信息

常见问题

Q1: 如何禁用自动调整高度？

A: 设置 autoHeight: false 并指定 inputHeight：

TextArea({
  value: $content,
  autoHeight: false,
  inputHeight: 200
})

Q2: 如何设置最大长度？

A: 使用 maxLength 属性：

TextArea({
  value: $content,
  maxLength: 500  // 最多500个字符
})

Q3: 如何显示字数统计？

A: 设置 showCount: true：

TextArea({
  value: $content,
  showCount: true
})

Q4: 如何控制自动调整的行数范围？

A: 使用 minRows 和 maxRows 属性：

TextArea({
  value: $content,
  autoHeight: true,
  minRows: 3,  // 最小3行
  maxRows: 10  // 最大10行
})

Q5: 如何设置输入框宽度？

A: 使用 inputWidth 属性：

TextArea({
  value: $content,
  inputWidth: 600  // 固定宽度
})

TextArea({
  value: $content,
  inputWidth: '100%'  // 百分比宽度
})

Q6: 如何设置固定高度？

A: 设置 autoHeight: false 并指定 inputHeight：

TextArea({
  value: $content,
  autoHeight: false,
  inputHeight: 200  // 固定高度200vp
})

Q7: 字数统计如何显示？

A: 字数统计显示在标签右侧：

无长度限制：显示 字符数
有长度限制：显示 当前数/最大数，超出时变红

总结

TextArea 是控件库中的多行文本输入组件，具有以下核心特性：

多行输入：支持多行文本输入，自动换行
字数统计：支持显示字数统计，实时反馈
自动调整高度：支持根据内容自动调整高度
行数控制：支持设置最小和最大行数
长度限制：支持最大长度限制
易于使用：简单的 API，开箱即用
主题配置：所有样式都可通过代码配置
品牌标识：自动包含品牌标识，保持视觉统一

关键要点

✅ 使用 $variableName 创建双向绑定
✅ 使用 showCount 显示字数统计
✅ 使用 autoHeight 控制自动调整高度
✅ 使用 minRows 和 maxRows 控制行数范围
✅ 使用 maxLength 设置长度限制
✅ 使用 label 属性添加标签
✅ 使用 hint 或 errorMessage 显示提示
✅ 使用 inputSize 属性选择合适尺寸
✅ 通过 ComponentTheme 自定义全局样式

适用场景

评论输入
内容编辑
详细描述
表单输入

下一篇预告：Label（基础标签）详解

本文档属于《鸿蒙PC UI控件库开发系列文章》第11篇

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

Harmony PC 开发者社区

赋能鸿蒙PC开发者，共建全场景原生生态，共享一次开发多端部署创新价值。

更多推荐

调试工具集：鸿蒙PC上的GDB、LLDB、strace等高级调试技巧

调试鸿蒙PC应用就像是在解决一个复杂的谜题。刚开始，工具不全、文档不多，每一步都很艰难。但当你一点点搭建起调试环境，掌握各种调试技巧后，那种成就感是巨大的。现在，当我再看到"Segmentation fault"时，不再感到恐慌。我知道我有GDB可以分析崩溃，有strace可以追踪调用，有各种工具可以帮助我找到问题的根源。调试不仅是修复bug的过程，更是深入理解系统如何工作的机会。每一次调试，都让

Harmony PC 开发者社区

鸿蒙PC应用开发深度实战：一次开发、多端适配的沉浸式音乐播放器迁移实践

Harmony PC 开发者社区

【鸿蒙PC桌面端开发】使用ArkTS做出RGB 色环选择器

随着开源鸿蒙（OpenHarmony）在桌面端（PC）的全面发力，开发者们面临着从移动端“小屏交互”到桌面端“大屏精准操作”的范式转变。在 PC 办公、设计类软件中，颜色选择器（Color Picker）是一个极其基础但又极具挑战性的组件。传统的列表选择或简单的网格选色已无法满足专业设计需求。直观的几何交互：通过色环（Color Wheel）映射色相（Hue）与饱和度（Saturation）。多维