鸿蒙新特性——TextArea 多行文本输入组件详解

雨季666

33人浏览 · 2026-06-27 16:13:38

雨季666 · 2026-06-27 16:13:38 发布

一、引言

文本输入是移动端应用最基础的用户交互方式之一。ArkUI 提供了两种文本输入组件：TextInput 用于单行输入（用户名、密码、邮箱、手机号等），TextArea 用于多行文本输入（笔记编辑、评论回复、意见反馈、个人简介等）。两者的 API 设计高度一致，但在交互行为和适用场景上有本质区别。

TextInput 适合简短的、格式固定的单行文本，而 TextArea 则专为大段文本设计——它支持自动扩展高度以适应内容增长、字符计数辅助用户控制长度、placeholder 在空状态提供指引，并且高度可配置（固定高度或自适应高度）。在需要用户输入多行文字的任何场景中，TextArea 都是首选方案。

本文通过一个备忘录笔记 Demo 深入讲解 TextArea 组件的核心用法：如何实现自适应高度？如何配置字符计数？placeholder 如何定制？以及如何与分类标签、笔记列表联动，构建一个完整的备忘录管理功能。

阅读完本文，你将能够：

理解 TextArea 与 TextInput 的区别和各自适用场景
使用 maxLength + showCounter 实现字符计数
使用 auto 高度实现自适应扩展
配置 placeholderColor 和 placeholderFont 定制占位提示
构建基于 TextArea 的笔记编辑与管理系统

二、TextArea 组件 API 总览

2.1 构造函数

TextArea(options?: TextAreaOptions)

interface TextAreaOptions {
  placeholder?: ResourceStr;    // 占位提示文本
  text?: ResourceStr;           // 绑定的文本内容
  controller?: TextAreaController; // 控制器
}

参数	类型	默认值	说明
`placeholder`	ResourceStr	-	无内容时显示的占位提示文字
`text`	ResourceStr	-	输入框的文本内容，支持双向绑定
`controller`	TextAreaController	-	控制器实例，用于程序化控制（聚焦、光标位置等）

2.2 核心链式方法

// 最大字符数限制
.maxLength(value: number): TextAreaAttribute

// 显示字符计数器
.showCounter(value: boolean, threshold?: number): TextAreaAttribute

// 占位文本颜色
.placeholderColor(value: ResourceColor): TextAreaAttribute

// 占位文本字体
.placeholderFont(value: Font): TextAreaAttribute

// 光标颜色
.caretColor(value: ResourceColor): TextAreaAttribute

// 输入变化回调
.onChange(callback: Callback<string>): TextAreaAttribute

// 键盘提交回调
.onSubmit(callback: Callback<SubmitEvent>): TextAreaAttribute

// 编辑状态变化回调
.onEditChange(callback: Callback<boolean>): TextAreaAttribute

方法	说明
`maxLength(number)`	最大输入字符数，超出后无法继续输入
`showCounter(boolean, threshold?)`	是否显示字符计数器（如 “45/500”），threshold 为开始显示的阈值
`placeholderColor(ResourceColor)`	占位文本的颜色
`placeholderFont(Font)`	占位文本的字体样式（大小、粗细等）
`caretColor(ResourceColor)`	输入光标的颜色
`onChange(Callback<string>)`	文本内容变化时的回调，参数为当前全文
`onSubmit(Callback<SubmitEvent>)`	键盘回车键提交时的回调
`onEditChange(Callback<boolean>)`	编辑状态变化回调（获焦/失焦）

2.3 TextArea vs TextInput

特性	TextArea	TextInput
输入行数	多行	单行
自动换行	支持	不支持
高度自适应	支持（`height: 'auto'`）	固定高度
字符计数	maxLength + showCounter	maxLength + showCounter
InputType	不支持（无密码/邮箱等类型）	支持 10+ 类型
showPasswordIcon	不支持	支持
典型场景	笔记、评论、反馈、简介	用户名、密码、邮箱、手机
键盘按钮	回车（换行）/ 完成	完成/搜索/发送/下一项

