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

红目香薰

发布于 2025-12-16 17:06:00

1960

文章被收录于专栏：CSDNToQQCodeCSDNToQQCode

演示视频地址：

https://www.bilibili.com/video/BV1jomdBBE4H/

📋 目录

概述
特性
快速开始
API 参考
使用示例
主题配置
最佳实践
常见问题
总结

概述

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篇

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2025-12-14，如有侵权请联系 cloudcommunity@tencent.com 删除

配置

textarea

表单

基础

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度