版本：v8

ion-searchbar

作用域

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

基本用法

搜索图标

搜索图标显示在搜索栏中输入字段的左侧。它可以自定义为任何 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

描述	如果为 `true`，则启用搜索栏动画。
属性	`animated`
类型	`布尔值`
默认值	`false`

autocapitalize

描述	指示文本值在用户输入/编辑时是否以及如何自动大写。可用选项：`"off"`、`"none"`、`"on"`、`"sentences"`、`"words"`、`"characters"`。
属性	`autocapitalize`
类型	`字符串`
默认值	`'off'`

autocomplete

描述	设置输入的自动完成属性。
属性	`autocomplete`
类型	"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"
默认值	`'off'`

autocorrect

描述	设置输入的自动更正属性。
属性	`autocorrect`
类型	`"off" ｜ "on"`
默认值	`'off'`

cancelButtonIcon

描述	设置取消按钮图标。仅适用于 `md` 模式。默认为 `arrow-back-sharp`。
属性	`cancel-button-icon`
类型	`字符串`
默认值	`config.get('backButtonIcon', arrowBackSharp) as string`

cancelButtonText

描述	设置取消按钮文本。仅适用于 `ios` 模式。
属性	`cancel-button-text`
类型	`字符串`
默认值	`'Cancel'`

clearIcon

描述	设置清除图标。对于 `ios` 默认为 `close-circle`，对于 `md` 默认为 `close-sharp`。
属性	`clear-icon`
类型	`字符串｜未定义`
默认值	`未定义`

颜色

描述	从您的应用程序调色板中使用的颜色。默认选项为：`"primary"`、`"secondary"`、`"tertiary"`、`"success"`、`"warning"`、`"danger"`、`"light"`、`"medium"` 和 `"dark"`。有关颜色的更多信息，请参阅主题。
属性	`颜色`
类型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜字符串｜未定义`
默认值	`未定义`

防抖

描述	设置每次按键后等待触发 `ionInput` 事件的时间（以毫秒为单位）。
属性	`防抖`
类型	`数字｜未定义`
默认值	`未定义`

禁用

描述	如果为 `true`，则用户无法与输入进行交互。
属性	`禁用`
类型	`布尔值`
默认值	`false`

enterkeyhint

描述	浏览器显示哪个 Enter 键的提示。可能的值：`"enter"`、`"done"`、`"go"`、`"next"`、`"previous"`、`"search"` 和 `"send"`。
属性	`enterkeyhint`
类型	`"done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜未定义`
默认值	`未定义`

inputmode

描述	浏览器显示哪个键盘的提示。可能的值：`"none"`、`"text"`、`"tel"`、`"url"`、`"email"`、`"numeric"`、`"decimal"` 和 `"search"`。
属性	`inputmode`
类型	`"decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜未定义`
默认值	`未定义`

maxlength

描述	此属性指定用户可以输入的最大字符数。
属性	`maxlength`
类型	`数字｜未定义`
默认值	`未定义`

minlength

描述	此属性指定用户可以输入的最小字符数。
属性	`minlength`
类型	`数字｜未定义`
默认值	`未定义`

模式

描述	模式决定使用哪个平台样式。
属性	`模式`
类型	`"ios" ｜ "md"`
默认值	`未定义`

名称

描述	如果在表单中使用，请设置控件的名称，该名称将与表单数据一起提交。
属性	`名称`
类型	`字符串`
默认值	`this.inputId`

占位符

描述	设置输入的占位符。`placeholder` 可以接受纯文本或 HTML 作为字符串。要显示通常为 HTML 保留的字符，必须对其进行转义。例如 `<Ionic>` 将变为 `<Ionic>` 有关更多信息：安全文档
属性	`占位符`
类型	`字符串`
默认值	`'Search'`

searchIcon

描述	用作搜索图标的图标。在 `ios` 模式下默认为 `search-outline`，在 `md` 模式下默认为 `search-sharp`。
属性	`search-icon`
类型	`字符串｜未定义`
默认值	`未定义`

showCancelButton

描述	设置取消按钮的行为。默认为 `"never"`。设置为 `"focus"` 将在获得焦点时显示取消按钮。设置为 `"never"` 将隐藏取消按钮。设置为 `"always"` 将始终显示取消按钮，而不管焦点状态如何。
属性	`show-cancel-button`
类型	`"always" ｜ "focus" ｜ "never"`
默认值	`'never'`

showClearButton

描述	设置清除按钮的行为。默认为 `"focus"`。设置为 `"focus"` 将在输入不为空时获得焦点时显示清除按钮。设置为 `"never"` 将隐藏清除按钮。设置为 `"always"` 将始终显示清除按钮，而不管焦点状态如何，但前提是输入不为空。
属性	`show-clear-button`
类型	`"always" ｜ "focus" ｜ "never"`
默认值	`'always'`

