3aa50be2创建于 2025年8月13日历史提交

Search

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

说明：

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

该组件仅支持单文本样式，若需实现富文本样式，建议使用RichEditor组件。

子组件

无

接口

Search(options?: SearchOptions)

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

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

参数:

参数名	类型	必填	说明
options	SearchOptions	否	搜索框组件初始化选项

SearchOptions¹⁸⁺对象说明

Search初始化参数。

说明：

为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

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

名称	类型	只读	可选	说明
value⁸⁺	string	否	是	设置当前显示的搜索文本内容。从API version 10开始，该参数支持$$双向绑定变量。从API version 18开始，该参数支持!!双向绑定变量。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
placeholder⁸⁺	ResourceStr	否	是	设置无输入时的提示文本。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
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优先。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
controller⁸⁺	SearchController	否	是	设置Search组件控制器。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

属性

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

searchButton

searchButton(value: string, option?: SearchButtonOptions)

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

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

Wearable设备上默认字体大小为18fp。

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

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

参数：

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

placeholderColor

placeholderColor(value: ResourceColor)

设置placeholder文本颜色，Wearable设备上默认值为'#99ffffff'。

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

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

参数：

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

placeholderFont

placeholderFont(value?: Font)

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

Wearable设备上默认字体大小为18fp。

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

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

参数：

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

textFont

textFont(value?: Font)

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

Wearable设备上默认字体大小为18fp。

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

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

参数：

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

textAlign⁹⁺

textAlign(value: TextAlign)

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

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

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

参数：

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

说明：

textAlign只能调整文本整体的布局，不影响字符的显示顺序。若需要调整字符的显示顺序，请参考镜像状态字符对齐。

copyOption⁹⁺

copyOption(value: CopyOptions)

设置输入的文本是否可复制。设置CopyOptions.None时，当前Search中的文字无法被复制、剪切、翻译、分享、搜索和帮写，支持粘贴和全选。

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

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

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

参数：

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

searchIcon¹⁰⁺

searchIcon(value: IconOptions | SymbolGlyphModifier)

设置左侧搜索图标样式。

Wearable设备上默认图标大小为16vp。

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

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

参数：

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

cancelButton¹⁰⁺

cancelButton(value: CancelButtonOptions | CancelButtonSymbolOptions)

设置右侧清除按钮样式。

Wearable设备上默认图标大小为18fp。

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

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

参数：

参数名	类型	必填	说明
value	CancelButtonOptions \| CancelButtonSymbolOptions	是	右侧清除按钮样式。默认值： { style: CancelButtonStyle.INPUT, icon: { size: '16vp', color: '#99ffffff', src: ' ' } } 当style为CancelButtonStyle.CONSTANT时，默认显示清除样式。

fontColor¹⁰⁺

fontColor(value: ResourceColor)

设置输入文本的字体颜色。文本通用属性fontSize、fontStyle、fontWeight和fontFamily在textFont属性中设置。

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

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	输入文本的字体颜色。默认值：'#FF182431' Wearable设备上默认值为：'#dbffffff'

caretStyle¹⁰⁺

caretStyle(value: CaretStyle)

设置光标样式。

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

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

参数：

参数名	类型	必填	说明
value	CaretStyle	是	光标样式。默认值： { width: '1.5vp', color: '#007DFF' }

说明：
从API version 12开始，此接口支持设置文本手柄颜色，光标和文本手柄颜色保持一致。

enableKeyboardOnFocus¹⁰⁺

enableKeyboardOnFocus(value: boolean)

设置Search通过点击以外的方式获焦时，是否主动拉起软键盘。

从API version 10开始，获焦默认绑定输入法。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	Search获焦时，是否主动拉起软键盘。 true表示主动拉起，false表示不主动拉起。默认值：true

selectionMenuHidden¹⁰⁺

selectionMenuHidden(value: boolean)

设置是否不弹出系统文本选择菜单。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	是否不弹出系统文本选择菜单。设置为true时，单击输入框光标、长按输入框、双击输入框、三击输入框或者右键输入框，不弹出系统文本选择菜单。设置为false时，弹出系统文本选择菜单。默认值：false

customKeyboard¹⁰⁺

customKeyboard(value: CustomBuilder, options?: KeyboardOptions)

设置自定义键盘。

当设置自定义键盘时，输入框激活后不会打开系统输入法，而是加载指定的自定义组件。

自定义键盘的高度可以通过自定义组件根节点的height属性设置，宽度不可设置，使用系统默认值。

自定义键盘采用覆盖原始界面的方式呈现，当没有开启避让模式或者输入框不需要避让的场景不会对应用原始界面产生压缩或者上提。

自定义键盘无法获取焦点，但是会拦截手势事件。

默认在输入控件失去焦点时，关闭自定义键盘，开发者也可以通过stopEditing方法控制键盘关闭。

如果设备支持拍摄输入，设置自定义键盘后，该输入框会不支持拍摄输入。

当设置自定义键盘时，可以通过绑定onKeyPrelme事件规避物理键盘的输入。

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

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

参数：

参数名	类型	必填	说明
value	CustomBuilder	是	自定义键盘。
options¹²⁺	KeyboardOptions	否	设置自定义键盘是否支持避让功能。

type¹¹⁺

type(value: SearchType)

设置输入框类型。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	SearchType	是	输入框类型。默认值：SearchType.Normal

maxLength¹¹⁺

maxLength(value: number)

设置文本的最大输入字符数。默认不设置最大输入字符数限制。到达文本最大字符限制，将无法继续输入字符。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	number	是	文本的最大输入字符数。

