docs.sheetjs.com/docz/docs/07-csf/04-book.md

100 lines
3.3 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
2022-06-01 22:59:29 +00:00
sidebar_position: 4
2022-05-16 03:26:04 +00:00
---
# Workbook Object
2022-09-05 10:00:35 +00:00
For a given workbook object `wb`:
2022-05-16 03:26:04 +00:00
2022-09-05 10:00:35 +00:00
`wb.SheetNames` is an ordered list of the sheets in the workbook.
`wb.Sheets` is an object whose keys are worksheet names (from `SheetNames`) and
whose values are worksheet objects.
2022-05-16 03:26:04 +00:00
`wb.Props` is an object storing the standard properties. `wb.Custprops` stores
custom properties. Since the XLS standard properties deviate from the XLSX
standard, XLS parsing stores core properties in both places.
`wb.Workbook` stores [workbook-level attributes](#workbook-level-attributes).
2022-09-05 10:00:35 +00:00
When reading a file, `wb.bookType` is the determined book type.
2022-05-16 03:26:04 +00:00
## File Properties
The various file formats use different internal names for file properties. The
workbook `Props` object normalizes the names:
2022-06-01 22:59:29 +00:00
<details open><summary><b>File Properties</b> (click to hide)</summary>
2022-05-16 03:26:04 +00:00
| JS Name | Excel Description |
|:--------------|:-------------------------------|
| `Title` | Summary tab "Title" |
| `Subject` | Summary tab "Subject" |
| `Author` | Summary tab "Author" |
| `Manager` | Summary tab "Manager" |
| `Company` | Summary tab "Company" |
| `Category` | Summary tab "Category" |
| `Keywords` | Summary tab "Keywords" |
| `Comments` | Summary tab "Comments" |
| `LastAuthor` | Statistics tab "Last saved by" |
| `CreatedDate` | Statistics tab "Created" |
</details>
For example, to set the workbook title property:
```js
if(!wb.Props) wb.Props = {};
wb.Props.Title = "Insert Title Here";
```
Custom properties are added in the workbook `Custprops` object:
```js
if(!wb.Custprops) wb.Custprops = {};
wb.Custprops["Custom Property"] = "Custom Value";
```
Writers will process the `Props` key of the options object:
```js
/* force the Author to be "SheetJS" */
2023-04-01 20:13:16 +00:00
XLSX.write(wb, { Props: { Author: "SheetJS" } });
2022-05-16 03:26:04 +00:00
```
## Workbook-Level Attributes
`wb.Workbook` stores workbook-level attributes.
### Defined Names
2023-05-14 07:48:56 +00:00
`wb.Workbook.Names` is an array of defined name objects. Defined names are
discussed in more detail in ["Defined Names"](/docs/csf/features/names)
2023-04-01 20:13:16 +00:00
2022-05-16 03:26:04 +00:00
### Workbook Views
`wb.Workbook.Views` is an array of workbook view objects which have the keys:
| Key | Description |
|:----------------|:----------------------------------------------------|
| `RTL` | If true, display right-to-left |
### Miscellaneous Workbook Properties
`wb.Workbook.WBProps` holds other workbook properties:
2022-10-30 05:45:37 +00:00
| Key | Description |
|:----------------|:-----------------------------------------------------------|
2023-05-23 18:53:11 +00:00
| `CodeName` | [VBA Workbook Name](/docs/csf/features/vba) |
2022-10-30 05:45:37 +00:00
| `date1904` | epoch: 0/false for 1900 system, 1/true for 1904 |
| `filterPrivacy` | Warn or strip personally identifying info on save |
2023-08-20 20:39:35 +00:00
### Sheet Metadata
`wb.Workbook.Sheets` is an array of sheet metadata objects which have the keys:
| Key | Description |
|:----------------|:----------------------------------------------------|
| `Hidden` | [Sheet Visibility](/docs/csf/features/visibility) |
| `CodeName` | [VBA Sheet Code Name](/docs/csf/features/vba) |