表格

表格用於使用行和列顯示表格數據。它們允許用戶快速掃描、排序、比較和對大量數據採取行動。

安裝

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

匯入

NextUI 導出 6 個與表格相關的組件

• Table：用於顯示表格的主要組件。
• TableHeader：表格的標題。
• TableBody：表格的主體。
• TableColumn：表格的列。
• TableRow：表格的行。
• TableCell：表格的儲存格。

用法

動態

若要動態渲染表格，您可以使用 columns 屬性來傳遞列，並使用 items 屬性來傳遞資料。

為何不使用陣列 map？

使用 items 屬性並提供渲染函式，可讓 react-aria 自動快取每個項目渲染結果，並避免在僅變更其中一個項目時，重新渲染集合中的所有項目。這對大型集合的效能有很大的好處。

您也可以使用 Array.map 來渲染項目，但其效能不如使用 items 和 columns 屬性。

範例

注意：若要了解更多關於 React Aria 集合以及如何使用它們的資訊，請查看 React Aria 集合。

空狀態

您可以使用 emptyContent 屬性，在表格為空時渲染自訂元件。

無標題

如果您不想渲染標題，可以使用 hideHeader 屬性。

無外框

預設情況下，表格會被包在一個具有小型陰影效果和圓角的 div 元素中。您可以使用 removeWrapper 屬性來移除外框，僅渲染表格。

自訂儲存格

您可以在表格儲存格內渲染任何元件。在下面的範例中，我們根據欄的 key 來渲染不同的元件。

條紋行

您可以使用 isStriped 屬性來渲染條紋行。

單行選取

可以使表格行可選取。要這樣做，您可以使用 selectionMode 屬性。使用 defaultSelectedKeys 來提供預設選取的行集合。

注意：所選鍵的值必須與行的 key 屬性相符。

多行選取

您也可以使用 selectionMode="multiple" 屬性來選取多行。使用 defaultSelectedKeys 來提供預設選取的行集合。

注意：當使用多重選取時，可選取的核取方塊將會渲染在表格的第一欄。

不允許空選取

表格還支援 disallowEmptySelection 屬性，強制使用者在表格中始終至少選取一行。在此模式下，如果選取了單一行，並且使用者再次按下它，則不會取消選取。

受控選取

要以程式方式控制行選取，請使用 selectedKeys 屬性，並搭配 onSelectionChange 回呼函數。當按下行時，選取行的 key 屬性將會傳遞到回呼函數中，讓您可以相應地更新狀態。

注意：selectedKeys 屬性必須是 Set 物件。

已停用行

您可以使用 disabledKeys 屬性來停用行。這將會阻止選取行，如下面的範例所示。

選取行為

預設情況下，表格使用 toggle 選取行為，其行為類似於核取方塊群組：點擊、輕觸或按下 空白鍵 或 Enter鍵 會切換焦點行的選取狀態。

當 selectionBehavior 屬性設定為 replace 時，使用滑鼠點擊一行會將選取狀態替換為僅該行。使用方向鍵會移動焦點和選取狀態。要選取多行，可以使用修飾鍵，例如 Ctrl、Cmd 和 Shift。

列操作

表格透過 onRowAction 回呼函式來支援列操作。在預設的 toggle 選擇行為中，當沒有選取任何項目時，點擊或輕觸列會觸發列操作。

在 replace 選擇行為中，此行為略有不同，單擊會選擇列，而雙擊則會執行操作。

排序列

當按下欄位標頭時，表格支援排序其資料。若要指定 Column 應支援排序，請提供 allowsSorting 屬性。

表格接受 sortDescriptor 屬性，該屬性定義目前要排序的欄位鍵和排序方向（遞增/遞減）。當使用者按下可排序的欄位標頭時，欄位的鍵和排序方向會傳遞到 onSortChange 回呼函式，讓您可以適當地更新 sortDescriptor。

我們建議使用來自 @react-stately/data 的 useAsyncList Hook 來管理資料排序。因此，請確保在使用排序功能之前安裝它。

請注意，我們將 isLoading 和 loadingContent 屬性傳遞給 TableBody，以便在擷取資料時呈現載入狀態。

載入更多資料

