detail/events.md

Event API

Generated: 2026-03-17

Subscription surface

Use SN.Event for registration and dispatch. SN.Event is an EventEmitter instance exposed on the root workbook object.

SN.Event.on('beforeCellEdit', (e) => {
  if (e.data.cell?.locked) e.cancel('Cell is locked')
})

SN.Event.once('afterSheetAdd', (e) => {
  console.log(e.data.sheet)
})

EventEmitter

Event Transmitter

Methods

`on(event, handler, options = {}): EventEmitter`

Register Event Listener

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	Event Name
handler	Function	Yes	-	Handling function
options	Object	No	{}	Options
options.id	string	Yes	-	Unique identity (anti duplicate binding)
options.priority	number	Yes	-	Priority (execute as soon as possible)
options.once	boolean	Yes	-	Whether to execute only once

Returns

Type: EventEmitter
Chain Calls Supported

`once(event, handler, options = {}): EventEmitter`

Sign up for a one-time event listener

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	Event Name
handler	Function	Yes	-	Handling function
options	Object	No	{}	Options

Returns

Type: EventEmitter

`off(event, idOrHandler): EventEmitter`

Remove Event Listener

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	Event Name
idOrHandler	string \| Function	Yes	-	id or handler reference

Returns

Type: EventEmitter

`offAll(): EventEmitter`

Remove all event listeners

Returns

Type: EventEmitter

`emit(event, data = {}): SheetEvent`

Trigger event

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	Event Name
data	Object	No	{}	Event Data

Returns

Type: SheetEvent
Event object (canceled status can be checked)

`async emitAsync(event, data = {}): Promise<SheetEvent>`

Trigger event with async hooks support.

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	event name
data	Object	No	{}	event data

Returns

Type: Promise<SheetEvent>

`hasListeners(event): boolean`

Check for listeners

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	Event Name

Returns

Type: boolean

`listenerCount(event): number`

Get the number of listeners

Parameters

Name	Type	Required	Default	Description
event	string	Yes	-	Event name (optional, return total if not passed)

Returns

Type: number

`listEvents(): Array<{event: string, count: number}>`

Get all event names and number of monitors

Returns

Type: Array<{event: string, count: number}>

SheetEvent

Event object

Props

Name	Type	Static	Default	Description
type	string	No	type	-
data	Object	No	data	-
target	Object	No	target	-
canceled	boolean	No	false	-
stopped	boolean	No	false	-
cancelReason	null	No	null	-
timestamp	number	No	Date.now()	-

Methods

`cancel(reason = '')`

Cancel event (block default behavior)

Parameters

Name	Type	Required	Default	Description
reason	string	No	‘’	Reason for canceling (optional, used as a reminder)

`stopPropagation()`

Stop event propagation (no longer performing follow-up listener)

`waitUntil(promise)`

Register async work for emitAsync to await.

Parameters

Name	Type	Required	Default	Description
promise	Promise	Yes	-	-

Emitted events

Total detected events: 114
Dynamic event patterns: 7

Col

Event	Mode	Cancelable	Payload Keys
after${eventBase}	emit	No	col, newHidden, oldHidden, row, sheet
afterColResize	emit	No	col, newWidth, oldWidth, sheet
before${eventBase}	emit	No	col, newHidden, oldHidden, row, sheet
beforeColResize	emit	No	col, newWidth, oldWidth, sheet

Sheet

