Skip to main content

写入文件

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.

如果省略 optionsoptions 对象中缺少 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);

writeXLSXwriteFileXLSXwritewriteFile 的限量版。它们支持写入 XLSX 文件格式。

¥writeXLSX and writeFileXLSX are limited versions of write and writeFile. They support writing to the XLSX file format.

对于专门导出到 XLSX 的网站来说,这些功能可以减少生产网站的大小。一般的 writewriteFile 函数在导出为 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输出数据编码(参见下面的输出类型)
cellDatesfalse将日期存储为 d 类型(默认为 n
cellStylesfalse将样式/主题信息保存到 .s 字段
codepage如果指定,则在适当时使用代码页**
bookSSTfalse生成共享字符串表**
bookType"xlsx"工作簿类型(有关支持的格式,请参阅下文)
bookVBA将工作簿对象中的 VBA blob 添加到文件 **
WTFfalse如果为 true,则对意外功能抛出错误 **
sheet""单表格式的工作表名称 **
compressionfalse对基于 ZIP 的格式使用 ZIP 压缩 **
Props写入时覆盖工作簿属性 **
themeXLSX编写 XLSX/XLSB/XLSM 时覆盖主题 XML **
ignoreECtrue抑制 "数字作为文本" 错误 **
numbersNUMBERS 导出的有效负载 **
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 type d 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 workbook Props 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 (to xl/theme/theme1.xml in the ZIP)

  • 由于程序中存在错误,某些功能(例如 "文本到列")会在忽略错误条件的工作表上导致 Excel 崩溃。默认情况下,编写器将标记文件以忽略错误。设置 ignoreECfalse 进行抑制。

    ¥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 to false to suppress.

  • FSRS 适用于 CSV 和文本输出格式。这些选项在 "CSV 和文本" 中讨论

    ¥FS and RS 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:

  1. 加载 xlsx.zahl 脚本

    ¥Load the xlsx.zahl script

  2. 将有效负载传递到 numbers 选项到 writewriteFile

    ¥Pass the payload into the numbers option to write or writeFile.

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>

支持的输出格式

¥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:

bookTypeextensionsheets描述
xlsx.xlsxmultiExcel 2007+ XML 格式
xlsm.xlsmmultiExcel 2007+ 宏 XML 格式
xlsb.xlsbmultiExcel 2007+ 二进制格式
biff8.xlsmultiExcel 97-2004 工作簿格式
biff5.xlsmultiExcel 5.0/95 工作簿格式
biff4.xlssingleExcel 4.0 工作表格式
biff3.xlssingleExcel 3.0 工作表格式
biff2.xlssingleExcel 2.0 工作表格式
xlml.xlsmultiExcel 2003-2004(SpreadsheetML)
numbers.numbersmultiNumbers 3.0+ 电子表格
ods.odsmulti开放文档电子表格
fods.fodsmulti扁平 OpenDocument 电子表格
wk3.wk3multiLotus 练习册 (WK3)
csv.csvsingle逗号分隔值
txt.txtsingleUTF-16 Unicode 文本 (TXT)
sylk.sylksingle符号链接 (SYLK)
html.htmlsingleHTML 文档
dif.difsingle数据交换格式 (DIF)
dbf.dbfsingledBASE II + VFP 扩展 (DBF)
wk1.wk1singleLotus 工作表 (WK1)
rtf.rtfsingle富文本格式 (RTF)
prn.prnsingle莲花格式的文本
eth.ethsingleEthercalc 记录格式 (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.

  • 如果未指定 bookTypewriteFile 将根据文件扩展名自动猜测输出文件格式。它将选择上述表中与扩展名匹配的第一个格式。

    ¥writeFile will automatically guess the output file format based on the file extension if bookType 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:

typeoutput
"base64"字符串:文件的 Base64 编码
"binary"字符串:二进制字符串(字节 ndata.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.