关键区别：TextArea 支持多行输入和自动换行，适合大段文本；TextInput 支持多种输入类型（Normal/Password/Email/Number 等）和密码可见性切换，适合格式化输入。

2.4 TextArea 与其他多行输入方案的对比

特性	TextArea	RichTextEditor	自建 Scroll+Text
多行输入	✓	✓	✗（只读）
rich text	✗	✓	✓
字符计数	✓ 内置	需手动	需手动
自适应高度	✓ `height: 'auto'`	✓	需手动计算
placeholder	✓	✗	✗
学习成本	低	高	中

TextArea 是纯文本多行输入的最佳选择，轻量且 API 直观。如果需要富文本编辑（加粗、颜色、图片等），则需要使用 RichTextEditor。
在这里插入图片描述

三、Demo 设计：备忘录笔记

3.1 功能概述

Demo 是一个备忘录笔记页面，模拟笔记应用的编辑管理流程：

多行笔记输入：TextArea 支持大段文本输入，placeholder 给出操作指引
字符计数：实时显示当前字符数/最大限制（如 123/500）
自适应高度：TextArea 随内容自动扩展，也可切换为固定高度模式
分类标签：四个预设分类（工作/个人/想法/待办），不同颜色标识
保存笔记：点击按钮保存，内容为空时按钮置灰
笔记列表：显示所有已保存的笔记，含分类标签、内容预览和时间戳
删除笔记：列表中每条笔记可删除
配置面板：动态调整自适应高度开关和最大字符数（100-2000）

3.2 交互点

#	交互	说明
1	TextArea 多行输入	输入大段文本，自动换行，placeholder 引导，实时字符计数
2	分类标签选择	四个分类标签点击切换，高亮选中 + 颜色区分
3	配置面板	自适应高度 Toggle + 最大字符数加减（步长 100）
4	保存笔记	保存到列表，显示分类/预览/时间，空内容时按钮禁用
5	删除笔记	从列表中移除指定笔记

四、完整代码实现

4.1 数据模型定义

interface NoteItem {
  id: number;
  content: string;
  category: string;
  timestamp: string;
}

NoteItem 包含唯一 ID、笔记正文、分类名称和存储时间戳。使用接口定义确保类型安全，这是 ArkTS 中 ForEach 遍历对象数组的标准做法。

4.2 状态变量

@State noteText: string = '';
@State notes: NoteItem[] = [];
@State nextId: number = 1;
@State autoExpand: boolean = true;
@State selectedCategory: string = '工作';
@State maxLength: number = 500;

private categories: string[] = ['工作', '个人', '想法', '待办'];

关键状态说明：

noteText：TextArea 绑定的文本内容，用户每输入一个字都会更新
notes：已保存的笔记列表，@State 确保增删操作触发 UI 刷新
autoExpand：控制 TextArea 高度模式，true 为自适应（'auto'），false 为固定高度（160vp）
selectedCategory：当前选中的笔记分类
maxLength：最大输入字符数，可由用户通过加减按钮调整（100-2000，步长 100）

4.3 TextArea 核心配置

TextArea({ placeholder: '写下你的想法...', text: this.noteText })
  .placeholderColor('#BBBBCC')
  .placeholderFont({ size: 14 })
  .maxLength(this.maxLength)
  .showCounter(true)
  .height(this.autoExpand ? 'auto' : 160)
  .fontSize(15)
  .fontColor('#1a1a2e')
  .caretColor('#1677FF')
  .backgroundColor('#F8F9FA')
  .borderRadius(10)
  .padding(14)
  .onChange((value: string) => {
    this.noteText = value;
  })

逐行解析：

