ion-searchbar

scoped

搜索栏表示可用于搜索集合的文本字段。它们可以显示在工具栏或主要内容内。应使用搜索栏而不是搜索列表的输入。

¥Searchbars represent a text field that can be used to search through a collection. They can be displayed inside of a toolbar or the main content. A searchbar should be used instead of an input to search lists.

基本用法

¥Basic Usage

搜索图标

¥Search Icon

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

¥A search icon is displayed to the left of the input field in a searchbar. It can be customized to any Ionicon.

清除按钮

¥Clear Button

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

¥A clear button is displayed when a searchbar has a value or upon entering input in the searchbar's text field. Clicking on the clear button will erase the text field and the input will remain focused. By default, the clear button is set to show when focusing the searchbar, but it can be set to always show or never show. The icon inside of the clear button can also be customized to any Ionicon.

取消按钮

¥Cancel Button

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

¥A cancel button can be enabled which will clear the input and lose the focus upon click. By default, cancel buttons are set to never show, but they can be set to always show or only show when focusing the searchbar. The cancel button is displayed as text in ios mode, and as an icon in md mode. Both the text and icon can be customized using different properties, with the icon accepting any Ionicon.

工具栏中的搜索栏

¥Searchbars in Toolbars

当放置在工具栏内时，搜索栏的样式看起来像是原生的。在 iOS 中，搜索栏应放置在其自己的工具栏中，位于包含页面标题的工具栏下方。在 Material Design 中，搜索栏要么永久显示在自己的工具栏中，要么展开到包含页面标题的工具栏上。

¥Searchbars are styled to look native when placed inside of a toolbar. In iOS, searchbars should be placed in their own toolbar, under a toolbar that contains the page title. In Material Design, searchbars are either persistently displayed in their own toolbar, or expand over a toolbar containing the page title.

去抖动

¥Debounce

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

¥A debounce can be set on the searchbar in order to delay triggering the ionInput event. This is useful when querying data, as it can be used to wait to make a request instead of requesting the data each time a character is entered in the input.

主题化

¥Theming

颜色

¥Colors

CSS 自定义属性

¥CSS Custom Properties

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

¥Searchbar uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector. Targeting the ion-searchbar for customization will not work, therefore we recommend adding a class and customizing it that way.

键盘显示

¥Keyboard Display

安卓

¥Android

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

¥By default, tapping the input will cause the keyboard to appear with a magnifying glass icon on the submit button. You can optionally set the inputmode property to "search", which will change the icon from a magnifying glass to a carriage return.

iOS

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

¥By default, tapping the input will cause the keyboard to appear with the text "return" on a gray submit button. You can optionally set the inputmode property to "search", which will change the text from "return" to "go", and change the button color from gray to blue. Alternatively, you can wrap the ion-searchbar in a form element with an action property. This will cause the keyboard to appear with a blue submit button that says "search".

接口

¥Interfaces

SearchbarChangeEventDetail

interface SearchbarChangeEventDetail {
  value?: string;
}

SearchbarCustomEvent

虽然不是必需的，但可以使用此接口代替 CustomEvent 接口，以便使用从此组件发出的 Ionic 事件进行更强的键入。

¥While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.

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

属性

¥Properties

animated

Description	If `true`, enable searchbar animation.
Attribute	`animated`
Type	`boolean`
Default	`false`

autocapitalize

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'`

autocomplete

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

autocorrect

Description	Set the input's autocorrect property.
Attribute	`autocorrect`
Type	`"off" ｜ "on"`
Default	`'off'`

cancelButtonIcon

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`

cancelButtonText

Description	Set the the cancel button text. Only applies to `ios` mode.
Attribute	`cancel-button-text`
Type	`string`
Default	`'Cancel'`

clearIcon

Description	Set the clear icon. Defaults to `close-circle` for `ios` and `close-sharp` for `md`.
Attribute	`clear-icon`
Type	`string ｜ undefined`
Default	`undefined`

color

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`

debounce

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`

disabled

Description	If `true`, the user cannot interact with the input.
Attribute	`disabled`
Type	`boolean`
Default	`false`

enterkeyhint

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`

inputmode

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`

maxlength

Description	This attribute specifies the maximum number of characters that the user can enter.
Attribute	`maxlength`
Type	`number ｜ undefined`
Default	`undefined`

minlength

Description	This attribute specifies the minimum number of characters that the user can enter.
Attribute	`minlength`
Type	`number ｜ undefined`
Default	`undefined`

mode

Description	The mode determines which platform styles to use.
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

name

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`

placeholder

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'`

searchIcon

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`

showCancelButton

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'`

showClearButton

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'`

spellcheck

Description	If `true`, enable spellcheck on the input.
Attribute	`spellcheck`
Type	`boolean`
Default	`false`

type

Description	Set the type of the input.
Attribute	`type`
Type	`"email" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "url"`
Default	`'search'`

value

Description	the value of the searchbar.
Attribute	`value`
Type	`null ｜ string ｜ undefined`
Default	`''`

事件

¥Events

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`

方法

¥Methods

getInputElement

Description	Returns the native `<input>` element used under the hood.
Signature	`getInputElement() => Promise<HTMLInputElement>`

setFocus

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>

CSS 阴影部分

¥CSS Shadow Parts

No CSS shadow parts available for this component.

CSS 自定义属性

¥CSS Custom Properties

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

插槽

¥Slots

No slots available for this component.

基本用法​

搜索图标​

清除按钮​

取消按钮​

工具栏中的搜索栏​

去抖动​

主题化​

颜色​

CSS 自定义属性​

键盘显示​

安卓​

iOS​

接口​

SearchbarChangeEventDetail​

SearchbarCustomEvent​

属性​

animated​

autocapitalize​

autocomplete​

autocorrect​

cancelButtonIcon​

cancelButtonText​

clearIcon​

color​

debounce​

disabled​

enterkeyhint​

inputmode​

maxlength​

minlength​

mode​

name​

placeholder​

searchIcon​

showCancelButton​

showClearButton​

spellcheck​

type​

value​

事件​

方法​

getInputElement​

setFocus​

CSS 阴影部分​

CSS 自定义属性​

插槽​

目录

基本用法

搜索图标

清除按钮

取消按钮

工具栏中的搜索栏

去抖动

主题化

颜色

CSS 自定义属性

键盘显示

安卓

iOS

接口

SearchbarChangeEventDetail

SearchbarCustomEvent

属性

animated

autocapitalize

autocomplete

autocorrect

cancelButtonIcon

cancelButtonText

clearIcon

color

debounce

disabled

enterkeyhint

inputmode

maxlength

minlength

mode

name

placeholder

searchIcon

showCancelButton

showClearButton

spellcheck

type

value

事件

方法

getInputElement

setFocus

CSS 阴影部分

CSS 自定义属性

插槽