#跟着若城学鸿蒙# UI组件篇-Search组件及其属性

Huang兄

831人浏览 · 2025-05-22 17:23:12

Huang兄 · 2025-05-22 17:23:12 发布

Search组件是ArkUI框架中提供的搜索框组件，适用于浏览器搜索内容输入框等应用场景。本文将从功能特性、接口属性、事件处理、使用示例等方面详细介绍Search组件的使用方法。

一、Search组件概述

Search组件从API Version 8开始支持，后续版本不断新增功能。它是一个功能完备的搜索输入框，具有以下特点：

支持设置搜索图标、提示文本和搜索按钮
提供丰富的文本输入控制能力
支持自定义键盘和输入过滤器
提供多种输入类型（普通文本、数字、邮箱等）
具备完整的生命周期事件和交互事件

二、Search组件接口

Search组件提供以下构造函数：

Search(options?: { value?: string, placeholder?: ResourceStr, icon?: string, controller?: SearchController })

参数说明：

参数名	类型	必填	说明
value	string	否	设置当前显示的搜索文本内容
placeholder	ResourceStr	否	设置无输入时的提示文本
icon	string	否	设置搜索图标路径
controller	SearchController	否	设置Search组件控制器

三、Search组件属性

Search组件支持丰富的属性设置，下面分类介绍：

1. 搜索按钮相关属性

searchButton(value: string, option?: SearchButtonOptions)

设置搜索框末尾搜索按钮，点击搜索按钮会同时触发onSubmit与onClick回调。

示例：

Search() .searchButton('搜索', { fontSize: '16fp', fontColor: '#ff3f97e9' })

2. 文本样式相关属性

placeholderColor(value: ResourceColor) // 设置placeholder文本颜色 placeholderFont(value?: Font) // 设置placeholder文本样式 
textFont(value?: Font) // 设置输入文本样式 
fontColor(value: ResourceColor) // 设置输入文本字体颜色

3. 文本对齐与布局

textAlign(value: TextAlign) // 设置文本对齐方式 
lineHeight(value: number | string | Resource) // 设置文本行高 
textIndent(value: Dimension) // 设置首行文本缩进 
letterSpacing(value: number | string | Resource) // 设置字符间距

4. 输入控制相关属性

copyOption(value: CopyOptions) // 设置文本是否可复制 
maxLength(value: number) // 设置最大输入字符数 
inputFilter(value: ResourceStr, error?: Callback<string>) // 设置输入过滤器 type(value: SearchType) // 设置输入框类型

5. 图标与按钮样式

searchIcon(value: IconOptions | SymbolGlyphModifier) // 设置左侧搜索图标样式 
cancelButton(value: CancelButtonOptions | CancelButtonSymbolOptions) // 设置右侧清除按钮样式

6. 光标与键盘控制

caretStyle(value: CaretStyle) // 设置光标样式 
enableKeyboardOnFocus(value: boolean) // 设置获焦时是否拉起软键盘 
enterKeyType(value: EnterKeyType) // 设置输入法回车键类型 customKeyboard(value: CustomBuilder, options?: KeyboardOptions) // 设置自定义键盘

四、Search组件事件

Search组件支持丰富的事件回调：

1. 提交事件

onSubmit(callback: (value: string) => void)

点击搜索图标、搜索按钮或按下软键盘搜索按钮时触发。

2. 输入变化事件

onChange(callback: EditableTextOnChangeCallback)

输入内容发生变化时触发。

3. 文本操作事件

onCopy(callback: (value: string) => void) // 复制时触发
 onCut(callback: (value: string) => void) // 剪切时触发 
onPaste(callback: (value: string, event: PasteEvent) => void) // 粘贴时触发

4. 选择与编辑事件

onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void) // 文本选择变化 
onEditChange(callback: Callback<boolean>) // 编辑状态变化

5. 输入与删除事件

onWillInsert(callback: Callback<InsertValue, boolean>) // 将要输入时触发
 onDidInsert(callback: Callback<InsertValue>) // 输入完成时触发 
onWillDelete(callback: Callback<DeleteValue, boolean>) // 将要删除时触发 
onDidDelete(callback: Callback<DeleteValue>) // 删除完成时触发

五、SearchController控制器

SearchController提供了对Search组件的控制能力：

1. 构造函数

constructor()

2. 光标控制

caretPosition(value: number): void // 设置输入光标位置

3. 编辑控制

stopEditing(): void // 退出编辑态

4. 文本选择

setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void

六、完整示例代码

下面是一个完整的Search组件使用示例：

