单元格对象

Cell 对象是纯 JS 对象，其键和值遵循以下约定：

¥Cell objects are plain JS objects with keys and values following the convention:

键	描述
	核心单元格特性
`t`	单元格类型 (更多信息)
`v`	基础值 (更多信息)
	数字格式 (更多信息)
`z`	与单元格关联的数字格式字符串（如果需要）
`w`	格式化文本（如果适用）
	公式（更多信息）
`f`	单元格公式编码为 A1 样式字符串（如果适用）
`F`	如果公式是数组公式，则封闭数组的范围（如果适用）
`D`	如果为 true，则数组公式是动态的（如果适用）
	其他单元特性 (更多信息)
`l`	单元格超链接/工具提示 (更多信息)
`c`	单元格注释 (更多信息)
`r`	富文本编码（如果适用）
`h`	富文本的 HTML 渲染（如果适用）
`s`	单元格的样式/主题（如果适用）

单元格对象应该有一个类型（t 属性）。具有值的单元格应将值存储在 v 属性中。单元格类型影响单元格值的解释。

¥Cell objects are expected to have a type (t property). Cells with values are expected to store the values in the v property. The cell type influences the interpretation of cell values.

内容和演示

¥Content and Presentation

电子表格通常将 "content" 与 "presentation" 分开。值为 $3.50 的单元格通常存储为数字单元格，其基础值为 3.5 和数字格式（例如 $0.00）

¥Spreadsheets typically separate "content" from "presentation". A cell with a value of $3.50 is typically stored as a numeric cell with an underlying value of 3.5 and a number format such as $0.00

单元格类型存储在单元格的 t 属性中。

¥The cell type is stored in the t property of the cell.

代表电子表格 "content" 的 JavaScript 等效值的基础值存储在单元格的 v 属性中。

¥The underlying value, representing a JavaScript equivalent of the spreadsheet "content", is stored in the v property of the cell.

数字格式字符串存储在单元格的 z 属性中。

¥The number format string is stored in the z property of the cell.

SheetJS 数字格式化库将生成格式化文本。它将存储在单元格的 w 属性中。

¥The SheetJS number formatting library will generate formatted text. It will be stored in the w property of the cell.

对于此示例，SheetJS 单元格表示将是

¥For this example, the SheetJS cell representation will be

var cell = {
  t: "n",     // numeric cell
  v: 3.5,     // underlying value 3.5
  z: "$0.00", // number format $0.00
  w: "$3.50"  // formatted text
};

大多数常见格式的解析器通常会在解析时生成格式化文本并跳过原始数字格式。有一些选项可以保留数字格式并跳过格式化文本生成。

¥Parsers for most common formats will typically generate formatted text at parse time and skip the original number formats. There are options to preserve the number formats and skip formatted text generation.

"数字格式" 更详细地讨论了格式设置。

¥"Number Formats" discusses formatting in more detail.

单元格类型

¥Cell Types

SheetJS 有 6 种单元格类型：

¥There are 6 SheetJS cell types:

类型	描述
`b`	布尔值：值解释为 JS `boolean`
`e`	错误：value 是一个数字代码，`w` 属性存储通用名称 **
`n`	数字：值为 JS `number` **
`d`	日期：value 是要解析为 Date 的 JS `Date` 对象或字符串 **
`s`	文本：值解释为 JS `string` 并写入为文本 **
`z`	存根：数据处理实用程序忽略的空白存根单元**

类型 n 是数字类型。这包括 Excel 以数字形式存储的所有形式的数据，例如日期/时间和布尔字段。Excel 专门使用可以适合 IEEE754 浮点数的数据，就像 JS Number 一样，因此 v 字段保存原始数字。w 字段保存格式化文本。日期默认存储为数字并使用 XLSX.SSF.parse_date_code 进行转换。

¥Type n is the Number type. This includes all forms of data that Excel stores as numbers, such as dates/times and Boolean fields. Excel exclusively uses data that can be fit in an IEEE754 floating point number, just like JS Number, so the v field holds the raw number. The w field holds formatted text. Dates are stored as numbers by default and converted with XLSX.SSF.parse_date_code.

类型 d 是 Date 类型，只有当选项 cellDates 被传递时才生成。由于 JSON 没有自然的日期类型，因此解析器通常应该存储 ISO 8601 日期字符串，就像从 date.toISOString() 中获取的那样。另一方面，编写器和导出器应该能够处理日期字符串和 JS Date 对象。请注意，Excel 忽略时区修饰符并处理本地时区中的所有日期。该库不会纠正此错误。日期有更详细的说明在日期部分

¥Type d is the Date type, generated only when the option cellDates is passed. Since JSON does not have a natural Date type, parsers are generally expected to store ISO 8601 Date strings like you would get from date.toISOString(). On the other hand, writers and exporters should be able to handle date strings and JS Date objects. Note that Excel disregards timezone modifiers and treats all dates in the local timezone. The library does not correct for this error. Dates are covered in more detail in the Dates section

