テーブル

テーブルは、行と列を使用して表形式のデータを表示するために使用されます。これにより、ユーザーは大量のデータをすばやくスキャン、ソート、比較し、アクションを実行できます。

インストール

npx nextui-cli@latest add table

上記のコマンドは個別のインストール専用です。もし @nextui-org/react がグローバルにインストール済みであれば、このステップはスキップできます。

インポート

NextUI は 6 つのテーブル関連コンポーネントをエクスポートします。

• Table: テーブルを表示するためのメインコンポーネント。
• TableHeader: テーブルのヘッダー。
• TableBody: テーブルのボディ。
• TableColumn: テーブルの列。
• TableRow: テーブルの行。
• TableCell: テーブルのセル。

使用方法

動的

テーブルを動的にレンダリングするには、columns プロパティで列を渡し、items プロパティでデータを渡します。

なぜ配列の map ではないのですか？

items プロパティを使用し、レンダリング関数を提供することで、react-aria が各アイテムのレンダリング結果を自動的にキャッシュし、コレクション内の1つのアイテムのみが変更された場合にすべてのアイテムを再レンダリングすることを回避できます。これは、大規模なコレクションの場合、パフォーマンスに大きなメリットをもたらします。

Array.map を使用してアイテムをレンダリングすることもできますが、items と columns プロパティを使用するほどパフォーマンスは高くありません。

例

import {Table, TableHeader, TableColumn, TableBody, TableRow, TableCell, getKeyValue} from "@nextui-org/react";

const rows = [...];

const columns = [...];

export default function App() {
  return (
    <Table aria-label="Example table with dynamic content">
      <TableHeader>
        {columns.map((column) =>
          <TableColumn key={column.key}>{column.label}</TableColumn>
        )}
      </TableHeader>
      <TableBody>
        {rows.map((row) =>
          <TableRow key={row.key}>
            {(columnKey) => <TableCell>{getKeyValue(row, columnKey)}</TableCell>}
          </TableRow>
        )}
      </TableBody>
    </Table>
  );
}

注: React Aria コレクションの詳細とそれらの使用方法については、React Aria コレクション をご確認ください。

空の状態

テーブルが空の場合にカスタムコンポーネントをレンダリングするには、emptyContent プロパティを使用できます。

ヘッダーなし

ヘッダーをレンダリングしたくない場合は、hideHeader プロパティを使用できます。

ラッパーなし

デフォルトでは、テーブルは、小さな影の効果とボーダー半径を持つ div 要素でラップされます。ラッパーを削除してテーブルのみをレンダリングするには、removeWrapper プロパティを使用できます。

カスタムセル

テーブルセル内に任意のコンポーネントをレンダリングできます。以下の例では、列の key に応じて異なるコンポーネントをレンダリングしています。

ストライプ行

ストライプ行をレンダリングするには、isStriped プロパティを使用できます。

単一行選択

テーブル行を選択可能にすることができます。これを行うには、selectionMode プロパティを使用できます。選択された行のデフォルトセットを提供するには、defaultSelectedKeys を使用します。

注: 選択されたキーの値は、行の key プロパティと一致する必要があります。

複数行選択

また、selectionMode="multiple" プロパティを使用することで、複数の行を選択できます。デフォルトで選択された行を設定するには、defaultSelectedKeys を使用します。

注: 複数選択を使用する場合、選択可能なチェックボックスがテーブルの最初の列に表示されます。

空の選択を禁止

テーブルは、disallowEmptySelection プロパティもサポートしており、ユーザーは常にテーブル内で少なくとも1行を選択する必要があります。このモードでは、1行が選択されている状態でユーザーがその行を押しても、選択が解除されることはありません。

選択の制御

プログラムで行選択を制御するには、selectedKeys プロパティと onSelectionChange コールバックを組み合わせて使用します。行が押されると、選択された行の key プロパティがコールバックに渡されるため、状態を適切に更新できます。

注: selectedKeys プロパティは、Set オブジェクトである必要があります。

無効化された行

disabledKeys プロパティを使用すると、行を無効化できます。これにより、以下の例に示すように、行を選択できなくなります。

選択の挙動

デフォルトでは、テーブルは toggle 選択動作を使用します。これは、チェックボックスグループのように動作します。クリック、タップ、または Space または Enter キーを押すと、フォーカスされている行の選択が切り替わります。

selectionBehavior プロパティが replace に設定されている場合、マウスで行をクリックすると、選択はその行のみに置き換えられます。矢印キーを使用すると、フォーカスと選択の両方が移動します。複数行を選択するには、Ctrl、Cmd、Shift などの修飾キーを使用できます。

行アクション

テーブルは、onRowAction コールバックを通じて行アクションをサポートしています。デフォルトの toggle 選択動作では、何も選択されていないときに、行をクリックまたはタップすると行アクションがトリガーされます。

この動作は、replace 選択動作ではわずかに異なります。ここでは、シングルクリックで行を選択し、ダブルクリックでアクションを実行します。

行のソート

テーブルは、列ヘッダーが押されたときにデータのソートをサポートします。Column がソートをサポートする必要があることを指定するには、allowsSorting プロパティを設定します。

テーブルは、ソートに使用する現在の列キーとソート方向（昇順/降順）を定義する sortDescriptor プロパティを受け入れます。ユーザーがソート可能な列ヘッダーを押すと、列のキーとソート方向が onSortChange コールバックに渡されるため、sortDescriptor を適切に更新できます。

データのソートを管理するには、@react-stately/data の useAsyncList フックを使用することをお勧めします。そのため、ソート機能を使用する前にインストールしてください。

npm install @react-stately/data

import {useAsyncList} from "@react-stately/data";

データがフェッチされている間にローディング状態を表示するために、isLoading プロパティと loadingContent プロパティを TableBody に渡したことに注意してください。

データの追加読み込み

テーブルでは、テーブルの末尾にカスタムコンポーネントを追加できます。以下の例では、より多くのデータをロードするためのボタンを使用しています。

注: ヘッダーを固定にするために、isHeaderSticky を Table コンポーネントに渡しました。

ページネーション付きテーブル

テーブルにページネーションを適用するには、Paginationコンポーネントを使用できます。

非同期ページネーション

テーブルのページネーションを非同期で行うことも可能です。データの取得には、Paginationコンポーネントを使用します。データ取得には、useSWRフックをSWRから使用しています。

無限ページネーション

テーブルは無限ページネーションにも対応しています。これを行うには、useAsyncListフックを@react-stately/dataと@nextui-org/use-infinite-scrollフックと組み合わせて使用できます。

使用例

テーブルを作成する際には、通常、ソート、ページネーション、フィルタリングといったコア機能が必要になります。以下の例では、これらの機能をすべて組み合わせて完全なテーブルを作成しています。

スロット

• 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

テーブルプロパティ

テーブルイベント

TableHeader の Props

TableColumn の Props

TableBody の Props

TableBody のイベント

TableRow の Props

TableCell の Props

テーブルの型

ソート記述子

type SortDescriptor = {
  column: React.Key;
  direction: "ascending" | "descending";
};

選択

type Selection = "all" | Set<React.Key>;

読み込み状態

type LoadingState = "loading" | "sorting" | "loadingMore" | "error" | "idle" | "filtering";