Defined Name

Packages	`@univerjs/sheets`

CORE

This class should not be instantiated directly. Use factory methods on univerAPI instead.

Overview

@univerjs/sheets

Method	Description
`build`	Builds the defined name parameter
`delete`	Deletes the defined name
`getComment`	Gets the comment of the defined name
`getFormulaOrRefString`	Gets the formula or reference string of the defined name
`getLocalSheetId`	Gets the local sheet id of the defined name
`getName`	Gets the name of the defined name
`isWorkbookScope`	Checks if the defined name is in the workbook scope
`load`	Loads the defined name mutation parameter
`setComment`	Sets the comment of the defined name builder
`setFormula`	Sets the formula of the defined name builder
`setHidden`	Sets the hidden status of the defined name builder
`setName`	Sets the name of the defined name builder
`setRef`	Sets the reference of the defined name builder
`setRefByRange`	Sets the reference of the defined name builder by range
`setScopeToWorkbook`	Sets the scope of the defined name to the workbook
`setScopeToWorksheet`	Sets the scope of the defined name to the worksheet
`toBuilder`	Converts the defined name to a defined name builder

APIs

Lifecycle & Creation

`build`

Builds the defined name parameter.

Signature

build(): ISetDefinedNameMutationParam

Returns

ISetDefinedNameMutationParam — The defined name mutation parameter.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .setComment('A reference to A1 cell in Sheet1')
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

Getters & Queries

`getComment`

Gets the comment of the defined name.

Signature

getComment(): string | undefined

Returns

string — The comment of the defined name.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
console.log(definedName?.getComment());

Source: @univerjs/sheets

`getFormulaOrRefString`

Gets the formula or reference string of the defined name.

Signature

getFormulaOrRefString(): string

Returns

string — The formula or reference string of the defined name.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
console.log(definedName?.getFormulaOrRefString());

Source: @univerjs/sheets

`getLocalSheetId`

Gets the local sheet id of the defined name.

Signature

getLocalSheetId(): string | undefined

Returns

string — The local sheet id of the defined name.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
console.log(definedName?.getLocalSheetId());

Source: @univerjs/sheets

`getName`

Gets the name of the defined name.

Signature

getName(): string

Returns

string — The name of the defined name.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
console.log(definedName?.getName());

Source: @univerjs/sheets

`isWorkbookScope`

Checks if the defined name is in the workbook scope.

Signature

isWorkbookScope(): boolean

Returns

boolean — True if the defined name is in the workbook scope, false otherwise.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
console.log(definedName?.isWorkbookScope());

Source: @univerjs/sheets

Setters & Modifiers

`setComment`

Sets the comment of the defined name builder.

Signature

setComment(comment: string): FDefinedNameBuilder

Parameters

comment string — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .setComment('A reference to A1 cell in Sheet1')
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`setFormula`

Sets the formula of the defined name builder.

Signature

setFormula(formula: string): FDefinedNameBuilder

Parameters

formula string — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setFormula('SUM(Sheet1!$A$1)')
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`setHidden`

Sets the hidden status of the defined name builder.

Signature

setHidden(hidden: boolean): FDefinedNameBuilder

Parameters

hidden boolean — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .setHidden(true)
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`setName`

Sets the name of the defined name builder.

Signature

setName(name: string): FDefinedNameBuilder

Parameters

name string — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`setRef`

Sets the reference of the defined name builder.

Signature

setRef(a1Notation: string): FDefinedNameBuilder

Parameters

a1Notation string — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`setRefByRange`

Sets the reference of the defined name builder by range .

Signature

setRefByRange(row: number, column: number, numRows: number, numColumns: number): FDefinedNameBuilder

Parameters

row number — No description
column number — No description
numRows number — No description
numColumns number — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameBuilder = univerAPI.newDefinedName()
  .setName('MyDefinedName')
  .setRefByRange(1, 3, 2, 5) // D2:H3
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`setScopeToWorkbook`

Sets the scope of the defined name to the workbook.

Signature

setScopeToWorkbook(): void

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
definedName?.setScopeToWorkbook();

Source: @univerjs/sheets

`setScopeToWorksheet`

Sets the scope of the defined name to the worksheet.

Signature

setScopeToWorksheet(worksheet: FWorksheet): void

Parameters

worksheet FWorksheet — No description

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const sheets = fWorkbook.getSheets();

// Get the first defined name and make it available only in the second worksheet
const definedName = fWorkbook.getDefinedNames()[0];
definedName?.setScopeToWorksheet(sheets[1]);

Source: @univerjs/sheets

Actions & Operations

`delete`

Deletes the defined name.

Signature

delete(): void

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
definedName?.delete();

Source: @univerjs/sheets

Miscellaneous

`load`

Loads the defined name mutation parameter.

Signature

load(param: ISetDefinedNameMutationParam): FDefinedNameBuilder

Parameters

param ISetDefinedNameMutationParam — No description

Returns

FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedNameParam = {
  id: '4TMPceoqg8',
  unitId: fWorkbook.getId(),
  name: 'MyDefinedName',
  formulaOrRefString: 'Sheet1!$A$1',
}
const definedNameBuilder = univerAPI.newDefinedName()
  .load(definedNameParam)
  .build();
fWorkbook.insertDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

`toBuilder`

Converts the defined name to a defined name builder.

Signature

toBuilder(): FDefinedNameBuilder

Returns

FDefinedNameBuilder — The defined name builder.

Examples

const fWorkbook = univerAPI.getActiveWorkbook();
const definedName = fWorkbook.getDefinedNames()[0];
if (!definedName) return;
const definedNameBuilder = definedName
  .toBuilder()
  .setName('NewDefinedName')
  .setFormula('SUM(Sheet1!$A$1)')
  .build();
fWorkbook.updateDefinedNameBuilder(definedNameBuilder);

Source: @univerjs/sheets

Table of Contents