Interface WriteOptions

Remarks

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).

Remarks

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.

Remarks

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.

Remarks

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.