下拉選單

顯示使用者可以選擇的動作或選項列表。

安裝

上述指令僅適用於單獨安裝。如果已全域安裝 @nextui-org/react ，則可以跳過此步驟。

導入

NextUI 導出 5 個與下拉選單相關的元件

• Dropdown：主要元件，是其他元件的包裝器。此元件是 Popover 元件的擴展，因此它接受 Popover 元件的所有屬性。
• DropdownTrigger：觸發開啟下拉選單的元件。
• DropdownMenu：包含下拉選單項目的元件。
• DropdownSection：包含一組下拉選單項目的元件。
• DropdownItem：代表下拉選單項目的元件。

用法

動態項目

下拉選單遵循 Collection Components API，接受靜態和動態集合。

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

停用的按鍵

可以使用 disabledKeys 屬性來停用 DropdownMenu 元件中的下拉選單項目。

注意：每個項目都必須有一個唯一的鍵值，否則停用的按鍵將不會生效。

動作事件

您可以使用 onAction 屬性來獲取所選項目的鍵值。

變體

您可以使用 DropdownMenu 元件中的 variant 屬性來變更下拉選單項目的 hover 樣式。

單選

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

多選

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

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

帶有快捷鍵

您可以使用 shortcut 屬性來為下拉選單項目新增快捷鍵。

注意：下拉選單不會處理快捷鍵事件，您需要自行處理。

帶有圖示

可以使用 startContent / endContent 屬性來為下拉選單項目新增圖示。

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

帶有描述

您可以使用 description 屬性來為下拉選單項目新增描述。

帶有區塊

您可以使用 DropdownSection 元件來分組下拉選單項目。

注意：沒有 title 的區塊必須提供 aria-label 以確保可訪問性。

自訂觸發器

您可以使用任何元件作為下拉選單的觸發器，只需將其包裝在 DropdownTrigger 元件中即可。

變更背景

如我們先前所述，Dropdown 元件是 Popover 元件的擴充功能，因此它會接受 Popover 元件的所有屬性，包括 backdrop 屬性。

路由

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

插槽

下拉選單有 3 個具有插槽的元件：DropdownMenu、DropdownItem 和 DropdownSection 元件。

DropdownMenu

• base：選單元件的主要包裝器。此插槽包裝 topContent、bottomContent 和 list 插槽。
• list：選單清單元件的插槽。您可以將此插槽視為 ul 插槽。
• emptyContent：當集合為空時要顯示的插槽內容。

DropdownItem

• base：下拉選單項目的主要插槽。它包裝所有其他插槽。
• wrapper：title 和 description 的包裝器。
• title：下拉選單項目的標題。
• description：下拉選單項目的描述。
• shortcut：快捷鍵插槽。
• selectedIcon：選取圖示插槽。只有在選取項目時才會顯示。

DropdownSection

• base：下拉選單區段的主要插槽。它包裝所有其他插槽。
• heading：在區段群組上方呈現的標題。
• group：下拉選單項目的群組。
• divider：在群組之間呈現的分隔線。只有當 showDivider 為 true 時才會顯示。

自訂下拉式彈出視窗

Dropdown 元件是 Popover 元件的延伸，因此您可以使用相同的插槽來自訂下拉選單。

自訂下拉選單項目樣式

您可以使用 DropdownMenu 的 itemClasses 屬性或 DropdownItem 插槽來自訂下拉選單項目。itemClasses 允許您一次自訂所有項目，而插槽允許您個別自訂每個項目。

鍵盤互動

資料屬性

DropdownItem 在 base 元素上具有下列屬性

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

無障礙功能

• 透過 ARIA 作為 button 搭配 menu 暴露給輔助技術。
• 支援單選、多選或不選。
• 支援禁用項目。
• 支援區塊。
• 支援複雜的項目標籤以實現無障礙功能。
• 支援鍵盤導航，包括方向鍵、Home/End、Page Up/Down。詳情請參閱鍵盤互動。
• 在鍵盤導航期間支援自動捲動。
• 支援使用方向鍵開啟選單，包括自動聚焦第一個或最後一個項目。
• 輸入預覽功能，允許透過輸入文字來聚焦項目。
• 虛擬化捲動支援，可提高長列表的效能。

API

下拉式選單屬性

下拉式選單事件

下拉式選單觸發器屬性

下拉式選單內容屬性

下拉式選單內容事件

下拉式選單區塊屬性

下拉式選單項目屬性

下拉式選單項目事件

類型

下拉選單項目選中圖示屬性