# Defined Names

Defined names are workbook or worksheet scoped names for a range reference or formula value. Use `univer run` to create and maintain them through the sheets facade provided by `@univerjs/sheets/facade`.

## Core Workflow

Use the workbook object to create, read, update, and delete defined names.

- `insertDefinedName(name, formulaOrRefString) -> FWorkbook` - shortcut for workbook-scoped defined names
- `getDefinedNames() -> FDefinedName[]` - list workbook defined names
- `getDefinedName(name) -> FDefinedName | null` - read one defined name by name
- `deleteDefinedName(name) -> boolean` - delete a defined name by name
- `newDefinedNameBuilder() -> FDefinedNameBuilder` - builder path for worksheet scope and advanced options
- `insertDefinedNameBuilder(param) -> void` - insert a builder result
- `updateDefinedNameBuilder(param) -> void` - update from a builder result

## Workbook-Scoped Defined Names

For simple workbook-scoped names, prefer `workbook.insertDefinedName(name, formulaOrRefString)`.

Pass a range reference directly:

```javascript
const workbook = univerAPI.getActiveWorkbook();
const sheet = workbook.getSheetByName("Sheet1");
if (!sheet) throw new Error("Sheet1 not found");

sheet.getRange("B2:B4").setValues([[100], [120], [90]]);
workbook.insertDefinedName("SalesRange", "Sheet1!$B$2:$B$4");

return {
  name: workbook.getDefinedName("SalesRange")?.getName(),
  formulaOrRefString: workbook.getDefinedName("SalesRange")?.getFormulaOrRefString()
};
```

Pass a formula value with a leading `=`:

```javascript
const workbook = univerAPI.getActiveWorkbook();

workbook.insertDefinedName("TotalSales", "=SUM(Sheet1!$B$2:$B$4)");

const definedName = workbook.getDefinedName("TotalSales");
return {
  name: definedName?.getName(),
  formulaOrRefString: definedName?.getFormulaOrRefString(),
  isWorkbookScope: definedName?.isWorkbookScope()
};
```

The shortcut creates workbook-scoped defined names. Use the builder path when you need worksheet scope, comments, hidden names, or update control.

## Read And Delete

Map defined names into plain objects before returning from a run script.

```javascript
const workbook = univerAPI.getActiveWorkbook();

const names = workbook.getDefinedNames().map((definedName) => ({
  name: definedName.getName(),
  formulaOrRefString: definedName.getFormulaOrRefString(),
  comment: definedName.getComment() ?? null,
  isWorkbookScope: definedName.isWorkbookScope(),
  localSheetId: definedName.getLocalSheetId() ?? null
}));

return { names };
```

Delete by name and verify with `getDefinedName(name)`.

```javascript
const workbook = univerAPI.getActiveWorkbook();

const deleted = workbook.deleteDefinedName("OldName");
return {
  deleted,
  missing: workbook.getDefinedName("OldName") === null
};
```

## Worksheet-Scoped Defined Names

Worksheet-scoped defined names require the builder path. Get the target worksheet first, then call `setScopeToWorksheet(sheet)`.

```javascript
const workbook = univerAPI.getActiveWorkbook();
const sheet = workbook.getSheetByName("Sheet1");
if (!sheet) throw new Error("Sheet1 not found");

const param = workbook
  .newDefinedNameBuilder()
  .setName("LocalSalesRange")
  .setRef("Sheet1!$B$2:$B$4")
  .setScopeToWorksheet(sheet)
  .build();

workbook.insertDefinedNameBuilder(param);

return {
  localNames: sheet.getDefinedNames().map((definedName) => ({
    name: definedName.getName(),
    formulaOrRefString: definedName.getFormulaOrRefString(),
    isWorkbookScope: definedName.isWorkbookScope(),
    localSheetId: definedName.getLocalSheetId() ?? null
  }))
};
```

Use `sheet.getDefinedNames()` when you need the names scoped to one worksheet. Use `workbook.getDefinedNames()` when you need the workbook-wide list.

## Use Builder For Advanced Options

Use `newDefinedNameBuilder()` when the shortcut does not cover the required shape.

- `setName(name)` - set the defined name
- `setRef(refString)` - set a range reference such as `Sheet1!$B$2:$B$4`
- `setFormula(formula)` - set a formula without the leading `=`, such as `SUM(Sheet1!$B$2:$B$4)`
- `setScopeToWorkbook()` - make the name workbook scoped
- `setScopeToWorksheet(sheet)` - make the name worksheet scoped
- `setComment(comment)` - store a comment
- `setHidden(hidden)` - set hidden status
- `build()` - produce the parameter for insert or update

Create a workbook-scoped name with comment metadata:

```javascript
const workbook = univerAPI.getActiveWorkbook();

const param = workbook
  .newDefinedNameBuilder()
  .setName("AuditedSales")
  .setRef("Sheet1!$B$2:$B$4")
  .setScopeToWorkbook()
  .setComment("Created by run script")
  .setHidden(false)
  .build();

workbook.insertDefinedNameBuilder(param);
```

Update an existing defined name with `toBuilder()` and `updateDefinedNameBuilder(param)`.

```javascript
const workbook = univerAPI.getActiveWorkbook();
const definedName = workbook.getDefinedName("TotalSales");
if (!definedName) throw new Error("TotalSales not found");

const param = definedName
  .toBuilder()
  .setName("TotalSales")
  .setRef("Sheet1!$B$2:$B$4")
  .setComment("Updated to reference the sales input range")
  .setScopeToWorkbook()
  .build();

workbook.updateDefinedNameBuilder(param);

return {
  updated: workbook.getDefinedName("TotalSales")?.getFormulaOrRefString()
};
```

## Hyperlink Interop

A range reference defined name can be converted into a sheet hyperlink target with `workbook.getUrlOfDefineName(name)`.

```javascript
const workbook = univerAPI.getActiveWorkbook();
const sheet = workbook.getSheetByName("Sheet1");
if (!sheet) throw new Error("Sheet1 not found");

workbook.insertDefinedName("SalesRange", "Sheet1!$B$2:$B$4");

const url = workbook.getUrlOfDefineName("SalesRange");
await sheet.getRange("A1").setHyperLink(url, "SalesRange");

return {
  parsed: workbook.parseSheetHyperlink(url)
};
```

Formula defined names such as `=SUM(Sheet1!$B$2:$B$4)` cannot be converted into hyperlink targets. See `univer help run hyperlinks` for complete hyperlink examples and the non-range failure path.

## Related Topics

- See `hyperlinks` for URL, sheet, range, and defined-name hyperlink targets.
- See `ranges` for direct range read/write APIs.
- See `formulas` for formula write and calculation readback guidance.
