導入ガイド

このガイドでは、Extableをアプリケーションへ統合するための基本事項を解説します。

導入

はじめに

初期化と基本設定の理解には、Basic Usage Demoから始めるのが最短です。

ショートカットキー登録

Undo/Redoのキーボードショートカットを登録します。

typescript

import { ExtableCore } from "@extable/core";

const table = new ExtableCore({
  root: container,
  schema,
  defaultData,
  defaultView: {},
});

// Ctrl+Z / Ctrl+Shift+Z（undo/redo）のキー操作を登録
const onKey = (e: KeyboardEvent) => {
  const key = e.key.toLowerCase();
  const isMod = e.metaKey || e.ctrlKey;
  if (!isMod) return;

  // 取り消し: Ctrl/Cmd+Z
  if (key === "z") {
    if (!table) return;
    e.preventDefault();
    e.stopPropagation();
    if (e.shiftKey) {
      table.redo();  // やり直し: Ctrl/Cmd+Shift+Z
    } else {
      table.undo();  // 取り消し: Ctrl/Cmd+Z
    }
  }
};
document.addEventListener("keydown", onKey, { capture: true });
window.addEventListener("beforeunload", () => {
  document.removeEventListener("keydown", onKey, { capture: true });
});

キーボードショートカット:

Ctrl/Cmd+Z - 直前の変更を取り消し
Ctrl/Cmd+Shift+Z - 取り消しをやり直し

Undo/Redoの詳細はデータアクセスAPIを参照してください。

レイアウトとレスポンシブ設計

テーブルのコンテナは明示的なサイズが必要です。以下に、各フレームワークでのHTML構造、class/style設定、CSS（またはTailwind）の例を示します。

テーブルはコンテナ（#table-root）いっぱいに表示します。親とコンテナに明示的なサイズを持たせ、flexで配置します。

html

<div class="app">
  <aside class="sidebar"><!-- Menu --></aside>
  <div class="main">
    <div class="toolbar"><!-- Controls --></div>
    <div id="table-root"></div>
  </div>
</div>

typescript

const core = new ExtableCore({
  root: document.getElementById("table-root")!,
  defaultData: data,
  schema: schema,
  options: {
    // 任意: デフォルトのクラス/スタイルを適用
    defaultClass: "table-container",
    defaultStyle: { border: "1px solid #e0e0e0" },
  },
});

CSS:

css

.app {
  display: flex;
  height: 100vh;
}

.sidebar {
  width: 250px;
  border-right: 1px solid #e0e0e0;
  overflow-y: auto;
}

.main {
  flex: 1;
  display: flex;
  flex-direction: column;
  min-width: 0;
}

.toolbar {
  padding: 8px 12px;
  border-bottom: 1px solid #e0e0e0;
  flex-shrink: 0;
}

#table-root {
  flex: 1;
  min-height: 0;
}

.table-container {
  /* Applied via options.defaultClass */
}

コンテナ要件

widthとheightを明示（autoは不可）
flex/gridではmin-width: 0とmin-height: 0を設定
コンテナのサイズ変更に自動追従

カスタマイズ

バリデーション - スキーマ制約
編集モード - 特定セル/列の保護
数式 - 計算列の追加
条件付きスタイル - 動的スタイル
スタイル - テーマと見た目

インタラクション設計

アプリの要件に合わせてインタラクションパターンを選びます。
詳細なAPIはデータアクセスAPIを参照してください。

読み取り専用モード

ユーザーは閲覧や検索のみ可能で編集できません。

typescript

const table = new ExtableCore({
  root: container,
  schema,
  defaultData,
  defaultView: {},
  options: {
    editMode: "readonly",  // すべての編集を無効化
  },
});

用途: レポート、ダッシュボード、監査ログ。

直接編集モード

編集は即時反映され、確認操作は不要です（設定されていればサーバーへ即送信）。

typescript

const table = new ExtableCore({
  root: container,
  schema,
  defaultData,
  defaultView: {},
  options: {
    editMode: "direct",  // デフォルト: 変更は即時反映
  },
});

// 行単位の変更を監視
table.subscribeRowState((rowId, event) => {
  if (event === "edit") {
    console.log(`Row ${rowId} was edited - send to server`);
  } else if (event === "new") {
    console.log(`Row ${rowId} was inserted`);
  } else if (event === "delete") {
    console.log(`Row ${rowId} was deleted`);
  }
});

用途: 迅速な入力フォーム、ライブダッシュボード、即時フィードバック。

コミットモード

編集は保留され、ユーザーが明示的にcommitするまで反映されません。

typescript

const table = new ExtableCore({
  root: container,
  schema,
  defaultData,
  defaultView: {},
  options: {
    editMode: "commit",  // 明示的なcommitが必要
  },
});

// 保留変更を監視してUI更新
table.subscribeTableState((state) => {
  const saveButton = document.getElementById("save-btn");
  // 保留がある時だけSaveボタンを有効化
  saveButton!.disabled = !state.canCommit;
  
  console.log(`${state.pendingCellCount} cells pending`);
});

ユーザーが「Save」や「Submit」などをクリックしたとき（アプリ側で実装）:

typescript

async function handleSave() {
  try {
    const changes = await table.commit();
    
    // 差分をサーバーへ送信
    const response = await fetch("/api/table/sync", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ changes }),
    });

    if (response.ok) {
      console.log("Changes saved successfully");
    }
  } catch (error) {
    console.error("Save failed:", error);
  }
}

用途: フォームワークフロー、一括インポート、トランザクション更新、監査対応。

テスト

ユニットテストとE2Eテスト戦略はユニットテストガイドを参照してください。

導入ガイド ​

導入 ​

はじめに ​

ショートカットキー登録 ​

レイアウトとレスポンシブ設計 ​

カスタマイズ ​

インタラクション設計 ​

読み取り専用モード ​

直接編集モード ​

コミットモード ​

テスト ​

導入ガイド

導入

はじめに

ショートカットキー登録

レイアウトとレスポンシブ設計

カスタマイズ

インタラクション設計

読み取り専用モード

直接編集モード

コミットモード

テスト