placeholder: '写下你的想法...'：TextArea 为空时显示的引导文案，提示用户输入内容
text: this.noteText：与 @State 变量双向绑定。当用户输入时触发 onChange 更新 noteText；当 saveNote() 方法清空 noteText 时，TextArea 也同步清空
.placeholderColor('#BBBBCC')：占位文字的颜色，通常使用浅灰与正文区分
.placeholderFont({ size: 14 })：占位文字的字体配置，可以是对象（含 size/weight/style/family）或直接用 number 表示字号
.maxLength(this.maxLength)：最大输入字符数。超出后用户无法继续输入（键盘输入不生效），保证数据长度可控
.showCounter(true)：在 TextArea 右下角显示字符计数器（如 “123/500”）。注意：计数器显示的是「已输入/上限」而非实时倒计数
.height(this.autoExpand ? 'auto' : 160)：核心交互——'auto' 让 TextArea 随内容自动扩展高度，内容越多高度越大；固定数值（如 160vp）则限制为固定高度，超出后内部滚动
.caretColor('#1677FF')：输入光标的颜色，用于匹配品牌色
.onChange(value: string)：每次文本内容变化时触发，value 参数是当前全文内容。注意与 TextInput 的 onChange 不同，TextArea 的参数是 string 而非事件对象

4.4 分类标签选择器

private categories: string[] = ['工作', '个人', '想法', '待办'];

private getCategoryColor(cat: string): string {
  if (cat === '工作') return '#1677FF';
  if (cat === '个人') return '#52C41A';
  if (cat === '想法') return '#FF9800';
  if (cat === '待办') return '#FF4D4F';
  return '#9999AA';
}

// UI 渲染
Row() {
  Text('分类')
    .fontSize(12)
    .fontColor('#9999AA')
    .margin({ right: 8 })

  ForEach(this.categories, (cat: string) => {
    Text(cat)
      .fontSize(12)
      .fontColor(this.selectedCategory === cat ? '#FFFFFF' : this.getCategoryColor(cat))
      .fontWeight(this.selectedCategory === cat ? FontWeight.Bold : FontWeight.Normal)
      .padding({ top: 4, bottom: 4, left: 12, right: 12 })
      .borderRadius(12)
      .backgroundColor(this.selectedCategory === cat ? this.getCategoryColor(cat) : '#F2F3F5')
      .margin({ right: 6 })
      .onClick(() => { this.selectedCategory = cat; })
  })
}

分类标签的设计要点：

选中态：背景色为分类色（蓝/绿/橙/红），文字白色加粗
未选中态：背景浅灰（#F2F3F5），文字为对应的分类色
颜色语义：蓝色=工作，绿色=个人，橙色=想法，红色=待办——每种颜色传达不同的心理暗示
点击切换：onClick 中直接设置 this.selectedCategory = cat，触发 UI 重新渲染所有标签

4.5 保存笔记

saveNote() {
  if (this.noteText.trim().length === 0) return;
  const now = new Date();
  const ts = `${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}`;
  this.notes = this.notes.concat([{
    id: this.nextId,
    content: this.noteText.trim(),
    category: this.selectedCategory,
    timestamp: ts
  }]);
  this.nextId++;
  this.noteText = '';
}

步骤解析：

空内容校验：trim() 去除首尾空格后判断，纯空格内容不允许保存
时间戳生成：使用 Date() 获取当前时分，padStart(2, '0') 确保两位数（如 “09:05” 而非 “9:5”）
数组追加：使用 concat()（而非被 ArkTS 禁止的展开运算符 ...）创建新数组，追加新笔记到末尾，新笔记显示在列表最上方
ID 递增：nextId++ 为每条笔记分配唯一 ID
清空输入：this.noteText = '' 清空 TextArea，与 text 参数的双向绑定自动同步

4.6 删除笔记

deleteNote(id: number) {
  this.notes = this.notes.filter(n => n.id !== id);
}

使用 filter() 过滤掉指定 ID 的笔记，返回新数组。@State 检测到数组引用变化后自动触发 UI 刷新。

4.7 笔记列表渲染