spellcheck

描述	如果为 `true`，则在输入上启用拼写检查。
属性	`spellcheck`
类型	`布尔值`
默认值	`false`

类型

描述	设置输入的类型。
属性	`类型`
类型	`"email" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "url"`
默认值	`'search'`

值

描述	搜索栏的值。
属性	`值`
类型	`空｜字符串｜未定义`
默认值	`''`

事件

名称	描述	冒泡
`ionBlur`	当输入失去焦点时发出。	`true`
`ionCancel`	当点击取消按钮时发出。	`true`
`ionChange`	当用户修改元素的值时，`ionChange` 事件会为 `<ion-searchbar>` 元素触发。与 `ionInput` 事件不同，`ionChange` 事件并不一定针对元素值的每次更改而触发。当用户提交值时，`ionChange` 事件将触发。这可能发生在元素失去焦点或按下“Enter”键时。`ionChange` 也可以在点击清除按钮或取消按钮时触发。通过编程方式设置 `value` 属性时，此事件不会发出。	`true`
`ionClear`	当点击清除输入按钮时发出。	`true`
`ionFocus`	当输入获得焦点时发出。	`true`
`ionInput`	当 `ion-searchbar` 元素的 `value` 发生更改时发出。	`true`

方法

getInputElement

描述	返回引擎盖下使用的本机 `<input>` 元素。
签名	`getInputElement() => Promise<HTMLInputElement>`

setFocus

描述	将焦点设置到 `ion-searchbar` 中的本机 `input` 上。使用此方法而不是全局 `input.focus()`。希望在页面进入时聚焦输入的开发人员应在 `ionViewDidEnter()` 生命周期方法中调用 `setFocus()`。希望在显示叠加层时聚焦输入的开发人员应在 `didPresent` 解析后调用 `setFocus`。有关更多信息，请参阅管理焦点。
签名	`setFocus() => Promise<void>`

CSS 阴影部分

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

CSS 自定义属性

名称	描述
`--background`	搜索栏输入的背景
`--border-radius`	搜索栏输入的边框半径
`--box-shadow`	搜索栏输入的盒子阴影
`--cancel-button-color`	搜索栏取消按钮的颜色
`--clear-button-color`	搜索栏清除按钮的颜色
`--color`	搜索栏文本的颜色
`--icon-color`	搜索栏图标的颜色
`--placeholder-color`	搜索栏占位符的颜色
`--placeholder-font-style`	搜索栏占位符的字体样式
`--placeholder-font-weight`	搜索栏占位符的字体粗细
`--placeholder-opacity`	搜索栏占位符的不透明度

名称	描述
`--background`	搜索栏输入的背景
`--border-radius`	搜索栏输入的边框半径
`--box-shadow`	搜索栏输入的盒子阴影
`--cancel-button-color`	搜索栏取消按钮的颜色
`--clear-button-color`	搜索栏清除按钮的颜色
`--color`	搜索栏文本的颜色
`--icon-color`	搜索栏图标的颜色
`--placeholder-color`	搜索栏占位符的颜色
`--placeholder-font-style`	搜索栏占位符的字体样式
`--placeholder-font-weight`	搜索栏占位符的字体粗细
`--placeholder-opacity`	搜索栏占位符的不透明度

插槽

此组件没有可用的插槽。

基本用法​

搜索图标​

清除按钮​

取消按钮​

工具栏中的搜索栏​

防抖​

主题​

颜色​

CSS 自定义属性​

键盘显示​

Android​

iOS​

接口​

SearchbarChangeEventDetail​

SearchbarCustomEvent​

属性​

animated​

autocapitalize​

autocomplete​

autocorrect​

cancelButtonIcon​

cancelButtonText​

clearIcon​

颜色​

防抖​

禁用​

enterkeyhint​

inputmode​

maxlength​

minlength​

模式​

名称​

占位符​

searchIcon​

showCancelButton​

showClearButton​

spellcheck​

类型​

值​

事件​

方法​

getInputElement​

setFocus​

CSS 阴影部分​

CSS 自定义属性​

插槽​

内容

基本用法

搜索图标

清除按钮

取消按钮

工具栏中的搜索栏

防抖

主题

颜色

CSS 自定义属性

键盘显示

Android

iOS

接口

SearchbarChangeEventDetail

SearchbarCustomEvent

属性

animated

autocapitalize

autocomplete

autocorrect

cancelButtonIcon

cancelButtonText

clearIcon

颜色

防抖

禁用

enterkeyhint

inputmode

maxlength

minlength

模式

名称

占位符

searchIcon

showCancelButton

showClearButton

spellcheck

类型

值

事件

方法

getInputElement

setFocus

CSS 阴影部分

CSS 自定义属性

插槽