版本：v8

ion-select

陰影

選取器是表單控制項，用於從一組選項中選擇一個或多個選項。當使用者點擊選取器時，會出現一個對話框，其中包含所有選項的大型、易於選擇的列表。

選取器應與子 <ion-select-option> 元素一起使用。如果子選項未給定 value 屬性，則其文字將用作值。

如果在 <ion-select> 上設定了 value，則將根據該值選擇選定的選項。

單一選取

預設情況下，選取器允許使用者僅選擇一個選項。警告介面會向使用者顯示一個帶有單選按鈕樣式的選項清單。選取器元件的值會接收所選選項的值。

單一選取的鍵盤互動會在下方的鍵盤互動區段中說明。

多重選取

透過將 multiple 屬性新增至選取器，使用者可以選擇多個選項。當可以選擇多個選項時，警告、彈出視窗或模態覆蓋會向使用者顯示一個帶有核取方塊樣式的選項清單。選取器元件的值會接收所有選定選項值的陣列。

注意

action-sheet 介面不支援多重選取。

多重選取的鍵盤互動會在下方的鍵盤互動區段中說明。

介面

預設情況下，選取器使用 ion-alert 在警告中開啟選項的覆蓋。可以將介面變更為使用 ion-action-sheet、ion-popover 或 ion-modal，方法是將 action-sheet、popover 或 modal 分別傳遞至 interface 屬性。請繼續閱讀其他章節，瞭解不同介面的限制。

警告

動作選單

回應互動

處理使用者與選取器互動的主要方式是 ionChange、ionDismiss 和 ionCancel 事件。請參閱事件，以瞭解關於這些事件以及選取器引發的其他事件的詳細資訊。

主控台

當從上面的範例記錄時，主控台訊息會顯示在這裡。

物件值參考

當使用物件作為選取值時，如果這些物件來自伺服器或資料庫，則這些物件的識別碼可能會變更，而選定值的識別碼保持不變。例如，當具有所需物件值的現有記錄載入到選取器中時，可能會發生這種情況，但新擷取的選取選項現在具有不同的識別碼。這會導致選取器看起來完全沒有值，即使原始選取仍然存在。

預設情況下，選取器使用嚴格相等 (===) 來判斷是否已選取選項。可以透過向 compareWith 屬性提供屬性名稱或函式來覆寫此設定。

使用 compareWith

主控台

當從上面的範例記錄時，主控台訊息會顯示在這裡。

物件值與多重選擇

主控台

當從上面的範例記錄時，主控台訊息會顯示在這裡。

對齊方式

開發者可以使用 justify 屬性來控制標籤和控制項在一行上的排列方式。

填滿式選取器

Material Design 為選取器提供了填滿樣式。選取器的 fill 屬性可以設定為 "solid" 或 "outline"。

透過將選取器的 mode 設定為 md，可以在 iOS 上使用填滿式選取器。

警告

由於元件之間的樣式衝突，使用 fill 的選取器不應在 ion-item 中使用。

選取按鈕

警示框支援兩個按鈕：Cancel 和 OK。每個按鈕的文字可以使用 cancelText 和 okText 屬性自訂。

action-sheet 和 popover 介面沒有 OK 按鈕，點擊任何選項都會自動關閉覆蓋層並選取該值。popover 介面沒有 Cancel 按鈕，點擊背景會關閉覆蓋層。

modal 介面在標頭中只有一個 Close 按鈕。此按鈕僅負責關閉模態視窗。點擊此按鈕或使用其他方式關閉模態視窗後，任何選取的項目都會保留。

介面選項

由於選取器使用警示框、動作表、快顯視窗和模態介面，因此可以透過 interfaceOptions 屬性將選項傳遞給這些元件。這可以用來傳遞自訂標頭、子標頭、CSS 類別等。

請參閱 ion-alert 文件、ion-action-sheet 文件、ion-popover 文件和 ion-modal 文件，了解每個介面接受的屬性。

注意：interfaceOptions 不會覆寫 alert 介面中的 inputs 或 buttons。

開始和結束插槽

start 和 end 插槽可用於在選取器的兩側放置圖示、按鈕或前綴/後綴文字。如果點擊插槽內容，選取器將不會開啟。

注意

在大多數情況下，放置在這些插槽中的 Icon 元件應具有 aria-hidden="true"。有關更多資訊，請參閱 Icon 無障礙文件。

如果插槽內容旨在互動，則應將其包裝在互動式元素中，例如 Button。這可確保可以使用 tab 鍵瀏覽內容。

自訂