enterKeyType¹²⁺

enterKeyType(value: EnterKeyType)

设置输入法回车键类型。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	EnterKeyType	是	输入法回车键类型。默认值：EnterKeyType.Search

lineHeight¹²⁺

lineHeight(value: number | string | Resource)

设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	number \| string \| Resource	是	文本的文本行高。

说明：

特殊字符字体高度远超出同行的其他字符高度时，文本框出现截断、遮挡、内容相对位置发生变化等不符合预期的显示异常，需要开发者调整组件高度、行高等属性，修改对应的页面布局。

decoration¹²⁺

decoration(value: TextDecorationOptions)

设置文本装饰线类型样式及其颜色。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	TextDecorationOptions	是	文本装饰线对象。默认值：{ type: TextDecorationType.None, color: Color.Black, style: TextDecorationStyle.SOLID }

letterSpacing¹²⁺

letterSpacing(value: number | string | Resource)

设置文本字符间距。设置该值为百分比时，按默认值显示。设置该值为0时，按默认值显示。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

当取值为负值时，文字会发生压缩，负值过小时会将组件内容区大小压缩为0，导致无内容显示。

对每个字符生效，包括行尾字符。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	number \| string \| Resource	是	文本字符间距。单位：fp

fontFeature¹²⁺

fontFeature(value: string)

设置文字特性效果，比如数字等宽的特性。

格式为：normal | <feature-tag-value>

<feature-tag-value>的格式为：<string> [ <integer> | on | off ]

<feature-tag-value>的个数可以有多个，中间用','隔开。

例如，使用等宽数字的输入格式为："ss01" on。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	string	是	文字特性效果。

Font Feature当前支持的属性见 fontFeature属性列表。设置 Font Feature 属性，Font Feature 是 OpenType 字体的高级排版能力，如支持连字、数字等宽等特性，一般用在自定义字体中，其能力需要字体本身支持。更多 Font Feature 能力介绍可参考 https://www.w3.org/TR/css-fonts-3/#font-feature-settings-prop 和 https://sparanoid.com/lab/opentype-features/

selectedBackgroundColor¹²⁺

selectedBackgroundColor(value: ResourceColor)

设置文本选中底板颜色。如果未设置不透明度，默认为20%不透明度。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	ResourceColor	是	文本选中底板颜色。

inputFilter¹²⁺

inputFilter(value: ResourceStr, error?: Callback< string >)

通过正则表达式设置输入过滤器。匹配表达式的输入允许显示，不匹配的输入将被过滤。

单字符输入场景仅支持单字符匹配，多字符输入场景支持字符串匹配，例如粘贴。

设置inputFilter且输入的字符不为空字符，会导致设置输入框类型(即type接口)附带的文本过滤效果失效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	ResourceStr	是	正则表达式。
error	Callback< string >	否	正则匹配失败时，返回被过滤的内容。

textIndent¹²⁺

textIndent(value: Dimension)

设置首行文本缩进。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	Dimension	是	首行文本缩进。默认值：0

minFontSize¹²⁺

minFontSize(value: number | string | Resource)

设置文本最小显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

需配合maxFontSize以及布局大小限制使用，单独设置不生效。

自适应字号生效时，fontSize设置不生效。

minFontSize小于或等于0时，自适应字号不生效，此时按照textFont属性里面size的取值生效，未设置时按照其默认值生效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	number \| string \| Resource	是	文本最小显示字号。单位：fp

maxFontSize¹²⁺

maxFontSize(value: number | string | Resource)

设置文本最大显示字号。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。

需配合minFontSize以及布局大小限制使用，单独设置不生效。

自适应字号生效时，fontSize设置不生效。

maxFontSize小于等于0或者maxFontSize小于minFontSize时，自适应字号不生效，此时按照textFont属性里面size的取值生效，未设置时按照其默认值生效。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
value	number \| string \| Resource	是	文本最大显示字号。单位：fp

halfLeading¹⁸⁺

halfLeading(halfLeading: Optional<boolean>)

设置文本是否将行间距平分至行的顶部与底部。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
halfLeading	Optional<boolean>	是	文本是否将行间距平分至行的顶部与底部。 true表示将行间距平分至行的顶部与底部，false则不平分。默认值：false

minFontScale¹⁸⁺

minFontScale(scale: Optional<number | Resource>)

设置文本最小的字体缩放倍数。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
scale	Optional<number \| Resource>	是	文本最小的字体缩放倍数，支持undefined类型。取值范围：[0, 1] 说明：设置的值小于0时，按值为0处理。设置的值大于1，按值为1处理。异常值默认不生效。使用前需在工程中配置configuration.json文件和app.json5文件，具体详见示例19设置最小字体范围与最大字体范围。

maxFontScale¹⁸⁺

maxFontScale(scale: Optional<number | Resource>)

设置文本最大的字体缩放倍数。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
scale	Optional<number \| Resource>	是	文本最大的字体缩放倍数，支持undefined类型。取值范围：[1, +∞) 说明：设置的值小于1时，按值为1处理。异常值默认不生效。设置maxFontScale属性后，search组件内容最多放大到2倍。使用前需在工程中配置configuration.json文件和app.json5文件，具体详见示例19设置最小字体范围与最大字体范围。

editMenuOptions¹²⁺

editMenuOptions(editMenu: EditMenuOptions)

设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
editMenu	EditMenuOptions	是	扩展菜单选项。

enablePreviewText¹²⁺

enablePreviewText(enable: boolean)

设置是否开启输入预上屏。

