写入文件
SheetJS 编写工作簿的主要方法是 write
。脚本接收通用 JavaScript 数据表示,并有望使用特定于平台的 API 编写或共享文件。
¥The main SheetJS method for writing workbooks is write
. Scripts receive common
JavaScript data representations and are expected to write or
share files using platform-specific APIs.
writeFile
辅助方法接受文件名并尝试使用 标准 API 写入本地文件。
¥The writeFile
helper method accepts a filename and tries to write to a local
file using standard APIs.
以指定的文件格式导出 SheetJS 工作簿对象
¥Export a SheetJS workbook object in a specified file format
var file_data = XLSX.write(wb, opts);
write
尝试写入工作簿 wb
并返回文件。
¥write
attempts to write the workbook wb
and return the file.
options
参数是必需的。必须指定
¥The options
argument is required. It must specify
-
bookType
(导出文件的文件格式)¥
bookType
(file format of the exported file) -
type
(返回值类型)¥
type
(return value type)
导出 SheetJS 工作簿对象并尝试写入本地文件
¥Export a SheetJS workbook object and attempt to write a local file
XLSX.writeFile(wb, filename, options);
writeFile
尝试将 wb
写入指定 filename
的本地文件。
¥writeFile
attempts to write wb
to a local file with specified filename
.
在基于浏览器的环境中,它将尝试强制客户端下载。它还支持 NodeJS、ExtendScript 应用和 Chromium 扩展。
¥In browser-based environments, it will attempt to force a client-side download. It also supports NodeJS, ExtendScript applications, and Chromium extensions.
如果省略 options
或 options
对象中缺少 bookType
,则将从文件扩展名推导出输出文件格式。
¥If options
is omitted or if bookType
is missing from the options
object,
the output file format will be deduced from the filename extension.
用于以 XLSX 格式导出数据的特殊功能
¥Special functions for exporting data in the XLSX format
// limited form of `write`
var file_data = XLSX.writeXLSX(wb, options);
// limited form of `writeFile`
XLSX.writeFileXLSX(wb, filename, options);
writeXLSX
和 writeFileXLSX
是 write
和 writeFile
的限量版。它们支持写入 XLSX 文件格式。
¥writeXLSX
and writeFileXLSX
are limited versions of write
and writeFile
.
They support writing to the XLSX file format.
对于专门导出到 XLSX 的网站来说,这些功能可以减少生产网站的大小。一般的 write
和 writeFile
函数在导出为 XLS 或 XLSB 或其他格式时更合适。
¥For websites that exclusively export to XLSX, these functions can reduce the
size of the production site. The general write
and writeFile
functions are
more appropriate when exporting to XLS or XLSB or other formats.
NodeJS-specific methods (click to show)
Export a workbook and attempt to write a local file using fs.writeFile
// callback equivalent of `XLSX.writeFile`
XLSX.writeFileAsync(filename, wb, cb);
// callback equivalent with options argument
XLSX.writeFileAsync(filename, wb, options, cb);
writeFileAsync
attempts 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.
writeFile
封装了许多导出技术,使其适用于浏览器下载、NodeJS、ExtendScript 应用和 Chromium 扩展。它不适用于具有更高级导出方法的其他环境。
¥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.
write
方法返回可以在 桌面应用 、 移动应用 和 服务器 中导出的原始字节或字符串。
¥The write
method returns raw bytes or strings that can be exported in
Desktop apps , Mobile apps , and
Servers.
demos 优先使用 writeFile
。当不支持 writeFile
时,演示将显示使用 write
和平台 API 创建文件。
¥The demos preferentially use writeFile
. When writeFile
is not
supported, the demos show file creation using write
and platform APIs.
写作选项
¥Writing Options
write 函数接受一个选项参数:
¥The write functions accept an options argument:
选项名称 | 默认 | 描述 |
---|---|---|
type | 输出数据编码(参见下面的输出类型) | |
cellDates | false | 将日期存储为 d 类型(默认为 n ) |
cellStyles | false | 将样式/主题信息保存到 .s 字段 |
codepage | 如果指定,则在适当时使用代码页** | |
bookSST | false | 生成共享字符串表** |
bookType | "xlsx" | 工作簿类型(有关支持的格式,请参阅下文) |
bookVBA | 将工作簿对象中的 VBA blob 添加到文件 ** | |
WTF | false | 如果为 true,则对意外功能抛出错误 ** |
sheet | "" | 单表格式的工作表名称 ** |
compression | false | 对基于 ZIP 的格式使用 ZIP 压缩 ** |
Props | 写入时覆盖工作簿属性 ** | |
themeXLSX | 编写 XLSX/XLSB/XLSM 时覆盖主题 XML ** | |
ignoreEC | true | 抑制 "数字作为文本" 错误 ** |
numbers | NUMBERS 导出的有效负载 ** | |
FS | "," | 字段之间的 "字段分隔符" 分隔符 ** |
RS | "\n" | 行之间的 "记录分隔符" 分隔符 ** |
-
bookSST
速度较慢且占用内存较多,但与旧版本的 iOS Numbers 具有更好的兼容性¥
bookSST
is slower and more memory intensive, but has better compatibility with older versions of iOS Numbers -
原始数据是唯一保证保存的数据。本自述文件中未描述的功能可能不会被序列化。
¥The raw data is the only thing guaranteed to be saved. Features not described in this README may not be serialized.
-
cellDates
仅适用于 XLSX 输出,不保证与第三方读卡器配合使用。Excel 本身通常不会写入类型为d
的单元格,因此非 Excel 工具可能会忽略存在日期的数据或错误。¥
cellDates
only applies to XLSX output and is not guaranteed to work with third-party readers. Excel itself does not usually write cells with typed
so non-Excel tools may ignore the data or error in the presence of dates. -
codepage
适用于包括 DBF 在内的旧格式。编码中缺少的字符将替换为下划线字符 (_
)。¥
codepage
is applied to legacy formats including DBF. Characters missing from the encoding will be replaced with underscore characters (_
). -
Props
是工作簿Props
字段的镜像对象。请参阅 工作簿文件属性 部分的表格。¥
Props
is an object mirroring the workbookProps
field. See the table from the Workbook File Properties section. -
如果指定,
themeXLSX
中的字符串将保存为 XLSX/XLSB/XLSM 文件的主要主题(保存到 ZIP 中的xl/theme/theme1.xml
)¥if specified, the string from
themeXLSX
will be saved as the primary theme for XLSX/XLSB/XLSM files (toxl/theme/theme1.xml
in the ZIP) -
由于程序中存在错误,某些功能(例如 "文本到列")会在忽略错误条件的工作表上导致 Excel 崩溃。默认情况下,编写器将标记文件以忽略错误。设置
ignoreEC
至false
进行抑制。¥Due to a bug in the program, some features like "Text to Columns" will crash Excel on worksheets where error conditions are ignored. The writer will mark files to ignore the error by default. Set
ignoreEC
tofalse
to suppress. -
FS
和RS
适用于 CSV 和文本输出格式。这些选项在 "CSV 和文本" 中讨论¥
FS
andRS
apply to CSV and Text output formats. The options are discussed in "CSV and Text" -
bookVBA
仅适用于支持的格式。"VBA" 部分更详细地解释了该功能。¥
bookVBA
only applies to supported formats. "VBA" section explains the feature in more detail. -
WTF
主要是为了开发。¥
WTF
is mainly for development.
Exporting NUMBERS files (click to show)
NUMBERS writer 需要相当大的基数。补充 xlsx.zahl
脚本提供支持。xlsx.zahl.js
设计用于独立和 NodeJS 使用,而 xlsx.zahl.mjs
适用于 ESM。
¥The NUMBERS writer requires a fairly large base. The supplementary xlsx.zahl
scripts provide support. xlsx.zahl.js
is designed for standalone and NodeJS
use, while xlsx.zahl.mjs
is suitable for ESM.
添加 NUMBERS 导出支持涉及两个步骤:
¥Adding NUMBERS export support involves two steps:
-
加载
xlsx.zahl
脚本¥Load the
xlsx.zahl
script -
将有效负载传递到
numbers
选项到write
或writeFile
。¥Pass the payload into the
numbers
option towrite
orwriteFile
.
- Browser
- NodeJS
- Bun
- Deno
https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.zahl.js is the URL for 0.20.3
<meta charset="utf8">
<body>
<script src="https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js"></script>
<script src="https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.zahl.js"></script>
<script>
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","விரிதாள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});
</script>
</body>
安装包后:
¥After installing the package:
npm i --save https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
这些脚本将在 xlsx/dist/xlsx.zahl
(CommonJS) 和 xlsx/dist/xlsx.zahl.mjs
(ESM) 上提供。
¥The scripts will be available at xlsx/dist/xlsx.zahl
(CommonJS) and
xlsx/dist/xlsx.zahl.mjs
(ESM).
var XLSX = require("xlsx");
var XLSX_ZAHL_PAYLOAD = require("xlsx/dist/xlsx.zahl");
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","விரிதாள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});
安装包后:
¥After installing the package:
bun i https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz
这些脚本将在 xlsx/dist/xlsx.zahl
(CommonJS) 和 xlsx/dist/xlsx.zahl.mjs
(ESM) 上提供。
¥The scripts will be available at xlsx/dist/xlsx.zahl
(CommonJS) and
xlsx/dist/xlsx.zahl.mjs
(ESM).
import * as XLSX from "xlsx";
import XLSX_ZAHL_PAYLOAD from "xlsx/dist/xlsx.zahl";
import * as fs from "fs";
XLSX.set_fs(fs);
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","விரிதாள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});
https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.zahl.mjs is the URL for 0.20.3
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-0.20.3/package/xlsx.mjs';
import XLSX_ZAHL_PAYLOAD from 'https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.zahl.mjs';
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","விரிதாள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});
支持的输出格式
¥Supported Output Formats
为了与第三方工具广泛兼容,该库支持多种输出格式。具体文件类型由 bookType
选项控制:
¥For broad compatibility with third-party tools, this library supports many
output formats. The specific file type is controlled with bookType
option:
bookType | extension | sheets | 描述 |
---|---|---|---|
xlsx | .xlsx | multi | Excel 2007+ XML 格式 |
xlsm | .xlsm | multi | Excel 2007+ 宏 XML 格式 |
xlsb | .xlsb | multi | Excel 2007+ 二进制格式 |
biff8 | .xls | multi | Excel 97-2004 工作簿格式 |
biff5 | .xls | multi | Excel 5.0/95 工作簿格式 |
biff4 | .xls | single | Excel 4.0 工作表格式 |
biff3 | .xls | single | Excel 3.0 工作表格式 |
biff2 | .xls | single | Excel 2.0 工作表格式 |
xlml | .xls | multi | Excel 2003-2004(SpreadsheetML) |
numbers | .numbers | multi | Numbers 3.0+ 电子表格 |
ods | .ods | multi | 开放文档电子表格 |
fods | .fods | multi | 扁平 OpenDocument 电子表格 |
wk3 | .wk3 | multi | Lotus 练习册 (WK3) |
csv | .csv | single | 逗号分隔值 |
txt | .txt | single | UTF-16 Unicode 文本 (TXT) |
sylk | .sylk | single | 符号链接 (SYLK) |
html | .html | single | HTML 文档 |
dif | .dif | single | 数据交换格式 (DIF) |
dbf | .dbf | single | dBASE II + VFP 扩展 (DBF) |
wk1 | .wk1 | single | Lotus 工作表 (WK1) |
rtf | .rtf | single | 富文本格式 (RTF) |
prn | .prn | single | 莲花格式的文本 |
eth | .eth | single | Ethercalc 记录格式 (ETH) |
-
compression
适用于基于 ZIP 的格式(XLSX、XLSM、XLSB、NUMBERS、ODS)¥
compression
applies to ZIP-based formats (XLSX, XLSM, XLSB, NUMBERS, ODS) -
仅支持单个工作表的格式需要指定工作表的
sheet
选项。如果字符串为空,则使用第一个工作表。¥Formats that only support a single sheet require a
sheet
option specifying the worksheet. If the string is empty, the first worksheet is used. -
如果未指定
bookType
,writeFile
将根据文件扩展名自动猜测输出文件格式。它将选择上述表中与扩展名匹配的第一个格式。¥
writeFile
will automatically guess the output file format based on the file extension ifbookType
is not specified. It will choose the first format in the aforementioned table that matches the extension.
输出类型
¥Output Type
type
选项指定输出的 JS 形式:
¥The type
option specifies the JS form of the output:
type | output |
---|---|
"base64" | 字符串:文件的 Base64 编码 |
"binary" | 字符串:二进制字符串(字节 n 是 data.charCodeAt(n) ) |
"string" | 字符串:JS 字符串(不兼容二进制格式) |
"buffer" | Node.js 缓冲区 |
"array" | ArrayBuffer,8 位无符号整数的后备数组 |
"file" | 字符串:将创建的文件的路径(仅限 nodejs) |
为了与 Excel 兼容,csv
输出将始终包含 UTF-8 字节顺序标记 ("BOM")。
¥For compatibility with Excel, csv
output will always include the UTF-8 byte
order mark ("BOM").
原始 sheet_to_csv
方法 将返回没有 UTF-8 BOM 的 JavaScript 字符串。
¥The raw sheet_to_csv
method will return
JavaScript strings without the UTF-8 BOM.