if (this.notes.length > 0) {
  Column() {
    Row() {
      Text('笔记列表')
        .fontSize(12).fontColor('#9999AA')
        .fontWeight(FontWeight.Bold).layoutWeight(1)
      Text(`${this.notes.length} 条笔记`)
        .fontSize(11).fontColor('#9999AA')
    }

    Column() {
      ForEach(this.notes, (note: NoteItem, idx: number) => {
        Column() {
          // 分类标签
          Row() {
            Text(note.category)
              .fontSize(10)
              .fontColor('#FFFFFF')
              .fontWeight(FontWeight.Bold)
              .padding({ top: 2, bottom: 2, left: 8, right: 8 })
              .borderRadius(8)
              .backgroundColor(this.getCategoryColor(note.category))
              .margin({ bottom: 6 })
          }

          // 笔记正文预览
          Text(note.content)
            .fontSize(14)
            .fontColor('#1a1a2e')
            .lineHeight(20)
            .maxLines(3)
            .textOverflow({ overflow: TextOverflow.Ellipsis })
            .width('100%')
            .margin({ bottom: 8 })

          // 底部：时间戳 + 删除按钮
          Row() {
            Text(note.timestamp)
              .fontSize(11)
              .fontColor('#BBBBCC')
              .fontFamily('monospace')
              .layoutWeight(1)

            Text('删除')
              .fontSize(12)
              .fontColor('#FF4D4F')
              .onClick(() => { this.deleteNote(note.id); })
          }
          .width('100%')
        }
        .width('100%')
        .padding({ top: 14, bottom: 14, left: 4, right: 4 })

        if (idx < this.notes.length - 1) {
          Divider().strokeWidth(0.5).color('#F2F3F5')
        }
      })
    }
  }
}

笔记卡片的三层结构：

分类标签：彩色小圆角标签，文字白色，背景色与分类对应
正文预览：最多显示 3 行（maxLines(3)），超出用省略号（TextOverflow.Ellipsis），lineHeight(20) 控制行距
底部行：左侧 monospace 时间戳（如 “14:35”），右侧红色"删除"文字按钮

相邻笔记之间用 Divider 分隔，最后一条笔记不显示分隔线。

4.8 配置面板

Column() {
  Text('输入配置')
    .fontSize(12).fontColor('#9999AA')
    .fontWeight(FontWeight.Bold)

  Column() {
    // 自适应高度开关
    Row() {
      Text('自适应高度')
        .fontSize(14).fontColor('#1a1a2e')
        .fontWeight(FontWeight.Medium).layoutWeight(1)
      Toggle({ type: ToggleType.Switch, isOn: this.autoExpand })
        .selectedColor('#1677FF')
        .onChange((value: boolean) => { this.autoExpand = value; })
    }

    Divider().strokeWidth(0.5).color('#F2F3F5')

    // 最大字符数调节
    Row() {
      Text('最大字符数')
        .fontSize(14).fontColor('#1a1a2e')
        .fontWeight(FontWeight.Medium).layoutWeight(1)
      Row() {
        Text('-')
          .onClick(() => { if (this.maxLength > 100) this.maxLength -= 100; })
        Text(this.maxLength.toString())
          .fontFamily('monospace')
        Text('+')
          .onClick(() => { if (this.maxLength < 2000) this.maxLength += 100; })
      }
    }
  }
}

配置面板提供两个可调参数：

自适应高度 Toggle：切换 autoExpand 状态，直接改变 TextArea 的 .height() 参数（'auto' vs 160）
最大字符数加减：步长 100，范围 100-2000。点击 - 减少，点击 + 增加，边界处操作无效。当前值用 monospace 字体居中显示

4.9 getPreview 工具方法

getPreview(content: string): string {
  return content.length > 40 ? content.substring(0, 40) + '...' : content;
}

虽然当前实现中笔记列表直接显示正文前 3 行（通过 maxLines(3)），但 getPreview 可作为数据层的截断方法，用于在非 UI 场景（如通知栏预览、搜索结果摘要）中生成简短预览文本。
在这里插入图片描述

五、关键技术点详解

5.1 自适应高度的工作原理

TextArea 的自适应高度是通过 .height('auto') 实现的。当 TextArea 内容超出当前高度时，组件会自动扩展高度以容纳全部内容：