预上屏内容定义为文字暂存态，目前不支持文字拦截功能，因此不触发onWillInsert、onDidInsert、onWillDelete、onDidDelete回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
enable	boolean	是	是否开启输入预上屏。 true表示开启输入预上屏，false表示不开启输入预上屏。默认值：true

说明：

“预上屏”描述的是一种文字暂存状态。需要在输入法中开启预上屏功能，在输入文本过程中，未确认输入候选词时，文本框中显示标记文本。例如，通过拼音输入中文时，未确定候选词之前，在输入框中显示拼音字母，该状态称为文字预上屏。

enableHapticFeedback¹³⁺

enableHapticFeedback(isEnabled: boolean)

设置是否开启触控反馈。

原子化服务API： 从API version 13开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
isEnabled	boolean	是	是否开启触控反馈。 true表示开启触控反馈，false表示不开启触控反馈。默认值：true

说明：

开启触控反馈时，需要在工程的module.json5中配置requestPermissions字段以开启振动权限，配置如下：
"requestPermissions": [
 {
    "name": "ohos.permission.VIBRATE",
 }
]

keyboardAppearance¹⁵⁺

keyboardAppearance(appearance: Optional<KeyboardAppearance>)

设置输入框拉起的键盘样式。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
appearance	Optional<KeyboardAppearance>	是	键盘样式。默认值：KeyboardAppearance.NONE_IMMERSIVE

stopBackPress¹⁵⁺

stopBackPress(isStopped: Optional<boolean>)

设置是否阻止返回键向其它组件或应用侧传递。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
isStopped	Optional<boolean>	是	是否阻止返回键。 true表示阻止返回键向其它组件或应用侧传递，false表示不阻止。默认值：true

IconOptions¹⁰⁺对象说明

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

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

名称	类型	只读	可选	说明
size	Length	否	是	图标尺寸，不支持百分比。
color	ResourceColor	否	是	图标颜色。
src	ResourceStr	否	是	图标/图片源。

SearchButtonOptions¹⁰⁺对象说明

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

名称	类型	只读	可选	说明
fontSize	Length	否	是	文本按钮字体大小，不支持百分比。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
fontColor	ResourceColor	否	是	文本按钮字体颜色。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
autoDisable¹⁸⁺	Boolean	否	是	Search无文本内容时按钮置灰且不可点击。默认值：false true表示开启按钮置灰功能，false表示不开启。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

CancelButtonStyle¹⁰⁺枚举说明

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

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

名称	说明
CONSTANT	清除按钮常显样式。
INVISIBLE	清除按钮常隐样式。
INPUT	清除按钮输入样式。

SearchType¹¹⁺枚举说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

名称	值	说明
NORMAL	0	基本输入模式。支持输入数字、字母、下划线、空格、特殊字符。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
NUMBER	2	纯数字输入模式。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
PHONE_NUMBER	3	电话号码输入模式。支持输入数字、空格、+ 、-、、#、(、)，长度不限。原子化服务API：* 从API version 12开始，该接口支持在原子化服务中使用。
EMAIL	5	邮箱地址输入模式。支持数字，字母，下划线、小数点、!、#、$、%、&、'、、+、-、/、=、?、^、`、{、\|、}、~，以及@字符（只能存在一个@字符）。原子化服务API：* 从API version 12开始，该接口支持在原子化服务中使用。
NUMBER_DECIMAL¹²⁺	12	带小数点的数字输入模式。支持数字，小数点（只能存在一个小数点）。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
URL¹²⁺	13	带URL的输入模式。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

CancelButtonOptions¹²⁺对象说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

名称	类型	只读	可选	说明
style	CancelButtonStyle	否	是	右侧清除按钮显示状态。
icon	IconOptions	否	是	右侧清除按钮图标。

CancelButtonSymbolOptions¹²⁺对象说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

名称	类型	只读	可选	说明
style	CancelButtonStyle	否	是	右侧清除按钮显示状态。
icon	SymbolGlyphModifier	否	是	右侧清除按钮Symbol图标。

事件

除支持通用事件外，还支持以下事件：

onSubmit

onSubmit(callback: Callback<string>)

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

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

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

参数：

参数名	类型	必填	说明
callback	Callback<string>	是	搜索提交回调，其返回值为当前搜索框中输入的文本内容。

onSubmit¹⁴⁺

onSubmit(callback: SearchSubmitCallback)

点击搜索图标、搜索按钮或者按下软键盘搜索按钮时触发该回调事件，提交事件时提供保持Search编辑状态的方法。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	SearchSubmitCallback	是	点击搜索图标、搜索按钮或者按下软键盘搜索按钮时的回调事件。

onChange

onChange(callback: EditableTextOnChangeCallback)

输入内容发生变化时，触发该回调。

在本回调中，若执行了光标操作，需要开发者在预上屏场景下依据previewText参数调整光标逻辑，以适应预上屏场景。

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

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

参数：

参数名	类型	必填	说明
callback	EditableTextOnChangeCallback	是	当前输入文本内容变化时的回调。

onCopy

onCopy(callback:Callback<string>)

进行复制操作时，触发该回调。

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

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

参数：

参数名	类型	必填	说明
callback	Callback<string>	是	复制回调，其返回值为复制的文本内容。

onCut

onCut(callback:Callback<string>)

进行剪切操作时，触发该回调。

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

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

参数：

参数名	类型	必填	说明
callback	Callback<string>	是	剪切回调，其返回值为剪切的文本内容。

onPaste

onPaste(callback:OnPasteCallback )

进行粘贴操作时，触发该回调。

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

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

