選擇器

「選取器」會顯示一個可摺疊的選項列表，並允許使用者選擇其中一個或多個選項。

安裝

上述指令僅適用於個別安裝。如果 @nextui-org/react 已全域安裝，您可以略過此步驟。

匯入

NextUI 匯出 3 個與選取器相關的元件

• Select：主要元件，是其他元件的包裝器。
• SelectSection：包含一組選取項目的元件。
• SelectItem：代表一個選取項目的元件。

使用方式

動態項目

選取器遵循集合元件 API，接受靜態和動態集合。

• 靜態：上面的使用範例顯示了靜態實作，當預先知道完整的選項列表時可以使用。
• 動態：當選項來自外部資料來源（例如 API 呼叫）或隨時間更新時，可以使用下面的範例。

多重選取

您可以使用 selectionMode="multiple" 屬性來允許多重選取。

已停用

已停用的項目

您可以使用 disabledKeys 屬性來停用特定項目。

必要

如果您將 isRequired 屬性傳遞給選取器，則標籤的末尾會出現一個 danger 星號，且選取器將會是必要的。

大小

色彩

變體

圓角半徑

標籤位置

您可以透過設定 labelPlacement 屬性為 inside、outside 或 outside-left 來更改標籤的位置。

注意：如果沒有傳遞 label，則 labelPlacement 屬性預設為 outside。

起始內容

您可以使用 startContent 和 endContent 屬性，在選擇器的開頭和結尾新增內容。

項目起始與結束內容

由於 Select 元件底層使用 Listbox 元件，您可以使用 SelectItem 元件的 startContent 和 endContent 屬性，在選項的開頭和結尾新增內容。

自訂選擇器圖示

預設情況下，選擇器使用 chevron-down 圖示作為選擇器圖示，並且在選擇器開啟時旋轉。您可以透過將自訂圖示傳遞給 selectorIcon 屬性來自訂此圖示。

注意：使用 disableSelectorIconRotation 屬性來停用圖示的旋轉。

無捲動陰影

Select 元件底層使用 ScrollShadow 來在選擇器內容可捲動時顯示陰影。您可以使用 scrollShadowProps 屬性來停用此陰影。

注意：您也可以使用 showScrollIndicators 屬性來停用捲動指示器。

含描述

您可以透過傳遞 description 屬性來為選擇器新增描述。

含錯誤訊息

您可以結合 isInvalid 和 errorMessage 屬性來顯示無效的選擇器。

受控模式

您可以使用 selectedKeys 和 onSelectionChange / onChange 屬性來控制選擇器的值。

使用 onSelectionChange

使用 onChange

控制開啟狀態

您可以使用 isOpen 和 onOpenChange / onClose 屬性來控制選單的開啟狀態。

自訂項目

您可以透過修改 SelectItem 的子元件來自訂選單項目。

自訂渲染值

預設情況下，選單會渲染所選項目的文字值，但您可以透過傳遞 renderValue 函式來自訂此行為。

renderValue 函式會接收所選項目作為參數，並且必須回傳一個 ReactNode。請參閱 渲染值函式 章節以取得更多詳細資訊。

非同步載入

選單支援非同步載入，在下面的範例中，我們使用自訂的 hook 來獲取 Pokemon API 的資料，並結合 useInfiniteScroll hook，以便在使用者到達列表末端時載入更多資料。

當資料正在獲取時，會使用 isLoading 屬性來顯示載入指示器，而不是選取器圖示。

虛擬化

選單支援虛擬化，這允許僅渲染視窗中可見的項目，從而有效率地渲染大型列表。您可以將 isVirtualized 屬性設定為 true 來啟用虛擬化。

注意：虛擬化策略基於 @tanstack/react-virtual 套件，該套件透過僅渲染視窗中可見的項目來提供大型列表的有效率渲染。

一萬個項目

以下是一個使用虛擬化處理 10,000 個項目的範例。

最大列表框高度

maxListboxHeight 屬性用於設定列表框的最大高度。在使用虛擬化時，這是必需的。預設情況下，它被設定為 256。

自訂項目高度

itemHeight 屬性用於設定列表框中每個項目的高度。在使用虛擬化時，這是必需的。預設情況下，它被設定為 32。

使用區塊

您可以使用 SelectSection 元件來分組選單項目。

自訂區塊樣式

您可以使用 SelectSection 元件的 classNames 屬性來自訂區塊的樣式。

多選控制

您可以使用與單選相同的屬性來控制多選，例如 selectedKeys 和 onSelectionChange / onChange。