選取器元件由兩個單元組成，每個單元都需要分別設定樣式。ion-select 元素在視圖上由選取的值（或如果沒有選取值，則由預留位置）和下拉圖示表示。介面（在上面的介面部分中定義）是點擊 ion-select 時開啟的對話方塊。介面包含透過新增 ion-select-option 元素定義的所有選項。以下各節將介紹這些樣式設定之間的差異。

設定選取器元素樣式

如前所述，ion-select 元素僅包含顯示在視圖上的值（或預留位置）和圖示。若要自訂此元素，請使用 CSS 和任何 CSS 自訂屬性的組合設定樣式。

或者，根據需要的瀏覽器支援，可以使用 CSS 陰影部分來設定選取器的樣式。請注意，透過使用 ::part，可以鎖定元素上的任何 CSS 屬性。

設定選取器介面樣式

自訂介面對話方塊應遵循該介面文件中的樣式設定章節（CSS 陰影部分、CSS 自訂屬性和插槽）。

但是，選取器選項會設定一個類別以方便設定樣式，並允許將類別傳遞至覆蓋層選項，請參閱選取器選項文件，以取得自訂選項的使用範例。

自訂切換圖示

可以使用 toggleIcon 和/或 expandedIcon 屬性將顯示在選取器文字旁的圖示設定為任何 Ionicon。

圖示翻轉行為

預設情況下，當選取器開啟時，切換圖示會在 md 模式下自動旋轉，並在 ios 模式下保持靜態。可以使用 CSS 自訂此行為。

以下範例還使用自訂 toggleIcon，以更好地展示 ios 上的翻轉行為，因為預設圖示是垂直對稱的。

預輸入元件

可以使用現有的 Ionic 元件建構預輸入或自動完成功能。我們建議使用 ion-modal 來充分利用可用的螢幕空間。

介面

SelectChangeEventDetail

interface SelectChangeEventDetail<T = any> {
  value: T;
}

SelectCustomEvent

雖然不是必需的，但此介面可以用於取代 CustomEvent 介面，以便更強烈地輸入此元件發出的 Ionic 事件。

interface SelectCustomEvent<T = any> extends CustomEvent {
  detail: SelectChangeEventDetail<T>;
  target: HTMLIonSelectElement;
}

從舊版選取器語法遷移

Ionic 7.0 中引入了更簡潔的選取器語法。這個新語法減少了設定選取器所需的樣板程式碼、解決了無障礙問題，並改善了開發人員體驗。

開發人員可以一次執行一個選取器的遷移。雖然開發人員可以繼續使用舊版語法，但我們建議盡快遷移。

使用現代語法

使用現代語法包含兩個步驟

移除 ion-label 並改為使用 ion-select 上的 label 屬性。可以使用 ion-select 上的 labelPlacement 屬性設定標籤的放置位置。
將 fill 和 shape 的任何使用方式從 ion-item 移動到 ion-select 上。

JavaScript
Angular
React
Vue

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->
<ion-item>
  <ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->
<ion-item>
  <ion-select label="Favorite Fruit:" labelPlacement="floating">...</ion-select>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</ion-select>

{/* Label and Label Position */}

{/* Before */}
<IonItem>
  <IonLabel position="floating">Favorite Fruit:</IonLabel>
  <IonSelect>...</IonSelect>
</IonItem>

{/* After */}
<IonItem>
  <IonSelect label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>
</IonItem>


{/* Fill */}

{/* Before */}
<IonItem fill="outline" shape="round">
  <IonLabel position="floating">Favorite Fruit:</IonLabel>
  <IonSelect>...</IonSelect>
</IonItem>

{/* After */}

{/* Inputs using `fill` should not be placed in IonItem */}
<IonSelect fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->
<ion-item>
  <ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Favorite Fruit:</ion-label>
  <ion-select>...</ion-select>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>

使用舊版語法

Ionic 使用啟發式方法來偵測應用程式是否正在使用現代選取器語法。在某些情況下，最好繼續使用舊版語法。開發人員可以將 ion-select 上的 legacy 屬性設定為 true，以強制該輸入實例使用舊版語法。

無障礙功能

鍵盤互動

Ionic 的鍵盤互動遵循網頁的實作模式，而不是原生 iOS 選取器，以便在所有平台上獲得一致的體驗。

當滿足以下條件時，這些鍵盤互動適用於所有 ion-select 元素

選取器已關閉。
選取器已聚焦。
選取器未停用。

按鍵	描述
`Enter`	開啟覆蓋層並聚焦於第一個選取的選項。如果沒有選取的選項，則會聚焦於第一個選項。
`空格鍵`	開啟覆蓋層並聚焦於第一個選取的選項。如果沒有選取的選項，則會聚焦於第一個選項。

