2022-06-01 22:59:29 +00:00
|
|
|
---
|
2023-08-18 20:39:12 +00:00
|
|
|
title: Cell Objects
|
2022-06-01 22:59:29 +00:00
|
|
|
sidebar_position: 2
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
Cell objects are plain JS objects with keys and values following the convention:
|
|
|
|
|
|
|
|
|
|
| Key | Description |
|
|
|
|
|
| --- | ---------------------------------------------------------------------- |
|
|
|
|
|
| | **Core Cell Properties** ([More Info](#data-types)) |
|
|
|
|
|
| `t` | type: `b` Boolean, `e` Error, `n` Number, `d` Date, `s` Text, `z` Stub |
|
2023-08-18 20:39:12 +00:00
|
|
|
| `v` | raw value (number, string, Date object, boolean) |
|
2023-05-18 09:21:08 +00:00
|
|
|
| | **Number Formats** ([More Info](/docs/csf/features/nf)) |
|
2022-06-01 22:59:29 +00:00
|
|
|
| `z` | number format string associated with the cell (if requested) |
|
|
|
|
|
| `w` | formatted text (if applicable) |
|
2022-10-30 05:45:37 +00:00
|
|
|
| | **Formulae** ([More Info](/docs/csf/features/formulae)) |
|
2022-08-23 03:20:02 +00:00
|
|
|
| `f` | cell formula encoded as an A1-Style string (if applicable) |
|
2022-06-01 22:59:29 +00:00
|
|
|
| `F` | range of enclosing array if formula is array formula (if applicable) |
|
|
|
|
|
| `D` | if true, array formula is dynamic (if applicable) |
|
2022-10-30 05:45:37 +00:00
|
|
|
| | **Other Cell Properties** ([More Info](/docs/csf/features)) |
|
|
|
|
|
| `l` | cell hyperlink / tooltip ([More Info](/docs/csf/features/hyperlinks)) |
|
|
|
|
|
| `c` | cell comments ([More Info](/docs/csf/features/comments)) |
|
2022-06-01 22:59:29 +00:00
|
|
|
| `r` | rich text encoding (if applicable) |
|
|
|
|
|
| `h` | HTML rendering of the rich text (if applicable) |
|
|
|
|
|
| `s` | the style/theme of the cell (if applicable) |
|
|
|
|
|
|
2023-08-18 20:39:12 +00:00
|
|
|
Cell objects are expected to have a type (`t` property).
|
|
|
|
|
|
|
|
|
|
Built-in utilities that use formatted text (such as the CSV exporter) will use
|
|
|
|
|
the `w` text if available. When programmatically changing values, the `w` text
|
|
|
|
|
should be deleted before attempting to export. Utilities will regenerate the `w`
|
2022-06-01 22:59:29 +00:00
|
|
|
text from the number format (`cell.z`) and the raw value if possible.
|
|
|
|
|
|
|
|
|
|
The actual array formula is stored in the `f` field of the first cell in the
|
|
|
|
|
array range. Other cells in the range will omit the `f` field.
|
|
|
|
|
|
|
|
|
|
### Data Types
|
|
|
|
|
|
|
|
|
|
The raw value is stored in the `v` value property, interpreted based on the `t`
|
|
|
|
|
type property. This separation allows for representation of numbers as well as
|
|
|
|
|
numeric text. There are 6 valid 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.
|
2022-10-30 05:45:37 +00:00
|
|
|
Dates are covered in more detail [in the Dates section](/docs/csf/features/dates)
|
2022-06-01 22:59:29 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2023-05-15 08:38:23 +00:00
|
|
|
Type `b` is the Boolean type. Values are either `true` or `false`.
|
|
|
|
|
|
2022-06-01 22:59:29 +00:00
|
|
|
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`.
|
|
|
|
|
|
2023-05-15 08:38:23 +00:00
|
|
|
Type `e` is the Error type. The `v` field holds numeric error codes, while `w`
|
|
|
|
|
holds the error message. Acceptable values are listed below:
|
|
|
|
|
|
|
|
|
|
| Value | Error Meaning |
|
|
|
|
|
| -----: | :-------------- |
|
|
|
|
|
| `0x00` | `#NULL!` |
|
|
|
|
|
| `0x07` | `#DIV/0!` |
|
|
|
|
|
| `0x0F` | `#VALUE!` |
|
|
|
|
|
| `0x17` | `#REF!` |
|
|
|
|
|
| `0x1D` | `#NAME?` |
|
|
|
|
|
| `0x24` | `#NUM!` |
|
|
|
|
|
| `0x2A` | `#N/A` |
|
|
|
|
|
| `0x2B` | `#GETTING_DATA` |
|
