鸿蒙5.0开发进阶：UI框架-ArkTS组件（Search）

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

Search

搜索框组件，适用于浏览器的搜索内容输入框等应用场景。

说明

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数:

参数名	类型	必填	说明
value	string	否	设置当前显示的搜索文本内容。 从API version 10开始，该参数支持$$双向绑定变量。
placeholder	ResourceStr10+	否	设置无输入时的提示文本。
icon	string	否	设置搜索图标路径，默认使用系统搜索图标。 说明： icon的数据源支持本地图片和网络图片。 - 支持的图片格式包括png、jpg、bmp、svg、gif、pixelmap和heif。 - 支持Base64字符串。格式data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。 如果与属性searchIcon同时设置，则searchIcon优先。
controller	SearchController	否	设置Search组件控制器。

属性

除支持通用属性外，还支持以下属性：

searchButton

searchButton(value: string, option?: SearchButtonOptions)

设置搜索框末尾搜索按钮。

点击搜索按钮，同时触发onSubmit与onClick回调。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string	是	搜索框末尾搜索按钮文本内容。
option	SearchButtonOptions	否	配置搜索框文本样式。 默认值： { fontSize: '16fp', fontColor: '#ff3f97e9' }

placeholderColor

placeholderColor(value: ResourceColor)

设置placeholder文本颜色。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	placeholder文本颜色。 默认值：'#99182431'。

placeholderFont

placeholderFont(value?: Font)

设置placeholder文本样式，包括字体大小，字体粗细，字体族，字体风格。当前支持'HarmonyOS Sans'字体和注册自定义字体。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Font	否	placeholder文本样式。

textFont

textFont(value?: Font)

设置搜索框内输入文本样式，包括字体大小，字体粗细，字体族，字体风格。目前仅支持默认字体族。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Font	否	搜索框内输入文本样式。

textAlign9+

textAlign(value: TextAlign)

设置文本在搜索框中的对齐方式。目前支持的对齐方式有：Start、Center、End。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	TextAlign	是	文本在搜索框中的对齐方式。 默认值：TextAlign.Start

copyOption9+

copyOption(value: CopyOptions)

设置输入的文本是否可复制。设置CopyOptions.None时，当前Search中的文字无法被复制或剪切，仅支持粘贴。

设置CopyOptions.None时，不允许拖拽。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	CopyOptions	是	输入的文本是否可复制。 默认值：CopyOptions.LocalDevice，支持设备内复制。

searchIcon10+

searchIcon(value: IconOptions | SymbolGlyphModifier)

设置左侧搜索图标样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	IconOptions | SymbolGlyphModifier	是	左侧搜索图标样式。 浅色模式默认值： { size: '16vp', color: '#99000000', src: ' ' } 深色模式默认值： { size: '16vp', color: '#99ffffff', src: ' ' }

cancelButton10+

cancelButton(value: CancelButtonOptions | CancelButtonSymbolOptions)

设置右侧清除按钮样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	CancelButtonOptions |