From abd00f34a937e04fae892283b32c245cc8284701 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Sun, 14 May 2023 03:48:56 -0400 Subject: [PATCH] names --- docz/docs/06-solutions/03-processing.md | 4 +- docz/docs/07-csf/04-book.md | 82 +------------ docz/docs/07-csf/07-features/05-names.md | 140 +++++++++++++++++++++++ 3 files changed, 144 insertions(+), 82 deletions(-) create mode 100644 docz/docs/07-csf/07-features/05-names.md diff --git a/docz/docs/06-solutions/03-processing.md b/docz/docs/06-solutions/03-processing.md index d67ea0a..e6cd089 100644 --- a/docz/docs/06-solutions/03-processing.md +++ b/docz/docs/06-solutions/03-processing.md @@ -120,11 +120,11 @@ if(!workbook.Workbook) workbook.Workbook = {}; if(!workbook.Workbook.Names) workbook.Workbook.Names = []; workbook.Workbook.Names.push({ Name: "SourceData", - Ref: "Sheet1!A1:D12" + Ref: "Sheet1!$A$1:$D$12" }); ``` -This is described in more detail in ["Workbook Object"](/docs/csf/book#defined-names). +This is described in more detail in ["Defined Names"](/docs/csf/features/names). _Set Workbook Properties_ diff --git a/docz/docs/07-csf/04-book.md b/docz/docs/07-csf/04-book.md index 0800ee6..c7d3125 100644 --- a/docz/docs/07-csf/04-book.md +++ b/docz/docs/07-csf/04-book.md @@ -68,86 +68,8 @@ XLSX.write(wb, { Props: { Author: "SheetJS" } }); ### Defined Names -
- Format Support (click to show) - -**Simple Defined Names**: XLSX/M, XLSB, BIFF8 XLS, XLML, ODS, SYLK - -**Unicode Defined Names**: XLSX/M, XLSB, BIFF8 XLS, XLML, ODS - -**Defined Name Comment**: XLSX/M, XLSB, BIFF8 XLS - -
- -`wb.Workbook.Names` is an array of defined name objects which have the keys: - -| Key | Description | -|:----------|:-----------------------------------------------------------------| -| `Sheet` | Name scope. Sheet Index (0 = first sheet) or `null` (Workbook) | -| `Name` | Case-sensitive name. Standard rules apply ** | -| `Ref` | A1-Style Reference (`"Sheet1!$A$1:$D$20"`) | -| `Comment` | Comment (only applicable for XLS/XLSX/XLSB) | - -Excel allows two sheet-scoped defined names to share the same name. However, a -sheet-scoped name cannot collide with a workbook-scope name. Workbook writers -may not enforce this constraint. - -The following snippet creates a worksheet-level defined name `"Global"` and a -local defined name `"Local"` with distinct values for first and second sheets: - -```js -/* ensure the workbook structure exists */ -if(!wb.Workbook) wb.Workbook = {}; -if(!wb.Workbook.Names) wb.Workbook.Names = []; - -/* "Global" workbook-level -> Sheet1 A1:A2 */ -wb.Workbook.Names.push({ Name: "Global", Ref: "Sheet1!$A$1:$A$2" }); - -/* "Local" scoped to the first worksheet -> Sheet1 B1:B2 */ -wb.Workbook.Names.push({ Name: "Local", Ref: "Sheet1!$B$1:$B$2", Sheet: 0 }); - -/* "Local" scoped to the second worksheet -> Sheet1 C1:C2 */ -wb.Workbook.Names.push({ Name: "Local", Ref: "Sheet1!$C$1:$C$2", Sheet: 1 }); -``` - -
Live Example (click to show) - -```jsx live -/* The live editor requires this function wrapper */ -function DefinedNameExport() { return ( ); } -``` - -
+`wb.Workbook.Names` is an array of defined name objects. Defined names are +discussed in more detail in ["Defined Names"](/docs/csf/features/names) ### Workbook Views diff --git a/docz/docs/07-csf/07-features/05-names.md b/docz/docs/07-csf/07-features/05-names.md new file mode 100644 index 0000000..78fcfef --- /dev/null +++ b/docz/docs/07-csf/07-features/05-names.md @@ -0,0 +1,140 @@ +--- +sidebar_position: 5 +--- + +# Defined Names + +
+ File Format Support (click to show) + +Defined names have evolved over the decades, with new features added over time: + +- "English" refers to defined names with English letters and numbers (ASCII) +- "Unicode" refers to defined names that non-English characters. +- "Comment" refers to comments that can be attached to defined names. + +| Formats | English | Unicode | Comment | +|:------------------|:-------:|:-------:|:-------:| +| XLSX / XLSM | ✔ | ✔ | ✔ | +| XLSB | ✔ | ✔ | ✔ | +| XLS | ✔ | ✔ | ✔ | +| XLML | ✔ | ✔ | | +| SYLK | ✔ | * | | +| ODS / FODS / UOS | ✔ | ✔ | | + +Asterisks (*) mark features that are not supported by the file formats. There is +no way to specify a Unicode defined name in the SYLK format. + +
+ +`wb.Workbook.Names` is an array of defined name objects which have the keys: + +| Key | Name in app | Description | +|:----------|:------------|:---------------------------------------------------| +| `Sheet` | "Scope" | Sheet Index (0 = first sheet) or `null` (Workbook) | +| `Name` | "Name" | Case-sensitive name. Standard rules apply | +| `Ref` | "Refers To" | A1-Style Reference (`"Sheet1!$A$1:$D$20"`) | +| `Comment` | "Comment" | Comment (for supported file formats) | + +Parsers do not always create the `Names` structure. Parsing and writing code +should test for the existence of the defined names array before use: + +```js +/* ensure the workbook structure exists */ +if(!wb.Workbook) wb.Workbook = {}; +if(!wb.Workbook.Names) wb.Workbook.Names = []; + +/* add a new defined name */ +wb.Workbook.Names.push({ Name: "MyData", Ref: "Sheet1!$A$1:$A$2" }); +``` + +## Ranges + +Defined name references in formulae are internally shifted to the cell address. +For example, given the defined name + +```js +{ Name: "MyData", Ref: "Sheet1!A1:A2" } // no $ means relative reference +``` + +If `D4` is set to `=SUM(MyData)`: + +```js +ws["D4"].f = "SUM(MyData)"; +``` + +Spreadsheet software will translate the defined name range down to the cell. +Excel will try to calculate `SUM(D4:D5)` and assign to cell `D4`. This will +elicit a circular reference error. + +The recommended approach is to fix the rows and columns of the reference: + +```js +{ Name: "MyData", Ref: "Sheet1!$A$1:$A$2" } // absolute reference +``` + +## Scoped Defined Names + +Excel allows two sheet-scoped defined names to share the same name. However, a +sheet-scoped name cannot collide with a workbook-scope name. Workbook writers +may not enforce this constraint. + +The following snippet creates a worksheet-level defined name `"Global"` and a +local defined name `"Local"` with distinct values for first and second sheets: + +```js +/* "Global" workbook-level -> Sheet1 A1:A2 */ +wb.Workbook.Names.push({ Name: "Global", Ref: "Sheet1!$A$1:$A$2" }); + +/* "Local" scoped to the first worksheet -> Sheet1 B1:B2 */ +wb.Workbook.Names.push({ Name: "Local", Ref: "Sheet1!$B$1:$B$2", Sheet: 0 }); + +/* "Local" scoped to the second worksheet -> Sheet1 C1:C2 */ +wb.Workbook.Names.push({ Name: "Local", Ref: "Sheet1!$C$1:$C$2", Sheet: 1 }); +``` + +## Live Demo + +The following example creates 3 defined names: + +- "Global" is a workbook-level name that references `Sheet1!$A$1:$A$2` +- "Local" in the first worksheet references `Sheet1!$B$1:$B$2` +- "Local" in the second worksheet references `Sheet1!$C$1:$C$2` + +Both worksheets include formulae referencing "Local" and "Global". Since the +referenced ranges are different, the expressions using "Local" will differ. + +```jsx live +/* The live editor requires this function wrapper */ +function DefinedNameExport() { return ( ); } +```