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

演示视频地址：

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

📋 目录

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

---

概述

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

设计理念

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

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

适用场景

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

---

特性

✨ 核心特性

• ✅多行输入：支持多行文本输入，自动换行
• ✅字数统计：支持显示字数统计（可选）
• ✅自动调整高度：支持根据内容自动调整高度
• ✅行数控制：支持设置最小和最大行数
• ✅长度限制：支持最大长度限制
• ✅标签和提示：支持标签、提示文本、错误提示
• ✅多种尺寸：支持 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. 尺寸选择

推荐：根据使用场景选择尺寸

• small：用于紧凑空间、简短输入
• medium：默认尺寸，适用于大多数场景
• large：用于重要内容或大屏幕显示

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 是控件库中的多行文本输入组件，具有以下核心特性：

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

关键要点

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

适用场景

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

---

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

---

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