From 2e540f5b1553cc20dbc235fddedf684495ddd8bc Mon Sep 17 00:00:00 2001 From: SheetJS Date: Tue, 11 Apr 2023 04:25:50 -0400 Subject: [PATCH] write-methods --- docz/docs/08-api/07-write-options.md | 54 +++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/docz/docs/08-api/07-write-options.md b/docz/docs/08-api/07-write-options.md index d0db38a..53ca7fd 100644 --- a/docz/docs/08-api/07-write-options.md +++ b/docz/docs/08-api/07-write-options.md @@ -5,19 +5,57 @@ title: Writing Files --- import current from '/version.js'; - -# Writing Options - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`XLSX.write(wb, write_opts)` attempts to write the workbook `wb` +**`XLSX.write(wb, options)`** + +`write` attempts to write the workbook `wb` and return the file. + +The `options` argument is required. It must specify +- [`bookType`](#supported-output-formats) (file format of the exported file) +- [`type`](#output-type) (return value type) + +**`XLSX.writeFile(wb, filename, options)`** + +`writeFile` attempts to write `wb` to a local file with specified `filename`. -`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`. In browser-based environments, it will attempt to force a client-side download. +It also supports NodeJS, Extendscript applications, and Chromium extensions. -`XLSX.writeFileAsync(filename, wb, o, cb)` attempts to write `wb` to `filename`. -If `o` is omitted, the writer will use the third argument as the callback. +If `options` is omitted or if `bookType` is missing from the `options` object, +the output file format will be deduced from the filename extension. + +
NodeJS-specific methods (click to show) + +**`XLSX.writeFileAsync(filename, wb, cb)`** + +**`XLSX.writeFileAsync(filename, wb, options, cb)`** + +attempt to write `wb` to `filename` and invoke the callback `cb` on completion. + +When an `options` object is specified, it is expected to be the third argument. + +This method only works in NodeJS and uses `fs.writeFile` under the hood. + +
+ +:::note Recommendation + +`writeFile` wraps a number of export techniques, making it suitable for browser +downloads, NodeJS, Extendscript apps, and Chromium extensions. It does not work +in other environments with more advanced export methods. + +The `write` method returns raw bytes or strings that can be exported in +[Desktop apps](/docs/demos/desktop/) , [Mobile apps](/docs/demos/mobile) , and +[Servers](/docs/demos/net/server). + +The [demos](/docs/demos) preferentially use `writeFile`. When `writeFile` is not +supported, the demos show file creation using `write` and platform APIs. + +::: + +## Writing Options The write functions accept an options argument: @@ -200,7 +238,7 @@ output formats. The specific file type is controlled with `bookType` option: ## Output Type -The `type` argument for `write` mirrors the `type` argument for `read`: +The `type` option specifies the JS form of the output: | `type` | output | |------------|-----------------------------------------------------------------|