参数：

参数名	类型	必填	说明
callback	OnPasteCallback	是	粘贴回调。

onTextSelectionChange¹⁰⁺

onTextSelectionChange(callback: OnTextSelectionChangeCallback)

文本选择的位置或编辑状态下光标位置发生变化时，触发该回调。

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

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

参数：

参数名	类型	必填	说明
callback	OnTextSelectionChangeCallback	是	文本选择变化回调或光标位置变化回调。

onContentScroll¹⁰⁺

onContentScroll(callback: OnContentScrollCallback)

文本内容滚动时，触发该回调。

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

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

参数：

参数名	类型	必填	说明
callback	OnContentScrollCallback	是	文本内容滚动回调。

onEditChange¹²⁺

onEditChange(callback: Callback< boolean >)

输入状态变化时，触发该回调。有光标时为编辑态，无光标时为非编辑态。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	Callback< boolean >	是	编辑状态改变回调，其返回值为true表示正在输入。

onWillInsert¹²⁺

onWillInsert(callback: Callback<InsertValue, boolean>)

在将要输入时，触发该回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	Callback<InsertValue, boolean>	是	在将要输入时调用的回调。在返回true时，表示正常插入，返回false时，表示不插入。在预上屏和候选词操作时，该回调不触发。仅支持系统输入法输入的场景。

onDidInsert¹²⁺

onDidInsert(callback: Callback<InsertValue>)

在输入完成时，触发该回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	Callback<InsertValue>	是	在输入完成时调用的回调。仅支持系统输入法输入的场景。

onWillDelete¹²⁺

onWillDelete(callback: Callback<DeleteValue, boolean>)

在将要删除时，触发该回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	Callback<DeleteValue, boolean>	是	在将要删除时调用的回调。在返回true时，表示正常删除，返回false时，表示不删除。在预上屏删除操作时，该回调不触发。仅支持系统输入法输入的场景。

onDidDelete¹²⁺

onDidDelete(callback: Callback<DeleteValue>)

在删除完成时，触发该回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	Callback<DeleteValue>	是	在删除完成时调用的回调。仅支持系统输入法输入的场景。

说明：

点击清除按钮不触发onDidDelete回调。

onWillChange¹⁵⁺

onWillChange(callback: Callback<EditableTextChangeValue, boolean>)

在文本内容将要发生变化时，触发该回调。

onWillChange的回调时序晚于onWillInsert、onWillDelete，早于onDidInsert、onDidDelete。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
callback	Callback<EditableTextChangeValue, boolean>	是	在文本内容将要发生变化时的回调。返回true时，表示正常修改。返回false时，表示拦截此次触发。

SearchController

Search组件的控制器继承自TextContentControllerBase，涉及的接口有getTextContentRect、getTextContentLineCount、getCaretOffset、addText、deleteText、getSelection、clearPreviewText以及系统接口getText。

导入对象

controller: SearchController = new SearchController();

constructor⁸⁺

constructor()

SearchController的构造函数。

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

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

caretPosition⁸⁺

caretPosition(value: number): void

设置输入光标的位置。

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

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

参数:

参数名	类型	必填	说明
value	number	是	从字符串开始到光标所在位置的长度。

stopEditing¹⁰⁺

stopEditing(): void

退出编辑态。

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

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

setTextSelection¹²⁺

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

组件在获焦状态下，调用该接口设置文本选择区域并高亮显示，且只有在selectionStart小于selectionEnd时，文字才会被选取并高亮显示。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
selectionStart	number	是	文本选择区域起始位置，文本框中文字的起始位置为0。当selectionStart小于0时、按照0处理；当selectionStart大于文字最大长度时、按照文字最大长度处理。
selectionEnd	number	是	文本选择区域结束位置。当selectionEnd小于0时、按照0处理；当selectionEnd大于文字最大长度时、按照文字最大长度处理。
options	SelectionOptions	否	选中文字时的配置。默认值：MenuPolicy.DEFAULT。

说明：

如果selectionStart或selectionEnd被赋值为undefined时，当作0处理。

如果selectionMenuHidden被赋值为true或设备为2in1时，即使options被赋值为MenuPolicy.SHOW，调用setTextSelection也不弹出菜单。

如果选中的文本含有emoji表情时，表情的起始位置包含在设置的文本选中区域内就会被选中。

SearchSubmitCallback¹⁴⁺

type SearchSubmitCallback = (searchContent: string, event?: SubmitEvent) => void

点击搜索图标、搜索按钮或者按下软键盘搜索按钮时的回调事件。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

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

参数：

参数名	类型	必填	说明
searchContent	string	是	当前搜索框中输入的文本内容。
event	SubmitEvent	否	提交事件。

示例

示例1（设置与获取光标位置）

从API version 8开始，该示例通过controller实现了光标位置的设置与获取的功能。

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State changeValue: string = '';
  @State submitValue: string = '';
  @State positionInfo: CaretOffset = { index: 0, x: 0, y: 0 };
  controller: SearchController = new SearchController();

  build() {
    Column({space: 10}) {
      Text('onSubmit:' + this.submitValue).fontSize(18).margin(15)
      Text('onChange:' + this.changeValue).fontSize(18).margin(15)
      Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller })
        .searchButton('SEARCH')
        .width('95%')
        .height(40)
        .backgroundColor('#F5F5F5')
        .placeholderColor(Color.Grey)
        .placeholderFont({ size: 14, weight: 400 })
        .textFont({ size: 14, weight: 400 })
        .onSubmit((value: string) => {
          this.submitValue = value;
        })
        .onChange((value: string) => {
          this.changeValue = value;
        })
        .margin(20)
      Button('Set caretPosition 1')
        .onClick(() => {
          // 设置光标位置到输入的第一个字符后
          this.controller.caretPosition(1);
        })
      Button('Get CaretOffset')
        .onClick(() => {
          this.positionInfo = this.controller.getCaretOffset();
        })
    }.width('100%')
  }
}

