# Defined Name

- Human documentation: [https://docs.univer.ai/reference/facade/defined-name](https://docs.univer.ai/reference/facade/defined-name)

- Agent Markdown: [https://docs.univer.ai/reference/facade/defined-name.md](https://docs.univer.ai/reference/facade/defined-name.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/defined-name.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/defined-name.mdx)

---

| Packages | `@univerjs/sheets` |
| -------- | ------------------ |

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

## Overview

### @univerjs/sheets

| Method                                            | Description                                              |
| ------------------------------------------------- | -------------------------------------------------------- |
| [`build`](#build)                                 | Builds the defined name parameter                        |
| [`delete`](#delete)                               | Deletes the defined name                                 |
| [`getComment`](#getcomment)                       | Gets the comment of the defined name                     |
| [`getFormulaOrRefString`](#getformulaorrefstring) | Gets the formula or reference string of the defined name |
| [`getLocalSheetId`](#getlocalsheetid)             | Gets the local sheet id of the defined name              |
| [`getName`](#getname)                             | Gets the name of the defined name                        |
| [`isWorkbookScope`](#isworkbookscope)             | Checks if the defined name is in the workbook scope      |
| [`load`](#load)                                   | Loads the defined name mutation parameter                |
| [`setComment`](#setcomment)                       | Sets the comment of the defined name builder             |
| [`setFormula`](#setformula)                       | Sets the formula of the defined name builder             |
| [`setHidden`](#sethidden)                         | Sets the hidden status of the defined name builder       |
| [`setName`](#setname)                             | Sets the name of the defined name builder                |
| [`setRef`](#setref)                               | Sets the reference of the defined name builder           |
| [`setRefByRange`](#setrefbyrange)                 | Sets the reference of the defined name builder by range  |
| [`setScopeToWorkbook`](#setscopetoworkbook)       | Sets the scope of the defined name to the workbook       |
| [`setScopeToWorksheet`](#setscopetoworksheet)     | Sets the scope of the defined name to the worksheet      |
| [`toBuilder`](#tobuilder)                         | Converts 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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```ts
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**

```typescript
delete(): void
```

**Examples**

```ts
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**

```ts
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**

```ts
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`