# FDefinedNameBuilder

> Language fallback: requested `zh-CN`; content is `en-US`.

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

## Access

Access through:

* [`FWorkbook.newDefinedNameBuilder()`](https://docs.univer.ai/zh-CN/reference/facade/workbook.md#newdefinednamebuilder)
* [`FDefinedName.toBuilder()`](https://docs.univer.ai/zh-CN/reference/facade/defined-name.md#tobuilder)

## Setup

Register [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) or a preset that includes it. In plugin mode, import `@univerjs/sheets/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/facade.md).

## `@univerjs/sheets`

### `FDefinedNameBuilder.build`

Builds the defined name parameter.

```typescript
build(): ISetDefinedNameMutationParam
```

**Returns**

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

**Types:** [`ISetDefinedNameMutationParam`](https://unpkg.com/@univerjs/engine-formula@1.0.0-rc.0/lib/types/commands/mutations/set-defined-name.mutation.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.load`

Loads the defined name mutation parameter.

```typescript
load(param: ISetDefinedNameMutationParam): FDefinedNameBuilder
```

**Parameters**

* `param` — Required. defined name mutation parameter

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md) · [`ISetDefinedNameMutationParam`](https://unpkg.com/@univerjs/engine-formula@1.0.0-rc.0/lib/types/commands/mutations/set-defined-name.mutation.d.ts)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setComment`

Sets the comment of the defined name builder.

```typescript
setComment(comment: string): FDefinedNameBuilder
```

**Parameters**

* `comment` — Required. The comment of the defined name.

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setFormula`

Sets the formula of the defined name builder.

```typescript
setFormula(formula: string): FDefinedNameBuilder
```

**Parameters**

* `formula` — Required. The formula of the defined name.

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setHidden`

Sets the hidden status of the defined name builder.

```typescript
setHidden(hidden: boolean): FDefinedNameBuilder
```

**Parameters**

* `hidden` — Required. The hidden status of the defined name.

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setName`

Sets the name of the defined name builder.

```typescript
setName(name: string): FDefinedNameBuilder
```

**Parameters**

* `name` — Required. The name of the defined name.

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setRef`

Sets the reference of the defined name builder.

```typescript
setRef(a1Notation: string): FDefinedNameBuilder
```

**Parameters**

* `a1Notation` — Required. The reference of the defined name.

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setRefByRange`

Sets the reference of the defined name builder by range .

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

**Parameters**

* `row` — Required. The start row index of the range. index start at 0.
* `column` — Required. The start column index of the range. index start at 0.
* `numRows` — Required. The number of rows in the range.
* `numColumns` — Required. The number of columns in the range.

**Returns**

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

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setScopeToWorkbook`

Sets the scope of the defined name to the workbook.

```typescript
setScopeToWorkbook(): FDefinedNameBuilder
```

**Returns**

The instance of `FDefinedNameBuilder` for method chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()

// Create a defined name and make it available in the entire workbook
const definedNameParam = fWorkbook
  .newDefinedNameBuilder()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .setScopeToWorkbook()
  .build()
fWorkbook.insertDefinedNameBuilder(definedNameParam)
```

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)

### `FDefinedNameBuilder.setScopeToWorksheet`

Sets the scope of the defined name to the worksheet.

```typescript
setScopeToWorksheet(worksheet: FWorksheet): FDefinedNameBuilder
```

**Parameters**

* `worksheet` — Required. The worksheet to set the scope to.

**Returns**

The instance of `FDefinedNameBuilder` for method chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()

// Create a defined name and make it available only in the second worksheet
const definedNameParam = fWorkbook
  .newDefinedNameBuilder()
  .setName('MyDefinedName')
  .setRef('Sheet1!$A$1')
  .setScopeToWorksheet(sheets[1])
  .build()
fWorkbook.insertDefinedNameBuilder(definedNameParam)
```

**Types:** [`FDefinedNameBuilder`](https://docs.univer.ai/zh-CN/reference/facade/defined-name-builder.md) · [`FWorksheet`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md)

**Package:** [`@univerjs/sheets`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs/sheets.md) · [Type definitions](https://unpkg.com/@univerjs/sheets@1.0.0-rc.0/lib/types/facade/f-defined-name.d.ts)