API 参考

Defined Name

本 API 页面目前提供英文正文。代码签名与标识符不随界面语言变化。
Packages@univerjs/sheets

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

Overview

@univerjs/sheets

MethodDescription
buildBuilds the defined name parameter
deleteDeletes the defined name
getCommentGets the comment of the defined name
getFormulaOrRefStringGets the formula or reference string of the defined name
getLocalSheetIdGets the local sheet id of the defined name
getNameGets the name of the defined name
isWorkbookScopeChecks if the defined name is in the workbook scope
loadLoads the defined name mutation parameter
setCommentSets the comment of the defined name builder
setFormulaSets the formula of the defined name builder
setHiddenSets the hidden status of the defined name builder
setNameSets the name of the defined name builder
setRefSets the reference of the defined name builder
setRefByRangeSets the reference of the defined name builder by range
setScopeToWorkbookSets the scope of the defined name to the workbook
setScopeToWorksheetSets the scope of the defined name to the worksheet
toBuilderConverts the defined name to a defined name builder

APIs

Lifecycle & Creation

build

Builds the defined name parameter.

Signature

TypeScript
build(): ISetDefinedNameMutationParam

Returns

  • ISetDefinedNameMutationParam — The defined name mutation parameter.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRef('Sheet1!$A$1')  .setComment('A reference to A1 cell in Sheet1')  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

Getters & Queries

getComment

Gets the comment of the defined name.

Signature

TypeScript
getComment(): string | undefined

Returns

  • string — The comment of the defined name.

Examples

TypeScript
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

TypeScript
getFormulaOrRefString(): string

Returns

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

Examples

TypeScript
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

TypeScript
getLocalSheetId(): string | undefined

Returns

  • string — The local sheet id of the defined name.

Examples

TypeScript
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

TypeScript
getName(): string

Returns

  • string — The name of the defined name.

Examples

TypeScript
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

TypeScript
isWorkbookScope(): boolean

Returns

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

Examples

TypeScript
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

TypeScript
setComment(comment: string): FDefinedNameBuilder

Parameters

  • comment string — No description

Returns

  • FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRef('Sheet1!$A$1')  .setComment('A reference to A1 cell in Sheet1')  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

setFormula

Sets the formula of the defined name builder.

Signature

TypeScript
setFormula(formula: string): FDefinedNameBuilder

Parameters

  • formula string — No description

Returns

  • FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setFormula('SUM(Sheet1!$A$1)')  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

setHidden

Sets the hidden status of the defined name builder.

Signature

TypeScript
setHidden(hidden: boolean): FDefinedNameBuilder

Parameters

  • hidden boolean — No description

Returns

  • FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRef('Sheet1!$A$1')  .setHidden(true)  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

setName

Sets the name of the defined name builder.

Signature

TypeScript
setName(name: string): FDefinedNameBuilder

Parameters

  • name string — No description

Returns

  • FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRef('Sheet1!$A$1')  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

setRef

Sets the reference of the defined name builder.

Signature

TypeScript
setRef(a1Notation: string): FDefinedNameBuilder

Parameters

  • a1Notation string — No description

Returns

  • FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRef('Sheet1!$A$1')  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

setRefByRange

Sets the reference of the defined name builder by range .

Signature

TypeScript
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

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRefByRange(1, 3, 2, 5) // D2:H3  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

setScopeToWorkbook

Sets the scope of the defined name to the workbook.

Signature

TypeScript
setScopeToWorkbook(): void

Examples

TypeScript
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

TypeScript
setScopeToWorksheet(worksheet: FWorksheet): void

Parameters

  • worksheet FWorksheet — No description

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const sheets = fWorkbook.getSheets();// Get the first defined name and make it available only in the second worksheetconst definedName = fWorkbook.getDefinedNames()[0];definedName?.setScopeToWorksheet(sheets[1]);
Source: @univerjs/sheets

Actions & Operations

delete

Deletes the defined name.

Signature

TypeScript
delete(): void

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedName = fWorkbook.getDefinedNames()[0];definedName?.delete();
Source: @univerjs/sheets

Miscellaneous

load

Loads the defined name mutation parameter.

Signature

TypeScript
load(param: ISetDefinedNameMutationParam): FDefinedNameBuilder

Parameters

  • param ISetDefinedNameMutationParam — No description

Returns

  • FDefinedNameBuilder — The instance of FDefinedNameBuilder for method chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder()  .load({    id: '4TMPceoqg8',    name: 'MyDefinedName',    formulaOrRefString: 'Sheet1!$A$1',  })  .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

toBuilder

Converts the defined name to a defined name builder.

Signature

TypeScript
toBuilder(): FDefinedNameBuilder

Returns

  • FDefinedNameBuilder — The defined name builder.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const definedName = fWorkbook.getDefinedNames()[0];if (!definedName) return;const definedNameParam = definedName  .toBuilder()  .setName('NewDefinedName')  .setFormula('SUM(Sheet1!$A$1)')  .build();fWorkbook.updateDefinedNameBuilder(definedNameParam);
Source: @univerjs/sheets

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.