# Именованные диапазоны

- Human documentation: [https://docs.univer.ai/ru-RU/guides/sheets/features/core/defined-names](https://docs.univer.ai/ru-RU/guides/sheets/features/core/defined-names)

- Agent Markdown: [https://docs.univer.ai/ru-RU/guides/sheets/features/core/defined-names.md](https://docs.univer.ai/ru-RU/guides/sheets/features/core/defined-names.md)

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

- Source: [sheets/features/core/defined-names.ru-RU.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/defined-names.ru-RU.mdx)

---

Именованные диапазоны позволяют назначать пользовательские имена ячейкам, диапазонам ячеек и формулам. Такие имена делают ссылки на данные понятнее, упрощают формулы и повышают читаемость и удобство сопровождения листа.

* **Повышение читаемости формул**: именованные диапазоны делают формулы понятнее. Например, `Amount` вместо `A1 + A2 + A3` яснее передаёт смысл формулы.
* **Упрощение сложных ссылок**: именованные диапазоны упрощают ссылки на несколько ячеек и сложные диапазоны. Например, можно определить имя `SalesData` для диапазона `A1:A10`, а затем использовать `SalesData` непосредственно в формулах.
* **Централизованное управление областями данных**: именованные диапазоны помогают управлять областями данных. При изменении диапазона достаточно обновить ссылку в его определении, не изменяя каждую формулу по отдельности.

## Использование

Кнопка диспетчера имён находится рядом с полем имени в левом верхнем углу листа. Там можно просмотреть список всех именованных диапазонов и открыть диспетчер, чтобы просматривать, изменять и удалять их.



Чтобы использовать именованный диапазон в формуле, просто введите его имя. Например, если задано имя `TotalSales`, ссылка на этот диапазон в формуле будет выглядеть как `=TotalSales`.

## Примечания

* **Уникальность имён**: имена должны быть уникальными в пределах одного листа и не должны совпадать с другими именами или встроенными функциями.
* **Допустимые имена**: имя не может начинаться с цифры и содержать пробелы или специальные символы, например `!`, `@` или `#`. Если имя не соответствует правилам, система выведет ошибку.
* **Изменение именованных диапазонов**: откройте панель редактирования «Задать имя», выберите нужное имя и измените его. Затем нажмите «ОК», чтобы сохранить изменения.
* **Удаление именованных диапазонов**: выберите ненужное имя на панели «Задать имя» и нажмите «Удалить». После удаления связанные формулы станут недействительными.
* **Использование на разных листах**: именованные диапазоны можно использовать на разных листах одной книги, однако имена должны оставаться уникальными. Одинаковые имена на разных листах могут привести к неоднозначным ссылкам.
* **Правила именования**: используйте понятные имена и избегайте слишком коротких или расплывчатых названий, чтобы другим пользователям было проще понимать и сопровождать книгу.
* **Отладка формул**: если при использовании именованных диапазонов возникают проблемы, проверьте правильность имён и ссылок на диапазоны, а также возможные конфликты имён.
* **Область действия**: имя можно задать на уровне книги или листа. Имена уровня книги доступны во всей книге, а имена уровня листа — только на соответствующем листе.

## Facade API

Полные определения типов Facade API доступны в [справочнике Facade API](https://docs.univer.ai/ru-RU/reference/facade.md).

### Создание именованных диапазонов

Метод `FWorkbook.newDefinedNameBuilder()` создаёт построитель именованного диапазона и возвращает экземпляр `FDefinedNameBuilder`. С помощью цепочки методов можно сформировать объект `ISetDefinedNameMutationParam` для создания именованного диапазона.

Некоторые методы [`FDefinedNameBuilder`](https://docs.univer.ai/ru-RU/reference/facade/defined-name-builder.md):

| Метод               | Описание                                |
| ------------------- | --------------------------------------- |
| build               | Создаёт объект именованного диапазона   |
| setName             | Задаёт имя                              |
| setFormula          | Задаёт формулу именованного диапазона   |
| setRef              | Задаёт ссылку на диапазон               |
| setComment          | Задаёт комментарий                      |
| setScopeToWorksheet | Делает имя доступным на указанном листе |
| setScopeToWorkbook  | Делает имя доступным во всей книге      |

Метод [`FWorkbook.insertDefinedNameBuilder()`](https://docs.univer.ai/ru-RU/reference/facade/workbook.md#insertdefinednamebuilder) создаёт именованный диапазон, доступный во всей книге.

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

Метод [`FWorkbook.insertDefinedName()`](https://docs.univer.ai/ru-RU/reference/facade/workbook.md#insertdefinedname) позволяет быстро создать именованный диапазон.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1')
```

Другие методы:

* [`FWorksheet.insertDefinedName()`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#insertdefinedname): создаёт именованный диапазон, доступный на указанном листе.

### Получение именованных диапазонов

Метод [`FWorkbook.getDefinedName()`](https://docs.univer.ai/ru-RU/reference/facade/workbook.md#getdefinedname) возвращает именованный диапазон книги в виде экземпляра `FDefinedName`.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

if (definedName) {
  definedName.setName('NewDefinedName')
}
```

Другие методы:

* Метод [`FWorkbook.getDefinedNames()`](https://docs.univer.ai/ru-RU/reference/facade/workbook.md#getdefinednames) возвращает все именованные диапазоны книги в виде массива `FDefinedName[]`.
* Метод [`FWorksheet.getDefinedNames()`](https://docs.univer.ai/ru-RU/reference/facade/worksheet.md#getdefinednames) возвращает все именованные диапазоны, доступные на этом листе, в виде массива `FDefinedName[]`.

### Изменение именованных диапазонов

Метод [`FWorkbook.updateDefinedNameBuilder()`](https://docs.univer.ai/ru-RU/reference/facade/workbook.md#updatedefinednamebuilder) изменяет именованный диапазон книги.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

// Modify the defined name
if (definedName) {
  const newDefinedNameParam = definedName.toBuilder()
    .setName('NewDefinedName')
    .setRef('Sheet1!$A$2')
    .build()
  fWorkbook.updateDefinedNameBuilder(newDefinedNameParam)
}
```

Экземпляр [`FDefinedName`](https://docs.univer.ai/ru-RU/reference/facade/defined-name.md) также позволяет напрямую изменять конфигурацию именованного диапазона.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

// Modify the defined name
if (definedName) {
  definedName.setName('NewDefinedName')
  definedName.setRef('Sheet1!$A$2')
}
```

### Удаление именованных диапазонов

Метод [`FWorkbook.deleteDefinedName()`](https://docs.univer.ai/ru-RU/reference/facade/workbook.md#deletedefinedname) удаляет именованный диапазон из книги.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.deleteDefinedName('MyDefinedName')
```

Именованный диапазон также можно удалить напрямую через возвращённый экземпляр [`FDefinedName`](https://docs.univer.ai/ru-RU/reference/facade/defined-name.md).

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

// Delete the defined name
if (definedName) {
  definedName.delete()
}
```