SpreadsheetGrid props

SpreadsheetGrid props (SpreadsheetGridProps<T>)

バーの表示制御(top / bottom)

トップ / ボトムバーは次の優先順で解決される。

• showTopBar / showBottomBar(マスタースイッチ): false ならそのバーは一切描画されない(render* / enable* より優先)。
• renderTopBar / renderBottomBar(カスタム): 指定時はそのまま描画。トップバーの内訳 props(showTopBarSummary / showTopBarFilter)はカスタム側が中身を決めるため関与しない。
• 既定バー: render* 未指定時のフォールバック。

既定トップバーは summary chips(左) と グローバルフィルター入力(右) の 2 パートからなり、独立に出し分けできる。

showTopBarSummary と showTopBarFilter(実効は showTopBarFilter && enableGlobalFilter)がともに false の場合、既定トップバーは描画されない(空バーを出さない)。

ボトムバーは Rows / Columns 件数のみ showBottomBarCounts で出し分けできる(右側の Active / Selection / 選択統計 / Cols は対象外)。それ以外の内訳を変えたい場合は renderBottomBar を使う。

コンテキストメニュー(enableContextMenu / getContextMenuItems)

セル / 行の右クリックで開く完全カスタムメニュー。既定は OFF(enableContextMenu={false})で、他機能の enable* と同じくマスタースイッチで有効化する(現状はまだ機能 / UI に改善余地があるため既定 OFF)。ライブラリは固定項目を一切持たず、getContextMenuItems が返した項目配列だけを描画する。用意されるのは「窓」(パネル外装 + 右クリック座標配置 + 開閉 / Escape / 外側クリック / スクロール close)だけで、中身(ラベル / アイコン / onSelect)はすべて利用側が渡す。列メニューと同じ .ssg-menu-panel / .ssg-menu-item 外装を再利用する。

opt-in と標準メニューへのフォールスルー

• enableContextMenu 未設定 / false(既定)→ ブラウザ標準の右クリックメニュー(getContextMenuItems を渡していても発火しない)。
• enableContextMenu={true} かつ getContextMenuItems が項目を返した → その項目が並んだメニューを右クリック座標に表示。
• enableContextMenu={true} でも getContextMenuItems 未指定 / [] を返した(対象で項目なし)→ ブラウザ標準メニュー(空パネルは浮かせない)。

対象と挙動

• ヘッダー右クリックは対象外(列メニュー enableColumnMenu が担当)。本メニューはボディの データセルと 行NO ガター専用。
• SSRM 未ロード行(まだ取得できていない行)の上では開かない(標準メニューになる)。
• uncontrolled のみ。右クリックしてもセル選択は変化しない(対象セル/行の情報は params で受け取る)。
• close 契機: 項目選択 / 外側クリック / Escape / スクロール。項目間のキーボード移動(矢印キー)は持たない。

GridContextMenuParams<T>(コールバック引数)

GridContextMenuItem(判別共用体)

• action(既定): { kind?: 'action'; id?; label: ReactNode; icon?: ReactNode; disabled?; danger?; onSelect: () => void } — クリックで onSelect 実行後に自動で閉じる。icon 省略時も左 14px 枠が空スペーサになりラベル左端が揃う。danger は削除など危険操作の赤系強調(Mantine の color="red" 相当)。
• label(見出し): { kind: 'label'; id?; label: ReactNode } — 非インタラクティブなセクション見出し(Mantine の Menu.Label 相当)。項目群のグルーピング表示に使う。
• separator: { kind: 'separator'; id? } — 区切り線(Mantine の Menu.Divider 相当)。
• custom(レンダラ / エスケープハッチ): { kind: 'custom'; id?; render: (ctx: { close: () => void }) => ReactNode } — パネル内に任意 JSX を差し込む。close() で任意タイミングに閉じられる。

id は React key 用(省略時は配列 index)。項目は非ジェネリック: 行データは getContextMenuItems 内で params を通じてクロージャに閉じ込める。

例