Event	Mode	Cancelable	Payload Keys
after${eventSuffix}	emit	No	[indexKey], changedCount, limitedCount, maxLevel, sheet
afterClearDataValidation	emit	No	…summary, sheet
afterConsolidate	emit	No	…summary, sheet
afterDeleteColumns	emit	No	col, count, sheet
afterDeleteRows	emit	No	count, row, sheet
afterFlashFill	emit	No	exampleCount, filledCount, sheet, sourceRange, strategy, targetRange
afterInsertColumns	emit	No	col, count, sheet
afterInsertRows	emit	No	count, row, sheet
afterMerge	emit	No	areas, mode, sheet
afterMoveArea	emit	No	moveArea, sheet, targetArea
afterSelectionChange	emit	No	newAreas, newCell, oldAreas, oldCell, sheet, type
afterSetDataValidation	emit	No	…summary, sheet
afterSheetRename	emit	No	newName, oldName, sheet
afterSort	emit	No	range, sheet, sortKeys, success
afterSubtotal	emit	No	…summary, options, sheet
afterTextToColumns	emit	No	columnCount, rowCount, sheet, sourceRange, targetRange
afterUnmerge	emit	No	cellAd, sheet
afterZoomChange	emit	No	newZoom, oldZoom, sheet
before${eventSuffix}	emit	No	[indexKey], areas, maxLevel, sheet
beforeClearDataValidation	emit	No	areas, sheet
beforeConsolidate	emit	No	functionName, sheet, skipBlanks, sourceRanges, targetRange
beforeDeleteColumns	emit	No	col, count, sheet
beforeDeleteRows	emit	No	count, row, sheet
beforeFlashFill	emit	No	exampleCount, sheet, sourceRange, strategy, targetRange
beforeInsertColumns	emit	No	col, count, sheet
beforeInsertRows	emit	No	count, row, sheet
beforeMerge	emit	No	areas, mode, sheet
beforeMoveArea	emit	No	moveArea, sheet, targetArea
beforeSelectionChange	emit	No	newAreas, newCell, oldAreas, oldCell, sheet, type
beforeSetDataValidation	emit	No	areas, rule, sheet
beforeSheetRename	emit	No	newName, oldName, sheet
beforeSort	emit	No	range, sheet, sortKeys
beforeSubtotal	emit	No	options, range, sheet
beforeTextToColumns	emit	No	options, sheet, sourceRange, targetRange
beforeUnmerge	emit	No	cellAd, sheet
beforeZoomChange	emit	No	newZoom, oldZoom, sheet

Workbook

Event	Mode	Cancelable	Payload Keys
afterActiveSheetChange	emit	No	newSheet, oldSheet
afterOperation	emitAsync	No	-
afterOperation:${op.type}	emitAsync	No	-
afterSheetAdd	emit	No	name, sheet
afterSheetDelete	emit	No	index, name, sheet
afterWorkbookRename	emit	No	newName, oldName
beforeActiveSheetChange	emit	No	newSheet, oldSheet
beforeOperation	emit	No	…data, operation
beforeOperation:${type}	emit	No	…data, operation
beforeSheetAdd	emit	No	name
beforeSheetDelete	emit	No	index, name, sheet
beforeWorkbookRename	emit	No	newName, oldName

AI

Event	Mode	Cancelable	Payload Keys
afterAIRequest	emitAsync	No	durationMs, request, response, result, status, textBlock, ui
aiRequestChunk	emit	No	chunk, chunkIndex, request, textBlock, ui
aiRequestError	emitAsync	No	durationMs, error, request, response, status, textBlock, ui
aiRequestFinally	emitAsync	No	durationMs, error, request, response, result, status, textBlock, ui
aiRequestStart	emit	No	request, textBlock, ui
beforeAIRequest	emitAsync	No	request, textBlock, ui

AutoFilter

Event	Mode	Cancelable	Payload Keys
afterAutoFilterApply	emit	No	…eventBase, allHiddenRowsAdded, allHiddenRowsRemoved, hiddenRowsAdded, hiddenRowsRemoved, range, sheet
afterAutoFilterClear	emit	No	…eventBase, range, ref, sheet
afterAutoFilterClearAllFilters	emit	No	…eventBase, sheet
afterAutoFilterClearColumnFilter	emit	No	…eventBase, colIndex, prevFilter, sheet
afterAutoFilterSetColumnFilter	emit	No	…eventBase, colIndex, filter, prevFilter, sheet
afterAutoFilterSetRange	emit	No	…eventBase, range, sheet
beforeAutoFilter	emit	No	…eventBase, action, colIndex, filter, range, sheet
beforeAutoFilterApply	emit	No	…eventBase, columns, range, sheet
beforeAutoFilterClear	emit	No	…eventBase, range, ref, sheet
beforeAutoFilterClearAllFilters	emit	No	…eventBase, filters, sheet
beforeAutoFilterClearColumnFilter	emit	No	…eventBase, colIndex, prevFilter, sheet
beforeAutoFilterSetColumnFilter	emit	No	…eventBase, colIndex, filter, prevFilter, sheet
beforeAutoFilterSetRange	emit	No	…eventBase, range, sheet

