鸿蒙应用开发UI基础第十五节：文本输入组件核心讲解与示例演示

【学习目标】

一、文本输入类组件核心认知

（一）组件整体定位

TextInput、TextArea、Search是鸿蒙ArkTS核心文本输入类组件，基于统一输入底层能力封装，支持通用样式与高频事件；针对单行短文本、多行长文本、搜索专属三大场景做差异化优化，是移动端应用开发必备基础组件。

（二）核心选型原则与组件差异

核心原则：按输入形态和业务场景选型，禁止跨场景混用。三者核心差异、专属优势与适配场景如下：

（三）核心绑定规范与组件接口

各组件对应专属构造函数，彼此独立不通用，核心接口与绑定规则如下：

说明：ResourceStr为联合类型（Resource | string），支持直接传入字符串或通过$r引用系统/应用资源。

二、核心能力

（一）通用事件

TextInput、TextArea、Search事件触发逻辑统一，仅onSubmit回调参数存在组件差异，其余事件参数完全一致：

时序说明：onWillChange执行时序晚于onWillInsert/onWillDelete，早于onDidInsert/onDidDelete。

（二）输入内容过滤

三大组件支持统一过滤方案，Search仅需将text绑定替换为value，过滤逻辑可直接复用：

• inputFilter：原生正则过滤，轻量高效，适用于基础字符级规则；
• onWillChange：内容变更前拦截，支持自定义逻辑，适用于位置、字节、自动修正等复杂场景。

1. inputFilter 原生正则过滤

仅需编写允许的字符集，无需添加^$首尾限定符，非法字符直接拦截：

// 仅允许字母/数字（账号/验证码场景）
TextInput({ text: this.content, placeholder: '请输入字母/数字' })
.inputFilter('[0-9A-Za-z]', (filtered) => {
console.log('过滤的非法内容：', filtered);
})

2. onWillChange 自定义逻辑过滤

仅支持返回boolean类型（true允许本次内容变更，false拦截变更，界面不更新），如需实现内容自动修正，需手动更新绑定的状态变量并返回false拦截原始输入，覆盖复杂业务规则：

// 首位禁止输入空格
TextInput({ text: this.inputText, placeholder: '首位无空格' })
.onWillChange((changeInfo:EditableTextChangeValue)=>{
return changeInfo.content.trimStart() !== "";
})

3. 组合过滤（生产高频用法）

inputFilter做底层字符限制 + onWillChange做业务规则校验，兼顾性能与需求：

// 账号规则：仅字母/数字 + 首位不能为数字
TextInput({ text: this.account, placeholder: '字母开头，字母/数字组合' })
.inputFilter('[0-9A-Za-z]')
.onWillChange((newValue) => {
return newValue.content.replace(/^[0-9]/, '') !== "";
});

（三）组件控制器

所有控制器继承自TextContentControllerBase，必须与组件一对一绑定，禁止跨组件混用，用于光标、选框、编辑状态精细控制。

1. 控制器-组件对应关系

2. 通用核心方法

3. 控制器基础使用方法

private inputController = new TextInputController();
// 光标移至文本开头
this.inputController.caretPosition(0);
// 选中0~6位字符
this.inputController.setTextSelection(0, 6);
// 主动退出编辑状态
this.inputController.stopEditing();

（四）全局焦点控制

焦点控制为页面级能力，与组件控制器解耦，是鸿蒙标准焦点管理方案：

1. 核心方法

2. 标准使用代码

// 获取全局焦点控制器
const focusController = this.getUIContext().getFocusController();
// 精准聚焦（组件必须绑定id）
focusController.requestFocus("account_input");
// 全局失焦，收起键盘
focusController.clearFocus();

注意：调用requestFocus前，必须为目标组件设置唯一.id('xxx')，否则聚焦失效。

（五）专属输入模式枚举

强制规范：各组件仅可使用自身专属枚举，严禁跨组件混用。

1. TextInput 专属：InputType

2. TextArea 专属：TextAreaType

3. Search 专属：SearchType

（六）通用回车键类型：EnterKeyType

三大组件通用枚举，自定义软键盘回车按钮样式与语义，触发后均执行onSubmit：

三、各组件专属能力

（一）Search 组件专属能力

基于TextInput封装，聚焦搜索场景，提供原生图标与按钮配置：

（二）TextArea 组件专属能力

聚焦多行长文本，提供排版与高度控制能力：

（三）TextInput 组件专属能力

聚焦单行表单/密码场景，提供表单专属样式与交互：

1. 专属属性

