已設定範圍
搜尋列代表一個文字欄位，可用於搜尋集合。它們可以顯示在工具列或主要內容中。搜尋清單時應使用搜尋列，而不是輸入欄位。
搜尋圖示顯示在搜尋列輸入欄位的左側。它可以自訂為任何 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;
}
| 描述 | 如果為 true，則啟用搜尋列動畫。 |
| 屬性 | animated |
| 類型 | boolean |
| 預設值 | false |
| 描述 | 表示文字值在使用者輸入/編輯時應如何自動大寫。可用選項："off"、"none"、"on"、"sentences"、"words"、"characters"。 |
| 屬性 | autocapitalize |
| 類型 | string |
| 預設值 | 'off' |
| 描述 | 設定輸入欄位的自動完成屬性。 |
| 屬性 | 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 |
| 類型 | "off" ｜ "on" |
| 預設值 | 'off' |
| 描述 | 設定取消按鈕圖示。僅適用於 md 模式。預設為 arrow-back-sharp。 |
| 屬性 | cancel-button-icon |
| 類型 | string |
| 預設值 | config.get('backButtonIcon', arrowBackSharp) as string |
| 描述 | 設定取消按鈕文字。僅適用於 ios 模式。 |
| 屬性 | cancel-button-text |
| 類型 | string |
| 預設值 | 'Cancel' |
| 描述 | 設定清除圖示。ios 的預設值為 close-circle，md 的預設值為 close-sharp。 |
| 屬性 | clear-icon |
| 類型 | string ｜ undefined |
| 預設值 | undefined |
| 描述 | 要從應用程式的調色盤使用的顏色。預設選項為："primary"、"secondary"、"tertiary"、"success"、"warning"、"danger"、"light"、"medium" 和 "dark"。如需有關顏色的詳細資訊，請參閱主題。 |
| 屬性 | color |
| 類型 | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| 預設值 | undefined |
| 描述 | 設定在每次按鍵後等待觸發 ionInput 事件的時間量（以毫秒為單位）。 |
| 屬性 | debounce |
| 類型 | number ｜ undefined |
| 預設值 | undefined |
| 描述 | 如果為 true，使用者將無法與輸入框互動。 |
| 屬性 | disabled |
| 類型 | boolean |
| 預設值 | false |
| 描述 | 瀏覽器顯示 Enter 鍵的提示。可能的值："enter"、"done"、"go"、"next"、"previous"、"search" 和 "send"。 |
| 屬性 | enterkeyhint |
| 類型 | "done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined |
| 預設值 | undefined |
| 描述 | 瀏覽器顯示鍵盤的提示。可能的值："none"、"text"、"tel"、"url"、"email"、"numeric"、"decimal" 和 "search"。 |
| 屬性 | inputmode |
| 類型 | "decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined |
| 預設值 | undefined |
| 描述 | 此屬性指定使用者可以輸入的最大字元數。 |
| 屬性 | maxlength |
| 類型 | number ｜ undefined |
| 預設值 | undefined |
| 描述 | 此屬性指定使用者可以輸入的最小字元數。 |
| 屬性 | minlength |
| 類型 | number ｜ undefined |
| 預設值 | undefined |
| 描述 | 模式決定要使用的平台樣式。 |
| 屬性 | mode |
| 類型 | "ios" ｜ "md" |
| 預設值 | undefined |
| 描述 | 如果在表單中使用，請設定控制項的名稱，該名稱會隨表單資料一起提交。 |
| 屬性 | name |
| 類型 | string |
| 預設值 | this.inputId |
| 描述 | 設定輸入框的佔位符文字。placeholder 可以接受純文字或 HTML 字串。若要顯示通常為 HTML 保留的字元，必須進行跳脫字元處理。例如，<Ionic> 會變成 <Ionic>。
更多資訊：安全性文件 |
| 屬性 | placeholder |
| 類型 | string |
| 預設值 | '搜尋' |
| 描述 | 用作搜尋圖示的圖示。在 ios 模式下預設為 search-outline，在 md 模式下預設為 search-sharp。 |
| 屬性 | 搜尋圖示 |
| 類型 | string ｜ undefined |
| 預設值 | undefined |
| 描述 | 設定取消按鈕的行為。預設值為 "never"。設定為 "focus" 會在焦點置入時顯示取消按鈕。設定為 "never" 會隱藏取消按鈕。設定為 "always" 會顯示取消按鈕，無論焦點狀態如何。 |
| 屬性 | 顯示取消按鈕 |
| 類型 | "always" ｜ "focus" ｜ "never" |
| 預設值 | 'never' |
| 描述 | 設定清除按鈕的行為。預設值為 "focus"。設定為 "focus" 會在焦點置入時，如果輸入框不為空，則顯示清除按鈕。設定為 "never" 會隱藏清除按鈕。設定為 "always" 會顯示清除按鈕，無論焦點狀態如何，但前提是輸入框不為空。 |
| 屬性 | 顯示清除按鈕 |
| 類型 | "always" ｜ "focus" ｜ "never" |
| 預設值 | 'always' |
| 描述 | 如果為 true，則在輸入框上啟用拼寫檢查。 |
| 屬性 | 拼寫檢查 |
| 類型 | boolean |
| 預設值 | false |
| 描述 | 設定輸入框的類型。 |
| 屬性 | 類型 |
| 類型 | "email" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" |
| 預設值 | 'search' |
| 描述 | 搜尋列的值。 |
| 屬性 | 值 |
| 類型 | null ｜ string ｜ undefined |
| 預設值 | '' |
| 名稱 | 描述 | 冒泡 |
|---|
ionBlur | 當輸入框失去焦點時觸發。 | true |
ionCancel | 當點擊取消按鈕時觸發。 | true |
ionChange | 當使用者修改 <ion-searchbar> 元素的值時，會觸發 ionChange 事件。與 ionInput 事件不同，ionChange 事件不一定會在每次變更元素值時都觸發。
當使用者提交值時，會觸發 ionChange 事件。這可能會在元素失去焦點或按下「Enter」鍵時發生。點擊清除或取消按鈕時，也可能會觸發 ionChange。
當以程式方式設定 value 屬性時，此事件不會觸發。 | true |
ionClear | 當點擊清除輸入按鈕時觸發。 | true |
ionFocus | 當輸入框獲得焦點時觸發。 | true |
ionInput | 當 ion-searchbar 元素的 value 變更時觸發。 | true |
| 描述 | 傳回底層使用的原生 <input> 元素。 |
| 簽章 | getInputElement() => Promise<HTMLInputElement> |
| 描述 | 將焦點設定在 ion-searchbar 中的原生 input 上。請使用此方法，而不是全域的 input.focus()。
希望在頁面進入時讓輸入框獲得焦點的開發人員，應該在 ionViewDidEnter() 生命周期方法中呼叫 setFocus()。
希望在顯示覆蓋層時讓輸入框獲得焦點的開發人員，應該在 didPresent 解析後呼叫 setFocus。
有關更多資訊，請參閱管理焦點。 |
| 簽章 | setFocus() => Promise<void> |
此元件沒有可用的 CSS shadow parts。
| 名稱 | 描述 |
|---|
--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 | 搜尋列佔位符文字的不透明度 |
此元件沒有可用的插槽。