<SpreadsheetGrid
  // …
  enableContextMenu // 既定 false。機能を使うにはこのマスタースイッチが必要
  getContextMenuItems={(params) => {
    const items: GridContextMenuItem[] = [];
    items.push({ kind: 'label', label: '操作' }); // セクション見出し
    if (params.target.type === 'cell') {
      const value = params.target.value; // narrowing はローカルへ退避してから onSelect で使う
      items.push({
        label: '値をコピー',
        icon: '📋',
        onSelect: () => navigator.clipboard?.writeText(String(value ?? '')),
      });
    }
    items.push({ kind: 'separator' });
    items.push({
      label: 'この行を削除',
      danger: true, // 赤系強調
      onSelect: () => deleteRow(params.target.rowKey),
    });
    items.push({ kind: 'separator' });
    items.push({
      label: '選択範囲を CSV 出力',
      disabled: !params.isTargetSelected,
      onSelect: () => gridRef.current?.downloadCsv('selection.csv', { scope: 'selection' }),
    });
    items.push({
      kind: 'custom',
      render: ({ close }) => (
        <div style={{ padding: '6px 8px' }}>
          行 {params.target.rowIndex}
          <button type="button" onClick={close}>閉じる</button>
        </div>
      ),
    });
    return items; // [] を返すと標準メニューへフォールスルー
  }}
  onContextMenuOpen={(params) => console.log('opened at', params.target)}
/>

レシピ: 右クリックからフィルター管理パネルを開く

適用中フィルターの一覧 / 編集 / クリアを行うフィルター管理パネル(列メニュー「フィルターを管理…」と同じもの)は、ハンドルの openFilterManager() で任意の場所から開ける。コンテキストメニューに載せる場合:

const gridRef = useRef<SpreadsheetGridHandle<Row>>(null);

<SpreadsheetGrid
  ref={gridRef}
  enableContextMenu
  getContextMenuItems={() => [
    {
      label: 'フィルターを管理…',
      onSelect: () => gridRef.current?.openFilterManager(),
    },
  ]}
/>;

スクロール位置インジケーター(scrollHint)

大量行(特に 100 万行級)ではスクロールバー 1px の移動が数百〜数千行に相当し、移動中に「今どの行にいるか」を見失う。scrollHint は次の 3 つのオーバーレイでこれに答える(既定は完全無効。opt-in)。

• 行番号バブル(bubble): スクロール中、スクロールバー脇(サム位置)に「行 N / 総行数」を表示。hintColumn / renderHint で任意の列値を添えられる。
• 行目盛りルーラー(ruler): ボディ右端に行数スケール(切りのよい刻み。刻みが 1 万の倍数のときは「10万」等の圧縮表記へ全目盛り統一)。スクロール中とスクロールバー帯ホバー中のみフェード表示。
• ジャンプ先プレビュー(ruler に含む): スクロールバー帯(右端)にポインタを置くと、スクロールバーのクリック / ドラッグと同じサム中心写像で「行 N へ」の点線 + ラベルを表示。
• カスタムスクロールバー(scrollbar): ヘッダー下から始まる専用ガターに常時表示のトラック + 最小 30px サムを自前描画(ドラッグ / クリックジャンプ / ホイール対応)。macOS のオーバーレイスクロールバーは自動で消え、大量行ではサムが極小になり「掴む場所」を見失うための置き換え。有効時はネイティブ縦スクロールバーを非表示化する(Chromium / WebKit。Firefox はネイティブ縦バーが残るがガター操作は有効)。

ScrollHintOptions<T>:

// 簡易: 行番号 + 品番
<SpreadsheetGrid scrollHint={{ hintColumn: 'partNo' }} />

// 完全カスタム: 品番 — 品名
<SpreadsheetGrid
  scrollHint={{
    trigger: 'scroll',
    renderHint: ({ rowData }) =>
      rowData ? `${rowData.partNo} — ${rowData.partName}` : null,
  }}
/>

データ量ゲート(minRows): 小規模データではバブル / ルーラー / カスタムスクロールバーがノイズになるため、minRows を指定すると「表示行数がしきい値以上のときだけ出る」挙動にできる(例: scrollHint={{ minRows: 100 }})。判定はバブルの「/ 総行数」と同じ行数(フィルター / グルーピング適用後のビュー行数。SSRM はサーバー総行数)で、フィルターで絞り込んでしきい値を割ればその間は自動 OFF になる。既定は 0(常時有効)。注意: scrollbar 有効時はしきい値またぎでガター余白が付け外しされるため、行数が変動する画面では僅かなレイアウトシフトが起きる(気になる場合は scrollbar: false と併用する)。