// 自适应高度：内容越多，TextArea 越高
TextArea({ placeholder: '写下你的想法...', text: this.noteText })
  .height('auto')

// 固定高度：内容超出后内部滚动
TextArea({ placeholder: '写下你的想法...', text: this.noteText })
  .height(160)

自适应模式适合需要看到全部输入内容的场景（如笔记编辑），固定高度模式适合需要保持页面布局稳定的场景（如评论框）。

内部实现：TextArea 使用 CSS 的 min-height + height: auto 策略，初始高度由内容量决定（至少一行），当内容行数增加时，高度随之增长。如果设置了 maxHeight，高度增长到 maxHeight 后停止，超出部分内部滚动。

5.2 字符计数器的阈值控制

.showCounter(true) 始终显示计数器。如果需要只在接近上限时显示计数器，可以传入 threshold 参数：

// 剩余 50 字符以内时才显示计数器
TextArea({ placeholder: '输入内容', text: this.noteText })
  .maxLength(500)
  .showCounter(true, 50)

threshold 的逻辑是：当 maxLength - currentLength <= threshold 时才显示计数器。例如 maxLength=500, threshold=50，当前长度 ≤ 450 时不显示，超过 450 后显示 “451/500”。

5.3 onChange 回调的性能考量

TextArea 的 onChange 在每次文本内容变化时触发，包括增删改每个字符。对于简单的状态同步场景（this.noteText = value）性能影响可忽略。但如果回调中涉及复杂计算（如实时保存到数据库、联网同步），需要做防抖处理：

// 防抖思路（伪代码，ArkTS 中可用 setTimeout 实现）
private debounceTimer: number = -1;

.onChange((value: string) => {
  this.noteText = value;
  // 取消上次延迟任务
  clearTimeout(this.debounceTimer);
  // 300ms 后执行保存
  this.debounceTimer = setTimeout(() => {
    this.autoSave(value);
  }, 300);
})

在本 Demo 中，onChange 仅做状态赋值，无需防抖。

5.4 双向绑定的清空机制

TextArea 的 text 参数与 @State 变量之间是单向数据流（ArkUI 是声明式框架，不提供传统意义的双向绑定）。当代码中设置 this.noteText = '' 时，ArkUI 检测到状态变化，重新渲染 TextArea 并传入新的 text 值，TextArea 随之显示清空。

这与 React 的受控组件（controlled component）模式一致——数据状态是唯一的数据源，UI 是状态的投影。

5.5 caretColor 的 UX 价值

.caretColor() 设置输入光标的颜色。虽然看似小细节，但在品牌化应用中极其重要：

// 默认光标（系统蓝）
TextArea({ placeholder: '输入', text: this.text })

// 品牌色光标
TextArea({ placeholder: '输入', text: this.text })
  .caretColor('#1677FF')

光标颜色应与应用主色调一致，保持视觉协调。同时确保光标在深色和浅色背景上都可见——在浅色背景上使用深色光标，深色背景上使用浅色光标。

5.6 EnterKeyType 控制键盘按钮

TextArea 的 .enterKeyType() 方法控制在软键盘上显示的回车键类型：

enum EnterKeyType {
  NEW_LINE,  // 换行（默认）
  DONE,      // 完成
  SEARCH,    // 搜索
  SEND,      // 发送
  GO,        // 前往
  NEXT,      // 下一个
  PREVIOUS   // 上一个
}

TextArea 默认使用 NEW_LINE（回车键=换行），这一点与 TextInput 不同（TextInput 默认回车键是确认/完成）。如果需要 TextArea 在回车时提交而非换行，设置 EnterKeyType.DONE 并在 onSubmit 中处理：

TextArea({ placeholder: '输入', text: this.text })
  .enterKeyType(EnterKeyType.DONE)
  .onSubmit((event: SubmitEvent) => {
    this.saveNote();
  })

六、运行效果

6.1 初始状态

