6.3 KiB
| title | sidebar_position |
|---|---|
| Defined Names | 5 |
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 with 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 | ✔ | ✔ |
X (✕) marks features that are not supported by the file formats. There is no way to specify a Unicode defined name in the SYLK format.
Defined names (sometimes called "named ranges") are labeled references to cells, ranges, constants or formulae. Meaningful labels can make formula expressions more readable and more robust to worksheet changes.
Why are Defined Names useful? (click to show)
For example, the NPV formula function calculates the net present value of a
series of cashflows. In large workbooks, raw data will be stored in separate
worksheets and the interest rate will be stored in a separate "Model Parameters"
worksheet. Formulae may have references to multiple sheets:
=NPV('Model Parameters'!B2,Data!B2:F2)
^^^^^^^^^^^^^^^^^^^^^ --- interest rate
A defined name Interest referencing 'Model Parameters'!B2 would greatly
simplify the formula:
=NPV(Interest,Data!B2:F2)
^^^^^^^^ --- interest rate
Judicious use of Defined Names generally lead to fewer formula errors.
Storage
The Workbook property of SheetJS workbook objects store workbook attributes.
The Names property of Workbook is an array of SheetJS defined name objects.
:::caution pass
Parsers do not always create the Names array or Workbook structure. Code
should test for the existence of the defined names array before use:
var wb = XLSX.utils.book_new();
/* ensure the workbook structure exists */
/* highlight-start */
if(!wb.Workbook) wb.Workbook = {};
if(!wb.Workbook.Names) wb.Workbook.Names = [];
/* highlight-end */
/* add a new defined name */
wb.Workbook.Names.push({ Name: "MyData", Ref: "Sheet1!$A$1:$A$2" });
:::
Defined Name Object
SheetJS defined name objects support the following properties:
| 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) |
Ranges
Defined name references in formulae are internally shifted to the cell address. For example, given the defined name
{ Name: "MyData", Ref: "Sheet1!A1:A2" } // no $ means relative reference
If D4 is set to =SUM(MyData):
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:
{ Name: "MyData", Ref: "Sheet1!$A$1:$A$2" } // absolute reference
Scope
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:
/* "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.
/* The live editor requires this function wrapper */
function DefinedNameExport() { return ( <button onClick={() => {
/* Create empty workbook */
var wb = XLSX.utils.book_new();
/* Create worksheet Sheet1 */
var ws1 = XLSX.utils.aoa_to_sheet([[1,2,3],[4,5,6],["Global",0],["Local",0]]);
XLSX.utils.book_append_sheet(wb, ws1, "Sheet1");
/* Create worksheet Sheet2 */
var ws2 = XLSX.utils.aoa_to_sheet([["Global",0],["Local",0]]);
XLSX.utils.book_append_sheet(wb, ws2, "Sheet2");
/* Create defined names */
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", Sheet: 0, Ref: "Sheet1!$B$1:$B$2" });
/* "Local" scoped to the second worksheet -> Sheet1 C1:C2 */
wb.Workbook.Names.push({ Name: "Local", Sheet: 1, Ref: "Sheet1!$C$1:$C$2" });
/* Create formulae */
ws1["B3"].f = "SUM(Global)"; // Sheet1 B3 =SUM(Global) 1 + 4 = 5
ws1["B4"].f = "SUM(Local)"; // Sheet1 B4 =SUM(Local) 2 + 5 = 7
ws2["B1"].f = "SUM(Global)"; // Sheet2 B1 =SUM(Global) 1 + 4 = 5
ws2["B2"].f = "SUM(Local)"; // Sheet2 B2 =SUM(Local) 3 + 6 = 9
/* Export to file (start a download) */
XLSX.writeFile(wb, "SheetJSDNExport.xlsx");
}}><b>Export XLSX!</b></button> ); }