SSRM / グルーピングでの挙動: バブル / プレビューの対象行が SSRM の未ロード行(またはグルーピングのグループ行)の場合、rowData は undefined になり、hintColumn 指定時は自動的に行番号のみへフォールバックする(renderHint には undefined がそのまま渡るので利用側で分岐する)。総行数とスクロール位置だけで駆動されるため、インジケーター自体は SSRM を含む全構成で動作する。

実装ノート: 行番号は仮想化の縦ジオメトリ(1M 行の pixel scaling / auto-height の prefix-sum)と同一の写像で解決するため常に正確。バブル / ルーラー / プレビューのオーバーレイは pointer-events: none で、スクロール・セル操作へ一切干渉しない。カスタムスクロールバーのガターのみポインタ操作を受けるが、コンテンツのスクロール自体はネイティブのまま(ガターは scrollTop を書くだけの鏡映し)。全行が viewport に収まりスクロール不能のときは何も表示しない。配色はテーマトークン(--ssg-pill-* / --ssg-scrollhint-*)で light / dark 両対応。

展開行(Master/Detail)(detailRow)

detailRow prop を渡すと、各行を「展開」してマスター行の直下に消費側 UI(カード)を差し込めます(AG Grid の Master/Detail 相当)。行グルーピングが「ライブラリがグループ行を作る」機能なのに対し、展開行は「行の下に何を出すかを利用側が全面的に決める」動線です。両者は独立で併用もできます。

<SpreadsheetGrid
  rows={rows}
  columns={columns}
  rowKeyGetter={(row) => row.id}
  detailRow={{
    height: 220,
    isExpandable: (row) => row.lines.length > 0,
    render: ({ row, rowKey, collapse }) => (
      <OrderLinesPanel order={row} onClose={collapse} />
    ),
  }}
  onExpandedDetailRowKeysChange={(keys) => save(keys)}
/>

DetailRowOptions<T>:

• 表示: 帯はマスター行の直下・グリッド全幅(3 ペインとも背景を描画)で、カードは中央ペインに position: sticky で置かれ、横スクロールしてもビューポート左端(左固定ペインの右隣)に留まります。幅は中央ペインの可視幅です。展開しても行の順序・view index は変わらず(第 3 の行種は作らない)、後続行が帯の高さぶん下がります。展開時にスクロール位置は動かしません。
• 状態: 展開状態は rowKeyGetter の行キーで保持されるため、ソート / フィルター / 行の追加削除を跨いで同じ行に追従します(フィルターで除外中の行は帯が出ず、復帰すると再表示)。UI 状態で undo/redo・getState() の対象外。永続化は onExpandedDetailRowKeysChange + setDetailRowExpanded() で行います。
• マウント: カードは仮想化の描画窓に載っている間だけマウントされます(スクロールアウトでアンマウント、戻ると再マウント)。カード内で保持したい状態は消費側で rowKey をキーに持ってください。
• イベント境界: カード内のキーボード / クリップボード / 右クリック / ダブルクリック / ドラッグ開始はグリッド本体へ伝播しません(カード内の input で矢印キーを押してもアクティブセルは動かない)。カード内にフォーカスがある間は、グリッド側のフォーカス復帰(編集確定・popover close 後)がフォーカスを奪いません。カード内に別の SpreadsheetGrid をネストしても、外側の自動高さ実測 / 列ヘッダー検索は内側のセルを対象にしません。
• renderCell からの操作(ctx.detail): detailRow 有効時、CellRenderContext に detail: { expanded, expandable, toggle(), setExpanded(bool) } が入ります(無効時は undefined)。showToggleColumn: false と組み合わせて、商品名セルの横などにトグルを自前配置できます。
• 選択 / アクティブセル: 帯はセルではないため選択・アクティブセルの対象外です。帯を跨ぐ範囲選択のハイライトは帯を避けて分割描画されます。
• serverSide(dataSource): 使えますが、(1) クエリ(フィルター / ソート / グローバル)が変わると展開状態はすべて閉じます(結果セットが総入れ替えされ、未ロード行のキーを走査できないため)。(2) 未ロード行の帯は表示されません。
• 上限: 帯は auto-height 行と同じ可変行高ジオメトリで描画するため、rows × rowHeight + 展開中の帯の合計 が 15,000,000px(36px 行で約 41 万行)を超える構成では帯を描画しません(開発時警告。展開状態は保持され、行数を絞ると表示されます)。
• 行グルーピング併用: 展開できるのは leaf 行のみ(グループ行は対象外)。

