ion-searchbar

scoped

搜索栏代表一个文本字段，可用于搜索集合。它们可以显示在工具栏内部或主要内容中。搜索列表时应使用搜索栏而不是输入框。

基本用法

搜索图标

搜索图标显示在搜索栏中输入字段的左侧。它可以自定义为任何 Ionicon。

清除按钮

当搜索栏有值或在搜索栏的文本字段中输入内容时，会显示一个清除按钮。点击清除按钮将擦除文本字段，并且输入框将保持焦点。默认情况下，清除按钮设置为在搜索栏获得焦点时显示，但可以设置为始终显示或从不显示。清除按钮内的图标也可以自定义为任何 Ionicon。

取消按钮

可以启用取消按钮，点击后会清除输入并失去焦点。默认情况下，取消按钮设置为从不显示，但可以设置为始终显示或仅在搜索栏获得焦点时显示。取消按钮在 ios 模式下显示为文本，在 md 模式下显示为图标。文本和图标都可以使用不同的属性进行自定义，图标可以接受任何 Ionicon。

工具栏中的搜索栏

搜索栏放置在工具栏内时，样式会呈现原生风格。在 iOS 中，搜索栏应放置在自己的工具栏中，位于包含页面标题的工具栏下方。在 Material Design 中，搜索栏要么持续显示在自己的工具栏中，要么展开覆盖包含页面标题的工具栏。

防抖

可以在搜索栏上设置防抖，以延迟触发 ionInput 事件。这在查询数据时非常有用，因为它可以用于等待发起请求，而不是每次在输入框中输入一个字符就请求数据。

主题

颜色

CSS 自定义属性

搜索栏使用作用域封装，这意味着它会在运行时通过为每个样式附加一个额外的类来自动限定其 CSS 的作用域。在 CSS 中覆盖作用域选择器需要具有更高特异性的选择器。针对 ion-searchbar 进行自定义将不起作用，因此我们建议添加一个类并以这种方式进行自定义。

键盘显示

Android

默认情况下，点击输入框会导致键盘出现，提交按钮上显示放大镜图标。你可以选择将 inputmode 属性设置为 "search"，这会将图标从放大镜更改为回车键。

iOS

默认情况下，点击输入框会导致键盘出现，灰色提交按钮上显示文本"return"。你可以选择将 inputmode 属性设置为 "search"，这会将文本从"return"更改为"go"，并将按钮颜色从灰色更改为蓝色。或者，你可以将 ion-searchbar 包装在带有 action 属性的 form 元素中。这将导致键盘出现一个蓝色提交按钮，上面显示"search"。

接口

SearchbarChangeEventDetail

interface SearchbarChangeEventDetail {
  value?: string;
}

SearchbarCustomEvent

虽然不是必需的，但此接口可以替代 CustomEvent 接口，用于与此组件发出的 Ionic 事件提供更强的类型支持。

interface SearchbarCustomEvent extends CustomEvent {
  detail: SearchbarChangeEventDetail;
  target: HTMLIonSearchbarElement;
}

属性

animated

说明	If true, enable searchbar animation.
属性	animated
类型	boolean
默认值	false

autocapitalize

说明	Indicates whether and how the text value should be automatically capitalized as it is entered/edited by the user. Available options: "off", "none", "on", "sentences", "words", "characters".
属性	autocapitalize
类型	string
默认值	'off'

autocomplete

说明	Set the input's autocomplete property.
属性	autocomplete
类型	"additional-name" ｜ "address-level1" ｜ "address-level2" ｜ "address-level3" ｜ "address-level4" ｜ "address-line1" ｜ "address-line2" ｜ "address-line3" ｜ "bday" ｜ "bday-day" ｜ "bday-month" ｜ "bday-year" ｜ "cc-additional-name" ｜ "cc-csc" ｜ "cc-exp" ｜ "cc-exp-month" ｜ "cc-exp-year" ｜ "cc-family-name" ｜ "cc-given-name" ｜ "cc-name" ｜ "cc-number" ｜ "cc-type" ｜ "country" ｜ "country-name" ｜ "current-password" ｜ "email" ｜ "family-name" ｜ "given-name" ｜ "honorific-prefix" ｜ "honorific-suffix" ｜ "impp" ｜ "language" ｜ "name" ｜ "new-password" ｜ "nickname" ｜ "off" ｜ "on" ｜ "one-time-code" ｜ "organization" ｜ "organization-title" ｜ "photo" ｜ "postal-code" ｜ "sex" ｜ "street-address" ｜ "tel" ｜ "tel-area-code" ｜ "tel-country-code" ｜ "tel-extension" ｜ "tel-local" ｜ "tel-national" ｜ "transaction-amount" ｜ "transaction-currency" ｜ "url" ｜ "username"
默认值	'off'

autocorrect

说明	Set the input's autocorrect property.
属性	autocorrect
类型	"off" ｜ "on"
默认值	'off'

cancelButtonIcon

说明	Set the cancel button icon. Only applies to md mode. Defaults to arrow-back-sharp.
属性	cancel-button-icon
类型	string
默认值	config.get('backButtonIcon', arrowBackSharp) as string

cancelButtonText

说明	Set the cancel button text. Only applies to ios mode.
属性	cancel-button-text
类型	string
默认值	'Cancel'

clearIcon

说明	Set the clear icon. Defaults to close-circle for ios and close-sharp for md.
属性	clear-icon
类型	string ｜ undefined
默认值	undefined