單選

單選鍵盤互動遵循 ARIA 的單選按鈕實作模式。

當覆蓋層呈現且聚焦時，這些鍵盤互動適用於 ion-action-sheet、ion-alert、ion-popover 和 ion-modal 元素。

按鍵	描述
`向下箭頭`	聚焦並選取清單中的下一個選項。如果沒有下一個選項，則選取會循環到第一個選項。
`向左箭頭`	聚焦並選取清單中的上一個選項。如果沒有上一個選項，則選取會循環到最後一個選項。
`向右箭頭`	聚焦並選取清單中的下一個選項。如果沒有下一個選項，則選取會循環到第一個選項。
`向上箭頭`	聚焦並選取清單中的上一個選項。如果沒有上一個選項，則選取會循環到最後一個選項。
`Enter`	如果選項已聚焦，則會選取該選項。沒有「確定」按鈕的覆蓋層會立即提交該值、關閉覆蓋層，並將焦點返回到 `ion-select` 元素。如果「確定」按鈕已聚焦，則會儲存使用者的選取項目、關閉覆蓋層，並將焦點返回到 `ion-select` 元素。
`Escape`	關閉覆蓋層，而不變更提交的選項。將焦點返回到 `ion-select` 元素。
`空格鍵`	如果焦點在未選取的單選按鈕上，則會取消選取目前已選取的單選按鈕，並選取焦點所在的單選按鈕。否則，不做任何動作。如果覆蓋層沒有「確定」按鈕，則會立即提交值並關閉覆蓋層。
`Tab 鍵`	將焦點移至覆蓋層上，下一個可聚焦的元素（取消按鈕、「確定」按鈕、選取項目或第一個選項）。如果下一個可聚焦的元素是選項，則焦點將會放在已選取的選項上，否則將會放在第一個選項上。

多重選取

多重選取鍵盤互動遵循核取方塊的 ARIA 實作模式。

這些鍵盤互動適用於當覆蓋層顯示且啟用多重選取時的 ion-alert、ion-popover 和 ion-modal 元素。

按鍵	描述
`Enter`	當焦點在「確定」按鈕上時，它將會儲存使用者的選取項目、關閉覆蓋層，並將焦點返回 `ion-select` 元素。
`Escape`	關閉覆蓋層，而不變更提交的選項。將焦點返回到 `ion-select` 元素。
`空格鍵`	選取或取消選取目前焦點所在的選項。這不會取消選取其他已選取的選項。如果覆蓋層沒有「確定」按鈕，則會立即提交值。
`Tab 鍵`	將焦點移至覆蓋層上的下一個可聚焦的元素（取消按鈕、「確定」按鈕或任何選項）。如果下一個可聚焦的元素是選項列表，則它應該逐一迭代每個選項。

屬性

cancelText

描述	要在取消按鈕上顯示的文字。
屬性	`cancel-text`
類型	`字串`
預設值	`'取消'`

color

