scoped
搜索栏是一种文本字段，可用于搜索集合。它们可以显示在工具栏或主要内容区域中。在搜索列表时，应使用搜索栏而非普通输入框。
搜索栏的输入字段左侧会显示一个搜索图标。该图标可以自定义为任意 Ionicon。
当搜索栏有值或在文本字段中输入内容时，会显示清除按钮。点击清除按钮将清空文本字段，且输入焦点保持不变。默认情况下，清除按钮在聚焦搜索栏时显示，但也可以设置为始终显示或从不显示。清除按钮内的图标同样可以自定义为任意 Ionicon。
可以启用取消按钮，点击该按钮将清除输入内容并失去焦点。默认情况下，取消按钮设置为从不显示，但也可以设置为始终显示或仅在聚焦搜索栏时显示。在 ios 模式下，取消按钮显示为文本；在 md 模式下，则显示为图标。文本和图标均可使用不同属性进行自定义，其中图标可接受任意 Ionicon。
当放置在工具栏内时，搜索栏会呈现原生样式。在 iOS 中，搜索栏应放置在其独立的工具栏中，位于包含页面标题的工具栏下方。在 Material Design 中，搜索栏要么持久显示在其独立的工具栏中，要么展开覆盖包含页面标题的工具栏。
可以为搜索栏设置防抖延迟，以推迟触发 ionInput 事件。这在查询数据时非常有用，因为它可以用于等待发起请求，而不是每次在输入框中输入字符时都请求数据。
搜索栏使用作用域封装，这意味着它会在运行时通过为每个样式附加一个额外的类来自动限定其 CSS 范围。要覆盖 CSS 中的作用域选择器，需要更高特异性的选择器。直接针对 ion-searchbar 进行自定义将不起作用，因此我们建议添加一个类并通过该类进行自定义。
默认情况下，点击输入框会触发键盘显示，提交按钮上会有一个放大镜图标。您可以选择将 inputmode 属性设置为 "search"，这会将图标从放大镜更改为回车键。
默认情况下，点击输入框会触发键盘显示，灰色提交按钮上会显示“return”文本。您可以选择将 inputmode 属性设置为 "search"，这会将文本从“return”更改为“go”，并将按钮颜色从灰色更改为蓝色。或者，您可以将 ion-searchbar 包裹在具有 action 属性的 form 元素中。这将使键盘显示一个蓝色的提交按钮，上面写着“search”。
interface SearchbarChangeEventDetail {
value?: string;
}
虽然不是必需的，但可以使用此接口替代 CustomEvent 接口，以便对此组件发出的 Ionic 事件进行更严格的类型检查。
interface SearchbarCustomEvent extends CustomEvent {
detail: SearchbarChangeEventDetail;
target: HTMLIonSearchbarElement;
}
| Description | If true, enable searchbar animation. |
| Attribute | animated |
| Type | boolean |
| Default | false |
| Description | 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". |
| Attribute | autocapitalize |
| Type | string |
| Default | 'off' |
| Description | Set the input's autocomplete property. |
| Attribute | autocomplete |
| Type | "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" |
| Default | 'off' |
| Description | Set the input's autocorrect property. |
| Attribute | autocorrect |
| Type | "off" ｜ "on" |
| Default | 'off' |
| Description | Set the cancel button icon. Only applies to md mode. Defaults to arrow-back-sharp. |
| Attribute | cancel-button-icon |
| Type | string |
| Default | config.get('backButtonIcon', arrowBackSharp) as string |
| Description | Set the cancel button text. Only applies to ios mode. |
| Attribute | cancel-button-text |
| Type | string |
| Default | 'Cancel' |
| Description | Set the clear icon. Defaults to close-circle for ios and close-sharp for md. |
| Attribute | clear-icon |
| Type | string ｜ undefined |
| Default | undefined |
| Description | 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. |
| Attribute | color |
| Type | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| Default | undefined |
| Description | Set the amount of time, in milliseconds, to wait to trigger the ionInput event after each keystroke. |
| Attribute | debounce |
| Type | number ｜ undefined |
| Default | undefined |
| Description | If true, the user cannot interact with the input. |
| Attribute | disabled |
| Type | boolean |
| Default | false |
| Description | A hint to the browser for which enter key to display. Possible values: "enter", "done", "go", "next", "previous", "search", and "send". |
| Attribute | enterkeyhint |
| Type | "done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined |
| Default | undefined |
| Description | A hint to the browser for which keyboard to display. Possible values: "none", "text", "tel", "url", "email", "numeric", "decimal", and "search". |
| Attribute | inputmode |
| Type | "decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined |
| Default | undefined |
| Description | This attribute specifies the maximum number of characters that the user can enter. |
| Attribute | maxlength |
| Type | number ｜ undefined |
| Default | undefined |
| Description | This attribute specifies the minimum number of characters that the user can enter. |
| Attribute | minlength |
| Type | number ｜ undefined |
| Default | undefined |
| Description | The mode determines which platform styles to use.
This is a virtual property that is set once during initialization and will not update if you change its value after the initial render. |
| Attribute | mode |
| Type | "ios" ｜ "md" |
| Default | undefined |
| Description | If used in a form, set the name of the control, which is submitted with the form data. |
| Attribute | name |
| Type | string |
| Default | this.inputId |
| Description | 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 <Ionic>
For more information: Security Documentation |
| Attribute | placeholder |
| Type | string |
| Default | 'Search' |
| Description | The icon to use as the search icon. Defaults to search-outline in ios mode and search-sharp in md mode. |
| Attribute | search-icon |
| Type | string ｜ undefined |
| Default | undefined |
| Description | 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. |
| Attribute | show-cancel-button |
| Type | "always" ｜ "focus" ｜ "never" |
| Default | 'never' |
| Description | 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. |
| Attribute | show-clear-button |
| Type | "always" ｜ "focus" ｜ "never" |
| Default | 'always' |
| Description | If true, enable spellcheck on the input. |
| Attribute | spellcheck |
| Type | boolean |
| Default | false |
| Description | Set the type of the input. |
| Attribute | type |
| Type | "email" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" |
| Default | 'search' |
| Description | the value of the searchbar. |
| Attribute | value |
| Type | null ｜ string ｜ undefined |
| Default | '' |
| Name | Description | Bubbles |
|---|
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 |
| Description | Returns the native <input> element used under the hood. |
| Signature | getInputElement() => Promise<HTMLInputElement> |
| Description | 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. |
| Signature | setFocus() => Promise<void> |
No CSS shadow parts available for this component.
| Name | Description |
|---|
--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 |
| Name | Description |
|---|
--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 |
No slots available for this component.