color

说明	The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
属性	color
类型	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认值	undefined

debounce

说明	Set the amount of time, in milliseconds, to wait to trigger the ionInput event after each keystroke.
属性	debounce
类型	number ｜ undefined
默认值	undefined

disabled

说明	If true, the user cannot interact with the input.
属性	disabled
类型	boolean
默认值	false

enterkeyhint

说明	A hint to the browser for which enter key to display. Possible values: "enter", "done", "go", "next", "previous", "search", and "send".
属性	enterkeyhint
类型	"done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined
默认值	undefined

inputmode

说明	A hint to the browser for which keyboard to display. Possible values: "none", "text", "tel", "url", "email", "numeric", "decimal", and "search".
属性	inputmode
类型	"decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined
默认值	undefined

maxlength

说明	This attribute specifies the maximum number of characters that the user can enter.
属性	maxlength
类型	number ｜ undefined
默认值	undefined

minlength

说明	This attribute specifies the minimum number of characters that the user can enter.
属性	minlength
类型	number ｜ undefined
默认值	undefined

mode

说明	The mode determines which platform styles to use. 这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性	mode
类型	"ios" ｜ "md"
默认值	undefined

name

说明	If used in a form, set the name of the control, which is submitted with the form data.
属性	name
类型	string
默认值	this.inputId

placeholder

说明	Set the input's placeholder. placeholder can accept either plaintext or HTML as a string. To display characters normally reserved for HTML, they must be escaped. For example <Ionic> would become &lt;Ionic&gt; For more information: Security Documentation
属性	placeholder
类型	string
默认值	'Search'

searchIcon

说明	The icon to use as the search icon. Defaults to search-outline in ios mode and search-sharp in md mode.
属性	search-icon
类型	string ｜ undefined
默认值	undefined

showCancelButton

说明	Sets the behavior for the cancel button. Defaults to "never". Setting to "focus" shows the cancel button on focus. Setting to "never" hides the cancel button. Setting to "always" shows the cancel button regardless of focus state.
属性	show-cancel-button
类型	"always" ｜ "focus" ｜ "never"
默认值	'never'

showClearButton

说明	Sets the behavior for the clear button. Defaults to "focus". Setting to "focus" shows the clear button on focus if the input is not empty. Setting to "never" hides the clear button. Setting to "always" shows the clear button regardless of focus state, but only if the input is not empty.
属性	show-clear-button
类型	"always" ｜ "focus" ｜ "never"
默认值	'always'

spellcheck

说明	If true, enable spellcheck on the input.
属性	spellcheck
类型	boolean
默认值	false

type

说明	Set the type of the input.
属性	type
类型	"email" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "url"
默认值	'search'

value

说明	the value of the searchbar.
属性	value
类型	null ｜ string ｜ undefined
默认值	''

事件

Name	说明	冒泡
ionBlur	Emitted when the input loses focus.	true
ionCancel	Emitted when the cancel button is clicked.	true
ionChange	The ionChange event is fired for <ion-searchbar> elements when the user modifies the element's value. Unlike the ionInput event, the ionChange event is not necessarily fired for each alteration to an element's value. The ionChange event is fired when the value has been committed by the user. This can happen when the element loses focus or when the "Enter" key is pressed. ionChange can also fire when clicking the clear or cancel buttons. This event will not emit when programmatically setting the value property.	true
ionClear	Emitted when the clear input button is clicked.	true
ionFocus	Emitted when the input has focus.	true
ionInput	Emitted when the value of the ion-searchbar element has changed.	true

方法

getInputElement

说明	Returns the native <input> element used under the hood.
签名	getInputElement() => Promise<HTMLInputElement>

setFocus

说明	Sets focus on the native input in ion-searchbar. Use this method instead of the global input.focus(). Developers who wish to focus an input when a page enters should call setFocus() in the ionViewDidEnter() lifecycle method. Developers who wish to focus an input when an overlay is presented should call setFocus after didPresent has resolved. See managing focus for more information.
签名	setFocus() => Promise<void>

CSS Shadow Parts

该组件没有可用的 CSS 阴影部分。

CSS 自定义属性

iOS

Name	说明
--background	Background of the searchbar input
--border-radius	Border radius of the searchbar input
--box-shadow	Box shadow of the searchbar input
--cancel-button-color	Color of the searchbar cancel button
--clear-button-color	Color of the searchbar clear button
--color	Color of the searchbar text
--icon-color	Color of the searchbar icon
--placeholder-color	Color of the searchbar placeholder
--placeholder-font-style	Font style of the searchbar placeholder
--placeholder-font-weight	Font weight of the searchbar placeholder
--placeholder-opacity	Opacity of the searchbar placeholder

MD

Name	说明
--background	Background of the searchbar input
--border-radius	Border radius of the searchbar input
--box-shadow	Box shadow of the searchbar input
--cancel-button-color	Color of the searchbar cancel button
--clear-button-color	Color of the searchbar clear button
--color	Color of the searchbar text
--icon-color	Color of the searchbar icon
--placeholder-color	Color of the searchbar placeholder
--placeholder-font-style	Font style of the searchbar placeholder
--placeholder-font-weight	Font weight of the searchbar placeholder
--placeholder-opacity	Opacity of the searchbar placeholder

插槽

该组件没有可用的插槽。