行ドラッグ並び替え(enableRowDrag)

enableRowDrag を付けると、先頭のハンドル列(⋮⋮)を掴んで行を上下へ動かせます(AG Grid の managed row dragging 相当)。並び替えの結果は通常の編集と同じく onRowsChange で新配列として返るため、消費側は rows を差し替えるだけです。

const [rows, setRows] = useState(initialRows);

<SpreadsheetGrid
  rows={rows}
  onRowsChange={setRows}
  columns={columns}
  rowKeyGetter={(row) => row.id}
  enableRowDrag
  isRowDraggable={(row) => !row.locked}
  onRowMove={({ rowKey, fromIndex, toIndex, rows }) => saveOrder(rows)}
/>

• 操作: ハンドルを押して上下へドラッグすると、挿入位置に水平のガイド線が出ます。ドロップで確定し、影響行が新しい位置へスライドします(prefers-reduced-motion では即時)。グリッドの枠外で離す / Escape でキャンセルします。上下端に近づくと自動スクロールします(仮想化された画面外の行へも運べます)。
• ゴースト: ドラッグ中はポインタ追従のピルに、先頭の(合成列でない)表示列の表示値(valueFormatter 適用後)を出します。空なら「行 N」。
• データ契約: 確定時は「1 要素を移動した新配列」(未変更行は参照共有)を onRowsChange に渡し、その直後に onRowMove を呼びます。掴んだ行の直上 / 直下(動かない位置)で離した場合はどちらも呼ばれません。履歴ラッパ経由のため Ctrl/Cmd+Z / undo() で戻せます。
• 有効条件: clientSide(rows + onRowsChange)専用です。dataSource(serverSide)/ 行グルーピング中 / onRowsChange 未指定ではハンドル列を挿入しません。readOnly は関係しません(並び替えはセル編集ではないため)。
• ソート / フィルター中: 表示順と rows の順が一致しないため、ハンドルは淡色(.ssg-row-drag-handle--disabled)+ 理由のツールチップになり操作できません(列はそのまま残るのでレイアウトは跳ねません)。解除すると復帰します。
• 展開行との併用: 展開中のマスター行は詳細パネルごと一緒に移動します。ドロップ位置の判定は詳細パネルの高さ込みで、パネルの上は「マスター行の下」として扱います。
• ハンドル列: 合成列のため、列メニュー / ソート / 列 DnD / autoSize / エクスポート / 並び替え管理パネルの対象外です。左固定列があるときは左固定側に、展開行トグル列よりさらに先頭に入ります。
• 命令的 API: moveRow(rowKey, toIndex) は表示状態(ソート / フィルター)に関わらず元配列上で移動します(onRowsChange → onRowMove の順)。
• 将来拡張: ドラッグ中に周囲の行がリアルタイムに退避する見せ方(rowDragMotion: 'live' 相当)は、スロット解決を共有したまま表示側だけ差し替えられる設計にしてあります(未実装)。
• スタイル: .ssg-row-drag-handle(+ --disabled)/ .ssg-body-cell--row-drag-handle / .ssg-row-drop-indicator / ドラッグ中の行 .ssg-body-row[data-ssg-row-dragging]。色はトークン(--ssg-drop-indicator / --ssg-glyph-* / --ssg-ghost-*)です。

キーボード操作

グリッド本体フォーカス中(編集中でない)の操作一覧。フィルター入力等のフォーム要素にフォーカス中は無効。

編集エディタ内: Enter = 確定して下へ(移動先は editorEnterMove で変更可。既定 'down')、Tab / Shift+Tab = 確定して右 / 左へ、Escape = キャンセル、フォーカスアウト = 確定。IME 変換中(isComposing)の Enter / Escape / Tab は IME の操作としてのみ扱われ、セル編集の確定 / キャンセルには使われない。

確定後の移動先は「確定を反映した再レンダー後」の行数・列数でクランプされる。このため、onRowsChange で末尾に空行を追加する消費側(Excel 的な入力グリッドの定石パターン)では、最終行の Enter 確定で「増えた行」へそのまま移動できる。行が増えない場合は従来どおり最終行に留まる。

スタイリング用の状態クラス(公開契約)

