Angular スプレッドシートコンポーネント | ng-hub-ui-spreadsheet
Excel のキーボード操作、矩形選択、Excel と往復できるクリップボード、固定枠、結合セルを備えた、編集できる Angular のスプレッドシート。MIT ライセンス、アクセシブル、有料プランなし。
API リファレンス
spreadsheet の完全な仕様をここにまとめました。バインド、リッスン、プロジェクション、テーマ設定ができるすべてが一か所に集約されています。必要なものを接続し、好きなようにスタイリングしてください — standalone で signal フレンドリーです。
インプット
55 個のインプットで spreadsheet を調整。通常の Angular @Input と同じようにバインドできます。
| 名前 | 型 | デフォルト | 説明 |
|---|---|---|---|
rows必須 | readonly TRow[] | — | 手元にあるままの行。シートがこれに書き込むことはありません。 |
columns必須 | readonly HubSpreadsheetColumn<TRow>[] | — | 各列が何を表示し、何を許可するか。 |
rowKey必須 | (row: TRow) => string | — | 行ごとの安定した名前。再読み込みしても保存状態がその行に付いていきます。 |
errors | Record<string, string> | {} | セルごとの検証メッセージ。キーは `states` と同じです。検証はデータの意味を知る側に属するため、ホストが管理します。セルは赤い枠で囲まれ、メッセージはホバーまたはキーボードフォーカスでツールチップに表示されます。 |
invalidDrafts | Record<string, string> | {} | 双方向。列が保存できる値ではないのに読み手がセルに残したテキストで、キーは states と同じです。セルはそれを表示し続け、枠で囲み、保存されていないことを伝えるメッセージを添えます。セルを開き直すと修正のために戻り、Escape で破棄し、セルに上書きするか、その行や列を削除すると消えます。これを読めば、古い値を黙って保存することを防げます。 |
states | Record<string, HubSpreadsheetCellState> | {} | セルごとの保存状態。キーは行キーと列の別名をタブで連結したものです。 |
decimalMark | ',' | '.' | ',' | この読み手が小数を入力するときに使う文字。貼り付けた値に生の数値が含まれていなかった場合にのみ参照されます。 |
emptyText | string | '' | 空のシートに表示する内容。 |
pageSize | number | 10 | Page Up と Page Down で移動する行数。 |
readonly | boolean | false | 個々のセルの設定にかかわらず、すべてのエディタを無効にします。 |
frozenColumns | number | 0 | 先頭側に固定される列の数。Excel がウィンドウ枠を固定する数え方に従います。 |
frozenRows | number | 0 | ヘッダーの下に固定される行の数。 |
spans | readonly HubGridSpan[] | [] | 結合ブロック。それぞれ左上隅と範囲で指定します。 |
disjointSelection | boolean | true | Ctrl(Mac では Cmd)を押しながらのクリックで、選択をやり直すのではなく二つめのブロックを足すかどうか。既定で有効です。表計算ソフトがそうしているからであり、この操作が空いていたからでもあります——普通のクリックでもう選択できるので、Ctrl には言うことがありませんでした。どのブロックにも印がつき、Delete はすべてを空にし、普通のクリックや矢印キーで選択は最初からやり直しになります。コピーはブロックが表の形に並ぶときだけ行われ、そうでなければ断られます。複数を選んでいる間はフィルハンドルが消えます。フィルは一つのブロックを延ばすものであり、複数のどれを延ばすのかには答えがないからです。 |
fillHandle | boolean | false | Whether the sheet offers the fill handle at the corner of the selection. Ctrl+D(Mac では Cmd+D)による下方向へのコピーも有効になります。 |
canUndo | boolean | false | 元に戻せるかどうか。シートは尋ねるだけで、履歴は所有者が保持します。 |
canRedo | boolean | false | やり直せるかどうか。 |
resizableColumns | boolean | false | 読み手が列の後端をドラッグして、幅を広げたり狭めたりできるかどうか。 |
reorderableColumns | boolean | false | 読み手がヘッダーをドラッグして、列を別の場所に移せるかどうか。 |
reorderableRows | boolean | false | 行をドラッグして別の場所に置けるかどうか。キーボードでは Alt+Shift と上下の矢印でカーソルのある行を 1 つ移動し、新しい位置を読み上げます。 |
rowHandleLabel | string | '' | 行のドラッグハンドルのアクセシブルな名前。 |
columnWidths | Record<string, number> | {} | 各列の幅(ピクセル)。キーは別名です。双方向で、読み手がドラッグするとシートが書き込み、それを永続化することもできます。 |
minColumnWidth | number | 48 | 列をドラッグして狭められる最小幅。 |
virtual | boolean | false | 表示領域が覆う行だけを描き、残りの高さを確保します。数千行のシート向けです。既定では無効で、代償もあります。視界の外の行は文書に入っていないので、ブラウザの検索も印刷も描かれている分しか届かず、行の高さはそろっている必要があります。有効にするとシートに 24rem の高さも与えます。伸びるに任せたシートは中身と同じ高さになり、そうなると仮想化するものが残らないからです。 |
rowHeight | number | 0 | 仮想化中の行の高さ(ピクセル)。0 なら最初に描いた行を測ります。行がそろっている限りそれで正しく、隠れたまま組み立てるシートでは明示してください。一度も配置されていない行は 0 と測られ、0 から求めた窓はシート全体になります。 |
formulas | boolean | false | 値が = で始まるセルを数式として読むかどうか。頼まれるまで無効です。テキストの列が =1+1 を「誰かが書いた文字列」として持っていて何もおかしくないからです。数式は列を別名で指せます — =[units] * [price]、=SUM([total:]) — 列を動かしても見出しを書き直しても意味は変わりません。表計算ソフトと同じ坐標でも指せます — =ROUND(SUM(E1:E4), 2) — その場合は「どの列か」でなく「どこにあったか」を言っているので、rewriteRowFormulas() がシートの形の変化に合わせて移し、消えたものへの参照は隣をこっそり読むのではなく #REF! になります。コロンは列全体を読み、尋ねているセルだけを外します。ほかの循環は追いかけずに #CYCLE! として見せます。 |
mergeable | boolean | false | 読み手がセルを結合し、また解除できるかどうか。コンテキストメニューから提供するので contextMenu も必要です。構造を変えるものはすべてそうであるように、頼まれるまで無効です。 |
editOn | 'click' | 'double-click' | 'double-click' | ポインタで編集を開くきっかけ。既定はダブルクリックで、表計算の慣習です。クリックはセルを選ぶだけで値には触れず、最初に打った文字が編集を開いてそのまま入り、一覧や日付を持つセルには一度のクリックで開く印が出ます。書き込むためのシートなら click にすると最初のクリックで開きます。どちらでも編集はボタンを離したときに、しかもポインタが動かなかったときだけ開くので、範囲のドラッグはそのまま使えます。 |
expansion | TemplateRef<HubSpreadsheetExpansionContext<TRow>> | null | null | 開いている行の下に描かれるテンプレートで、その行が数値の背後に持つものを表示します。 |
expandedRow | string | null | null | 双方向。どの行が開いているかを行のキーで示します。開くのは一度に一行です。 |
expandToggle | boolean | false | 詳細を開く各行の端に小さなボタンを描きます。所有者がボタンを置かなくても読者が開けます。 |
expandToggleLabel | string | '' | そのボタンのアクセシブル名。シートは辞書を持ちません。 |
rowLevel | (row: TRow) => number | undefined | () => 0 | 行がアウトラインでどれだけ深いか。1 は 1 つの折り、2 は 2 つ、0 またはなしはどの折りにも入りません。 |
collapsedRows | readonly string[] | [] | 双方向。折りたたまれた行グループ(グループ id ごと)。 |
collapsedColumns | readonly string[] | [] | 双方向。折りたたまれた列グループ(グループ id ごと)。 |
rowToggleLabel | string | '' | 行グループのボタンのアクセシブル名。 |
columnToggleLabel | string | '' | 列グループのボタンのアクセシブル名。 |
direction | 'auto' | 'ltr' | 'rtl' | 'auto' | シートの流れる向き。auto はページに従います — 右から左の記事の中のシートは記事と同じ向きで読まれます。dir は継承されるためです — 一方 ltr と rtl は、周囲のページに逆らって流れる必要があるシートのために強制します。 |
contextMenu | boolean | false | 右クリックで構造変更のメニューを出すかどうか。各項目は引き続き権限を通る必要があり、メニューが空で開くことはありません。 |
columns[].kind | 'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select' | 'text' | 列が値をどう表示し、入力された内容をどう読み戻すか。select 列はリストを開き、リストにないものを拒否します。boolean は 1 クリックで反転するチェックボックスを描きます。date は日付フィールドを開きます。 |
columns[].formula | string | — | この列のすべてのセルを導く数式。データに持たせるのではなくコードで宣言します。明細の合計、税、繰越残高などです。読み手が打つ数式とは逆で、あちらは行が持つ値であり、ほかの値と同じように変えられます。この列のセルはそもそも開けません。一つを置き換えるとその行だけ数式が消え、合計が合わなくなるまで誰も気づかないからです。シート側の formulas が必要です。 |
columns[].placeholder | string | — | この列の空のセルにポインターを置いている間だけ表示されるヒント。値の代わりには決して表示しません。常に画面に出ているヒントの列は、内容の列に見えてしまうからです。 |
columns[].append | HubSpreadsheetAppend<TRow> | — | 主な値の後ろに表示され、短いリストから選ぶ2つ目の値。数量の後の単位や、値引き額の後の値引きの種類など。変更は、列キーが append.key の commit として届きます。コピーでは両方が書き出され、CSV と XLSX では主な値だけがエクスポートされます。 |
columns[].options | readonly HubSpreadsheetOption[] | — | select 列が提示する選択肢。セルは保存された値ではなく一致するラベルを表示し、一致するものがなければ生の値にフォールバックするため、廃止された選択肢を持つ行も読めるままです。 |
structure | HubSpreadsheetStructureOptions<TRow> | {} | 読み手が要求できる構造変更。許可されるまで、すべて拒否されます。 |
retiredColumnKeys | readonly string[] | [] | 削除された列の別名。新しい列が失効した識別子を引き継がないようにします。 |
hubSpreadsheetCell (directive on ng-template)必須 | string | — | セルを既定のレンダラーの代わりにこのテンプレートで描画する列のエイリアス。ディレクティブ属性そのものとしてバインドします: hubSpreadsheetCell="state"。 |
hubSpreadsheetCellRows (hubSpreadsheetCell) | readonly TRow[] | [] | シートに渡したものと同じ行。どこからも読み取られず、テンプレートコンテキスト内の行にコンパイラが型を付けられるようにするためだけのものです。 |
hubSpreadsheetCellAction (hubSpreadsheetCell) | string | ((row: TRow) => boolean) | '' | セルから別の対象を開ける列としてマークし、その入口のアクセシブルな名前を指定します。行ごとに関数で決定できます。開く操作には Enter が確保され、押下は opened を通じて通知されます。 |
hubSpreadsheetEditor (directive on ng-template)必須 | string | — | エディターを組み込みのものの代わりにこのテンプレートで描画する列のエイリアス。ディレクティブ属性そのものとしてバインドします: hubSpreadsheetEditor="assignee"。 |
hubSpreadsheetEditorRows (hubSpreadsheetEditor) | readonly TRow[] | [] | シートに渡したものと同じ行。どこからも読み取られず、テンプレートコンテキスト内の行にコンパイラが型を付けられるようにするためだけのものです。 |
hubSpreadsheetControl (directive on ng-container)必須 | HubSpreadsheetControlConfig | — | provideHubSpreadsheetControls() で登録されたコントロールアダプターを通じてセルエディターを描画します。設定はエディターが開くときに一度だけ読み取られます。 |
value (hub-spreadsheet-field, ng-hub-ui-spreadsheet/signals) | TRow[] | [] | 行を Signal Forms のフィールド値として保持する双方向モデル([(value)] を使用)。ユーザーがセルを変更するたびに書き戻されます。valueChange を発行します。 |
disabled (hub-spreadsheet-field) | boolean | false | Signal Forms の FormField ディレクティブによってバインドされ、すべてのエディターを無効にします。 |
errors (hub-spreadsheet-field) | readonly ValidationError.WithOptionalFieldTree[] | [] | Signal Forms の FormField ディレクティブによってバインドされます。ここには配列フィールド自身のエラーだけが届くため、セルごとではなくまとめて表示されます。hub-spreadsheet-field は columns、rowKey、states、decimalMark、emptyText、pageSize、readonly、frozenColumns、frozenRows、spans も hub-spreadsheet と同じ意味で受け取り、selectionChange を発行します。 |
アウトプット
spreadsheet の動作に反応 — ロジックを接続できる 21 個のイベント。
| 名前 | 型 | 説明 |
|---|---|---|
commit | HubSpreadsheetCommit<TRow> | セルが新しい値になり、それまでの値と異なっている。 |
pasted | HubSpreadsheetPaste<TRow> | ブロックが貼り付けられた。シートの外にはみ出した数と、数値ではなかった数が付きます。 |
cleared | HubSpreadsheetCellRef<TRow>[] | 複数のセル、またはリストやはい/いいえのセルの上で Delete または Backspace が押された。対象となった編集可能なセルを伴います。単一のテキストセルでは、代わりに空のエディタが開きます。 |
opened | HubSpreadsheetCellRef<TRow> | セルの action が使われました — ポインタで、または編集するフィールドがない場所では Enter で。 |
selectionChange | HubGridRange | null | 選択された矩形が変わった。 |
filled | HubSpreadsheetPaste<TRow> | フィルハンドルのドラッグが終了した。一連の操作全体が 1 つのイベントとして報告されます。 |
undoRequested | void | 読み手が元に戻すことを要求しました。 |
redoRequested | void | 読み手がやり直しを要求しました。 |
columnMoved | { from: number; to: number; key: string; keys: string[] } | 列が別の場所にドロップされた。報告のみで適用はしません。ペイロードには並べ替え済みの別名が入っています。 |
rowMoved | { from: number; to: number; key: string; keys: string[] } | 行が別の場所にドロップされました。適用はされず報告のみ: ペイロードには並べ替え済みのキーが含まれます。 |
invalidDraftsChange | Record<string, string> | 未保存のテキストが変わりました。読み手が保存できないテキストを残してセルを離れたか、そのテキストを修正・破棄・上書きしました。 |
mergeRequested | HubSpreadsheetMergeRequest | 選択範囲の結合が求められました。作る結合と、それが飲み込む結合の基点が渡されます。前者だけ足して後者を外さないと、同じセルを二つの結合が主張することになります。applySpanMerge() が一行で片づけます。 |
unmergeRequested | readonly HubGridCoords[] | 選択範囲が触れている結合の解除が求められました。基点で示されます。applySpanUnmerge() で適用します。 |
selectionRangesChange | readonly HubGridRange[] | 選択のすべての矩形を、変わるたびに。カーソルがいる矩形を伝え続ける selectionChange の隣に置いてあります。選択範囲の合計を出す側は全部が要り、「B4 にいます」と出す側は要りません。Ctrl でブロックを足していなければ要素は一つです。 |
insertRequested | HubSpreadsheetInsertRequest | The reader asked to add rows or columns. シートより長い貼り付けも、不足行数を count に入れてこの方法で行を要求します。 |
deleteRequested | HubSpreadsheetDeleteRequest | 読み手が行または列の削除を求めた。対象となる別名を示します。 |
valueChange (hub-spreadsheet-field) | TRow[] | 行が変更されたときに、双方向の value モデルから発行されます。 |
columnWidthsChange | Record<string, number> | ユーザーが列のサイズを変更したときに、双方向の columnWidths モデルから発行されます。 |
expandedRowChange | string | null | 行が展開または折りたたまれたときに、双方向の expandedRow モデルから発行されます。 |
collapsedColumnsChange | readonly string[] | 列グループが折りたたまれたり展開されたりしたときに、双方向の collapsedColumns モデルから発行されます。 |
collapsedRowsChange | readonly string[] | 行グループが折りたたまれたり展開されたりしたときに、双方向の collapsedRows モデルから発行されます。 |
メソッド
spreadsheet をコードから操作 — プログラム操作のための 19 個のメソッドを備えています。
| 名前 | シグネチャ | 戻り値 | 説明 |
|---|---|---|---|
HubSpreadsheetComponent.focusCell | focusCell(rowKey: string, column?: string): void | — | 行キーと列エイリアスでセルにカーソルとキーボードを移します。追加したばかりの行を待ち、エイリアスがなければ入力できる最初のセルに置くので、次のキーでそのセルが開きます。 |
HubSpreadsheetComponent.editCell | editCell(rowKey: string, column?: string): void | — | コードからセルのエディターを値を保ったまま開きます(F2 と同じ)。focusCell と同様に、追加されたばかりの行を待ちます。編集できないセルではカーソルを置くだけです。 |
sheetToXlsx | sheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8Array | Uint8Array | シートを本物の .xlsx として、バイト列で返します。数値は数値のまま、日付列は日付になります。CSV では運べないものです。書き出すのはセルが見せている値で、リスト列はラベル、数式は結果です。行が持つ値そのものが要るときは values: 'stored' を渡します。 |
downloadXlsx | downloadXlsx(filename: string, bytes: Uint8Array): void | — | そのブックを保存用として読み手に渡します。名前に .xlsx がなければ付けます。どのホストも同じ六行を書き、object URL の解放を忘れるので、ここに置いてあります。 |
xlsxToRecords | xlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>> | Promise<Array<Record<string, string>>> | ブックの最初のシートを、列の別名をキーにした行として読みます。CSV には無い二つのこと——共有文字列と、日数として保存された日付——を元に戻します。本物のブックは圧縮されており、展開はプラットフォームの機能を使うので非同期です。 |
sheetToCsv | sheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): string | string | シートを CSV として返します。区切り文字を指定しなければ小数点記号から決まります。小数点に使う文字で区切ることはできないので、1.234,56 と書く環境向けのファイルにはセミコロンを使います。 |
downloadText | downloadText(filename: string, text: string, type?: string): void | — | テキストファイルを保存用として読み手に渡します。表計算ソフトが UTF-8 として開くためのバイト順マークを付けるので、文字化けしません。 |
csvToRecords | csvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>> | Array<Record<string, string>> | CSV を、列の別名をキーにした行として読みます。区切り文字は決め打ちせず一行目から見分けます。見出しはまず見出しで、次に別名で突き合わせ、大文字小文字と前後の空白は無視します。 |
sheetValues | sheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][] | HubSpreadsheetValue[][] | 各セルが持つ値。数式は計算済みで、失敗した数式は表計算ソフトと同じ綴りで入ります。二つの書き出しが読んでいるのはこれで、独自のファイルを書くホストのために公開しています。 |
evaluateSheet | evaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheet | HubFormulaSheet | シートの数式をすべて、依存関係が要求する順で実行します。必要になった時に計算し、覚えておきます。循環は閉じた瞬間に捕まえ、追いかけません。描画せずに答えだけが欲しいホストのために公開しています。 |
rewriteRowFormulas | rewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[] | TRow[] | シートの形が変わったとき——列が移動した、行や列を挿入した、削除した——行の中の座標をすべて動かします。消えたものへの参照は、隣をこっそり読むのではなく #REF! になります。行はホストのものなので、呼ぶのはホストです。 |
mergeRequestFor | mergeRequestFor(spans, range): HubSpreadsheetMergeRequest | null | HubSpreadsheetMergeRequest | null | 選択範囲がなるはずの結合ブロックと、それが飲み込むアンカー。単一セルなら null です。飲み込むアンカーはホストが自力でやると間違えるところで、外さずに追加すると二つのブロックが同じセルを主張します。 |
applySpanMerge | applySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[] | HubGridSpan[] | その結合のあとのブロック一覧。飲み込まれたものは落ちます。 |
applySpanUnmerge | applySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[] | HubGridSpan[] | それらを分解したあとのブロック一覧。 |
spreadsheetRecords | spreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[] | HubSpreadsheetRecord[] | 各行を、列の別名をキーにした素のデータとして返します。座標を位置で自分のフィールドに割り当てるのではなく、{ price: 12, units: 3 } を扱えます。 |
parseForColumn | parseForColumn<TRow>(text, column, decimalMark: ',' | '.'): HubSpreadsheetValue | undefined | HubSpreadsheetValue | undefined | 打ち込まれた、あるいは貼り付けられた文字列が、その列でいくらになるか。値、空セルなら null、その列が持てないものなら undefined を返すので、呼ぶ側はゴミを保存せずに断れます。 |
nextColumnKey | nextColumnKey(taken: Iterable<string>, prefix?: string): string | string | ほかの列のものだったことが一度もない別名。新しい列が引退した名前を使い回さないので、保存済みの参照が別のものに解決されることがありません。 |
danglingColumnKeys | danglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[] | string[] | もうどの列にも解決しない参照。つまり削除が宙ぶらりんに残すもののことです。 |
provideHubSpreadsheetControls | provideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProviders | EnvironmentProviders | コントロールのアダプターを登録します。以後すべてのリスト列がそれで開きます——検索付きで、すでに開いた状態で、セルを開いた文字を検索欄に入れて。アダプターが無ければシートはネイティブのリストを描き、それがこのライブラリ単体で入れられる理由です。 |
テンプレート
自分好みに — 3 個のテンプレートスロットでカスタムマークアップをプロジェクションできます。
| 名前 | 説明 | サンプル |
|---|---|---|
hubSpreadsheetEditor | 指定した別名の列の編集をテンプレートに差し替えます。テンプレートには値と commit・cancel の組、閉じずに値を保持するための draft、そして `seed`(読み手が入力して開いたときの最初の文字。ピッカーの検索欄に入れるもの)が渡されます。シートは自分のエディターと同じように閉じます。Escape では元のまま(中で開いているリストが先に閉じます)、Tab では draft が保持する値で、フォーカスが別の場所へ移ったときも同様です。ただし、コントロールのいずれかが aria-controls で指す、hub-select のリストのようなポップアップへ移った場合は閉じません。それ以外のキーは Enter も含めてエディターのものです。シートは中身に一切依存しません。 | <ng-template hubSpreadsheetEditor="assignee" let-value let-seed="seed" let-commit="commit">
<hub-select [items]="people" autoOpen [initialSearchTerm]="seed ?? null" [ngModel]="value" (ngModelChange)="commit($event)" />
</ng-template> |
hubSpreadsheetCell | 編集していないあいだの列のセルを自分で描きます。状態のバッジ、名前の横のアバター、並んだアクションなど。セルのもう半分を受け持つ hubSpreadsheetEditor の対になるものです。クリップボードには描いたものではなく値が乗り、キーボードが立っているのは変わらずセルです。hubSpreadsheetCellRows で行を渡せば、コンパイラは `row` が何かを知ります。 | <ng-template hubSpreadsheetCell="state" let-value>
<hub-badge variant="soft" [color]="colourOf(value)">{{ labelOf(value) }}</hub-badge>
</ng-template> |
hubSpreadsheetHeader | 列見出しのタイトルを自分で描画します。名前の横のアイコンや、列を編集するボタンなどです。見出し版の hubSpreadsheetCell です。<th> はシートのままで、幅、固定、スティッキー位置、全選択チェックボックスも保たれます。内部のボタン、リンク、入力欄は列をドラッグせずに押せます。テンプレートには列、index、key、テキストの header が渡されます。 | <ng-template hubSpreadsheetHeader="price" let-column>
{{ column.header }} <button type="button" (click)="editPrice()">Edit</button>
</ng-template> |