使用 onSelectionChange

使用 onChange

多選搭配標籤 (Chips)

您可以使用 renderValue 屬性，將任何元件呈現為選取的值。在這個範例中，我們使用 Chip 元件來呈現選取的項目。

注意：請確保將 isMultiline 屬性傳遞給 Select 元件，以允許標籤 (chips) 自動換行。

renderValue 函式會接收所選項目作為參數，並且必須回傳一個 ReactNode。請參閱 渲染值函式 章節以取得更多詳細資訊。

自訂選取器

您可以使用 classNames 屬性來自訂選取器的任何插槽。選取器元件也提供 popoverProps 和 listboxProps 屬性來自訂彈出視窗和列表框元件。

插槽

• base：選取器的主要包裝器。它包裝了其餘的插槽。
• label：選取器的標籤。
• mainWrapper：包裝 helperWrapper 和 trigger 插槽。
• trigger：選取器的觸發器。它包裝標籤、內部包裝器和選取器圖示。
• innerWrapper：選取器內容的包裝器。它包裝開始/結束內容和選取的值。
• selectorIcon：選取器的選取器圖示。這是選取器開啟時會旋轉的圖示 (data-open)。
• value：選取的值。這也是包裝 renderValue 函數結果的插槽。
• listboxWrapper：列表框的包裝器。它包裝列表框元件，此插槽用於捲軸陰影元件之上。
• listbox：列表框元件。這是包裝選取項目的元件。
• popoverContent：彈出視窗內容插槽。使用此插槽來修改彈出視窗內容的樣式。
• helperWrapper：輔助文字的包裝器。它包裝輔助文字和錯誤訊息。
• description：選取器的描述。
• errorMessage：選取器的錯誤訊息。

資料屬性

Select 在 base 元素上具有以下屬性

• data-filled：表示選取器是否有值、是否聚焦、是否有開始/結束內容或是否開啟。
• data-has-value：表示選取器是否已選取項目。
• data-has-label：表示選取器是否有標籤。基於 label 屬性。
• data-has-helper：表示選取器是否有輔助文字。基於 errorMessage 或 description 屬性。
• data-invalid：表示選取器是否無效。基於 isInvalid 屬性。

Select 在 trigger 元素上具有以下屬性

• data-open：表示選取器是否開啟。
• data-disabled：當選取器觸發器停用時。基於選取器的 isDisabled 屬性。
• data-focus：當選取器觸發器正在聚焦時。基於 useFocusRing。
• data-focus-visible：當使用鍵盤選取觸發器時。基於 useFocusRing。
• data-pressed：當選取觸發器被按下時。基於 usePress。
• data-hover：當滑鼠游標懸停在選取觸發器上方時。基於 useHover。

Select 在 selectorIcon 元素上具有以下屬性

• data-open：表示選取器是否開啟。

SelectItem 在 base 元素上具有以下屬性

• data-disabled：當選取項目停用時。基於選取 disabledKeys 屬性。
• data-selected：當選取項目被選取時。基於選取 selectedKeys 屬性。
• data-hover：當滑鼠游標懸停在選取項目上方時。基於 useHover。
• data-pressed：當選取項目被按下時。基於 usePress。
• data-focus：當選取項目被選取時。基於 useFocusRing。
• data-focus-visible：當使用鍵盤選取項目時。基於 useFocusRing。

輔助功能

• 透過 ARIA 作為具有列表框彈出視窗的按鈕公開給輔助技術（結合 Listbox）。
• 支援選取單一選項。
• 支援選取多個選項。
• 支援停用的選項。
• 支援區塊。
• 標籤支援輔助功能。
• 支援透過 ARIA 連結至輸入的描述和錯誤訊息說明文字。
• 支援滑鼠、觸控和鍵盤互動。
• Tab 鍵停止焦點管理。
• 鍵盤支援使用方向鍵開啟列表框，包括自動將焦點放在第一個或最後一個項目。
• 輸入式提前選取，即使未開啟列表框，也可透過輸入文字來選取選項。
• 透過隱藏的原生 <select> 元素進行瀏覽器自動填寫整合。
• 行動螢幕閱讀器列表框關閉支援。

API

選取屬性

選取事件

選取項目屬性

請查看 ListboxItem 的屬性。

SelectItem 事件

請查看 ListboxItem 的事件。

SelectSection 屬性

請查看 ListboxSection 的屬性。

類型

渲染值函式

T 類型是傳遞給選擇項目的數據的類型 items。