docs.sheetjs.com/docz/docs/06-solutions/03-processing.md

199 lines
4.8 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
---
sidebar_position: 3
---
# Data Processing
2022-10-30 05:45:37 +00:00
The ["Common Spreadsheet Format"](/docs/csf/general) is a simple object
2022-05-16 03:26:04 +00:00
representation of the core concepts of a workbook. The utility functions work
with the object representation and are intended to handle common use cases.
2022-10-30 05:45:37 +00:00
The [Data Input](/docs/solutions/input) and [Data Output](/docs/solutions/output) sections cover how to
2022-08-24 23:48:22 +00:00
read from data sources and write to data sources.
2022-05-16 03:26:04 +00:00
2022-08-24 23:48:22 +00:00
## Workbook
### Worksheets
2023-09-24 03:59:48 +00:00
:::note pass
2022-08-24 23:48:22 +00:00
Worksheet names are case-sensitive.
:::
_List the Worksheet names in tab order_
```js
var wsnames = workbook.SheetNames;
```
The `SheetNames` property of the workbook object is a list of the worksheet
names in "tab order". API functions will look at this array.
_Access a Worksheet by name_
```js
var worksheet = workbook.Sheets[sheet_name];
```
The workbook object's `Sheets` property is an object whose keys are sheet names
and whose values are worksheet objects.
_Access the first Worksheet_
```js
var first_ws = workbook.Sheets[workbook.SheetNames[0]];
```
2022-08-25 08:22:28 +00:00
Combining the previous examples, `workbook.Sheets[workbook.SheetNames[0]]` is
the first worksheet if it exists in the workbook.
2022-08-24 23:48:22 +00:00
_Replace a Worksheet in place_
```js
workbook.Sheets[sheet_name] = new_worksheet;
```
The `Sheets` property of the workbook object is an object whose keys are names
and whose values are worksheet objects. By reassigning to a property of the
`Sheets` object, the worksheet object can be changed without disrupting the
rest of the worksheet structure.
2022-05-16 03:26:04 +00:00
_Append a Worksheet to a Workbook_
```js
XLSX.utils.book_append_sheet(workbook, worksheet, sheet_name);
```
2023-06-25 09:36:58 +00:00
The [`book_append_sheet`](/docs/api/utilities/wb) utility function appends a
worksheet to the workbook.
2022-05-16 03:26:04 +00:00
_Append a Worksheet to a Workbook and find a unique name_
```js
var new_name = XLSX.utils.book_append_sheet(workbook, worksheet, name, true);
```
2023-06-25 09:36:58 +00:00
If the fourth argument is `true`, the function will try to find a new worksheet
name in case of a collision.
2022-05-16 03:26:04 +00:00
#### Examples
```js
var ws_name = "SheetJS";
/* Create worksheet */
var ws_data = [
[ "S", "h", "e", "e", "t", "J", "S" ],
[ 1 , 2 , 3 , 4 , 5 ]
];
var ws = XLSX.utils.aoa_to_sheet(ws_data);
2022-08-24 23:48:22 +00:00
/* Create workbook */
var wb = XLSX.utils.book_new();
2022-05-16 03:26:04 +00:00
/* Add the worksheet to the workbook */
2022-08-24 23:48:22 +00:00
// highlight-next-line
2022-05-16 03:26:04 +00:00
XLSX.utils.book_append_sheet(wb, ws, ws_name);
2022-08-24 23:48:22 +00:00
/* Write to file */
XLSX.writeFile(wb, "SheetJS.xlsx");
2022-05-16 03:26:04 +00:00
```
2022-08-24 23:48:22 +00:00
### Other Properties
2022-05-16 03:26:04 +00:00
2022-08-24 23:48:22 +00:00
_Add a Defined Name_
2022-05-16 03:26:04 +00:00
2022-08-24 23:48:22 +00:00
```js
if(!workbook.Workbook) workbook.Workbook = {};
if(!workbook.Workbook.Names) workbook.Workbook.Names = [];
workbook.Workbook.Names.push({
Name: "SourceData",
2023-05-14 07:48:56 +00:00
Ref: "Sheet1!$A$1:$D$12"
2022-08-24 23:48:22 +00:00
});
```
2023-05-14 07:48:56 +00:00
This is described in more detail in ["Defined Names"](/docs/csf/features/names).
2022-08-24 23:48:22 +00:00
_Set Workbook Properties_
```js
if(!wb.Props) wb.Props = {};
wb.Props["Company"] = "SheetJS LLC";
```
The full set of property names, and their mapping to the Excel UI, is included
2022-10-30 05:45:37 +00:00
in ["File Properties"](/docs/csf/book#file-properties)
2022-08-24 23:48:22 +00:00
## Worksheet
### Cells
_Modify a single cell value in a Worksheet_
2022-05-16 03:26:04 +00:00
```js
XLSX.utils.sheet_add_aoa(worksheet, [[new_value]], { origin: address });
```
2022-08-24 23:48:22 +00:00
_Modify multiple cell values in a Worksheet_
2022-05-16 03:26:04 +00:00
```js
XLSX.utils.sheet_add_aoa(worksheet, aoa, opts);
```
The `sheet_add_aoa` utility function modifies cell values in a worksheet. The
first argument is the worksheet object. The second argument is an array of
arrays of values. The `origin` key of the third argument controls where cells
will be written. The following snippet sets `B3=1` and `E5="abc"`:
```js
XLSX.utils.sheet_add_aoa(worksheet, [
[1], // <-- Write 1 to cell B3
, // <-- Do nothing in row 4
[/*B5*/, /*C5*/, /*D5*/, "abc"] // <-- Write "abc" to cell E5
], { origin: "B3" });
```
2022-10-30 05:45:37 +00:00
["Array of Arrays Input"](/docs/api/utilities#array-of-arrays-input) describes the
2022-05-16 03:26:04 +00:00
function and the optional `opts` argument in more detail.
#### Examples
The special origin value `-1` instructs `sheet_add_aoa` to start in column A of
the row after the last row in the range, appending the data:
```js
XLSX.utils.sheet_add_aoa(worksheet, [
["first row after data", 1],
["second row after data", 2]
], { origin: -1 });
```
2022-08-24 23:48:22 +00:00
### Other Properties
_Merge a group of cells_
```js
if(!worksheet["!merges"]) worksheet["!merges"] = [];
worksheet["!merges"].push(XLSX.utils.decode_range("A1:E1"));
```
2022-10-30 05:45:37 +00:00
The `!merges` property of a worksheet object is a list of [Cell Ranges](/docs/csf/general#cell-ranges).
2022-08-24 23:48:22 +00:00
The data for the cell will be taken from the top-left cell.
A range can be created with `decode_range` or specified manually:
```js
worksheet["!merges"].push({
s: { r: 2, c: 1 }, // s ("start"): c = 1 r = 2 -> "B3"
e: { r: 3, c: 4 } // e ("end"): c = 4 r = 3 -> "E4"
});
```
2023-09-24 03:59:48 +00:00
:::caution pass
2022-05-16 03:26:04 +00:00
2022-08-24 23:48:22 +00:00
This approach does not verify if two merged ranges intersect.
2022-05-16 03:26:04 +00:00
2022-08-24 23:48:22 +00:00
:::