HarmonyOS6 ArkTS Search组件使用文档

Search是 HarmonyOS6 提供的搜索输入组件，基于 ArkTS 开发，适配 API 11+ 版本，集成了文本输入、搜索触发、光标控制、选区操作、自定义交互等一站式搜索能力。该组件可灵活配置样式、图标、按钮及输入规则，支持自定义键盘和编辑菜单，满足应用内全局搜索、页面局部搜索、条件筛选等各类搜索场景需求，是鸿蒙应用开发中实现搜索功能的核心基础组件。

完整代码

@Entry @Component struct SearchFullDemo { // 基础状态 @State searchValue: string = ''; @State submitValue: string = ''; @State cursorIndex: number = 0; // 自定义键盘 controller: SearchController = new SearchController(); build() { Column({ space: 12 }) { // 标题 Text('Search 官方全部示例整合版') .fontSize(22) .fontWeight(FontWeight.Bold) .margin({ top: 20 }); // 实时显示 Text('搜索内容：' + this.searchValue) .fontSize(16) .width('90%'); Text('提交内容：' + this.submitValue) .fontSize(16) .width('90%'); // ====================== 搜索框（整合所有属性） ====================== Search({ value: this.searchValue, placeholder: '请输入搜索内容', controller: this.controller }) // 基础样式 .width('90%') .height(50) .backgroundColor('#F5F5F5') .borderRadius(25) .padding({ left: 15, right: 15 }) // 图标与按钮 .searchIcon({ size: 20, color: '#666' }) .cancelButton({ style: CancelButtonStyle.CONSTANT, icon: { size: 18 } }) .searchButton('搜索', { fontColor: '#007DFF', fontSize: 16 }) // 文字样式 .placeholderColor('#999') .placeholderFont({ size: 15, weight: FontWeight.Normal }) .textFont({ size: 16, weight: FontWeight.Medium }) .fontColor('#333') // 光标与选中 .caretStyle({ width: 2, color: '#007DFF' }) .selectedBackgroundColor('#a0c8ff') // 输入控制 .maxLength(20) .type(SearchType.NORMAL) .enterKeyType(EnterKeyType.Search) .enablePreviewText(true) .enableHapticFeedback(true) .copyOption(CopyOptions.LocalDevice) .inputFilter('[a-zA-Z0-9\u4e00-\u9fa5\\s]*') .textAlign(TextAlign.Start) // 高级文本样式 .lineHeight(24) .letterSpacing(0.5) .decoration({ type: TextDecorationType.None }) .minFontSize(12) .maxFontSize(18) .halfLeading(true) .enableAutoSpacing(false) // 键盘与菜单 .enableKeyboardOnFocus(true) .selectionMenuHidden(false) .stopBackPress(true) .customKeyboard(this.CustomKeyboard()) .editMenuOptions(this.CustomEditMenu()) // ====================== 全部事件 ====================== .onChange((value) => { this.searchValue = value; }) .onSubmit((value) => { this.submitValue = value; this.controller.stopEditing(); }) .onEditChange((isEditing) => { console.info('编辑状态：', isEditing); }) .onTextSelectionChange((start, end) => { this.cursorIndex = start; }) .onCopy((value) => console.info('复制：', value)) .onCut((value) => console.info('剪切：', value)) .onPaste(() => console.info('粘贴')) .onWillInsert((value) => { console.info('将要插入：', value.insertValue); return true; }) .onDidInsert((value) => console.info('插入完成：', value.insertValue)) .onWillDelete((value) => { console.info('将要删除：', value.deleteValue); return true; }) .onDidDelete((value) => console.info('删除完成：', value.deleteOffset)) .onContentScroll((x, y) => console.info('滚动：', x, y)) // ====================== 功能按钮 ====================== Row({ space: 10 }) { Button('光标移到末尾') .onClick(() => { this.controller.caretPosition(this.searchValue.length); }); Button('选中前3位') .onClick(() => { this.controller.setTextSelection(0, 3); }); Button('关闭键盘') .onClick(() => { this.controller.stopEditing(); }); } .width('90%') .justifyContent(FlexAlign.Center); } .width('100%') .backgroundColor('#fff') .padding({ bottom: 30 }); } // ====================== 自定义键盘（示例3） ====================== @Builder CustomKeyboard() { Column() { Row() { Button('关闭键盘') .onClick(() => { this.controller.stopEditing(); }) .margin({ bottom: 10 }); } Grid() { ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, 0], (item: number) => { GridItem() { Button(item.toString()) .width(80) .height(40) .onClick(() => { this.searchValue += item; }); } }); } .maxCount(3) .columnsGap(6) .rowsGap(6) .padding(10); } .backgroundColor('#eee'); } // ====================== 自定义菜单（示例10） ====================== CustomEditMenu(): EditMenuOptions { return { onCreateMenu: (menuItems: Array<TextMenuItem>) => { menuItems.push({ content: '我的菜单', id: TextMenuItemId.of('custom') }); return menuItems; }, onMenuItemClick: (item: TextMenuItem) => { console.info('点击菜单：', item.content); return true; } }; } }

运行效果如图：

核心API

1 组件构造参数

Search组件通过构造参数初始化核心绑定值和控制器，参数说明如下：

2 核心控制器：SearchController

通过new SearchController()创建，是操作Search组件的核心入口，提供以下关键方法：

3 主要属性分类详解

3.1 基础样式属性

用于配置搜索框整体外观，包括尺寸、背景、圆角等，贴合鸿蒙UI设计规范：

3.2 图标与按钮属性

自定义搜索框内置的搜索图标、取消按钮、右侧搜索按钮，支持样式和显示规则配置：

3.3 文字样式属性

分别配置占位符和输入文本的样式，支持精细化字体控制：

3.4 光标与选中文本属性

配置光标样式和选中文本的背景色，提升输入交互体验：

3.5 输入控制属性

限制输入规则、配置输入行为，保障输入内容的合法性和交互一致性：

3.6 高级文本样式属性

对输入文本进行精细化样式配置，支持排版优化：

3.7 键盘与菜单扩展属性

配置键盘拉起规则，绑定自定义键盘和自定义编辑菜单，实现个性化交互：

4 全部事件监听

Search组件提供全生命周期的事件监听，覆盖输入、提交、编辑、操作等所有场景，支持事件拦截和回调处理：

5 自定义扩展能力

5.1 自定义键盘

通过@Builder装饰器构建自定义键盘布局，替代系统默认软键盘，适用于数字输入、固定字符输入等场景：

1. 定义：使用@Builder CustomKeyboard()构建键盘UI，包含按钮、布局等鸿蒙基础组件；
2. 绑定：通过search.customKeyboard(this.CustomKeyboard())绑定到搜索框；
3. 交互：在自定义键盘按钮的点击事件中，直接修改搜索框绑定的searchValue实现文本输入，通过controller.stopEditing()收起键盘。

5.2 自定义编辑菜单

通过配置EditMenuOptions对象，在系统默认编辑菜单基础上添加自定义菜单项，支持菜单项点击事件监听：

1. 定义：创建返回值为EditMenuOptions的方法，包含onCreateMenu和onMenuItemClick两个核心回调；
   • onCreateMenu：接收系统默认菜单项数组，可通过push添加自定义菜单项（包含content文字、id唯一标识）；
   • onMenuItemClick：监听菜单项点击事件，入参为当前点击的菜单项对象；
2. 绑定：通过search.editMenuOptions(this.CustomEditMenu())绑定到搜索框。

常用功能使用示例

1 基础搜索功能实现

1. 绑定searchValue实时获取输入内容，通过onChange事件更新状态；
2. 配置enterKeyType(EnterKeyType.Search)和searchButton，通过onSubmit事件触发搜索逻辑；
3. 在onSubmit中调用controller.stopEditing()收起键盘，提升交互体验。

2 光标与选区控制

1. 移动光标：通过controller.caretPosition(索引值)将光标移到指定位置，示例：移到文本末尾controller.caretPosition(this.searchValue.length)；
2. 选中文本：通过controller.setTextSelection(起始索引, 结束索引)选中指定范围文本，示例：选中前3位controller.setTextSelection(0, 3)。

3 输入内容过滤

通过inputFilter属性设置正则表达式，限制仅允许指定内容输入，示例：

.inputFilter('[a-zA-Z0-9\u4e00-\u9fa5\\s]*') // 仅允许中英文、数字、空格

4 输入/删除拦截

通过onWillInsert和onWillDelete实现输入和删除行为的拦截，示例：

.onWillInsert((value) => { // 禁止输入空字符串 if (value.insertValue === ' ') return false; return true; })

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