Cell Objects
Cell objects are plain JS objects with keys and values following the convention:
| Key | Description |
|---|---|
| Core Cell Properties | |
t | cell type (more info) |
v | underlying value (more info) |
| Number Formats (More Info) | |
z | number format string associated with the cell (if requested) |
w | formatted text (if applicable) |
| Formulae (More Info) | |
f | cell formula encoded as an A1-Style string (if applicable) |
F | range of enclosing array if formula is array formula (if applicable) |
D | if true, array formula is dynamic (if applicable) |
| Other Cell Properties (More Info) | |
l | cell hyperlink / tooltip (More Info) |
c | cell comments (More Info) |
r | rich text encoding (if applicable) |
h | HTML rendering of the rich text (if applicable) |
s | the style/theme of the cell (if applicable) |
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​
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
The cell type is stored in the t property of the cell.
The underlying value, representing a JavaScript equivalent of the spreadsheet
"content", is stored in the v property of the cell.
The number format string is stored in the z property of the cell.
The SheetJS number formatting library will generate formatted text. It will be
stored in the w property of the cell.
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​
There are 6 SheetJS cell types:
| Type | Description |
|---|---|
b | Boolean: value interpreted as JS boolean |
e | Error: value is a numeric code and w property stores common name ** |
n | Number: value is a JS number ** |
d | Date: value is a JS Date object or string to be parsed as Date ** |
s | Text: value interpreted as JS string and written as text ** |
z | Stub: blank stub cell that is ignored by data processing utilities ** |
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.
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
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.
Type b is the Boolean type. Values are either true or false.
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.
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​
Spreadsheet conventions do not always line up with JavaScript conventions. The library attempts to translate between Excel values and JavaScript primitives.
Excel Values​
Each value in Excel has a type which can be displayed with the TYPE function.
There are four scalar types:
| Description | Example | Formula Expression | Result |
|---|---|---|---|
| Number / Date / Blank | 54337 | =TYPE(54337) | 1 |
| Text | SheetJS | =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. See "Dates and Times" for more info.
Number​
Each valid Excel number can be represented as a JavaScript number primitive.1
SheetJS libraries normally generate JavaScript numbers. For cells with date-like
number formats2, there are options to generate JavaScript Date objects.
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​
Each valid Excel string can be represented as a JavaScript string primitive. SheetJS libraries generate JavaScript strings.
Boolean​
There are two Boolean values: "true" and "false".
Excel renders the Boolean values in uppercase: TRUE and FALSE
JavaScript renders Boolean literals in lowercase: true and false
SheetJS libraries generate the JavaScript form. The formatted text will be the
uppercase TRUE or FALSE, matching Excel rendering.
Error​
The underlying value for an Excel error is a number. The supported error types and numeric values are listed below:
| Excel Error | Value |
|---|---|
#NULL! | 0x00 |
#DIV/0! | 0x07 |
#VALUE! | 0x0F |
#REF! | 0x17 |
#NAME? | 0x1D |
#NUM! | 0x24 |
#N/A | 0x2A |
#GETTING_DATA | 0x2B |
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!, 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. There are 5 types in the ECMAScript 5 dialect of JavaScript:
| Type | Example | typeof |
|---|---|---|
| Undefined | undefined | "undefined" |
| Null | null | "null" |
| Boolean | true | "boolean" |
| String | "SheetJS" | "string" |
| Number | 5433795 | "number" |
Undefined​
undefined in JavaScript is spiritually equivalent to a blank cell value in
Excel. By default, SheetJS methods that generate worksheets skip undefined.
Null​
null in JavaScript typically is used to represent no data. The #NULL! error
in Excel is intended to break formula expressions that reference the cells3.
#NULL! is spiritually similar to NaN.
By default, SheetJS methods that generate worksheets skip null. Some methods
include options to generate #NULL! error cells.
Boolean​
There are two Boolean values: "true" and "false".
SheetJS libraries map JavaScript true / false literals to Excel TRUE /
FALSE Boolean values.
String​
The underlying value of a JavaScript string is always the original string.
SheetJS export methods will shorten or re-encode strings as necessary to export valid strings for the requested file formats.
Number​
The underlying value of a JavaScript number is always the original number.
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 objects are Objects. They can be distinguished from other
Objects with the instanceof operator.
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.
Footnotes​
-
Each valid Excel number can be represented as an IEEE754 double. Excel does not support denormalized numbers, the
NaNfamily,Infinity, or-Infinity. See "Floating-point arithmetic may give inaccurate results in Excel" in the Excel documentation for more information. ↩ -
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. ↩
-
NULLfunction in the Excel documentation explains the intended use case. ↩