2. 专属事件

四、工程结构

基于鸿蒙6.0 API 20、Stage模型创建InputApplication工程，标准目录结构如下：

InputApplication/
├── AppScope/
│ └── app.json5
├── entry/
│ ├── src/
│ │ ├── main/
│ │ │ ├── ets/
│ │ │ │ ├── entryability/
│ │ │ │ │ └── EntryAbility.ets
│ │ │ │ ├── pages/
│ │ │ │ │ ├── Index.ets // 导航主页面
│ │ │ │ │ ├── InputBasicPage.ets // 示例1：三大组件基础用法
│ │ │ │ │ ├── RegisterFormPage.ets // 示例2：注册表单实战
│ │ │ │ │ └── InputSearchBarPage.ets // 示例3：顶部搜索栏实战
│ │ │ │ │ └── CommentAreaPage.ets // 示例4：评论区实战
│ │ │ ├── resources/
│ │ │ │ └── media/ // 自定义图标：icon_back、search、icon_clear
│ │ │ └── module.json5
│ │ └── build-profile.json5
└── build-profile.json5

五、导航主页面（Index.ets）

import { router } from '@kit.ArkUI';

interface RouterButton {
title: string;
url: string;
}

@Entry
@Component
struct Index {
private buttonList: RouterButton[] = [
{ title: "示例1：三大组件基础用法", url: 'pages/InputBasicPage' },
{ title: "示例2：标准注册表单实战", url: 'pages/RegisterFormPage' },
{ title: "示例3：顶部搜索栏实战", url: 'pages/InputSearchBarPage' },
{ title: "示例4：发布评论实战", url: 'pages/CommentAreaPage' },
];

build() {
Column({ space: 12 }) {
Text("TextInput/TextArea/Search")
.fontSize(30)
.fontWeight(FontWeight.Bold)
.margin({ bottom: 30 });

ForEach(
this.buttonList,
(item: RouterButton) => {
Button(item.title)
.width('85%')
.height(42)
.backgroundColor($r('sys.color.brand'))
.fontColor(Color.White)
.borderRadius(8)
.fontSize(15)
.onClick(() => router.pushUrl({ url: item.url }));
},
(item: RouterButton) => item.url
);
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.backgroundColor('#F5F5F5');
}
}

运行效果

六、示例1：三大组件基础用法（InputBasicPage.ets）

核心掌握点

import { router } from '@kit.ArkUI';

interface RouterButton {
title: string;
url: string;
}

@Entry
@Component
struct Index {
private buttonList: RouterButton[] = [
{ title: "示例1：三大组件基础用法", url: 'pages/InputBasicPage' },
{ title: "示例2：标准注册表单实战", url: 'pages/RegisterFormPage' },
{ title: "示例3：顶部搜索栏实战", url: 'pages/InputSearchBarPage' },
{ title: "示例4：发布评论实战", url: 'pages/CommentAreaPage' },

];

build() {
Column({ space: 12 }) {
Text("TextInput/TextArea/Search")
.fontSize(30)
.fontWeight(FontWeight.Bold)
.margin({ bottom: 30 });

ForEach(
this.buttonList,
(item: RouterButton) => {
Button(item.title)
.width('85%')
.height(42)
.backgroundColor($r('sys.color.brand'))
.fontColor(Color.White)
.borderRadius(8)
.fontSize(15)
.onClick(() => router.pushUrl({ url: item.url }));
},
(item: RouterButton) => item.url
);
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.backgroundColor('#F5F5F5');
}
}

运行效果

七、示例2：标准注册表单实战（RegisterFormPage.ets）

核心掌握点

@Entry
@Component
struct RegisterFormPage {
@State phone: string = '';
@State pwd: string = '';
@State confirmPwd: string = '';
@State phoneError: string = '';
@State pwdError: string = '';
@State confirmPwdError: string = '';
@State isShowPwd: boolean = false;

private phoneController = new TextInputController();
private pwdController = new TextInputController();
private confirmPwdController = new TextInputController();

private showToast(message: string) {
try {
this.getUIContext().getPromptAction().showToast({ message, duration: 2000 });
} catch (error) {}
}

private validateForm(): boolean {
this.phoneError = this.pwdError = this.confirmPwdError = '';
let isPass = true;

if (!/^1[3-9]\\d{9}$/.test(this.phone.trim())) {
this.phoneError = this.phone ? '手机号格式错误' : '请输入手机号';
isPass = false;
}

if (this.pwd.trim().length < 6 || this.pwd.trim().length > 16) {
this.pwdError = this.pwd ? '密码长度为6-16位' : '请设置密码';
isPass = false;
}

if (this.confirmPwd.trim() !== this.pwd.trim()) {
this.confirmPwdError = this.confirmPwd ? '两次密码不一致' : '请确认密码';
isPass = false;
}

return isPass;
}

private submitRegister() {
if (this.validateForm()) {
this.showToast('注册成功');
this.phone = this.pwd = this.confirmPwd = '';
this.isShowPwd = false;
this.getUIContext().getFocusController().clearFocus();
}
}

onPageShow(): void {
try {
setTimeout(() => {
this.getUIContext().getFocusController().requestFocus('phone_id');
}, 200);
} catch (error) {}
}

build() {
Scroll() {
Column({ space: 20 }) {
Text("用户注册")
.fontSize(28)
.fontWeight(FontWeight.Bold)
.margin({ top: 40, bottom: 20 })
.width('100%')
.textAlign(TextAlign.Center);

// 手机号输入
TextInput({
placeholder: '请输入手机号',
controller: this.phoneController,
text: this.phone
})
.inputFilter('[0-9]', (filteredChars) => {
console.log('过滤非数字字符：', filteredChars);
})
.type(InputType.PhoneNumber)
.maxLength(11)
.width('90%')
.showUnderline(true)
.underlineColor({ error: '#FF4D4F' })
.showError(this.phoneError)
.id('phone_id')
.onChange((value) => {
this.phone = value;
this.phoneError = '';
})
.onBlur(() => {
if (this.phone && !/^1[3-9]\\d{9}$/.test(this.phone)) {
this.phoneError = '手机号格式错误';
}
})
.onSubmit(() => {
try {
this.getUIContext().getFocusController().requestFocus('pwd_id');
} catch (error) {}
});

// 密码输入
TextInput({
placeholder: '请设置密码（6-16位）',
controller: this.pwdController,
text: this.pwd
})
.type(InputType.Password)
.maxLength(16)
.width('90%')
.id('pwd_id')
.onWillChange((newValue) => {
return newValue.content.trimStart() !== "";
})
.inputFilter('[a-zA-Z0-9!@#$%^&*]', (filtered) => {
filtered && this.showToast(`禁止输入：${filtered}`);
})

.showPasswordIcon(true)
.showPassword(this.isShowPwd)
.onSecurityStateChange((isShowPassword: boolean) => {
this.isShowPwd = isShowPassword;
})
.onChange((value) => {
this.pwd = value;
this.pwdError = '';
})
.onSubmit(() => {
try {
this.getUIContext().getFocusController().requestFocus('confirm_pwd_id');
} catch (error) {}
});

// 确认密码
TextInput({
placeholder: '请再次输入密码',
controller: this.confirmPwdController,
text: this.confirmPwd
})
.type(InputType.Normal)
.maxLength(16)
.width('90%')
.showUnderline(true)
.underlineColor({ error: '#FF4D4F' })
.showError(this.confirmPwdError)
.id('confirm_pwd_id')
.inputFilter('[a-zA-Z0-9!@#$%^&*]')
.showPasswordIcon(true)
.showPassword(this.isShowPwd)
.onSecurityStateChange((isShowPassword: boolean) => {
this.isShowPwd = isShowPassword;
})
.onChange((value) => {
this.confirmPwd = value;
this.confirmPwdError = '';
})
.onSubmit(() => this.submitRegister());

Row({ space: 8 }) {
Checkbox()
.select(this.isShowPwd)
.selectedColor($r('sys.color.brand'))
.onChange((v) => this.isShowPwd = v);
Text('显示密码').fontSize(14).fontColor('#666666');
}
.width('90%')
.margin({ top: 5 });

Button("立即注册")
.width('90%')
.height(45)
.backgroundColor(
this.phone.trim() && this.pwd.trim() && this.confirmPwd.trim()
? $r('sys.color.brand')
: '#CCCCCC'
)
.fontColor(Color.White)
.enabled(this.phone.trim() && this.pwd.trim() && this.confirmPwd.trim() ? true:false)
.onClick(() => this.submitRegister());
}
.width('100%')
.alignItems(HorizontalAlign.Center);
}
.width('100%')
.onClick(() => this.getUIContext().getFocusController().clearFocus())
.backgroundColor(Color.White);
}
}

运行效果

八、示例3：顶部搜索栏实战（InputSearchBarPage.ets）

核心掌握点

import router from '@ohos.router';

@Entry
@Component
struct InputSearchBarPage {
// 搜索关键词状态
@State searchKey: string = '';
// 联想词列表状态（空数组初始值）
@State suggestList: string[] = [];
// 预设联想词库
private allSuggestWords = [
'ArkTS基础教程',
'鸿蒙组件开发',
'鸿蒙基础入门',
'TextInput用法',
'Search组件实战',
'鸿蒙布局规范',
'ArkUI开发指南'
];

// 基础提示
private showToast(message: string) {
try {
this.getUIContext().getPromptAction().showToast({ message: message });
} catch (error) {
// TODO: Implement error handling.
}
}

build() {
Column({ space: 0 }) {
// 顶部搜索栏布局
Row({ space: 20 }) {

Image($r('app.media.icon_back'))
.width(25)
.height(25)
.objectFit(ImageFit.Contain)
.onClick(()=>{
router.back()
})
// 搜索框（Search专属能力配置）
Search({ placeholder: '搜索本页内容…', value: this.searchKey })
.id('searchInput')
.type(SearchType.NORMAL)
.height(36)
.placeholderFont({ size: 14 })
.enterKeyType(EnterKeyType.Search)
.backgroundColor('#F5F5F5')
.layoutWeight(1)
.constraintSize({maxWidth:375*1.5})
.searchIcon({ color: '#999', size: 18,src:$r('app.media.search')}) // 自定义搜索图标
.cancelButton({
style: CancelButtonStyle.INPUT,
icon: { src: $r('app.media.icon_clear'), size: 16, color: '#666' } // 自定义清除图标
})
.searchButton('搜索', {
fontSize: 15,
fontColor: '#007DFF',
autoDisable: true // 无内容时按钮置灰不可点击
})
// 输入内容变化时，生成联想词
.onChange((value: string) => {
this.searchKey = value;
this.getSearchSuggest(value);
})
// 失去焦点时，延迟清空联想词
.onBlur(() => {
setTimeout(() => {
this.suggestList = [];
}, 200);
})
// 回车/点击搜索按钮提交
.onSubmit((searchContent: string) => {
this.doSearch(searchContent);
this.suggestList = [];
this.getUIContext().getFocusController().clearFocus(); // 搜索完成全局失焦
})
// 粘贴事件：校验粘贴内容格式
.onPaste((value) => {
if (value.length > 50) {
this.showToast('搜索内容不能超过50字');
}
});
}
.width('100%')
.height(60)
.padding({left:15,right:15})
.justifyContent(FlexAlign.SpaceBetween)
.backgroundColor(Color.White);

// 联想词列表
List() {
ForEach(this.suggestList, (item: string) => {
ListItem() {
Text(item)
.fontSize(14)
.fontColor('#333')
.padding({ left: 20, top: 12, bottom: 12 })
.width('100%')
}
.backgroundColor(Color.White)
// 点击联想词：填充+搜索+失焦
.onClick(() => {
this.searchKey = item;
this.doSearch(item);
this.suggestList = [];
this.getUIContext().getFocusController().clearFocus();
});
},
(item: string) => item
)
}
.divider({strokeWidth:1,startMargin:20,endMargin:20})
.width('100%')
.height('calc(100% – 60vp)')
.backgroundColor($r('sys.color.comp_background_list_card'));

}
.width('100%')
.height('100%')
.backgroundColor('#F5F5F5');
}

// 生成联想词方法（根据输入关键词过滤预设词库）
private getSearchSuggest(keyword: string) {
if (!keyword || keyword.trim() === '') {
this.suggestList = [];
return;
}
// 不区分大小写过滤
this.suggestList = this.allSuggestWords.filter(item =>
item.toLowerCase().includes(keyword.toLowerCase())
);
}

// 通用搜索方法（可扩展为接口请求、内容检索等业务逻辑）
private doSearch(keyword: string) {
if (!keyword || keyword.trim() === '') {
this.showToast("请输入搜索关键词");
return;
}
this.showToast(`执行搜索：${keyword}`);
console.log(`执行搜索：${keyword}`);
}
}

运行效果

九、核心知识点总结

（一）组件选型核心原则

（二）枚举与绑定规范

（三）通用开发规范

（四）事件与交互规范

（五）组件专属能力要点

十、配套代码

• 工程名称：InputApplication
• 仓库地址：https://gitee.com/HarmonyOS-UI-Basics/harmony-os-ui-basics.git

十一、下节预告

下一节我们将学习核心基础组件（三）图片展示组件 Image，从三大核心维度系统掌握图片展示全场景开发能力：