示例2（设置搜索和删除图标）

该示例通过searchButton（从API version 8开始）、searchIcon（从API version 10开始）、cancelButton（从API version 10开始）属性展示了设置搜索和删除图标的效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State changeValue: string = '';
  @State submitValue: string = '';

  build() {
    Column() {
      Text('onSubmit:' + this.submitValue).fontSize(18).margin(15)
      Search({ value: this.changeValue, placeholder: 'Type to search...' })
        .searchButton('SEARCH')
        .searchIcon({
          src: $r('sys.media.ohos_ic_public_search_filled')
        })
        .cancelButton({
          style: CancelButtonStyle.CONSTANT,
          icon: {
            src: $r('sys.media.ohos_ic_public_cancel_filled')
          }
        })
        .width('90%')
        .height(40)
        .maxLength(20)
        .backgroundColor('#F5F5F5')
        .placeholderColor(Color.Grey)
        .placeholderFont({ size: 14, weight: 400 })
        .textFont({ size: 14, weight: 400 })
        .onSubmit((value: string) => {
          this.submitValue = value;
        })
        .onChange((value: string) => {
          this.changeValue = value;
        })
        .margin(20)
    }.width('100%')
  }
}

searchButton

示例3（设置自定义键盘）

该示例通过customKeyboard（从API version 10开始）属性实现了自定义键盘的功能。

// xxx.ets
@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();
  @State inputValue: string = "";

  // 自定义键盘组件
  @Builder CustomKeyboardBuilder() {
    Column() {
      Button('x').onClick(() => {
        // 关闭自定义键盘
        this.controller.stopEditing();
      })
      Grid() {
        ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => {
          GridItem() {
            Button(item + "")
              .width(110).onClick(() => {
              this.inputValue += item;
            })
          }
        })
      }.maxCount(3).columnsGap(10).rowsGap(10).padding(5)
    }.backgroundColor(Color.Gray)
  }

  build() {
    Column() {
      Search({ controller: this.controller, value: this.inputValue})
        // 绑定自定义键盘
        .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 })
    }
  }
}

customKeyboard

示例4（设置输入法回车键类型）

该示例通过enterKeyType（从API version 12开始）属性实现了动态切换输入法回车键的效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State text: string = '';
  @State enterTypes: Array<EnterKeyType> = [EnterKeyType.Go, EnterKeyType.Search, EnterKeyType.Send, EnterKeyType.Done, EnterKeyType.Next, EnterKeyType.PREVIOUS, EnterKeyType.NEW_LINE];
  @State index: number = 0;
  build() {
    Column({ space: 20 }) {
      Search({ placeholder: '请输入文本', value: this.text })
        .width(380)
        .enterKeyType(this.enterTypes[this.index])
        .onChange((value: string) => {
          this.text = value;
        })
        .onSubmit((value: string) => {
          console.log("trigger search onsubmit" + value);
        })

      Button('改变EnterKeyType').onClick(() => {
        this.index = (this.index + 1) % this.enterTypes.length;
      })
    }.width('100%')
  }
}

searchEnterKeyType

示例5（设置文本样式）

从API version 12开始，该示例通过lineHeight、letterSpacing、decoration属性展示了不同样式的文本效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  build() {
    Row() {
      Column() {
        Text('lineHeight').fontSize(9).fontColor(0xCCCCCC)
        Search({value: 'lineHeight unset'})
          .border({ width: 1 }).padding(10)
        Search({value: 'lineHeight 15'})
          .border({ width: 1 }).padding(10).lineHeight(15)
        Search({value: 'lineHeight 30'})
          .border({ width: 1 }).padding(10).lineHeight(30)

        Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC)
        Search({value: 'letterSpacing 0'})
          .border({ width: 1 }).padding(5).letterSpacing(0)
        Search({value: 'letterSpacing 3'})
          .border({ width: 1 }).padding(5).letterSpacing(3)
        Search({value: 'letterSpacing -1'})
          .border({ width: 1 }).padding(5).letterSpacing(-1)

        Text('decoration').fontSize(9).fontColor(0xCCCCCC)
        Search({value: 'LineThrough, Red'})
          .border({ width: 1 }).padding(5)
          .decoration({type: TextDecorationType.LineThrough, color: Color.Red})
        Search({value: 'Overline, Red, DOTTED'})
          .border({ width: 1 }).padding(5)
          .decoration({type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DOTTED})
        Search({value: 'Underline, Red, WAVY'})
          .border({ width: 1 }).padding(5)
          .decoration({type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY})
      }.height('90%')
    }
    .width('90%')
    .margin(10)
  }
}

SearchDecoration

示例6（设置文字特性效果）

该示例通过fontFeature（从API version 12开始）属性实现了文本在不同文字特性下的展示效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State text1: string = 'This is ss01 on : 0123456789';
  @State text2: string = 'This is ss01 off: 0123456789';

  build() {
    Column(){
      Search({value: this.text1})
        .margin({top:200})
        .fontFeature("\"ss01\" on")
      Search({value: this.text2})
        .margin({top:10})
        .fontFeature("\"ss01\" off")
    }
    .width("90%")
    .margin("5%")
  }
}