类型 s 是字符串类型。值显式存储为文本。Excel 会将这些单元格解释为 "以文本形式存储的数字"。生成的 Excel 文件会自动抑制此类错误，但其他格式可能会引发错误。

¥Type s is the String type. Values are explicitly stored as text. Excel will interpret these cells as "number stored as text". Generated Excel files automatically suppress that class of error, but other formats may elicit errors.

类型 b 是布尔类型。值为 true 或 false。

¥Type b is the Boolean type. Values are either true or false.

类型 z 代表空白存根单元格。它们是在单元格没有分配值但保存注释或其他元数据的情况下生成的。它们被核心库数据处理实用函数忽略。默认情况下，不会生成这些单元格；解析器 sheetStubs 选项必须设置为 true。

¥Type z represents blank stub cells. They are generated in cases where cells have no assigned value but hold comments or other metadata. They are ignored by the core library data processing utility functions. By default these cells are not generated; the parser sheetStubs option must be set to true.

类型 e 是错误类型。v 字段保存数字错误代码，而 w 保存错误消息。有效值列于在 "错误" 表中。

¥Type e is the Error type. The v field holds numeric error codes, while w holds the error message. Valid values are listed in the "Error" table.

基本值

¥Underlying Values

电子表格约定并不总是与 JavaScript 约定一致。该库尝试在 Excel 值和 JavaScript 基础类型之间进行转换。

¥Spreadsheet conventions do not always line up with JavaScript conventions. The library attempts to translate between Excel values and JavaScript primitives.

Excel 值

¥Excel Values

Excel 中的每个值都有一个可以使用 TYPE 函数显示的类型。有四种标量类型：

¥Each value in Excel has a type which can be displayed with the TYPE function. There are four scalar types:

描述	示例	公式表达	结果
数字/日期/空白	`54337`	`=TYPE(54337)`	`1`
文本	`SheetJS`	`=TYPE("SheetJS")`	`2`
布尔（逻辑）	`TRUE`	`=TYPE(TRUE)`	`4`
错误	`#VALUE!`	`=TYPE(#VALUE!)`	`16`

Lotus 1-2-3、Excel 和其他电子表格软件通常将日期存储为数字，并使用数字格式来确定值是否代表日期。请参阅 "日期和时间" 了解更多信息。

¥Lotus 1-2-3, Excel, and other spreadsheet software typically store dates as numbers and use the number format to determine if values represent dates. See "Dates and Times" for more info.

数字

¥Number

每个有效的 Excel 数字都可以表示为 JavaScript 数字基元。[^1]

¥Each valid Excel number can be represented as a JavaScript number primitive.[^1]

SheetJS 库通常生成 JavaScript 数字。对于具有类似日期数字格式 [^2] 的单元格，可以选择生成 JavaScript Date 对象。

¥SheetJS libraries normally generate JavaScript numbers. For cells with date-like number formats[^2], there are options to generate JavaScript Date objects.

Excel 用大写 E 显示指数数字，而 JavaScript 数字传统上用小写 e 显示。尽管潜在的值可能看起来不同，但它们在功能上是相同的。

¥Excel displays exponential numbers with an uppercase E while JavaScript numbers are traditionally displayed with a lowercase e. Even though the underlying values may appear different, they are functionally identical.

文本

¥Text

每个有效的 Excel 字符串都可以表示为 JavaScript 字符串基础类型。SheetJS 库生成 JavaScript 字符串。

¥Each valid Excel string can be represented as a JavaScript string primitive. SheetJS libraries generate JavaScript strings.

布尔值

¥Boolean

有两个布尔值："true" 和 "false"。

¥There are two Boolean values: "true" and "false".

Excel 以大写形式渲染布尔值：TRUE 和 FALSE

¥Excel renders the Boolean values in uppercase: TRUE and FALSE

JavaScript 以小写形式渲染布尔字面量：true 和 false

¥JavaScript renders Boolean literals in lowercase: true and false

SheetJS 库生成 JavaScript 表单。格式化文本将为大写 TRUE 或 FALSE，与 Excel 渲染相匹配。

¥SheetJS libraries generate the JavaScript form. The formatted text will be the uppercase TRUE or FALSE, matching Excel rendering.

错误

¥Error

Excel 错误的基础值是一个数字。下面列出了支持的错误类型和数值：

¥The underlying value for an Excel error is a number. The supported error types and numeric values are listed below:

Excel 错误	值
`#NULL!`	`0x00`
`#DIV/0!`	`0x07`
`#VALUE!`	`0x0F`
`#REF!`	`0x17`
`#NAME?`	`0x1D`
`#NUM!`	`0x24`
`#N/A`	`0x2A`
`#GETTING_DATA`	`0x2B`

