列表框 (Listbox)

列表框會顯示選項列表，並允許使用者選擇其中一個或多個選項。

安裝

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

導入

NextUI 匯出 3 個與列表框相關的元件

• Listbox：主要元件，是其他元件的包裝器。
• ListboxSection：包含一組列表框項目的元件。
• ListboxItem：表示列表框項目的元件。

用法

動態項目

列表框遵循 Collection Components API，接受靜態和動態集合。

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

停用的索引鍵

可以使用 disabledKeys 屬性來停用列表框項目，此屬性屬於 Listbox 元件。

注意：每個項目都必須有一個唯一的索引鍵，否則停用的索引鍵將無法運作。

變體

您可以使用 Listbox 元件中的 variant 屬性來變更列表框項目的 hover 樣式。

單選

您可以將 selectionMode 屬性設定為 single，以允許使用者一次僅選擇一個項目。

多選

您可以將 selectionMode 屬性設定為 multiple，以允許使用者一次選擇多個項目。

注意：若要允許空選，您可以將 disallowEmptySelection 屬性設定為 false。

帶有圖示

可以使用 startContent / endContent 屬性在列表框項目中添加圖示。

注意：如果使用 currentColor 作為圖示顏色，則圖示的顏色會與項目文字的顏色相同。

帶有描述

您可以使用 description 屬性為列表框項目添加描述。

帶有頂部和底部內容

您可以使用 topContent 和 bottomContent 屬性在列表框項目的上方和下方添加內容。

帶有區塊

您可以使用 ListboxSection 元件對列表框項目進行分組。

注意：沒有 title 的區塊必須提供 aria-label 以實現輔助功能。

路由

<ListboxItem> 元件可與框架和客戶端路由（例如 Next.js 和 React Router）一起使用。請參閱路由指南，了解如何設定。

虛擬化

選擇支援虛擬化，透過僅呈現視窗中可見的項目，來實現大型列表的有效渲染。您可以將 isVirtualized 屬性設定為 true 來啟用虛擬化。

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

一萬個項目

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

插槽

列表框 (Listbox) 具有 3 個帶有插槽的元件，分別是基礎的 Listbox、ListboxItem 和 ListboxSection 元件。

Listbox

• base (基礎)：列表框元件的主要包裝器。此插槽包裹 topContent、bottomContent 和 list 插槽。
• list (列表)：列表框元件的列表插槽。您可以將此插槽視為 ul 插槽。
• emptyContent (空內容)：當集合為空時要顯示的插槽內容。

ListboxItem

• base (基礎)：列表框項目的主要插槽。它包裹所有其他插槽。
• wrapper (包裝器)：title 和 description 的包裝器。
• title (標題)：列表框項目的標題。
• description (描述)：列表框項目的描述。
• selectedIcon (選取圖示)：選取圖示插槽。只有在選取項目時才會顯示。

ListboxSection

• base (基礎)：列表框區段的主要插槽。它包裹所有其他插槽。
• heading (標題)：在區段群組頂部呈現的標題。
• group (群組)：列表框項目的群組。
• divider (分隔線)：在群組之間呈現的分隔線。只有在 showDivider 為 true 時才會顯示。

自訂列表框

您可以使用 itemClasses 屬性並傳遞自訂的 Tailwind CSS 類別，來自訂 Listbox 項目樣式。

注意：在以上範例中，我們使用了 Boxicons 圖示集合。

鍵盤互動

資料屬性

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

• data-disabled：當列表框項目被停用時。基於列表框 disabledKeys 屬性。
• data-selected：當選取列表框項目時。基於列表框 selectedKeys 屬性。
• data-selectable：當列表框項目可選取時。基於列表框 selectionMode 屬性。
• data-hover：當滑鼠游標懸停在列表框項目上時。基於 useHover
• data-pressed：當按下列表框項目時。基於 usePress
• data-focus：當列表框項目取得焦點時。基於 useFocusRing。
• data-focus-visible：當使用鍵盤將焦點放在列表框項目上時。基於 useFocusRing。

協助工具

• 使用 ARIA 作為 listbox 向輔助技術公開。
• 支援單選、多選或不選。
• 支援停用的項目。
• 支援區段。
• 支援協助工具標籤。
• 支援滑鼠、觸控和鍵盤互動。
• Tab 鍵停靠點焦點管理。
• 鍵盤導航支援，包括方向鍵、Home/End、Page Up/Down、全選和清除。
• 鍵盤導航期間自動捲動支援。
• 輸入預選功能，允許透過輸入文字來聚焦選項。

API

Listbox 屬性

Listbox 事件

ListboxSection 屬性

ListboxItem 屬性

ListboxItem 事件

類型

Listbox 項目選取圖示屬性