Skip to main content

Cell Objects单元格对象

Cell objects are plain JS objects with keys and values following the convention:单元格对象是简单的JS对象，其键和值遵循约定：

Key键Description描述
Core Cell Properties核心单元属性
tcell type (more info)单元格类型（更多信息）
vunderlying value底层值 (more info)
Number Formats字格式 (More Info)
znumber format string associated with the cell (if requested)与单元格关联的数字格式字符串（如果请求）
wformatted text (if applicable)格式化文本（如果适用）
Formulae公式 (More Info)
fcell formula encoded as an A1-Style string (if applicable)编码为A1样式字符串的单元格公式（如果适用）
Frange of enclosing array if formula is array formula (if applicable)如果公式是数组公式，则封闭数组的范围（如果适用）
Dif true, array formula is dynamic (if applicable)如果为true，则数组公式是动态的（如果适用）
Other Cell Properties其他单元格属性 (More Info)
lcell hyperlink / tooltip单元格超链接/工具提示 (More Info)
ccell comments单元格注释 (More Info)
rrich text encoding (if applicable)富格文本编码（如果适用）
hHTML rendering of the rich text (if applicable)富文本的HTML呈现（如果适用）
sthe style/theme of the cell (if applicable)单元格的样式/主题（如果适用）

Cell objects are expected to have a type (t property). 单元格对象应具有类型（t属性）。Cells with values are expected to store the values in the v property. The cell type influences the interpretation of cell values.具有值的单元格应将值存储在v属性中。单元格类型会影响单元格值的解释。

Content and Presentation内容和演示​

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值为$3.50的单元格通常存储为基本值为3.5、数字格式（如$0.00）的数字单元格

The cell type is stored in the t property of the cell.单元格类型存储在单元格的t属性中。

The underlying value, representing a JavaScript equivalent of the spreadsheet "content", is stored in the v property of the cell.基本值表示相当于电子表格“内容”的JavaScript，存储在单元格的v属性中。

The number format string is stored in the z property of the cell.数字格式字符串存储在单元格的z属性中。

The SheetJS number formatting library will generate formatted text. It will be stored in the w property of the cell.SheetJS数字格式化库将生成格式化文本。它将存储在单元格的w属性中。

For this example, the SheetJS cell representation will be对于本例，SheetJS单元格表示形式将为

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单元格类型​

There are 6 SheetJS cell types:有6种SheetJS单元格类型：

Type类型Description描述
bBoolean: value interpreted as JS booleanBoolean：被解释为JSboolean
eError: value is a numeric code and w property stores common nameError：值是一个数字代码，w属性存储通用名称 **
nNumber: value is a JS numberNumber：值是JSnumber **
dDate: value is a JS Date object or string to be parsed as DateDate：值是要解析为日期时间的JS Date对象或字符串 **
sText: value interpreted as JS string and written as textText：值被解释为JSstring，并被写成文本 **
zStub: blank stub cell that is ignored by data processing utilitiesStub：数据处理实用程序忽略的空白存根单元格 **

Type n is the Number type. This includes all forms of data that Excel stores as numbers, such as dates/times and Boolean fields. 类型n是数字类型。这包括Excel存储为数字的所有形式的数据，如日期/时间和布尔字段。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. Excel只使用可以放入IEEE754浮点数的数据，就像JS数字一样，因此v字段包含原始数字。The w field holds formatted text. w字段包含格式化文本。Dates are stored as numbers by default and converted with XLSX.SSF.parse_date_code.默认情况下，日期存储为数字，并使用XLSX.SSF.parse_date_code进行转换。

Type d is the Date type, generated only when the option cellDates is passed. 类型d是日期类型，仅在传递选项cellDates时生成。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(). 由于JSON没有自然的Date类型，因此通常要求解析器存储ISO 8601日期字符串，就像从date.toISOString()中获得的那样。On the other hand, writers and exporters should be able to handle date strings and JS Date objects. 另一方面，编写器和导出器应该能够处理日期字符串和JS-date对象。Note that Excel disregards timezone modifiers and treats all dates in the local timezone. 请注意，Excel不考虑时区修饰符，而是处理本地时区中的所有日期。The library does not correct for this error. 库无法更正此错误。Dates are covered in more detail in the Dates section日期部分详细介绍了日期

Type s is the String type. 类型s是字符串类型。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.Excel将这些单元格解释为“以文本形式存储的数字”。生成的Excel文件会自动抑制此类错误，但其他格式可能会引发错误。

Type b is the Boolean type. Values are either true or false.类型b是布尔类型。值要么为true，要么为false。

Type z represents blank stub cells. They are generated in cases where cells have no assigned value but hold comments or other metadata. 类型z表示空白存根单元格。它们是在单元格没有赋值但包含注释或其他元数据的情况下生成的。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.默认情况下，不会生成这些单元格；解析器sheetStubs选项必须设置为true。

Type e is the Error type. 类型e是错误类型。The v field holds numeric error codes, while w holds the error message. v字段包含数字错误代码，而w字段包含错误消息。Valid values are listed in the "Error" table.有效值列在“错误”表中。

Underlying Values底层值​

Spreadsheet conventions do not always line up with JavaScript conventions. The library attempts to translate between Excel values and JavaScript primitives.电子表格约定并不总是与JavaScript约定一致。该库尝试在Excel值和JavaScript基元之间进行转换。

Excel ValuesExcel值​

Each value in Excel has a type which can be displayed with the TYPE function. Excel中的每个值都有一个类型，可以使用TYPE函数显示。There are four scalar types:有四种标量类型：