fontFeature

示例7（自定义键盘避让）

该示例通过customKeyboard（从API version 10开始）属性配置KeyboardOptions（从API version 12开始）接口实现了自定义键盘避让的效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();
  @State inputValue: string = "";
  @State height1: string | number = '80%';
  @State supportAvoidance: boolean = true;

  // 自定义键盘组件
  @Builder
  CustomKeyboardBuilder() {
    Column() {
      Row() {
        Button('x').onClick(() => {
          // 关闭自定义键盘
          this.controller.stopEditing();
        }).margin(10)
      }

      Grid() {
        ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => {
          GridItem() {
            Button(item + "")
              .width(110).onClick(() => {
              this.inputValue += item;
            })
          }
        })
      }.maxCount(3).columnsGap(10).rowsGap(10).padding(5)
    }
    .backgroundColor(Color.Gray)
  }

  build() {
    Column() {
      Row() {
        Button("20%")
          .fontSize(24)
          .onClick(() => {
            this.height1 = "20%";
          })
        Button("80%")
          .fontSize(24)
          .margin({ left: 20 })
          .onClick(() => {
            this.height1 = "80%";
          })
      }
      .justifyContent(FlexAlign.Center)
      .alignItems(VerticalAlign.Bottom)
      .height(this.height1)
      .width("100%")
      .padding({ bottom: 50 })

      Search({ controller: this.controller, value: this.inputValue })// 绑定自定义键盘
        .customKeyboard(this.CustomKeyboardBuilder(), { supportAvoidance: this.supportAvoidance })
        .margin(10)
        .border({ width: 1 })
        .onChange((value: string) => {
          this.inputValue = value;
        })
    }
  }
}

CustomSearchKeyType

示例8（设置文本自适应）

从API version 12开始，该示例通过minFontSize、maxFontSize属性展示了文本自适应字号的效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  build() {
    Row() {
      Column() {
        Text('adaptive font').fontSize(9).fontColor(0xCCCCCC)

        Search({value: 'This is the text without the adaptive font'})
          .width('80%').height(90).borderWidth(1)
        Search({value: 'This is the text without the adaptive font'})
          .width('80%').height(90).borderWidth(1)
          .minFontSize(4)
          .maxFontSize(40)
      }.height('90%')
    }
    .width('90%')
    .margin(10)
  }
}

searchAdaptFont

示例9（支持插入和删除回调）

从API version 12开始，该示例通过onWillInsert、onDidInsert、onWillDelete、onDidDelete接口实现了插入和删除的效果。

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State insertValue: string = "";
  @State deleteValue: string = "";
  @State insertOffset: number = 0;
  @State deleteOffset: number = 0;
  @State deleteDirection: number = 0;

  build() {
    Row() {
      Column() {
        Search({ value: "Search支持插入回调文本" })
          .height(60)
          .onWillInsert((info: InsertValue) => {
            this.insertValue = info.insertValue;
            return true;
          })
          .onDidInsert((info: InsertValue) => {
            this.insertOffset = info.insertOffset;
          })

        Text("insertValue:" + this.insertValue + "  insertOffset:" + this.insertOffset).height(30)

        Search({ value: "Search支持删除回调文本b" })
          .height(60)
          .onWillDelete((info: DeleteValue) => {
            this.deleteValue = info.deleteValue;
            this.deleteDirection = info.direction;
            return true;
          })
          .onDidDelete((info: DeleteValue) => {
            this.deleteOffset = info.deleteOffset;
            this.deleteDirection = info.direction;
          })

        Text("deleteValue:" + this.deleteValue + "  deleteOffset:" + this.deleteOffset).height(30)
        Text("deleteDirection:" + (this.deleteDirection == 0 ? "BACKWARD" : "FORWARD")).height(30)

      }.width('100%')
    }
    .height('100%')
  }
}

SearchInsertAndDelete

示例10（文本扩展自定义菜单）

从API version 12开始，该示例通过editMenuOptions接口实现了文本设置自定义菜单扩展项的文本内容、图标以及回调的功能。

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State text: string = 'Search editMenuOptions';
  onCreateMenu = (menuItems: Array<TextMenuItem>) => {
    let item1: TextMenuItem = {
      content: 'custom1',
      icon: $r('app.media.startIcon'),
      id: TextMenuItemId.of('custom1'),
    };
    let item2: TextMenuItem = {
      content: 'custom2',
      id: TextMenuItemId.of('custom2'),
      icon: $r('app.media.startIcon'),
    };
    menuItems.push(item1);
    menuItems.unshift(item2);
    return menuItems;
  }
  onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => {
    if (menuItem.id.equals(TextMenuItemId.of("custom2"))) {
      console.log("拦截 id: custom2 start:" + textRange.start + "; end:" + textRange.end);
      return true;
    }
    if (menuItem.id.equals(TextMenuItemId.COPY)) {
      console.log("拦截 COPY start:" + textRange.start + "; end:" + textRange.end);
      return true;
    }
    if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) {
      console.log("不拦截 SELECT_ALL start:" + textRange.start + "; end:" + textRange.end);
      return false;
    }
    return false;
  }
  @State editMenuOptions: EditMenuOptions = {
    onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick
  };

  build() {
    Column() {
      Search({ value: this.text })
        .width('95%')
        .editMenuOptions(this.editMenuOptions)
        .margin({ top: 100 })
    }
    .width("90%")
    .margin("5%")
  }
}

searchEditMenuOptions

示例11（设置symbol类型清除按钮）

