OptionalanchorHow the listened range follows rows and columns inserted or deleted around it.
TwoCell: the range follows its cells, as a formula reference does. An insert above it
moves it down, a delete inside it shrinks it, and deleting all of its cells makes it
#REF!. Each move is an 'address' event.OneCell: the top-left follows its cell and the extent is kept, as a picture anchored to
one cell. Deleting the top-left cell leaves the range where it is.Absolute: the range never moves. It names the same addresses whatever is inserted or
deleted, so it never has an 'address' event. This is what a view listening to the rows
it shows wants: the cells on screen, not the cells that were there when it subscribed.OptionaleditsWhether an 'address' event carries the edits that changed the range's cells
(Event.getEdits).
OptionalignoreIf true, the listener will not be called when the range's
address changes (due to row/column insert/delete, moves, or a rename of
the sheet a qualified range names). The range still follows its cells; see anchor
for a range that should not.
OptionalignoreIf true, the listener will not be called when the data
within the range changes.
OptionalonceIf true then will auto deregister once fired.
OptionaltransactionalWhether the listener takes part in the operations that change its range.
true when the listener is added through a range reached through the object a
batch hands its callback (IWorkbook.doBatch, IWorksheet.doBatch,
doBatch), and false otherwise.
A transactional listener (a participant):
A non-transactional listener (an observer) is told once, after the operation has landed,
with everything the operation changed in its range, and not at all if the operation is
rolled back. What it writes is an operation of its own. It is told of an undo or a redo
('restore'), and it survives them.
await workbook.doBatch(async (_commit, wb) => {
const total = wb.getSelectedWorksheet()!.getRange('B1');
const input = wb.getSelectedWorksheet()!.getRange('A1');
input.addListener(() => total.setValue((input.getValue() as number) * 2)); // a participant
input.setValue(21);
total.getValue(); // 42
});
OptionalweaklyIf true then the listener will be weakly and will be auto removed it the listener is gc'ed.
Options to control which events trigger a listener. By default, all event types will trigger the listener. Setting any of these options to
truewill prevent the listener from being called for that event type.