描述	要從應用程式的調色盤中使用的顏色。預設選項為：`"primary"`、`"secondary"`、`"tertiary"`、`"success"`、`"warning"`、`"danger"`、`"light"`、`"medium"` 和 `"dark"`。有關顏色的更多資訊，請參閱主題。此屬性僅在使用現代 select 語法時可用。
屬性	`color`
類型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜字串｜ undefined`
預設值	`undefined`

compareWith

描述	此屬性允許開發人員指定自訂函數或屬性名稱，以便在判斷 ion-select 中選取的選項時比較物件。如果未指定，預設行為將使用嚴格相等 (===) 進行比較。
屬性	`compare-with`
類型	`((currentValue: any, compareValue: any) => boolean) ｜ null ｜字串｜ undefined`
預設值	`undefined`

disabled

描述	如果為 `true`，使用者將無法與選取器互動。
屬性	`disabled`
類型	`布林值`
預設值	`false`

expandedIcon

描述	當選取器開啟時要顯示的切換圖示。如果已定義，則 `md` 模式中的圖示旋轉行為將會停用。如果未定義，當選取器開啟和關閉時，都將使用 `toggleIcon`。
屬性	`expanded-icon`
類型	`字串｜ undefined`
預設值	`undefined`

fill

描述	項目的填滿方式。如果為 `"solid"`，則項目將具有背景。如果為 `"outline"`，則項目將為透明且具有邊框。僅在 `md` 模式中可用。
屬性	`fill`
類型	`"outline" ｜ "solid" ｜ undefined`
預設值	`undefined`

interface

描述	選取器應使用的介面：`action-sheet`、`popover`、`alert` 或 `modal`。
屬性	`interface`
類型	`"action-sheet" ｜ "alert" ｜ "modal" ｜ "popover"`
預設值	`'alert'`

interfaceOptions

描述	`alert`、`action-sheet` 或 `popover` 介面可以採用的任何其他選項。請參閱ion-alert 文件、ion-action-sheet 文件、ion-popover 文件和ion-modal 文件，以取得每個介面的建立選項。注意：`interfaceOptions` 不會覆寫 `alert` 介面中的 `inputs` 或 `buttons`。
屬性	`interface-options`
類型	`any`
預設值	`{}`

justify

描述	如何在同一行中對齊標籤和選取器。當 `labelPlacement` 設定為 `"floating"` 或 `"stacked"` 時，如果標籤和選取器位於不同行，則 `justify` 不適用。`"start"`：標籤和選取器在 LTR 中將顯示在左側，在 RTL 中將顯示在右側。`"end"`：標籤和選取器在 LTR 中將顯示在右側，在 RTL 中將顯示在左側。`"space-between"`：標籤和選取器將顯示在該行的相對兩端，兩者之間有空間。
屬性	`justify`
類型	`"end" ｜ "space-between" ｜ "start" ｜ undefined`
預設值	`undefined`

label

描述	與選取器關聯的可見標籤。如果需要呈現純文字標籤，請使用此項。如果同時使用 `label` 屬性和 `label` 插槽，則 `label` 屬性將優先。
屬性	`label`
類型	`字串｜ undefined`
預設值	`undefined`

labelPlacement

描述	標籤相對於選取器的放置位置。`"start"`：標籤在 LTR 中將顯示在選取器的左側，在 RTL 中將顯示在右側。`"end"`：標籤在 LTR 中將顯示在選取器的右側，在 RTL 中將顯示在左側。`"floating"`：當選取器具有焦點或有值時，標籤會顯示較小且在選取器的上方。否則，它將顯示在選取器的上方。`"stacked"`：標籤會顯示較小且在選取器的上方，即使選取器失去焦點或沒有值時也是如此。`"fixed"`：標籤的行為與 `"start"` 相同，只是它也具有固定寬度。長文字將會使用省略符號 ("...") 截斷。當使用 `"floating"` 或 `"stacked"` 時，我們建議使用 `value` 或 `placeholder` 初始化選取器。
屬性	`label-placement`
類型	`"end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" ｜ undefined`
預設值	`'start'`

mode

描述	模式決定要使用的平台樣式。
屬性	`mode`
類型	`"ios" ｜ "md"`
預設值	`undefined`

multiple

描述	如果為 `true`，則選取器可以接受多個值。
屬性	`multiple`
類型	`布林值`
預設值	`false`

name

描述	控制項的名稱，會與表單資料一起提交。
屬性	`name`
類型	`字串`
預設值	`this.inputId`

okText

描述	要在確定按鈕上顯示的文字。
屬性	`ok-text`
類型	`字串`
預設值	`'確定'`

placeholder

描述	當選取器為空時要顯示的文字。
屬性	`placeholder`
類型	`字串｜ undefined`
預設值	`undefined`

selectedText

描述	要顯示的文字，而非選取選項的值。
屬性	`selected-text`
類型	`null ｜字串｜ undefined`
預設值	`undefined`

shape

描述	選取器的形狀。如果為「圓形」，則邊框半徑將會增加。
屬性	`shape`
類型	`"round" ｜ undefined`
預設值	`undefined`

toggleIcon

描述	要使用的切換圖示。預設為 `ios` 模式的 `chevronExpand`，或 `md` 模式的 `caretDownSharp`。
屬性	`toggle-icon`
類型	`字串｜ undefined`
預設值	`undefined`

value

描述	選取器的值。
屬性	`value`
類型	`any`
預設值	`undefined`

事件

名稱	描述	冒泡
`ionBlur`	當選取器失去焦點時發出。	`true`
`ionCancel`	當選取項目被取消時發出。	`true`
`ionChange`	當值變更時發出。當以程式方式設定 `value` 屬性時，不會發出此事件。	`true`
`ionDismiss`	當覆蓋層關閉時發出。	`true`
`ionFocus`	當選取器具有焦點時發出。	`true`

方法

open

描述	開啟選取器覆蓋層。覆蓋層是警示、動作表單或彈出視窗，取決於 `ion-select` 上的 `interface` 屬性。
簽名	`open(event?: UIEvent) => Promise<any>`

CSS 陰影部分

名稱	描述
`container`	選取的文字或預留位置的容器。
`icon`	選取器圖示容器。
`label`	label
`placeholder`	描述選取器的標籤文字。
`placeholder`	當沒有值時，在選取器中顯示的文字。

text

名稱	描述
`選取器的顯示值。`	CSS 自訂屬性
`--background`	選取器的背景
`--border-color`	選取器邊框的顏色
`--border-radius`	選取器邊框的半徑。當使用 fill="outline" 時，大的半徑可能會顯示不均勻；如果需要，請改用 shape="round" 或增加 --padding-start。
`--border-style`	選取器邊框的樣式
`--border-width`	選取器邊框的寬度
`--highlight-color-focused`	當具有焦點時，選取器上醒目提示的顏色
`--highlight-color-invalid`	當無效時，選取器上醒目提示的顏色
`--highlight-color-valid`	當有效時，選取器上醒目提示的顏色
`--highlight-height`	選取器上醒目提示的高度。僅適用於 md 模式。
`--padding-bottom`	選取器的底部邊距
`--padding-end`	如果方向是從左到右，則為選取器的右邊距，如果方向是從右到左，則為左邊距
`--padding-start`	如果方向是從左到右，則為選取器的左邊距，如果方向是從右到左，則為右邊距
`--padding-top`	選取器的頂部邊距
`--placeholder-color`	選取器預留位置文字的顏色
`--placeholder-opacity`	選取器預留位置文字的不透明度

名稱	描述
`選取器的顯示值。`	CSS 自訂屬性
`--background`	選取器的背景
`--border-color`	選取器邊框的顏色
`--border-radius`	選取器邊框的半徑。當使用 fill="outline" 時，大的半徑可能會顯示不均勻；如果需要，請改用 shape="round" 或增加 --padding-start。
`--border-style`	選取器邊框的樣式
`--border-width`	選取器邊框的寬度
`--highlight-color-focused`	當具有焦點時，選取器上醒目提示的顏色
`--highlight-color-invalid`	當無效時，選取器上醒目提示的顏色
`--highlight-color-valid`	當有效時，選取器上醒目提示的顏色
`--highlight-height`	選取器上醒目提示的高度。僅適用於 md 模式。
`--padding-bottom`	選取器的底部邊距
`--padding-end`	如果方向是從左到右，則為選取器的右邊距，如果方向是從右到左，則為左邊距
`--padding-start`	如果方向是從左到右，則為選取器的左邊距，如果方向是從右到左，則為右邊距
`--padding-top`	選取器的頂部邊距
`--placeholder-color`	選取器預留位置文字的顏色
`--placeholder-opacity`	選取器預留位置文字的不透明度

--ripple-color

名稱	描述
`MD 模式下漣漪效果的顏色。`	插槽
`label`	end
`在選取器的尾端顯示的內容。`	label

標籤​

標籤位置​

標籤插槽​

無可見標籤​

單一選取​

多重選取​

介面​

警告​

動作選單​

彈出視窗​

模態框​

回應互動​

物件值參考​

使用 compareWith​

物件值與多重選擇​

對齊方式​

填滿式選取器​

選取按鈕​

介面選項​

開始和結束插槽​

自訂​

設定選取器元素樣式​

設定選取器介面樣式​

自訂切換圖示​

圖示翻轉行為​

預輸入元件​

介面​

SelectChangeEventDetail​

SelectCustomEvent​

從舊版選取器語法遷移​

使用現代語法​

使用舊版語法​

無障礙功能​

鍵盤互動​

單選​

多重選取​

屬性​

cancelText​

color​

compareWith​

disabled​

expandedIcon​

fill​

interface​

interfaceOptions​

justify​

label​

labelPlacement​

mode​

multiple​

name​

okText​

placeholder​

selectedText​

shape​

toggleIcon​

value​

事件​

方法​

open​

CSS 陰影部分​

text

--ripple-color

在選取器的前端顯示的內容。

標籤

標籤位置

標籤插槽

無可見標籤

單一選取

多重選取

介面

警告

動作選單

彈出視窗

模態框

回應互動

物件值參考

使用 compareWith

物件值與多重選擇

對齊方式

填滿式選取器

選取按鈕

介面選項

開始和結束插槽

自訂

設定選取器元素樣式

設定選取器介面樣式

自訂切換圖示

圖示翻轉行為

預輸入元件

介面

SelectChangeEventDetail

SelectCustomEvent

從舊版選取器語法遷移

使用現代語法

使用舊版語法

無障礙功能

鍵盤互動

單選

多重選取

屬性

cancelText

color

compareWith

disabled

expandedIcon

fill

interface

interfaceOptions

justify

label

labelPlacement

mode

multiple

name

okText

placeholder

selectedText

shape

toggleIcon

value

事件

方法

open

CSS 陰影部分