Zenn
📘

shadcn-tableを理解する

2024/09/09に公開
datatable
shadcn/ui
shadcn/ui
tech

ゴール

shadcn/uiを利用したDataTableであるShadcn Tableを今後利用しやすくするために以下の項目についてまとめる。（READMEにあることを少し掘り下げたり、補足したりしていく）

  • 機能
  • ローカルでの動かし方
  • 導入の仕方
  • 理解しておくと良さそうなこと

機能

  • サーバサイドでのページ分割、ソート、フィルタリング（useDataTableフック経由）
  • カスタマイズ可能なカラム (dataTable と columns props)
  • 動的なデバウンス検索フィルタとファセットフィルタ (filterFields prop)
  • 検索、フィルタ、アクションを備えた動的なDatatableツールバー
  • Notion likeな、高度なフィルタリング(enableAdvancedFilter prop)
  • Liner likeな、行選択時のフローティング・バー(floatingBar prop)

※内部的にはTanStack Tableを利用している。

おそらくshadcn/uiのDataTableにある、独自コンポーネント構築ガイドにしたがって作られたコンポーネントのため、shadcn/uiを利用してDataTableを構築する時にとても参考になる。

要件に合っていればそのまま利用することもできるだろうし、ベースとして利用することもできる。

ローカルでの動かし方

リポジトリの説明にはDBの準備は書いてないため、その部分を追加した手順をまとめておく。

  1. リポジトリをクローン
    git clone https://github.com/sadmann7/shadcn-table
  2. Dockerを利用して、PostgreSQLを起動
    docker-compose.yml
    name: 'shadcn-table'

services:
  postgres:
    image: postgres:15
    container_name: shadcn-table_postgres
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: P@ssw0rd
      POSTGRES_DB: shadcn-table
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:


    docker compose up -d
  3. pnpmを使って依存関係をインストール
    pnpm install
  4. .env.exampleをコピーして.envにし、変数を更新
    cp .env.example .env
    .env
    DATABASE_URL="postgres://postgres:P@ssw0rd@localhost:5432/shadcn-table"
  5. 開発サーバーを起動
    pnpm run dev
  6. データベーススキーマをプッシュ
    pnpm run db:push
  7. （任意）シードデータの追加
    pnpm run db:seed

導入の仕方

※まだ深くまで理解しきれておらず、うまくまとまってない🙏

利用の仕方や利用しているDB、ライブラリにもよると思うため、ここでは以下の条件の場合に大枠で何をすればいいかをまとめる。

  • 機能については、デフォルトで存在する機能に対して追加・削除は行わない
  • データについては、デフォルトの「タスク」から変更されることを想定する
    • => スキーマ
    • => UIの構成
  • DBやORMが変更されることを想定する

1. フォルダとファイルをプロジェクト内の指定された場所にコピー

  • src/components/data-table => 全部コピー。
  • src/db/index.ts => 利用するDBとORMによる。
  • src/hooks => 全部コピー。
  • src/lib => filter-column.tsだけORMに依存している部分あり。
  • src/types => drizzleの部分のみ、利用するORMによって要不要が変わる。
src/components/data-tableの詳細
  • advanced/ => advanced filter（より高度な絞り込みができる）用のコンポーネントたち
  • data-table-column-header.tsx => ヘッダー
  • data-table-faceted-filter.tsx => 表示カラムのフィルタ
  • data-table-pagination.tsx => ページネーション
  • data-table-skeleton.tsx => フォールバック用のコンポーネント
  • data-table-toolbar.tsx => フィルタや独自の操作を置けるツールバー
  • data-table-view-options.tsx => カラムの表示・非表示コントロール
  • data-table.tsx => ベースとなるコンポーネント

2. 必要なライブラリのインストール

必要なshadcnコンポーネントのインストール

pnpm dlx shadcn@latest init

pnpm dlx shadcn@latest add badge button calendar checkbox command dialog dropdown-menu form input label popover select separator skeleton sonner table toggle-group tooltip

DBやORM周りのパッケージのインストール

何が必要かはDBやORMによるため省略

3. データベース設定

スキーマとバリデーションの設定。
ORMなどによるので省略。

4. クエリとミューテーションの設定

CRUD処理を追加する。

  • 作成
  • 更新
  • 一括更新
  • 削除
  • 一括削除
  • 全取得
  • ステータスごとの数取得（スキーマによる）
  • 優先順位ごとの数取得（スキーマによる）

./_lib/queries.ts、および ./_lib/actions.ts が参考

5. テーブルの操作パーツ作成

パーツとなるもの（以下の形式である必要はないが参考まで）

  • 作成Dialog（参考：./_components/create-task-dialog.tsx）
  • 作成Form（参考：./_components/create-task-form.tsx）
  • 削除Dialog（参考：./_components/delete-tasks-dialog.tsx）
  • ツールバーのアクション（参考：./_components/tasks-table-toolbar-actions.tsx）
  • フローティング バー（参考：./_components/tasks-table-floating-bar.tsx）

※テーブルのカラム定義内で利用するものもある（例：削除Dialogなどは、アクションのセルに含めたりすることがある）

6. テーブルの定義とUI構築

定義

  • テーブルのカラム定義（参考：./_components/tasks-table-columns.tsx）

UI構築

  • テーブルのコンポーネント
    • データの取得部分
    • テーブルのカラムをメモ化（React.useMemoを利用して、不要な再レンダリングを防ぐ）
    • フィルタの設定
    • 初期状態の設定
  • テーブルコンポーネントの呼び出し側
    • データ取得の設定
    • テーブルコンポーネントにデータを渡すようにする

理解しておくと良さそうなこと

構築のされ方や構成について理解が捗りそう

機能を追加したいときに理解していると捗りそう

Discussion