Cell

Event	Mode	Cancelable	Payload Keys
afterCellEdit	emit	No	cell, col, newValue, oldValue, row, sheet
afterCellStyleChange	emit	No	cell, col, newStyle, oldStyle, row, sheet
afterHyperlinkInsert	emit	No	cell, col, hyperlink, row, sheet
beforeCellEdit	emit	No	cell, col, newValue, oldValue, row, sheet
beforeCellStyleChange	emit	No	cell, col, newStyle, oldStyle, row, sheet
beforeHyperlinkInsert	emit	No	cell, col, hyperlink, row, sheet

Drawing

Event	Mode	Cancelable	Payload Keys
afterDrawingAdd	emit	No	config, drawing, sheet
afterDrawingRemove	emit	No	drawing, id, sheet
beforeDrawingAdd	emit	No	config, sheet
beforeDrawingRemove	emit	No	drawing, id, sheet

PivotTable

Event	Mode	Cancelable	Payload Keys
afterPivotTableAdd	emit	No	config, pivotTable, sheet
afterPivotTableChange	emit	No	action, pivotTable, sheet, sourceRangeRef, sourceSheet
beforePivotTableAdd	emit	No	config, sheet
beforePivotTableChange	emit	No	action, pivotTable, sheet, sourceRangeRef, sourceSheet

UndoRedo

Event	Mode	Cancelable	Payload Keys
afterRedo	emit	No	tx
afterUndo	emit	No	tx
beforeRedo	emit	No	tx
beforeUndo	emit	No	tx

Row

Event	Mode	Cancelable	Payload Keys
afterRowResize	emit	No	newHeight, oldHeight, row, sheet
beforeRowResize	emit	No	newHeight, oldHeight, row, sheet

Slicer

Event	Mode	Cancelable	Payload Keys
afterSlicerAdd	emit	No	config, sheet, slicer
afterSlicerRemove	emit	No	id, sheet, slicer
beforeSlicerAdd	emit	No	config, sheet
beforeSlicerRemove	emit	No	id, sheet, slicer

Sparkline

Event	Mode	Cancelable	Payload Keys
afterSparklineAdd	emit	No	config, sheet, sparkline
afterSparklineRemove	emit	No	c, r, sheet, sparkline
beforeSparklineAdd	emit	No	config, sheet
beforeSparklineRemove	emit	No	c, r, sheet, sparkline

Table

Event	Mode	Cancelable	Payload Keys
afterTableAdd	emit	No	options, sheet, table
afterTableAutoFilterToggle	emit	No	newValue, oldValue, sheet, table
afterTableRemove	emit	No	id, sheet, table
afterTableRename	emit	No	newName, oldName, sheet, table
afterTableResize	emit	No	newRef, oldRef, sheet, table
afterTableStyleChange	emit	No	newStyle, oldStyle, sheet, table
afterTableTotalsRowToggle	emit	No	newValue, oldValue, sheet, table
beforeTableAdd	emit	No	options, sheet
beforeTableAutoFilterToggle	emit	No	newValue, oldValue, sheet, table
beforeTableRemove	emit	No	id, sheet, table
beforeTableRename	emit	No	newName, oldName, sheet, table
beforeTableResize	emit	No	newRef, oldRef, sheet, table
beforeTableStyleChange	emit	No	newStyle, oldStyle, sheet, table
beforeTableTotalsRowToggle	emit	No	newValue, oldValue, sheet, table

Comment

Event	Mode	Cancelable	Payload Keys
event	emit	No	-