HarmonyOS6 ArkTS TextArea组件使用文档

完整代码

@Entry @Component struct TextAreaFullDemo { @State inputText: string = ''; controller: TextAreaController = new TextAreaController(); build() { Column({ space: 20 }) { Text("TextArea 完整功能演示") .fontSize(22) .fontWeight(FontWeight.Bold) .margin({ top: 30 }); // 多行输入框 TextArea({ text: this.inputText, placeholder: "请输入内容，支持多行、自动换行、字数限制...", controller: this.controller }) // 提示文字样式 .placeholderColor("#999999") .placeholderFont({ size: 16, weight: FontWeight.Normal }) // 输入文字样式 .fontSize(16) .fontColor("#333333") .fontWeight(FontWeight.Normal) // 光标颜色 .caretColor("#007DFF") // 对齐方式 .textAlign(TextAlign.Start) // 最大输入字符数 .maxLength(100) // 显示计数器 .showCounter(true, { thresholdPercentage: 80, highlightBorder: true }) // 最大行数，超出滚动 .maxLines(5) // 超长省略 .textOverflow(TextOverflow.Ellipsis) // 输入过滤：仅允许字母、数字、中文 .inputFilter('[a-zA-Z0-9\u4e00-\u9fa5\s]*', (invalid) => { console.info("过滤非法字符：", invalid); }) // 复制/剪切/粘贴 监听 .onCopy((value) => console.info("复制内容：", value)) .onCut((value) => console.info("剪切内容：", value)) .onPaste((value) => console.info("粘贴内容：", value)) // 内容变化监听 .onChange((value) => { this.inputText = value; }) // 编辑状态变化 .onEditChange((isEditing) => { console.info("是否正在编辑：", isEditing); }) // 文本选中变化 .onTextSelectionChange((start, end) => { console.info("选中范围：", start, "-", end); }) // 基础样式 .width("90%") .height(180) .backgroundColor("#f8f8f8") .border({ width: 1, color: "#e0e0e0" }) .borderRadius(12) .padding(15) // 实时显示输入内容 Text(`已输入：${this.inputText.length}/100 字`) .fontSize(14) .fontColor("#666") .width("90%") .textAlign(TextAlign.Start) } .width('100%') .backgroundColor('#FFFFFF') .padding({ bottom: 40 }) } }

运行效果如图：

核心基础配置

1. 组件初始化参数

TextArea通过构造函数传入核心初始化参数，实现初始值绑定、占位符提示和控制器关联，是组件使用的基础，参数说明如下：

2. 控制器创建

通过TextAreaController创建组件控制器，为输入框提供高级操作能力，创建方式简单，直接实例化即可：

controller: TextAreaController = new TextAreaController();

官方扩展能力：可通过控制器调用caretPosition()设置光标位置、setTextSelection(start, end)选中指定文本、stopEditing()关闭编辑状态。

样式自定义配置

1. 占位符样式定制

针对输入框为空时的提示文本，通过placeholderColor和placeholderFont实现颜色、字号、粗细的定制，让占位符与整体界面风格统一：

2. 输入文字样式定制

对用户输入的文本进行样式配置，支持字号、颜色、粗细的自定义，与占位符样式配合，保证文本展示的可读性：

3. 光标与对齐样式

定制输入光标颜色和文本对齐方式，适配不同的界面布局和交互需求：

4. 基础布局样式

继承鸿蒙通用布局样式，实现输入框宽高、背景、边框、圆角、内边距的定制，让输入框融入整体界面设计，属性说明如下：

输入与显示控制

1. 字数限制与计数器

通过maxLength和showCounter组合，实现最大输入字符数限制和实时字数统计，并支持阈值提醒和超限样式高亮，是表单输入场景的高频能力：

2. 显示行数与超长处理

控制输入框的最大显示行数，超出后自动滚动，并对超长文本进行省略处理，保证输入框布局稳定，不超出界面范围：

3. 输入过滤

通过inputFilter实现正则表达式过滤非法字符，只允许符合规则的字符输入，同时可监听过滤的非法字符，适用于手机号、账号、密码等有输入规则的场景：

.inputFilter('[a-zA-Z0-9\u4e00-\u9fa5\s]*', (invalid) => { console.info("过滤非法字符：", invalid); })

全量事件监听

TextArea提供丰富的事件回调，覆盖内容变化、编辑状态、文本选中、剪贴板操作等全场景，满足各类交互需求，核心事件说明如下：

1. 内容变化事件

.onChange((value) => { this.inputText = value; })

• 触发时机：输入框内容发生任何变化时（键盘输入、粘贴、剪切等）
• 回调参数：value为当前输入框的完整文本内容
• 核心作用：实现输入内容与响应式变量的双向绑定，变量更新同步至其他关联组件

2. 编辑状态事件

.onEditChange((isEditing) => { console.info("是否正在编辑：", isEditing); })

• 触发时机：输入框进入编辑态（获取焦点）或退出编辑态（失去焦点）时
• 回调参数：isEditing为布尔值，true表示正在编辑，false表示退出编辑
• 适用场景：根据编辑状态调整界面样式、触发数据验证等

3. 文本选中事件

.onTextSelectionChange((start, end) => { console.info("选中范围：", start, "-", end); })

• 触发时机：用户在输入框中选中部分文本时
• 回调参数：start为选中文本的起始索引，end为选中文本的结束索引
• 适用场景：实现选中文本的复制、剪切、替换等自定义操作

4. 剪贴板操作事件

覆盖复制、剪切、粘贴三大剪贴板操作，可监听操作的文本内容，实现自定义剪贴板逻辑：

// 复制事件：用户复制选中文本时触发 .onCopy((value) => console.info("复制内容：", value)) // 剪切事件：用户剪切选中文本时触发 .onCut((value) => console.info("剪切内容：", value)) // 粘贴事件：用户向输入框粘贴文本时触发 .onPaste((value) => console.info("粘贴内容：", value))

• 回调参数：value为当前操作的文本内容
• 适用场景：剪贴板内容校验、日志记录、自定义粘贴格式处理等

组件运行效果

1. 初始加载：输入框显示浅灰色占位符文本，无输入内容，右下角显示0/100字数计数器，整体为浅灰色背景、圆角边框样式；
2. 输入操作：点击输入框获取焦点，显示蓝色光标，可输入字母、数字、中文和空格，非法字符被自动过滤，计数器实时更新；
3. 阈值提醒：输入字符数达到80（80%阈值）时，计数器样式变化，提醒即将超限；
4. 超限限制：输入字符数达到100时，禁止继续输入，输入框边框高亮，计数器显示100/100；
5. 行数控制：输入内容超过5行时，输入框出现滚动条，可上下滑动查看全部内容，输入框高度保持不变；
6. 交互操作：支持选中文本进行复制、剪切、粘贴，相关操作日志实时打印；输入框失去焦点时，退出编辑态，控制台打印编辑状态变化；
7. 关联展示：输入框下方的文本组件实时显示当前输入字符数，与输入框计数器保持同步。

官方API扩展属性

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力