页面顶部显示标题栏"备忘录"，下方是组件介绍卡片。紧接着是 TextArea 编辑器区，placeholder 显示"写下你的想法…“，字符计数器显示"0/500”。分类标签栏默认选中"工作"（蓝色高亮）。保存按钮因内容为空呈现置灰状态。下方显示空状态提示"还没有笔记"。

6.2 输入笔记并保存

在 TextArea 中输入笔记内容，字符计数器实时更新（如 “45/500”）。点击分类标签切换分类（如"想法"），标签变为橙色高亮。保存按钮变为蓝色可点击态。点击"保存笔记"，笔记列表出现第一条笔记，显示"想法"分类标签、正文内容和保存时间（如 “14:35”）。TextArea 自动清空，等待下一条输入。

6.3 配置面板交互

切换到"输入配置"卡片。关闭"自适应高度" Toggle，TextArea 变为固定 160vp 高度，内容超出后内部滚动。点击"最大字符数"的 + 按钮，数值变为 600、700……最长可调至 2000；点击 - 按钮减少，最低减至 100。

6.4 多条笔记管理

连续添加多条笔记，列表头部显示"X 条笔记"计数。每条笔记显示对应的分类标签颜色和正文内容。点击某条笔记的"删除"按钮，该笔记从列表中移除，计数自动更新。

七、最佳实践与注意事项

7.1 何时使用 TextArea

笔记/备忘录编辑：需要输入大段文字，自适应高度展示全部内容
评论/回复输入：多行评论框，固定高度+内部滚动保持布局稳定
意见反馈/表单：用户描述问题或建议，需要更多空间
个人简介/签名编辑：多行展示，通常配合 maxLength 限制长度
消息编辑：聊天应用中的多行消息输入（配合 EnterKeyType.SEND）

7.2 何时使用 TextInput 替代 TextArea

用户名、密码、邮箱、手机号等格式化输入
需要密码可见性切换（showPasswordIcon）
需要特定键盘类型（number、email、URL 等）
内容长度较短、不适合换行的场景

7.3 常见问题

Q: TextArea 可以和 TextInput 一样设置 InputType 吗？

A: 不可以。TextArea 不支持 InputType，它是纯文本多行输入。如果需要"多行密码输入"或"多行数字输入"，需要在 onChange 回调中自行过滤和校验。

Q: 如何同时展示 TextArea 和软键盘？

A: TextArea 获焦时自动拉起软键盘。如果页面有 TextArea 和其他内容，建议将 TextArea 放在页面上半部分或使用 scrollTo 确保聚焦后 TextArea 不被键盘遮挡。

Q: showCounter 的字符计数支持中文吗？

A: 支持。maxLength 和 showCounter 按 Unicode 字符计数，中文、英文、数字、emoji 均按 1 个字符计算。一个中文字 = 1 个字符，一个 emoji = 1 个字符（而非 UTF-16 的 2 个码点）。

Q: TextArea 可以设置最小行数和最大行数吗？

A: 可以通过 .height() 设置固定高度控制行数，或使用 'auto' 实现完全自适应。ArkUI 不直接提供"最小 X 行、最大 Y 行"的语义化 API，需要通过 minHeight/maxHeight 通用属性间接实现。

7.4 安全意识

TextArea 的输入内容可能包含换行符（\n）、特殊字符等，存储和展示时需要注意：
- 存储到数据库时做参数化查询，防止 SQL 注入
- 展示到 WebView 时做 HTML 转义，防止 XSS
- 作为 URL 参数时做 URL 编码
敏感信息（如身份证号、银行卡号）不应在 TextArea 中明文输入和存储

八、拓展思考

8.1 从备忘录到富文本编辑器

本 Demo 的备忘录是纯文本的。如果升级为支持富文本（加粗、斜体、不同颜色、图片插入），需要将 TextArea 替换为 RichTextEditor 组件。RichTextEditor 提供完整的富文本编辑能力，但 API 复杂度高很多：

// RichTextEditor 替代（概念示意）
RichTextEditor({
  controller: this.richTextController
})
  .onReady(() => { /* 编辑器就绪 */ })
  .onSelectionChange((range: TextRange) => { /* 选区变化 */ })