Description描述Example实例Formula Expression公式表达式Result后果
Number / Date / Blank54337=TYPE(54337)1
TextSheetJS=TYPE("SheetJS")2
Boolean (Logical)TRUE=TYPE(TRUE)4
Error#VALUE!=TYPE(#VALUE!)16

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. Lotus 1-2-3、Excel和其他电子表格软件通常将日期存储为数字，并使用数字格式来确定值是否表示日期。See "Dates and Times" for more info.请参阅日期和时间了解更多信息。

Number​

Each valid Excel number can be represented as a JavaScript number primitive.每个有效的Excel数字都可以表示为一个JavaScript数字基元。1

SheetJS libraries normally generate JavaScript numbers. For cells with date-like number formatsSheetJS库通常生成JavaScript数字。对于具有类似日期的数字格式的单元格2, there are options to generate JavaScript Date objects.，有生成JavaScriptDate对象的选项。

Excel displays exponential numbers with an uppercase E while JavaScript numbers are traditionally displayed with a lowercase e. Excel以大写E显示指数数字，而JavaScript数字传统上以小写e显示。Even though the underlying values may appear different, they are functionally identical.尽管基本值可能看起来不同，但它们在功能上是相同的。

Text​

Each valid Excel string can be represented as a JavaScript string primitive. SheetJS libraries generate JavaScript strings.每个有效的Excel字符串都可以表示为JavaScript字符串基元。SheetJS库生成JavaScript字符串。

Boolean​

There are two Boolean values: "true" and "false".有两个布尔值：“true”和“false”。

Excel renders the Boolean values in uppercase: Excel以大写形式呈现布尔值：TRUE and 和FALSE

JavaScript renders Boolean literals in lowercase: true and falseJavaScript以小写形式呈现布尔文字：true和false

SheetJS libraries generate the JavaScript form. The formatted text will be the uppercase TRUE or FALSE, matching Excel rendering.SheetJS库生成JavaScript表单。格式化的文本将是大写的TRUE或FALSE，与Excel呈现相匹配。

Error​

The underlying value for an Excel error is a number. The supported error types and numeric values are listed below:Excel错误的基本值是一个数字。下面列出了支持的错误类型和数值：

Excel ErrorExcel错误Value值
#NULL!0x00
#DIV/0!0x07
#VALUE!0x0F
#REF!0x17
#NAME?0x1D
#NUM!0x24
#N/A0x2A
#GETTING_DATA0x2B

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.SheetJS解析器标记错误单元格的单元格类型，并存储列出的数值。格式化后的文本将是Excel中显示的错误字符串。

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

JavaScript Values值​

Each primitive value in JavaScript has a type which can be displayed with the typeof operator. JavaScript中的每个基元值都有一个可以用typeof运算符显示的类型。There are 5 types in the ECMAScript 5 dialect of JavaScript:JavaScript的ECMAScript 5方言中有5种类型：

Type类型Exampletypeof
Undefinedundefined"undefined"
Nullnull"null"
Booleantrue"boolean"
String"SheetJS""string"
Number5433795"number"

Undefined​

undefined in JavaScript is spiritually equivalent to a blank cell value in Excel. JavaScript中的undefined在精神上等同于Excel中的空白单元格值。By default, SheetJS methods that generate worksheets skip undefined.默认情况下，生成工作表的SheetJS方法跳过undefined的。

Null​

null in JavaScript typically is used to represent no data. JavaScript中的null通常用于表示没有数据。The #NULL! error in Excel is intended to break formula expressions that reference the cells3. #NULL! is spiritually similar to NaN.Excel中的#NULL!错误旨在破坏引用单元格3的公式表达式。#NULL!在精神上与NaN相似。

By default, SheetJS methods that generate worksheets skip null. 默认情况下，生成工作表的SheetJS方法跳过null。Some methods include options to generate #NULL! error cells.一些方法包括生成#NULL!错误单元格。

Boolean​

There are two Boolean values: "true" and "false".有两个布尔值：“true”和“false”。

SheetJS libraries map JavaScript true / false literals to Excel TRUE / FALSE Boolean values.SheetJS库将JavaScripttrue / false文本映射到Excel true/false布尔值。

String​

The underlying value of a JavaScript string is always the original string.JavaScript字符串的基本值始终是原始字符串。

SheetJS export methods will shorten or re-encode strings as necessary to export valid strings for the requested file formats.SheetJS导出方法将根据需要缩短或重新编码字符串，以导出所请求文件格式的有效字符串。

Number​

The underlying value of a JavaScript number is always the original number.JavaScript数字的基本值始终是原始数字。

SheetJS export methods will translate supported numbers to numeric cells. SheetJS导出方法将支持的数字转换为数字单元格。NaN values will be translated to Excel #NUM! errors. 值将被转换为Excel#NUM!错误。Infinities and denormalized values are translated to #DIV/0!.无穷大和非规范化值被转换为#DIV/0!。

Dates​

JavaScript Date objects are Objects. 对象就是对象。They can be distinguished from other Objects with the instanceof operator.可以使用instanceof运算符将它们与其他对象区分开来。

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.SheetJS日期单元格可以容纳date对象。将工作簿导出为不具有本机日期类型的格式时，这些值将被转换为日期代码。

  1. Each valid Excel number can be represented as an IEEE754 double. Excel does not support denormalized numbers, the NaN family, Infinity, or -Infinity. 每个有效的Excel数字都可以表示为IEEE754双精度。Excel不支持非规范化数字、NaN族、Infinity或-Infinity。See "Floating-point arithmetic may give inaccurate results in Excel" in the Excel documentation for more information.有关详细信息，请参阅Excel文档中的“浮点运算可能会在Excel中给出不准确的结果”。↩
  2. 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.“数字格式”的“日期和时间”部分的表列出了SheetJS用于确定是否应将单元格值视为日期的标记。↩
  3. NULL function in the Excel documentation explains the intended use case.Excel文档中的NULL函数解释了预期的用例。↩