import { SymbolGlyphModifier } from '@kit.ArkUI'

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController()
  @State changeValue: string = ''
  @State submitValue: string = ''

  build() {
    Column() {
      Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller })
        .searchIcon(new SymbolGlyphModifier($r('sys.symbol.magnifyingglass')).fontColor([Color.Red]))
        .cancelButton({
          style: CancelButtonStyle.CONSTANT,
          icon: new SymbolGlyphModifier($r('sys.symbol.xmark')).fontColor([Color.Green])
        })
        .searchButton('SEARCH')
        .width('95%')
        .height(40)
        .backgroundColor('#F5F5F5')
        .placeholderColor(Color.Grey)
        .placeholderFont({ size: 14, weight: 400 })
        .textFont({ size: 14, weight: 400 })
        .margin(10)
        .onSubmit((value: string) => {
          this.submitValue = value
          console.log('Search submitted: ' + value)
        })
        .onChange((value: string) => {
          this.changeValue = value
        })
    }.width('100%').height('100%')
  }
}

七、高级功能

1. 自定义键盘

Search组件支持设置自定义键盘：

import { SymbolGlyphModifier } from '@kit.ArkUI'

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController()
  @State changeValue: string = ''
  @State submitValue: string = ''

  build() {
    Column() {
      Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller })
        .searchIcon(new SymbolGlyphModifier($r('sys.symbol.magnifyingglass')).fontColor([Color.Red]))
        .cancelButton({
          style: CancelButtonStyle.CONSTANT,
          icon: new SymbolGlyphModifier($r('sys.symbol.xmark')).fontColor([Color.Green])
        })
        .customKeyboard(CustomKeyboardBuilder,  { supportAvoidance: true })
        .searchButton('SEARCH')
        .width('95%')
        .height(40)
        .backgroundColor('#F5F5F5')
        .placeholderColor(Color.Grey)
        .placeholderFont({ size: 14, weight: 400 })
        .textFont({ size: 14, weight: 400 })
        .margin(10)
        .onSubmit((value: string) => {
          this.submitValue = value
          console.log('Search submitted: ' + value)
        })
        .onChange((value: string) => {
          this.changeValue = value
        })
    }.width('100%').height('100%')
  }
}

@Builder
function

CustomKeyboardBuilder() {
  Column() {
    Row() {
      Button('1').onClick(() => {
        /* 处理按键 */
      })
      Button('2').onClick(() => {
        /* 处理按键 */
      })
      // 更多按键...
    }
  }
}

2. 输入类型控制

Search组件支持多种输入类型：

enum SearchType { 
NORMAL, // 普通输入 
NUMBER, // 纯数字 
PHONE_NUMBER, // 电话号码 
EMAIL, // 邮箱地址 
NUMBER_DECIMAL // 带小数点的数字 
}
 Search() .type(SearchType.EMAIL)

3. 输入过滤器

可以通过正则表达式设置输入过滤器：

Search() .inputFilter('[0-9]', (error: string) => { console.log('Filtered: ' + error) })

八、最佳实践

性能优化：对于大数据量的搜索场景，建议使用防抖或节流技术控制onChange事件的触发频率。
用户体验：
- 提供清晰的placeholder提示
- 合理设置maxLength限制输入长度
- 根据输入内容类型设置合适的type
无障碍访问：
- 为搜索按钮设置适当的无障碍标签
- 确保搜索功能可以通过键盘操作完成
多语言支持：
- placeholder和searchButton文本应支持多语言
- 考虑RTL(从右到左)布局的支持

九、总结

ArkUI的Search组件是一个功能强大、高度可定制的搜索输入框组件。通过本文的介绍，我们了解了它的各种属性、事件和控制方法。合理使用Search组件可以大大提升应用的搜索体验，同时保持代码的简洁和可维护性。

在实际开发中，开发者可以根据具体需求选择合适的配置组合，打造出既美观又实用的搜索功能。随着ArkUI的不断发展，Search组件也会持续增强，为开发者提供更多便利。

----

以上

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙 Next 长辈专属语音菜谱 App 开发实战：适老化大字体设计 + 语音朗读引擎 + 收藏系统 + 第十八款 App

人工智能6S服务平台

鸿蒙 Next 睡前故事定制机 App 开发实战：10 个内置故事 + 角色替换引擎 + 语音朗读 + 主题筛选 + 第十九款 App

人工智能6S服务平台

【共创季稿事节】鸿蒙原生ArkTS布局方式之Column最大宽度约束

人工智能6S服务平台

所有评论(0)

查看更多评论

Huang兄

@huangyuan_xuan

已为社区贡献6条内容

#跟着若城学鸿蒙# UI组件篇-Search组件及其属性

Huang兄

一、Search组件概述

二、Search组件接口

三、Search组件属性

1. 搜索按钮相关属性

2. 文本样式相关属性

3. 文本对齐与布局

4. 输入控制相关属性

5. 图标与按钮样式

6. 光标与键盘控制

四、Search组件事件

1. 提交事件

2. 输入变化事件

3. 文本操作事件

4. 选择与编辑事件

5. 输入与删除事件

五、SearchController控制器

1. 构造函数

2. 光标控制

3. 编辑控制

4. 文本选择

六、完整示例代码

七、高级功能

1. 自定义键盘

2. 输入类型控制

3. 输入过滤器

八、最佳实践

九、总结

所有评论(0)

温馨提示：您尚未绑定手机号

Huang兄