SheetJS 解析器标记错误单元格的单元格类型并存储列出的数值。格式化文本将是 Excel 中显示的错误字符串。

¥SheetJS parsers mark the cell type of error cells and store the listed numeric value. The formatted text will be the error string shown in Excel.

#SPILL!、#CONNECT! 和 #BLOCKED! 错误将作为 #VALUE! 保存到文件中。

¥#SPILL!, #CONNECT!, and #BLOCKED! errors are saved to files as #VALUE!.

JavaScript 值

¥JavaScript Values

JavaScript 中的每个原始值都有一个可以使用 typeof 运算符显示的类型。JavaScript 的 ECMAScript 5 方言中有 5 种类型：

¥Each primitive value in JavaScript has a type which can be displayed with the typeof operator. There are 5 types in the ECMAScript 5 dialect of JavaScript:

类型	示例	`typeof`
未定义	`undefined`	`"undefined"`
Null	`null`	`"null"`
布尔值	`true`	`"boolean"`
字符串	`"SheetJS"`	`"string"`
数字	`5433795`	`"number"`

未定义

¥Undefined

JavaScript 中的 undefined 在精神上相当于 Excel 中的空白单元格值。默认情况下，生成工作表的 SheetJS 方法会跳过 undefined。

¥undefined in JavaScript is spiritually equivalent to a blank cell value in Excel. By default, SheetJS methods that generate worksheets skip undefined.

Null

JavaScript 中的 null 通常用于表示没有数据。Excel 中的 #NULL! 错误旨在破坏引用单元格 [^3] 的公式表达式。#NULL! 在精神上与 NaN 相似。

¥null in JavaScript typically is used to represent no data. The #NULL! error in Excel is intended to break formula expressions that reference the cells[^3]. #NULL! is spiritually similar to NaN.

默认情况下，生成工作表的 SheetJS 方法会跳过 null。某些方法包括生成 #NULL! 错误单元的选项。

¥By default, SheetJS methods that generate worksheets skip null. Some methods include options to generate #NULL! error cells.

布尔值

¥Boolean

有两个布尔值："true" 和 "false"。

¥There are two Boolean values: "true" and "false".

SheetJS 库将 JavaScript true / false 字面量映射到 Excel TRUE / FALSE 布尔值。

¥SheetJS libraries map JavaScript true / false literals to Excel TRUE / FALSE Boolean values.

字符串

¥String

JavaScript 字符串的基础值始终是原始字符串。

¥The underlying value of a JavaScript string is always the original string.

SheetJS 导出方法将根据需要缩短或重新编码字符串，以导出所请求文件格式的有效字符串。

¥SheetJS export methods will shorten or re-encode strings as necessary to export valid strings for the requested file formats.

数字

¥Number

JavaScript 数字的基础值始终是原始数字。

¥The underlying value of a JavaScript number is always the original number.

SheetJS 导出方法会将支持的数字转换为数字单元格。NaN 值将转换为 Excel #NUM! 错误。无穷大和非规范化值将转换为 #DIV/0!。

¥SheetJS export methods will translate supported numbers to numeric cells. NaN values will be translated to Excel #NUM! errors. Infinities and denormalized values are translated to #DIV/0!.

日期

¥Dates

JavaScript Date 对象是对象。可以使用 instanceof 运算符将它们与其他对象区分开。

¥JavaScript Date objects are Objects. They can be distinguished from other Objects with the instanceof operator.

SheetJS 日期单元格可以保存 Date 对象。将工作簿导出为不具有原生日期类型的格式时，这些值将转换为日期代码。

¥SheetJS date cells can hold Date objects. When exporting workbooks to formats that do not have native Date types, the values will be translated to date codes.

[^1]: 每个有效的 Excel 数字都可以表示为 IEEE754 双精度数。Excel 不支持非规范化数字、NaN 系列、Infinity 或 -Infinity。有关详细信息，请参阅 Excel 文档中的 "在 Excel 中浮点运算可能会给出不准确的结果"。

¥Each valid Excel number can be represented as an IEEE754 double. Excel does not support denormalized numbers, the NaN family, Infinity, or -Infinity. See "Floating-point arithmetic may give inaccurate results in Excel" in the Excel documentation for more information.

[^2]: "数字格式" 的 "日期和时间" 部分中的表列出了 SheetJS 用于确定单元格值是否应被视为日期的标记。

¥The table in "Dates and Times" section of "Number Formats" lists the tokens that SheetJS uses to determine if a cell value should be treated as a Date.

[^3]: Excel 文档中的 NULL 功能解释了预期的用例。

¥NULL function in the Excel documentation explains the intended use case.

内容和演示​

单元格类型​

基本值​

Excel 值​

数字​

文本​

布尔值​

错误​

JavaScript 值​

未定义​

Null​