OptionalformatOptional file type hint (extension, MIME type, or export key).
Used for type detection when it cannot be inferred from the destination. Examples: 'xlsx', 'csv', 'application/json', 'Excel'
A destination whose extension already names a different format is an error, not an override: changing a file's type means writing to a new name (see IWorkbookIO.writeAs).
OptionalonDecides whether a write that would lose something goes ahead.
Called at most once per write, after the format handler has produced the bytes and before the store persists them, and only when the handler raised a warning that an earlier write to the same file did not already let through this session — a repeat save of the same lossy workbook does not ask again. The event carries every warning, deduplicated, so a host shows one dialog listing them rather than one per finding.
Returning false cancels the write — IWorkbookIO.write then resolves to null, like
a dismissed save dialog — but only when WriteWarningsEvent.canCancel is true. A
prompted write (a Save As, a first save, a download) always proceeds, because the destination
the user just chose has nothing in it to protect and a browser save picker has already created
the file: an empty file there is worse than a lossy one. The workbook still holds everything
that was not written, so the recovery is to save a copy in a format that can hold it.
Omitted, every write proceeds and the warnings are reported through progress.onWarning only.
OptionalpasswordWhat to do about file encryption — a deliberate three-state field:
| Value | Meaning |
|---|---|
| omitted | Keep the destination's current encryption |
string |
Encrypt with this password |
null |
Write plaintext explicitly — the "remove password" verb |
Omitting it is not "write plaintext": re-saving an encrypted workbook must not quietly
produce an unencrypted file, which is a security downgrade caused by a keystroke. When the
destination is encrypted and no password is available, IWorkbookIO.write throws
PasswordRequiredError rather than guessing. Removing encryption is possible, but has to be
said — that is what null is for.
Unrelated to sheet/workbook protection, which is model state and travels in the file.
OptionalprogressOptional progress callback for long running writes.
Its onWarning receives each write warning (a feature the format cannot hold) once the format
handler has finished, already deduplicated. It is a log channel; the decision to proceed is
onWarnings.
OptionalpromptForce the store to resolve a destination even when the workbook's handle is already bound and writable — the "Save As" interaction.
Without this a store persists silently to a handle it holds (see IWorkbookIO.IBackingStore.write), which is exactly right for Save and exactly wrong for a Save As the user asked for: re-targeting the origin to a name that happens to match the handle it already had would overwrite the original with no dialog at all.
It is opt-in rather than implied by the verb, because IWorkbookIO.writeAs means
reorigin, not ask: a script or host that named a real destination
(writeAs(wb, 'out/report.xlsx')) wants it written, not a picker. Only the caller knows which
of the two it is doing.
"Resolve a destination" is the store's own affair — the native save picker in the browser. A store with no way to ask (a browser without the File System Access API, whose only write path is a download) simply writes; there is nothing to force.
Options for IWorkbookIO.writeAs — everything a write takes, plus the one thing only a reorigin can mean.