cellClassName / getRowClassName の返すクラスは、下記の内部付与クラスと連結セレクタで組み合わせて使える(例: .ssg-body-cell.my-diff で基底に勝たせ、.ssg-body-cell.my-diff.ssg-body-cell--row-hovered でホバー時色を切替)。以下は公開契約とし、変更時は breaking 扱いにする。

※上記以外の ssg-* クラス(内部構造クラス)は非公開の実装詳細で、予告なく変わり得る。セレクタで依存しないこと。

補助型(props で参照される shape)

• GridRowKey = string | number
• GridColumnPinned = 'left' | 'right'
• GridSelectFilterOption = { label: string; value: string }
• CellRenderContext<T> = { row, rowIndex, sourceRowIndex, rowKey, colIndex, value, column, isActive, isSelected, isEditing, readOnly, setValue, detail? }
  • detail?: CellDetailContext = { expanded, expandable, toggle, setExpanded } は detailRow prop 有効時のみ定義(「展開行(Master/Detail)」節)。
• DetailRowOptions<T> / DetailRowRenderContext<T> = { row, rowKey, rowIndex, sourceRowIndex, collapse } / CellDetailContext(展開行。バレルから公開)
• RowDragContext = { rowKey, sourceRowIndex }(isRowDraggable の第 2 引数)/ RowMoveParams<T> = { rowKey, fromIndex, toIndex, rows }(onRowMove の引数。いずれもバレルから公開)
• CellStyleContext<T> = 上記から setValue を除いた読み取り専用版(cellClassName 関数へ渡る)。バレル(index.ts)から公開(import type { CellStyleContext } from '@ishibashi0112/spreadsheet-grid')
  • rowIndex はビュー行 index(ソート / フィルター適用後の表示位置)、sourceRowIndex は元 rows の index、rowKey は行キー(rowKeyGetter 由来、既定は source index)。ソート / フィルター ON の画面で「エラー行 index の集合」など source 基準のデータと突き合わせるときは sourceRowIndex / rowKey を使う(getInvalidCells() の返す sourceRowIndex / rowKey と同一基準)。serverSide では view 順が正準のため sourceRowIndex は view index と同値。
• RowStyleContext<T> = { row, rowIndex, sourceRowIndex, rowKey, isSelected }(getRowClassName の第 3 引数。バレルから公開)
  • rowIndex / sourceRowIndex / rowKey の基準は CellStyleContext と同一。isSelected はチェックボックス行選択(enableRowSelection)の選択状態(範囲選択とは別)。グループ行(grouping 有効時)は専用描画のため getRowClassName の対象外。
• GridScrollPosition = { top: number; left: number }(getScrollPosition の返り値 / setScrollPosition の基準)
• GridScrollEventParams = { top: number; left: number; source: 'user' | 'api' }(onScroll の引数。source の意味は props 表の onScroll 行を参照)
• HeaderRenderContext<T> = { colIndex, width, column, filterValue?, isFiltered? }
• SpreadsheetGridSlotContext<T> = { rows, filteredRows, columns, visibleColumns, globalFilterText, columnFilterValues, sortState, setGlobalFilterText, activeCell, selection, derivedSummary, globalFilterStatus, globalFilterProgress }
  • derivedSummary は SpreadsheetGridDerivedSummary(行/列/フィルター/ソートの summary 文字列・選択統計などを内包)。helper を import せずトップ/ボトムバーで使える。
  • globalFilterStatus: GlobalFilterStatus('idle' | 'filtering' | 'ready')/ globalFilterProgress: number(0..1)。グローバルテキストフィルタは行数が大きい(しきい値 50,000 行・条件は rows.length > 50000)とき、入力を主スレッドを塞がず時間分割で適用する。適用中は status='filtering'・progress が進捗(0..1)になる。空/無効は 'idle'、確定は 'ready'(progress=1)。50,000 行以下は同期適用のため即 'ready'('filtering' を経由しない)。ローディング表示はグリッドが本体に重ねる組み込み overlay(autosize の計測中 overlay と同じ作法)で行うため、トップバーやカスタム UI 側で扱う必要は通常ない。 この 2 値は、入力の無効化や独自インジケータなどカスタム UI を出したい場合の参照用に公開している。serverSide では基本 'idle' / 'ready'(取得中表示は行スケルトンが担当)。