API リファレンス
公開API(オプション・イベント・メソッド)の一覧。src/tssgrid.d.ts を正本に自動生成しています。使い方・サンプルは ドキュメント(ガイド) をどうぞ。
グリッド オプション
67 項目(new TssGrid(el, options))。
| オプション | 型 | 説明 |
|---|---|---|
headers | string[] | |
data | any[][] | Record<string, any>[] | 初期データ。2次元配列 or オブジェクト配列。 |
history | HistoryManager | 渡すと複数グリッドで Undo を共有。 |
name | string | |
showDump | boolean | |
enterMoves | MoveDir | Enter 確定後の移動方向(既定 'down')。Shift で逆。実行時に書換可。 |
tabMoves | MoveDir | Tab 確定後の移動方向(既定 'right')。Shift で逆。実行時に書換可。 |
initialCell | [number, number] | { r: number; c: number | string } | |
nextCell | (a: { r: number; c: number; key: string; shift: boolean }) => { r: number; c: number } | null | 入力フロー制御。Enter/Tab の移動先を上書き(null で既定方向)。入力セルだけ巡回できる。 |
columns | ColumnDef[] | |
invalidMode | 'revert' | 'keep' | 検証NG時。'revert'=元に戻す / 'keep'=赤く警告して残す。 |
invalidTitle | boolean | |
messages | Record<string, any> | ((info: { code: string; params?: any; level?: string }) => string) | エラーの共通メッセージカタログ。 |
pasteOverflow | 'clip' | 'error' | |
pasteAutoGrow | boolean | 貼付元の行数がグリッド行数を超える時、不足分を insertRows で一括生成してから貼る(既定 false=従来のクランプ)。行生成+値貼付は1回の undo で戻る。maxRows 上限内・超過分は pasteOverflow に従う。 |
colWidths | number[] | Record<string, number> | |
rowHeights | number[] | Record<string, number> | |
defaultColWidth | number | |
defaultRowHeight | number | |
minColWidth | number | |
minRowHeight | number | |
resizeMode | 'preview' | 'live' | |
frozenCols | number | 左から固定する列数。freezeCols(n) でも変更可。 |
frozenRows | number | 上から固定する行数。freezeRows(n) でも変更可。frozenCols 併用で四隅固定。 |
nestedHeaders | Array<Array<string | { label: string; colspan?: number }>> | ヘッダ結合(複数段見出し)。最下段がリーフ=実列。 |
width | number | string | |
height | number | string | |
resizeCols | boolean | |
resizeRows | boolean | |
cursor | boolean | false で選択カーソルを非表示(表示専用グリッド向け・内部選択は保持)。 |
stretchH | 'none' | 'last' | 'all' | |
rowHeaders | boolean | |
rowHeaderWidth | number | 行番号列の幅(px)。既定 40。大量行で桁数が増える時に広げる。 |
rowHeaderLabel | false | ((r: number) => string | number) | 行ヘッダの表示内容。未指定=行番号(r+1) / false=数字なし(空) / (r)=>文字列=カスタム表示。 |
rowReorder | boolean | 'header' | 行のドラッグ並べ替え。true=行ヘッダーセルの ⠿ アイコンを掴んで移動 / 'header'=行ヘッダーセル全体が移動ハンドル(クリック=選択/ドラッグ=移動)。 |
rowReorderMark | 'before' | 'after' | false | 行ヘッダーの ⠿ マークの位置。'before'=番号の前(既定)/ 'after'=番号の後 / false=マークを出さない。 |
rowDelete | boolean | 右端に非データの「削除列」(🗑)を1列出す。既定 false。クリックで deleteRows(右クリック→行を削除と同一経路・1 undo で復活)。 最後の1行(0行にはできない)は削除でなく「中身クリア(行は残す)」=🗑 は無効にならず内容だけ空に(readOnly はスキップ・1 undo で復活)。 minRows>1 のロック時は下限で🗑 を無効表示(削除もクリアもしない)。allowDeleteRows:false なら列ごと出さない。 getRows/getData/toCSV・列インデックス・列選択/リサイズ/reorder の対象外。 |
rowDeleteWidth | number | 削除列の幅(px)。既定 36。 |
virtual | boolean | { buffer?: number } | 仮想スクロール(固定行高ウィンドウイング)。大量行を可視窓だけ描画。true か { buffer:窓上下バッファ行数(既定6) }。 制約(v1): 行高一定/固定行列・折り返し・セル結合は非対応(指定時は自動無効化)。 |
colHeaders | boolean | |
hiddenColumns | number[] | |
wordWrap | boolean | |
multilineEnter | 'commit' | 'newline' | multiline 列の Enter 挙動。'commit'(既定・Excel風): Enter=確定 / Alt+Enter=改行。'newline'(メモ帳風): Enter=改行 / Ctrl+Enter=確定。 |
multilineMark | boolean | multiline セル右上の「複数行」ヒント表示(既定 true)。色は CSS 変数 --tg-ml-mark。false で非表示。 |
multilineEditMaxLines | number | multiline 編集時に伸びる箱の最大行数(既定 10)。超えた分はボックス内スクロール。ビューポート/wrap を超える時はそちらが優先。 |
placeholder | string | |
className | string | |
fillHandle | boolean | { direction?: 'vertical' | 'horizontal' | 'both'; autoInsertRow?: boolean } | false でフィル完全OFF。詳細指定も可。 |
autoColumnSize | boolean | number | |
copyPaste | boolean | |
suppressAutofill | boolean | 共有エディタへのブラウザ自動入力(Chrome の「ポイントカード/住所/支払い」等)を強めに抑止する。既定 false。 通常は name + autocomplete='off' で抑止するが、Chrome は loyalty/payment 系で 'off' を無視することがある。 true にすると autocomplete='new-password' に切り替えて確実に止める(副作用として環境により鍵アイコンや生成PW提案が出る場合あり=opt-in)。 周囲に自前のラベル付き `<input>`(フォーム塊)を並べる埋め込み画面で有効。 |
minSpareRows | number | |
autoWrapRow | boolean | |
autoWrapCol | boolean | |
minRows | number | |
maxRows | number | |
minCols | number | |
maxCols | number | |
readOnly | boolean | グリッド全体を読み取り専用(ビューア用途)。 |
contextMenu | boolean | Array<string | MenuItem> | { items: Array<string | MenuItem> } | 右クリックメニュー。true=既定 / false=無効 / 配列 or {items} =構成(組込キー文字列+カスタム MenuItem)。 |
disjointSelect | boolean | Ctrl+ヘッダで行/列を飛び飛び複数選択(既定 true)。false で Ctrl+クリックは単一選択に戻る。 |
allowInsertRows | boolean | |
allowDeleteRows | boolean | |
allowInsertCols | boolean | |
allowDeleteCols | boolean | |
shortcuts | any[] | |
plugins | any[] | プラグイン(関数 or 登録名)。init(grid) で初期化。 |
イベント / コールバック
24 個。値変更系(onBeforeChange/onAfterChange)は編集・貼付・フィル・Delete の全経路を通ります。
| イベント | シグネチャ | 説明 |
|---|---|---|
onBeforeChange | (changes: ChangeItem[], source: ChangeSource) => boolean | void | 確定の直前。検証・自動整形。false で全取消、change.newValue 書換で整形。 |
onAfterChange | (changes: ChangeItem[], source: ChangeSource) => void | 確定の直後(undo/redo 含む)。保存・再計算に。 |
onEditStart | (info: { r: number; c: number; value: any }) => void | |
onEditEnd | (info: { r: number; c: number; oldValue: any; newValue: any; canceled: boolean }) => void | |
onSelectionChange | (info: SelectionInfo) => void | |
onBeforeSelectionChange | (info: SelectionInfo) => boolean | void | |
onBeforePaste | (data: string[][]) => boolean | string[][] | void | |
onAfterPaste | (data: string[][], info: { range: SelectionRange }) => void | |
onBeforeCopy | (data: string[][], info: { range: SelectionRange }) => boolean | string[][] | void | |
onBeforeCut | (data: string[][], info: { range: SelectionRange }) => boolean | string[][] | void | |
onAfterCopy | (data: string[][], info: { range: SelectionRange; cut: boolean }) => void | |
onBeforeStructureChange | (info: StructureInfo) => boolean | void | |
onStructureChange | (info: StructureInfo) => void | |
onViewportChange | (start: number, end: number) => void | 遅延ロード(push): 描画窓が変わった時に呼ぶ (start,end)。未取得(PENDING)行を fillRows で埋めるトリガ。 |
onSortFilterChange | (state: { type: 'sort' | 'filter'; sort?: any; filter?: any }) => void | 遅延ロード(push): dataComplete=false で sort/filter 要求が来た時に呼ぶ。エンジンはローカル計算せず、これで通知+パージ=プラグインがサーバ側で並替/絞込して setRowCount+fillRows し直す。 |
onBeforeAutofill | (src: SelectionRange, target: SelectionRange) => boolean | void | |
onAfterAutofill | (src: SelectionRange, target: SelectionRange) => void | |
onBeforeKeyDown | (e: KeyboardEvent) => boolean | void | |
onHeaderClick | (c: number, e: MouseEvent) => boolean | void | |
onHeaderRender | (th: HTMLTableCellElement, c: number) => void | 各列ヘッダ th の生成後に呼ぶ(再描画毎に自動で再実行)。ソートアイコン等の要素差し込み用。 |
onInvalid | (rejections: Rejection[], source: ChangeSource) => void | |
onReadOnly | (blocked: ReadOnlyBlock[], source: ChangeSource) => void | |
onChange | (grid: TssGrid) => void | |
onPasteOverflow | (info: { anchor: CellCoord; height: number; width: number; rows: number; cols: number; overRows: number; overCols: number }) => void |
列オプション(columns[c])
列ごとのセルタイプ・検証・書式など。
| オプション | 型 | 説明 |
|---|---|---|
data | string | number | data オブジェクトのキー。配列データなら省略可(位置で対応)。 |
title | string | ヘッダ見出し(headers より優先)。 |
type | CellType | セルタイプ。既定 'text'。 |
options | Array<string | { value: string; label?: string }>
| ((r: number, row: any[]) => Array<string | { value: string; label?: string }>) | dropdown の選択肢。関数を渡すと**行ごとに異なる依存ドロップダウン**(例: 都道府県→市区町村)。 `(r, row)=>[…]` の row はその行の値配列(`grid.data[r]`)。静的配列は全行共通(後方互換)。 |
width | number | 列ごとの初期幅(px)。列定義に同居=並べ替え/コピペで幅が追従。 |
resizable | boolean | false でこの列だけリサイズ禁止。 |
align | 'left' | 'center' | 'right' | 列既定の水平/垂直整列。 |
valign | 'top' | 'middle' | 'bottom' | |
readOnly | boolean | ((value: any, cell: CellCoord) => boolean) | 列単位の読み取り専用。関数でセル単位判定も可。 |
validator | (value: any, cell: CellCoord) => ValidatorResult | 入力検証。編集/貼付/フィルの全経路に効く。 |
editor | EditorDef | (() => EditorDef) | カスタム編集UI(薄いオブジェクト契約 or それを返す関数)。 |
parse | (input: string, cell: CellCoord) => any | 入力の正規化(保存値へ変換)。 |
format | string | object | ((value: any, cell: CellCoord, row: any[]) => string) | 表示の整形(保存値→表示)。文字列 or 宣言的 CellFormat or 関数。 関数は `(value, { r, c }, row)`=第3引数 `row` はその行の値配列(`grid.data[r]`・options と同形)。 html:true 併用でセル内にボタン/アイコン等の HTML を描ける(空セルでも実行される)。 |
thousands | boolean | 数値型: 千区切り表示。 |
prefix | string | 数値型: 接頭辞(例 '¥')。 |
cellClass | (r: number, c: number, value: any, row: any) => string | 値/行を見てセルに付与する CSS クラス(条件付き書式)。 |
cellStyle | (r: number, c: number, value: any, row: any) => Partial<CSSStyleDeclaration> | Record<string, string> | セル単位のインラインスタイル(連続色・データバー等)。 |
html | boolean | true で表示だけ生HTML(値はテキスト保存のまま)。 |
wordWrap | boolean | 列単位の折り返し。 |
multiline | boolean | 複数行(改行)入力を有効化。編集は隠し textarea(IME 直打ち対応)、表示は改行保持(pre-wrap)。行高は自動で伸びないので rowHeights 等で確保する。 |
placeholder | string | 空セルの薄いヒント文字。 |
メソッド
公開メソッド 67 個。インスタンス grid.xxx(...) で呼べます。
データ
getData(): any[][]全データを2次元配列で取得(コピー)。
getRows(): Record<string, any>[]全行をオブジェクト配列で取得(columns[c].data キー基準)。
getRow(r: number): Record<string, any>r 行目をオブジェクトで取得。
getColumn(cOrKey: number | string): any[] | undefined列を縦に取得(index か data キー)。
getColumns(): any[][]全列を配列の配列で取得。
getValue(r: number, cOrKey: number | string): any1セルの値を取得(c は index か data キー)。
setData(rows: any[][] | Record<string, any>[]): voidデータを差し替え(履歴・フィルタ・整列状態はリセット)。
appendRows(rows: any[][] | Record<string, any>[], opts?: { keepScroll?: boolean; noHistory?: boolean }): void背景で"育てる"追記(progressive)。data 末尾へ rows を足し、可視窓+スペーサだけ再描画する。 buildTable 全再描画をせず、スクロール位置・アクティブセル・フォーカス・選択・編集中のエディタと値を保ち、履歴にも積まない。 「先頭ページを描く→残りを idle で appendRows」して first-paint を早める土台(既存の setData/insertRows 経路は不変)。 rows は現在のデータと同形(オブジェクトモードはオブジェクト配列/配列モードは行配列)。
setRowCount(total: number): void遅延ロード(push・on-demand)。総行数を total に確保し、未取得ぶんを PENDING 行で埋める(virtual 前提)。 dataComplete=false になり、この間 minSpareRows は自動無効。onViewportChange で「今要る範囲」を受け fillRows で埋める流れ。 setData で解除。AG Grid の Infinite Row Model 相当を push プリミティブで。
fillRows(start: number, rows: any[][] | Record<string, any>[]): void遅延ロード(push): PENDING 行 [start, start+rows.length) を実データに差し替える(onViewportChange への応答)。 塗り替え範囲が可視窓に重なる時だけ窓を再描画=スクロール/選択/アクティブは不変。全 PENDING が埋まると dataComplete=true。
setValue(r: number, cOrKey: number | string, val: any, force?: boolean): void1セルに書き込み(履歴あり・検証/onBeforeChange 経由)。force=true で readOnly 貫通。
setValueRaw(r: number, cOrKey: number | string, val: any): void履歴に積まず・検証も通さず直接書き込み(計算列など派生値用。readOnly 貫通)。
並べ替え / フィルタ
sortBy(cOrKey: number | string, dir?: 'asc' | 'desc'): void列で並べ替え(c は index か data キー)。
sortByCols(specs: Array<{ col: number | string; dir?: 'asc' | 'desc' }>): void多段(複数列)で並べ替え。specs は優先順(先頭=第1キー)。各段は sortBy と同じ比較規則。
sortRows(cmp: (a: any[], b: any[]) => number): void比較関数で並べ替え。
clearSort(): void並べ替え解除(入力順に戻す)。
isSorted(): booleanfilter(pred: ((row: any[], masterIndex: number, src: any) => boolean) | Record<string, any>): void非破壊フィルタ。pred(row, masterIndex, src)=>boolean、または { col: 値|fn }。
clearFilter(): voidフィルタ解除(フィルタ中に編集/追加した行も含め全部戻る)。
isFiltered(): booleangetAllRows(): Record<string, any>[]フィルタ中でも全行(マスタ)を取得。
選択 / カーソル
setActive(r: number, c: number): voidsetExtent(r: number, c: number): voidselectRect(r0: number, c0: number, r1: number, c1: number): voidselectRow(r: number): voidselectCol(c: number): voidselectAll(): voidgetSelectedColumns(): number[]選択中の列インデックス(Ctrl+ヘッダクリックの飛び飛び選択に対応・昇順)。列選択モードでなければ `[]`。
getSelectedRows(): number[]選択中の行インデックス(Ctrl+行ヘッダクリックの飛び飛び選択に対応・昇順)。行選択モードでなければ `[]`。
deleteColsSet(cols: number[]): void飛び飛びの複数列をまとめて削除(高index側から。右クリック「N 列を削除」の実体)。
deleteRowsSet(rows: number[]): void飛び飛びの複数行をまとめて削除(高index側から。右クリック「N 行を削除」の実体)。
行 / 列 構造
insertRow(ri: number, where?: 'above' | 'below'): voidinsertRows(ri: number, count?: number, where?: 'above' | 'below'): voidcount 行を1回の再描画・1つの undo コマンドで挿入(大量挿入を O(N) に)。maxRows 上限でクランプ。既定 count=1 は insertRow と等価。
deleteRows(r0: number, r1?: number): voidclearRow(r: number): void行 r の中身を空にする(行自体は残す・readOnly はスキップ・1 undo)。rowDelete の🗑を最後の1行で押した時の実体。
insertCol(ci: number, where?: 'left' | 'right'): voiddeleteCols(c0: number, c1?: number): voidmoveRow(from: number, to: number): void1行を移動(Undo 対応)。
moveRows(r0: number, r1: number, to: number): void複数行をまとめて移動(Undo 対応)。
列の表示 / 幅 / 固定 / 行高
hideColumn(c: number): voidshowColumn(c: number): voidtoggleColumn(c: number): voidisColumnHidden(c: number): booleangetHiddenColumns(): number[]setColWidth(c: number, px: number): voidautoSizeColumn(c: number): voidautoSizeAllColumns(): voidfreezeCols(n: number): voidfreezeRows(n: number): voidsetRowHeight(r: number, px: number): voidセル状態 / 検証
setAlignment(align: string, range?: SelectionRange): voidgetAlignment(r: number, c: number): stringsetCellReadOnly(flag: boolean, range?: SelectionRange): voidgetInvalidCells(): Rejection[]今の全セルを検証し、NG を一覧で返す(保存前チェック等)。
出力 / 再描画 / 破棄
toCSV(opts?: CsvOptions): stringdownloadCSV(filename: string, opts?: CsvOptions): voidredraw(): void列定義変更後などの再描画(データ・選択は保持)。
refreshGeometry(): void画像/フォント等の遅延レイアウト後に幾何キャッシュを再構築する保険。
destroy(): voidグリッドを破棄(リスナ除去・DOM 撤去・idempotent)。フレームワークの teardown で呼ぶ。
拡張
addShortcut(s: { name: string; keys: string; handler: (grid: TssGrid, e: KeyboardEvent) => void }): voidremoveShortcut(name: string): voidusePlugin(plugin: ((grid: TssGrid, opts?: any) => any) | string, opts?: any): anygetPlugin(name: string): any低レベル(公開はするが通常は上位APIを推奨)
clearRange(): void選択範囲(または range)をクリア。※通常は値消去なら setValue('') を推奨。一括の低レベル手段。
copy(cut?: boolean): void選択範囲をクリップボードへ。cut=true で切り取り。
buildTable(): voidテーブルDOMを再構築(低レベル)。※通常は redraw() を推奨。主にプラグイン拡張者向け。
cellEl(r: number, c: number): HTMLTableCellElement | nullセルの DOM 要素を返す(低レベル・内部DOM構造に依存)。結合セルはアンカーに解決。
HistoryManager
Undo/Redo 履歴。複数グリッドで共有すると Undo タイムラインが繋がります。
push(cmd: { apply: () => void; revert: () => void }): voidundo(): voidredo(): voidclear(): voidcanUndo(): booleancanRedo(): boolean