範囲・選択・セル
以下から目的のセクションへ進んでください。基本操作、応用例、設定、トラブルシューティングをこのページにまとめ、完全な API 定義は Reference で管理しています。
範囲
範囲（Range）とは、ワークシート上の矩形領域であり、開始行番号・開始列番号と縦横の長さ、または開始行番号・開始列番号と終了行番号・終了列番号によって特定されます。
スプレッドシートにおける多くの操作（値の設定／取得、スタイルの設定／取得など）は Range API を通じて実行できます。
範囲関連 Facade API の完全な定義は FRange FacadeAPI を参照してください。
範囲の生成
範囲を取得するには、開始行番号・開始列番号・行数（高さ）・列数（幅）を指定します。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// セル A1 の範囲を生成const fRange = fWorksheet.getRange(0, 0)console.log(fRange, fRange.getA1Notation())// セル A1:B2 の範囲を生成const fRange2 = fWorksheet.getRange(0, 0, 2, 2)console.log(fRange2, fRange2.getA1Notation())TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Sheet1 シート上の A1:B2 範囲を取得const fRange1 = fWorksheet.getRange('Sheet1!A1:B2')console.log(fRange1, fRange1.getA1Notation())// 単一セル A1 を取得const fRange2 = fWorksheet.getRange('A1')console.log(fRange2, fRange2.getA1Notation())// A1:B2 範囲を取得const fRange3 = fWorksheet.getRange('A1:B2')console.log(fRange3, fRange3.getA1Notation())// 列 A 全体を取得const fRange4 = fWorksheet.getRange('A:A')console.log(fRange4, fRange4.getA1Notation())// 行 1 全体を取得const fRange5 = fWorksheet.getRange('1:1')console.log(fRange5, fRange5.getA1Notation())範囲データの取得
範囲左上セルの値を取得：
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValue()) // 範囲左上セルの値console.log(fRange.getRawValue()) // 範囲左上セルの生値console.log(fRange.getDisplayValue()) // 範囲左上セルの表示値console.log(fRange.getCellData()) // 範囲左上セルのセルデータconst value = fRange.getValue(true)console.log(value)if (value !== null && typeof value === 'object') { console.log(value.toPlainText())}getValue(true) はリッチテキストのオブジェクトを保持します。空のセルは null / undefined、通常のセルは文字列・数値・真偽値を返します。toPlainText() はリッチテキストのオブジェクトにのみ使用してください。
範囲内すべてのセル値を取得：
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getValues()) // 全セルの値console.log(fRange.getRawValues()) // 全セルの生値console.log(fRange.getDisplayValues()) // 全セルの表示値console.log(fRange.getCellDataGrid()) // 全セルのセルデータconsole.log(fRange.getValues(true))範囲内の数式を取得：
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getFormula()) // 範囲左上セルの数式console.log(fRange.getFormulas()) // 範囲内全セルの数式範囲への値設定
単一値の設定
値またはセルオブジェクトを渡すと、範囲内の全セルがその内容で上書きされます。文字列が = で始まる場合は数式として解釈されます。
例: A1:B2 に Hello, Univer を設定
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValue('Hello, Univer')入力セルとは別の C1 に =A1+B1 を設定します：
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()if (!fWorkbook) throw new Error('No active workbook')const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('C1')fRange.setValue('=A1+B1')セルオブジェクトを設定：
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValue({ v: 'Hello, Univer', custom: { key: 'value', },})範囲左上セルのみ設定したい場合は FRange.setValueForCell：
TypeScript
fRange.setValueForCell('Hello, Univer')配列による複数値設定
渡す二次元配列の行数・列数は範囲の行数・列数と一致している必要があります。
セル値またはセルオブジェクトを使用できます。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValues([ ['A1', 'B1'], ['A2', 'B2'],])fRange.setValues([ [{ v: 'A1' }, { v: 'B1' }], [{ v: 'A2' }, { v: 'B2' }],])オブジェクトによる複数値設定
オブジェクトを渡す場合、第 1 インデックスが行番号、第 2 インデックスが列番号を表し、範囲サイズと一致している必要はありません（指定された座標のみ反映）。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setValues({ 0: { 0: 'A1', 1: 'B1', }, 1: { 0: 'A2', 1: 'B2', },})範囲データのクリア
FRange.clear： コンテンツと書式をすべてクリアFRange.clearContent： コンテンツのみクリアFRange.clearFormat： 書式のみクリア
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorkSheet = fWorkbook.getActiveSheet()const fRange = fWorkSheet.getRange('A1:D10')// コンテンツと書式をクリアfRange.clear()範囲スタイルの取得
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellStyleData()) // 左上セルのスタイルデータconsole.log(fRange.getCellStyle()) // 左上セルのスタイルconsole.log(fRange.getCellStyles()) // 全セルのスタイル範囲スタイルの設定
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange .setValues([ [1, 2], [3, 4], ]) .setFontWeight('bold') .setFontLine('underline') .setFontFamily('Arial') .setFontSize(24) .setFontColor('red')範囲スタイルのリセット
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')fRange.setFontWeight(null).setFontLine(null).setFontFamily(null).setFontSize(null).setFontColor(null)選択
Univer Sheets は複数の離散的な選択範囲（マルチセレクション）をサポートしており、選択集合は Range の配列です。各要素は Range API を通じて操作できます。
また、現在の選択の取得・選択状態の設定・選択変更イベントの監視用 API も提供しています。
選択関連 Facade API の完全な定義は FSelection FacadeAPI を参照してください。
アクティブ選択の取得
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:B2 を新たにアクティブ選択にするconst fRange = fWorksheet.getRange('A1:B2')fRange.activate()// 現在のアクティブ選択を取得const fSelection = fWorksheet.getSelection()console.log(fSelection)const activeRange = fSelection.getActiveRange()console.log(activeRange.getA1Notation()) // A1:B2選択の設定
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// FRange で A1:B2 を選択const fRange = fWorksheet.getRange('A1:B2')fRange.activate()// FWorksheet で C1:D2 に切替fWorksheet.setActiveSelection(fWorksheet.getRange('C1:D2'))現在セルの取得
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A10:B11 をアクティブ選択const fRange = fWorksheet.getRange('A10:B11')fRange.activate()// 現在のアクティブセルlet fSelection = fWorksheet.getSelection()const { actualRow, actualColumn } = fSelection.getCurrentCell()console.log(fWorksheet.getRange(actualRow, actualColumn).getA1Notation()) // A10// アクティブセルを B11 に更新fSelection = fSelection.updatePrimaryCell(fWorksheet.getRange('B11'))const { actualRow: newRow, actualColumn: newColumn } = fSelection.getCurrentCell()console.log(fWorksheet.getRange(newRow, newColumn).getA1Notation()) // B11選択の無効化／有効化／非表示／再表示
無効化すると選択操作に反応しません。非表示（transparent）は動作自体は有効なまま可視描画のみ消えます。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()// 無効化fWorkbook.disableSelection()// 有効化fWorkbook.enableSelection()// 非表示fWorkbook.transparentSelection()// 再表示fWorkbook.showSelection()選択変更の監視
TypeScript
univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params) => { const { worksheet, workbook, selections } = params console.log(params)})セル
セルデータはワークシート内部で二次元 Map として保持され、第 1・第 2 インデックスがそれぞれ行番号・列番号に対応します。
典型的なセルオブジェクト例:
TypeScript
const data = { v: 'Hello, Univer', s: 'styleId', t: CellValueType.STRING,}フィールド詳細は Configure Cell Data を参照してください。
補足
- セル操作は高さ 1・幅 1 の範囲操作とみなせます。範囲操作については Range を参照。
- Univer API プラグインは拡張セル属性を
Workbookのresourcesプロパティにも格納します。詳細は Plugin Custom Model を参照。
範囲の応用操作
セル挿入
FRange.insertCells は指定範囲内に空セルを挿入し、指定次元方向に既存データを押し出します。
TypeScript
// アクティブシートは空と仮定const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const values = [ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8],]// A1:D5 を初期化// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange = fWorksheet.getRange('A1:D5')fRange.setValues(values)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// A1:B2 に列方向で空セルを挿入// | | 1 | 2// | | 2 | 3// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange2 = fWorksheet.getRange('A1:B2')fRange2.insertCells(univerAPI.Enum.Dimension.COLUMNS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[null, null, 1, 2], [null, null, 2, 3], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// 再度 A1:D5 を元に戻す// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8fRange.setValues(values)// A1:B2 に行方向で空セルを挿入// | | 3 | 4// | | 4 | 5// 1 | 2 | 5 | 6// 2 | 3 | 6 | 7// 3 | 4 | 7 | 8const fRange3 = fWorksheet.getRange('A1:B2')fRange3.insertCells(univerAPI.Enum.Dimension.ROWS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[null, null, 3, 4], [null, null, 4, 5], [1, 2, 5, 6], [2, 3, 6, 7], [3, 4, 7, 8]]セル削除
FRange.deleteCells は指定範囲を削除し、指定次元方向へデータを詰めます。
TypeScript
// アクティブシートは空と仮定const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const values = [ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8],]// 初期状態// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange = fWorksheet.getRange('A1:D5')fRange.setValues(values)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// A1:B2 を列方向で削除// 3 | 4 | |// 4 | 5 | |// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8const fRange2 = fWorksheet.getRange('A1:B2')fRange2.deleteCells(univerAPI.Enum.Dimension.COLUMNS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[3, 4, null, null], [4, 5, null, null], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]// 再設定// 1 | 2 | 3 | 4// 2 | 3 | 4 | 5// 3 | 4 | 5 | 6// 4 | 5 | 6 | 7// 5 | 6 | 7 | 8fRange.setValues(values)// A1:B2 を行方向で削除// 3 | 4 | 3 | 4// 4 | 5 | 4 | 5// 5 | 6 | 5 | 6// | | 6 | 7// | | 7 | 8const fRange3 = fWorksheet.getRange('A1:B2')fRange3.deleteCells(univerAPI.Enum.Dimension.ROWS)console.log(fWorksheet.getRange('A1:D5').getValues()) // [[3, 4, 3, 4], [4, 5, 4, 5], [5, 6, 5, 6], [null, null, 6, 7], [null, null, 7, 8]]セル結合
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// B1:B2 を結合const fRange = fWorksheet.getRange('B1:B2')fRange.merge()console.log(fRange.isMerged()) // true// A1:B2 についてconst fRange2 = fWorksheet.getRange('A1:B2')console.log(fRange2.isMerged()) // falseconsole.log(fRange2.isPartOfMerge()) // true// 結合解除fRange2.breakApart()// 水平結合：fRange2.mergeAcross();// 垂直結合：fRange2.mergeVertically();// シート内の全結合範囲取得：fWorksheet.getMergedRanges();範囲のハイライト
FRange.highlight は指定スタイルと主セル（primary cell）で範囲を強調表示します。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 既定スタイルで C3:E5 をハイライトconst fRange = fWorksheet.getRange('C3:E5')fRange.highlight()// カスタムスタイル＋主セル D8 で C7:E9 をハイライトconst fRange2 = fWorksheet.getRange('C7:E9')const primaryCell = fWorksheet.getRange('D8').getRange()const disposable = fRange2.highlight( { stroke: 'red', fill: 'yellow', }, { ...primaryCell, actualRow: primaryCell.startRow, actualColumn: primaryCell.startColumn, },)// 5 秒後に C7:E9 のハイライト解除setTimeout(() => { disposable.dispose()}, 5000)テキストを列に分割
FRange.splitTextToColumns は指定した区切り文字に従いテキストを複数列へ分割します。
デフォルト区切り文字の例:
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:A3 の値:// A |// 1,2,3 |// 4,,5,6 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1,2,3'], ['4,,5,6']])// splitTextToColumns(true) 呼び出し後:// A | |// 1 | 2 | 3// 4 | 5 | 6fRange.splitTextToColumns(true)// splitTextToColumns(false) 呼び出し後:// A | | |// 1 | 2 | 3 |// 4 | | 5 | 6fRange.splitTextToColumns(false)特定区切り文字の例:
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:A3：// A |// 1;;2;3 |// 1;,2;3 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1;;2;3'], ['1;,2;3']])// セミコロン + カンマで分割（空要素保持 = false），結果：// A | | |// 1 | | 2 | 3// 1 | | 2 | 3fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma)// 空要素圧縮 = true，結果：// A | |// 1 | 2 | 3// 1 | 2 | 3fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma)カスタム区切り文字の例:
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// A1:A3：// A |// 1#2#3 |// 4##5#6 |const fRange = fWorksheet.getRange('A1:A3')fRange.setValues([['A'], ['1#2#3'], ['4##5#6']])// カスタム '#'、空要素保持 = false// A | | |// 1 | 2 | 3 |// 4 | | 5 | 6fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#')// 空要素圧縮 = true// A | |// 1 | 2 | 3// 4 | 5 | 6fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#')範囲の座標取得
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCellRect()) // width、heigh、left、right、top、bottom、x、y結合情報と座標の同時取得
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:B2')console.log(fRange.getCell())シート端でのキーボード移動
allowArrowKeyWrapOnSheetBoundary は、矢印キーでシート端を越えて別の行や列へ折り返すかを制御します。既定値は true です。false にすると端で停止します。選択範囲内の Enter/Tab による循環移動には影響しません。プリセットでは sheets 内に、プラグインでは UniverSheetsUIPlugin に直接指定します。
TypeScript
univer.registerPlugin(UniverSheetsUIPlugin, { allowArrowKeyWrapOnSheetBoundary: false,})TypeScript
createUniver({ presets: [ UniverSheetsCorePreset({ sheets: { allowArrowKeyWrapOnSheetBoundary: false, }, }), ],})セルのイベントと編集
ポインター、描画、編集、クリップボードの操作別に例を示します。全イベントと引数型は Events Reference を参照してください。プラグインモードでは購読前に @univerjs/sheets-ui/facade を読み込みます。Sheets Core プリセットには含まれています。コンポーネントやページの破棄時には購読を解除してください。
使用パターン
全イベントは addEvent で監視可能:
TypeScript
import '@univerjs/sheets-ui/facade'const subscription = univerAPI.addEvent(univerAPI.Event.CellClicked, ({ row, column }) => { console.log(row, column)})// Call subscription.dispose() when the owning component or page is removed.Cell PointerMove イベント
CellPointerMove イベントは、マウスカーソルがセル上を移動した際にトリガーされます。現在ポインタ直下にあるセル情報を提供します。
TypeScript
univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => { // イベントパラメータ取得 const { worksheet, workbook, row, column } = params console.log('Current cell position:', worksheet.getRange(row, column).getA1Notation())})Cell PointerDown イベント
CellPointerDown イベントは、セル上でマウスボタンが押下されたときにトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => { const { worksheet, workbook, row, column } = params console.log('Mouse down cell:', worksheet.getRange(row, column).getA1Notation())})Cell PointerUp イベント
CellPointerUp イベントは、セル上でマウスボタンが解放されたときにトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => { const { worksheet, workbook, row, column } = params console.log('Mouse up cell:', worksheet.getRange(row, column).getA1Notation())})Cell Hover イベント
CellHover イベントは、マウスがセル上にホバーした時点でトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.CellHover, (params) => { const { worksheet, workbook, row, column } = params console.log('Hovered cell:', worksheet.getRange(row, column).getA1Notation())})Cell DragOver イベント
DragOver イベントは、ドラッグ中の要素がセル領域上を通過したときにトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.DragOver, (params) => { const { worksheet, workbook, row, column } = params console.log('Drag over cell:', worksheet.getRange(row, column).getA1Notation())})Cell Drop イベント
Drop イベントは、ドラッグ要素がセル上にドロップされた際にトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.Drop, (params) => { const { worksheet, workbook, row, column } = params console.log('Drop target cell:', worksheet.getRange(row, column).getA1Notation())})Cell Click イベント
CellClicked イベントは、セルがクリックされたときにトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => { const { worksheet, workbook, row, column } = params console.log('Clicked cell:', worksheet.getRange(row, column).getA1Notation())})Cell Render イベント
registerCellCustomRender はセル用のカスタムレンダラーを登録します。
例 1: 固定位置レンダリング（行追加などによる位置変動なし）
TypeScript
// 固定位置レンダリングuniverAPI.registerCellCustomRender([ { drawWith: (ctx, info, skeleton, spreadsheets) => { const { row, col } = info // 位置 (1,1) にチェックマークを描画 if (row === 1 && col === 1) { const { primaryWithCoord } = info const { startX, startY } = primaryWithCoord ctx.fillText('✅', startX, startY + 10) } }, },])// 再描画反映univerAPI.getActiveWorkbook().getActiveSheet().refreshCanvas()例 2: マーカー方式（行／列シフトに追随）
TypeScript
// マーカー設定univerAPI .getActiveWorkbook() .getActiveSheet() .getRange('B2') .setValue({ custom: { key: 'needCheck' } })// マーカーに基づき描画univerAPI.registerCellCustomRender([ { drawWith: (ctx, info, skeleton, spreadsheets) => { const { row, col, data } = info // マーカーを持つセルにチェックマークを描画 if (data?.custom?.key === 'needCheck') { const { primaryWithCoord } = info const { startX, startY } = primaryWithCoord ctx.fillText('✅', startX, startY + 10) } }, },])// 再描画univerAPI.getActiveWorkbook().getActiveSheet().refreshCanvas()セル編集イベント
編集開始
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.startEditing()編集終了
TypeScript
// true で確定、false でキャンセル// 非同期関数のため await が必要const fWorkbook = univerAPI.getActiveWorkbook()await fWorkbook.endEditingAsync(true)編集開始イベント
BeforeSheetEditStart はセル編集が開始される直前にトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => { const { worksheet, workbook, row, column, eventType, keycode } = params console.log('Before cell edit:', params) // 編集状態遷移を阻止する場合 params.cancel = true})SheetEditStarted はセル編集開始時にトリガーされます。
TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => { const { worksheet, workbook, row, column, eventType, keycode } = params console.log(params)})// disposable.dispose() で解除編集終了イベント
BeforeSheetEditEnd イベントは、セルの編集が終了する前にトリガーされます。
TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => { const { worksheet, workbook, row, column, value, eventType, keycode, isConfirm } = params console.log(params) // Cancel the cell edit end operation params.cancel = true})// disposable.dispose() で解除SheetEditEnded イベントは、セルの編集が終了した後にトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => { const { worksheet, workbook, row, column, eventType, keycode, isConfirm } = params console.log('After cell edit:', params)})クリップボードイベント
BeforeClipboardChange
BeforeClipboardChange イベントは、クリップボード内容が変更される直前にトリガーされます。変更前の内容監視や上書き制御に利用できます。
TypeScript
univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (params) => { const { text, html } = params console.log('Clipboard content:', text, html) // 貼り付けをキャンセルする場合： // params.cancel = true;})BeforeClipboardPaste
BeforeClipboardPaste イベントは貼り付け実行直前にトリガーされます。貼り付け内容の検査・変換・拒否に利用できます。
TypeScript
univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => { const { text, html } = params console.log('Content to paste:', text, html) // 貼り付けをキャンセルする場合： // params.cancel = true;})ClipboardChanged
ClipboardChanged イベントはクリップボード内容の変更後にトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (params) => { const { text, html } = params console.log('New clipboard content:', text, html)})ClipboardPasted
ClipboardPasted イベントは貼り付け操作完了後にトリガーされます。
TypeScript
univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (params) => { const { text, html } = params console.log('Pasted content:', text, html)})セル編集のトラブルシューティング
セルエディタ内の内容をリアルタイム取得するには？
SheetEditChanging を購読すると、編集中のセルのリッチテキスト値を取得できます。この値はまだエディター内にあり、編集終了時にシートへ確定されます。
TypeScript
import '@univerjs/sheets-ui/facade'const subscription = univerAPI.addEvent(univerAPI.Event.SheetEditChanging, ({ value }) => { console.log(value.toPlainText())})// Call subscription.dispose() when the owning component or page is removed.セルエディタがフォーカス中に外部ボタン操作でイベントをトリガーされも、スナップショットに編集中セルの内容が含まれない
セルデータはエディタがフォーカスを失ったタイミング（編集終了）で同期されます。取得前に明示的に編集を終了させてください。
TypeScript
import '@univerjs/sheets-ui/facade'async function saveWorkbook() { const fWorkbook = univerAPI.getActiveWorkbook() if (!fWorkbook) return await fWorkbook.endEditingAsync(true) const snapshot = fWorkbook.save() console.log(snapshot)}$btn.addEventListener('click', () => { saveWorkbook().catch(console.error)})参考：https://github.com/dream-num/univer/issues/1314
Facade API で Workbook を生成直後に一部 API が動作しない
一部 API は UI の完全レンダリング後でないと機能しません。Rendered または Steady ライフサイクル段階で処理を行うことを推奨します。
TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === univerAPI.Enum.LifecycleStages.Steady) { // 実行コード }})// disposable.dispose() で解除参考：Lifecycle
このガイドはいかがですか？