write-methods

This commit is contained in:
SheetJS 2023-04-11 04:25:50 -04:00
parent 34938cc39a
commit 2e540f5b15

@ -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.
<details><summary><b>NodeJS-specific methods</b> (click to show)</summary>
**`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.
</details>
:::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 |
|------------|-----------------------------------------------------------------|