表格允許您在表格末尾新增自訂元件，在下面的範例中，我們使用按鈕來載入更多資料。

注意：我們將 isHeaderSticky 傳遞給 Table 元件，以使標頭保持固定。

分頁表格

您可以使用 Pagination 元件來為表格分頁。

非同步分頁

也可以使用 Pagination 元件以非同步方式為表格分頁。為了擷取資料，我們使用來自 SWR 的 useSWR Hook。

無限分頁

表格也支援無限分頁。為此，您可以使用來自 @react-stately/data 的 useAsyncList Hook 和 @nextui-org/use-infinite-scroll Hook。

使用案例範例

建立表格時，通常需要排序、分頁和篩選等核心功能。在下面的範例中，我們結合了所有這些功能來建立一個完整的表格。

插槽

• base：為表格元件定義彈性的欄位配置和相對定位。
• wrapper：套用於最外層的包裝器，提供內邊距、彈性配置、相對定位、視覺樣式和可捲動的溢位處理。
• table：設定表格具有完整最小寬度和自動調整的高度。
• thead：指定表格標頭中第一個子列的圓角。
• tbody：沒有將特定樣式套用於表格的主體。
• tr：表格列的樣式，包括群組焦點、外框屬性和一組未定義的焦點可見類別。
• th：表格標頭的樣式，包括內邊距、文字對齊、字型屬性和可排序欄位的特殊樣式。
• td：套用於表格儲存格，具有內距、對齊和相對定位的屬性，外加用於第一個子元素、選取指示和停用儲存格的特殊樣式。
• tfoot：沒有特定的樣式套用於表格的頁尾。
• sortIcon：排序圖示的樣式，具有基於排序方向和懸停狀態的邊距、不透明度和過渡效果的屬性。
• emptyWrapper：定義空表格的樣式，具有文字對齊、顏色和指定的高度。
• loadingWrapper：表格載入時套用的樣式，將其置於容器的中心位置。

自訂樣式

您可以將自訂的 Tailwind CSS 類別傳遞到元件插槽，來自訂 Table 元件。

資料屬性

TableBody 具有以下屬性

• data-empty：當表格為空時。
• data-loading：當表格資料正在載入時。基於 TableBody 的 isLoading 和 loadingContent 屬性。

TableRow 具有以下屬性

• data-selected：當選取列時。基於 Table 的 selectedKeys 屬性。
• data-disabled：當停用列時。基於 Table 的 disabledKeys 屬性。
• data-hover：當滑鼠懸停在列上時。基於 useHover
• data-focus-visible：當使用鍵盤選取列時。基於 useFocusRing。
• data-first：當列是第一列時。
• data-middle：當列在中間時。
• data-odd：當列是奇數列時。
• data-last：當列是最後一列時。

TableCell 具有以下屬性

• data-selected：當選取儲存格所在的列時。基於 Table 的 selectedKeys 屬性。
• data-focus-visible：當使用鍵盤選取儲存格時。基於 useFocusRing。

輔助功能

• 使用 ARIA 作為網格暴露給輔助技術。
• 透過方向鍵在欄、列、儲存格和儲存格內的可選取元素之間進行鍵盤導覽。
• 透過滑鼠、觸控或鍵盤互動進行單一、多個或無列選取。
• 支援無法選取的停用列。
• 支援欄排序。
• 支援非同步載入、無限捲動、篩選和排序。
• 支援切換和取代選取行為。
• 支援輔助功能的標籤。
• 確保使用 ARIA 即時區域宣告選取。
• 支援將欄標記為列標題，這會在使用螢幕閱讀器瀏覽列時讀取。
• 可選擇在每列中使用核取方塊進行選取，以及在標題中選取所有列。
• 在鍵盤導覽期間自動捲動支援。
• 支援透過雙擊、Enter 鍵或點擊進行列動作。
• 支援透過輸入文字來選取列的預先輸入。
• 當同時存在選取和列動作時，在觸控時長按進入選取模式。

API

表格屬性

表格事件

表格標題屬性

表格欄位屬性

表格主體屬性

表格主體事件

表格列屬性

表格儲存格屬性

表格類型

排序描述符

選取

載入狀態