从API version 10开始，该示例通过searchIcon、cancelButton属性展示了自定义右侧symbol类型清除按钮样式的效果。

// xxx.ets
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)
    }
    .width('100%')
    .height('100%')
  }
}

searchSymbolGlyphModifierIcon

示例12（设置文本是否可复制）

从API version 9开始，该示例通过copyOption属性展示如何设置文本是否可复制。

// xxx.ets

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();
  @State copyValue: string = '';
  @State cutValue: string = '';

  build() {
    Column({ space: 3 }) {
      Text("copy: " + this.copyValue)
      Text("cut:" + this.cutValue)
      Search({ value: 'Search CopyOption:None', controller: this.controller })
        .width('95%')
        .height(40)
        .copyOption(CopyOptions.None)
        .onCopy((value: string) => {
          this.copyValue = value;
        })
        .onCut((value: string) => {
          this.cutValue = value;
        })
      Search({ value: 'Search CopyOption:InApp', controller: this.controller })
        .width('95%')
        .height(40)
        .copyOption(CopyOptions.InApp)
        .onCopy((value: string) => {
          this.copyValue = value;
        })
        .onCut((value: string) => {
          this.cutValue = value;
        })
      Search({ value: 'Search CopyOption:LocalDevice', controller: this.controller })
        .width('95%')
        .height(40)
        .copyOption(CopyOptions.LocalDevice)
        .onCopy((value: string) => {
          this.copyValue = value;
        })
        .onCut((value: string) => {
          this.cutValue = value;
        })
    }
    .width('100%')
    .height('100%')
  }
}

searchCopyOption

示例13（设置文本水平对齐/光标样式/选中背景色）

该示例通过textAlign（从API version 9开始）、caretStyle（从API version 10开始）、selectedBackgroundColor（从API version 12开始）属性展示如何设置文本的水平对齐、光标样式和选中背景色。

// xxx.ets

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();

  build() {
    Column({ space: 3 }) {
      Search({ value: 'Search textAlign sample', controller: this.controller })
        .width('95%')
        .height(40)
        .stopBackPress(true)
        .textAlign(TextAlign.Center)
        .caretStyle({ width: 3, color: Color.Green })
        .selectedBackgroundColor(Color.Gray)
    }
    .width('100%')
    .height('100%')
  }
}

searchTextAlign

示例14（设置默认获焦并拉起软键盘）

该示例通过defaultFocus（从API version 9开始）、enableKeyboardOnFocus（从API version 10开始）属性展示如何设置默认获焦并拉起软键盘。

// xxx.ets

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();
  @State value: string = 'false';

  build() {
    Column({ space: 3 }) {
      Text('editing: ' + this.value)
      Search({ placeholder: 'please enter...', controller: this.controller })
        .width('95%')
        .height(40)
        .defaultFocus(true)
        .enableKeyboardOnFocus(true)
        .enablePreviewText(true)
        .enableHapticFeedback(true)
        .onEditChange((data: boolean) => {
          this.value = data ? 'true' : 'false';
        })
    }
    .width('100%')
    .height('100%')
  }
}

searchEnableKeyboardOnFocus

示例15（关闭系统文本选择菜单）

该示例通过selectionMenuHidden（从API version 10开始）属性展示如何关闭系统文本选择菜单。

// xxx.ets

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();

  build() {
    Column({ space: 3 }) {
      Search({ value: '123456', controller: this.controller })
        .width('95%')
        .height(40)
        .type(SearchType.NUMBER)
        .selectionMenuHidden(true)
    }
    .width('100%')
    .height('100%')
  }
}

searchSelectionMenuHidden

示例16（对输入的文本进行过滤）

从API version 12开始，该示例通过inputFilter属性展示如何对输入的文本进行内容的过滤，以限制输入内容。

// xxx.ets

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

  build() {
    Column({ space: 3 }) {
      Text('Filter:' + this.filterValue)
      Search({ placeholder: 'please enter...', controller: this.controller })
        .width('95%')
        .height(40)
        .textIndent(5)
        .halfLeading(true)
        .inputFilter('[a-z]', (filterValue: string) => {
          this.filterValue = filterValue;
        })
    }
    .width('100%')
    .height('100%')
  }
}

searchInputFilter

示例17（设置选中指定区域的文本内容）

该示例通过setTextSelection（从API version 12开始）方法展示如何设置选中指定区域的文本内容以及菜单的显隐策略。

// xxx.ets

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();
  @State startIndex: number = 0;
  @State endIndex: number = 0;

  build() {
    Column({ space: 3 }) {
      Text('Selection start:' + this.startIndex + ' end:' + this.endIndex)
      Search({ value: 'Hello World', controller: this.controller })
        .width('95%')
        .height(40)
        .minFontScale(1)
        .maxFontScale(1.5)
        .defaultFocus(true)
        .onTextSelectionChange((selectionStart: number, selectionEnd: number) => {
          this.startIndex = selectionStart;
          this.endIndex = selectionEnd;
        })

      Button('Selection [0,3]')
        .onClick(() => {
          this.controller.setTextSelection(0, 3, { menuPolicy: MenuPolicy.SHOW });
        })
    }
    .width('100%')
    .height('100%')
  }
}

searchSetTextSelection

示例18（设置文本滚动事件）

从API version 10开始，该示例通过onContentScroll事件展示如何设置文本滚动事件的回调。

// xxx.ets

@Entry
@Component
struct SearchExample {
  controller: SearchController = new SearchController();
  @State offsetX: number = 0;
  @State offsetY: number = 0;

  build() {
    Column({ space: 3 }) {
      Text('offset x:' + this.offsetX + ' y:' + this.offsetY)
      Search({ value: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', controller: this.controller })
        .width(200)
        .height(40)
        .onContentScroll((totalOffsetX: number, totalOffsetY: number) => {
          this.offsetX = totalOffsetX;
          this.offsetY = totalOffsetY;
        })
    }
    .width('100%')
    .height('100%')
  }
}

searchOnContentScroll

示例19（设置最小字体范围与最大字体范围）

从API version 18开始，该示例通过minFontScale、maxFontScale设置字体显示最小与最大范围。

// 开启应用缩放跟随系统
// AppScope/resources/base，新建文件夹profile。
// AppScope/resources/base/profile，新建文件configuration.json。
// AppScope/resources/base/profile/configuration.json，增加如下代码。
{
  "configuration": {
    "fontSizeScale": "followSystem",
    "fontSizeMaxScale": "3.2"
  }
}

// AppScope/app.json5，修改如下代码。
{
  "app": {
    "bundleName": "com.example.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "configuration": "$profile:configuration"
  }
}

// xxx.ets
@Entry
@Component
struct SearchExample {
  @State minFontScale: number = 0.85;
  @State maxFontScale: number = 2;

  build() {
    Column() {
      Column({ space: 30 }) {
        Text("系统字体变大变小，变大变小aaaaaaaAAAAAA")
        Search({
          placeholder: 'The text area can hold an unlimited amount of text. input your word...',
        })
          .minFontScale(this.minFontScale)// 设置最小字体缩放倍数，参数为undefined则跟随系统默认倍数缩放
          .maxFontScale(this.maxFontScale)// 设置最大字体缩放倍数，参数为undefined则跟随系统默认倍数缩放
      }.width('100%')
    }
  }
}

Search

子组件

接口

SearchOptions18+对象说明

属性

searchButton

placeholderColor

placeholderFont

textFont

textAlign9+

copyOption9+

searchIcon10+

cancelButton10+

fontColor10+

caretStyle10+

enableKeyboardOnFocus10+

selectionMenuHidden10+

customKeyboard10+

type11+

maxLength11+

enterKeyType12+

lineHeight12+

decoration12+

letterSpacing12+

fontFeature12+

selectedBackgroundColor12+

inputFilter12+

textIndent12+

minFontSize12+

maxFontSize12+

halfLeading18+

minFontScale18+

maxFontScale18+

editMenuOptions12+

enablePreviewText12+

enableHapticFeedback13+

keyboardAppearance15+

stopBackPress15+

IconOptions10+对象说明

SearchButtonOptions10+对象说明

CancelButtonStyle10+枚举说明

SearchType11+枚举说明

CancelButtonOptions12+对象说明

CancelButtonSymbolOptions12+对象说明

事件

onSubmit

onSubmit14+

onChange

onCopy

onCut

onPaste

onTextSelectionChange10+

onContentScroll10+

onEditChange12+

onWillInsert12+

onDidInsert12+

onWillDelete12+

onDidDelete12+

onWillChange15+

SearchController

导入对象

constructor8+

caretPosition8+

stopEditing10+

setTextSelection12+

SearchSubmitCallback14+

示例

示例1（设置与获取光标位置）

示例2（设置搜索和删除图标）

示例3（设置自定义键盘）

示例4（设置输入法回车键类型）

示例5（设置文本样式）

示例6（设置文字特性效果）

示例7（自定义键盘避让）

示例8（设置文本自适应）

示例9（支持插入和删除回调）

示例10（文本扩展自定义菜单）

示例11（设置symbol类型清除按钮）

示例12（设置文本是否可复制）

示例13（设置文本水平对齐/光标样式/选中背景色）

SearchOptions¹⁸⁺对象说明

textAlign⁹⁺

copyOption⁹⁺

searchIcon¹⁰⁺

cancelButton¹⁰⁺

fontColor¹⁰⁺

caretStyle¹⁰⁺

enableKeyboardOnFocus¹⁰⁺

selectionMenuHidden¹⁰⁺

customKeyboard¹⁰⁺

type¹¹⁺

maxLength¹¹⁺

enterKeyType¹²⁺

lineHeight¹²⁺

decoration¹²⁺

letterSpacing¹²⁺

fontFeature¹²⁺

selectedBackgroundColor¹²⁺

inputFilter¹²⁺

textIndent¹²⁺

minFontSize¹²⁺

maxFontSize¹²⁺

halfLeading¹⁸⁺

minFontScale¹⁸⁺

maxFontScale¹⁸⁺

editMenuOptions¹²⁺

enablePreviewText¹²⁺

enableHapticFeedback¹³⁺

keyboardAppearance¹⁵⁺

stopBackPress¹⁵⁺

IconOptions¹⁰⁺对象说明

SearchButtonOptions¹⁰⁺对象说明

CancelButtonStyle¹⁰⁺枚举说明

SearchType¹¹⁺枚举说明

CancelButtonOptions¹²⁺对象说明

CancelButtonSymbolOptions¹²⁺对象说明

onSubmit¹⁴⁺

onTextSelectionChange¹⁰⁺

onContentScroll¹⁰⁺

onEditChange¹²⁺

onWillInsert¹²⁺

onDidInsert¹²⁺

onWillDelete¹²⁺

onDidDelete¹²⁺

onWillChange¹⁵⁺

constructor⁸⁺

caretPosition⁸⁺

stopEditing¹⁰⁺

setTextSelection¹²⁺

SearchSubmitCallback¹⁴⁺