---
pkg: "@nocobase/plugin-ui-templates"
---

# Шаблоны интерфейса (UI)

## Введение

Шаблоны интерфейса используются для повторного использования конфигураций при построении интерфейса, что позволяет сократить объем повторяющейся работы и поддерживать синхронизацию настроек в нескольких местах при необходимости.

В настоящее время поддерживаются следующие типы шаблонов:

- **Шаблон блока**: повторное использование конфигурации всего блока.
- **Шаблон поля**: повторное использование конфигурации «области полей» в блоках формы или деталей.
- **Шаблон всплывающего окна**: повторное использование конфигураций всплывающих окон, вызываемых действиями или полями.

## Основные концепции

### Ссылка и Копия

При использовании шаблонов обычно существует два способа:

- **Ссылка**: несколько мест используют одну и ту же конфигурацию шаблона. При изменении шаблона или любого места, где он используется по ссылке, обновления синхронизируются во всех остальных местах.
- **Копия**: создание независимой конфигурации на основе шаблона. Последующие изменения в шаблоне или копии не влияют друг на друга.

### Сохранение как шаблон

Когда блок или всплывающее окно уже настроены, вы можете использовать функцию `Сохранить как шаблон` в меню настроек и выбрать способ сохранения:

- **Преобразовать текущий... в шаблон**: после сохранения текущий объект будет переключен на использование этого шаблона по ссылке.
- **Скопировать текущий... как шаблон**: создается только шаблон, а текущий объект остается без изменений.

## Шаблон блока

### Сохранение блока как шаблона

1) Откройте меню настроек целевого блока и нажмите `Сохранить как шаблон`.  
2) Укажите `Название шаблона` / `Описание шаблона` и выберите режим сохранения:
   - **Преобразовать текущий блок в шаблон**: после сохранения текущий блок будет заменен на блок `Шаблон блока` (т. е. будет ссылаться на этот шаблон).
   - **Скопировать текущий блок как шаблон**: будет создан только шаблон, текущий блок останется прежним.

![save-as-template-block-20251228](https://static-docs.nocobase.com/save-as-template-block-20251228.png)

![save-as-template-block-full-20251228](https://static-docs.nocobase.com/save-as-template-block-full-20251228.png)

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

1) Добавить блок → «Другие блоки» → `Шаблон блока`.  
2) В конфигурации выберите:
   - **Шаблон**: выберите нужный шаблон.
   - **Режим**: `Ссылка` или `Копия`.

![block-template-menu-20251228](https://static-docs.nocobase.com/block-template-menu-20251228.png)

![select-block-template-20251228](https://static-docs.nocobase.com/select-block-template-20251228.png)

### Преобразование ссылки в копию

Если блок использует шаблон по ссылке, вы можете выбрать в меню настроек блока пункт `Преобразовать ссылку в копию`. Это превратит текущий блок в обычный (разорвет связь с шаблоном), и последующие изменения не будут влиять друг на друга.

![convert-block-template-duplicate-20251228](https://static-docs.nocobase.com/convert-block-template-duplicate-20251228.png)

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

- В режиме `Копия` будут заново сгенерированы UID для блока и его дочерних узлов. Некоторые настройки, зависящие от UID, могут потребовать повторной конфигурации.

## Шаблон поля

Шаблоны полей используются в **блоках форм** и **блоках деталей** для повторного использования конфигураций области полей (выбор полей, макет и настройки полей), чтобы избежать многократного добавления одних и тех же полей на разных страницах или в разных блоках.

> Шаблоны полей влияют только на «область полей» и не заменяют весь блок целиком. Чтобы повторно использовать весь блок, используйте Шаблон блока, описанный выше.

### Использование шаблона поля в блоках формы/деталей

1) Войдите в режим настройки, откройте меню «Поля» в блоке формы или деталей.  
2) Выберите `Шаблон поля`.  
3) Выберите шаблон и укажите режим: `Ссылка` или `Копия`.

![field-template-menu-20251228](https://static-docs.nocobase.com/field-template-menu-20251228.png)

![use-field-template-config-20251228](https://static-docs.nocobase.com/use-field-template-config-20251228.png)

#### Предупреждение о замене

Если в блоке уже есть поля, при использовании режима **Ссылка** обычно появляется запрос на подтверждение (так как поля из шаблона заменят текущую область полей).

### Преобразование полей по ссылке в копию

Если блок ссылается на шаблон поля, вы можете использовать в меню настроек блока пункт `Преобразовать поля по ссылке в копию`. Это сделает текущую область полей независимой конфигурацией (разорвет связь), и последующие изменения не будут влиять друг на друга.

![convert-field-template-duplicate-20251228](https://static-docs.nocobase.com/convert-field-template-duplicate-20251228.png)

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

- Шаблоны полей применимы только к **блокам форм** и **блокам деталей**.
- Если коллекция данных шаблона и текущего блока не совпадают, шаблон будет отображаться в списке как недоступный с указанием причины.
- Если вы хотите внести «индивидуальные корректировки» в поля текущего блока, рекомендуется сразу использовать режим `Копия` или сначала выполнить команду «Преобразовать поля по ссылке в копию».

## Шаблон всплывающего окна

Шаблоны всплывающих окон используются для повторного использования интерфейса и логики взаимодействия всплывающих окон. Информацию об общих настройках, таких как способ открытия и размер окна, см. в разделе [Редактировать всплывающее окно](/interface-builder/actions/action-settings/edit-popup).

### Сохранение всплывающего окна как шаблона

1) Откройте меню настроек кнопки или поля, вызывающего всплывающее окно, и нажмите `Сохранить как шаблон`.  
2) Укажите название и описание шаблона и выберите режим сохранения:
   - **Преобразовать текущее окно в шаблон**: после сохранения текущее окно переключится на использование этого шаблона по ссылке.
   - **Скопировать текущее окно как шаблон**: будет создан только шаблон, текущее окно останется без изменений.

![save-as-template-popup-20251228](https://static-docs.nocobase.com/save-as-template-popup-20251228.png)

### Использование шаблона в конфигурации всплывающего окна

1) Откройте настройки всплывающего окна кнопки или поля.  
2) В поле `Шаблон всплывающего окна` выберите нужный шаблон для повторного использования.

![edit-popup-select-20251228](https://static-docs.nocobase.com/edit-popup-select-20251228.png)

### Условия использования (область доступности шаблона)

Шаблоны всплывающих окон зависят от сценария действия, которое их вызывает. Селектор автоматически отфильтрует или отключит несовместимые шаблоны в зависимости от текущего сценария (с указанием причины, если условия не соблюдены).

| Текущий тип действия | Доступные шаблоны всплывающих окон |
| --- | --- |
| **Действие коллекции** | Шаблоны, созданные действиями той же коллекции |
| **Действие с записью без связи** | Шаблоны, созданные действиями коллекции или действиями с записью без связи той же коллекции |
| **Действие с записью связи** | Шаблоны, созданные действиями коллекции или действиями с записью без связи той же коллекции; или шаблоны, созданные действиями с записью связи того же поля связи |

### Всплывающие окна связанных данных

Для всплывающих окон, вызываемых связанными данными (полями связи), действуют особые правила сопоставления:

#### Строгое соответствие для шаблонов окон связи

Если шаблон всплывающего окна был создан на основе **действия с записью связи** (шаблон содержит `associationName`), этот шаблон может быть использован только действиями или полями с **точно таким же полем связи**.

Например: шаблон, созданный для поля связи `Заказ.Клиент`, может быть использован только другими действиями поля связи `Заказ.Клиент`. Его нельзя использовать для поля связи `Заказ.Рекомендатель` (даже если оба поля ссылаются на одну и ту же коллекцию `Клиенты`).

Это связано с тем, что внутренние переменные и конфигурации шаблонов окон связи зависят от конкретного контекста отношений связи.

#### Использование шаблонов целевой коллекции в действиях связи

Поля и действия связи могут повторно использовать **шаблоны окон без связи из целевой коллекции** (шаблоны, созданные действиями коллекции или действиями с записью без связи), если коллекции совпадают.

Например: поле связи `Заказ.Клиент` может использовать шаблоны всплывающих окон коллекции `Клиенты`. Этот подход удобен для совместного использования одной и той же конфигурации окна в нескольких полях связи (например, единое окно деталей клиента).

### Преобразование ссылки в копию

Если всплывающее окно использует шаблон по ссылке, вы можете выбрать в меню настроек пункт `Преобразовать ссылку в копию`. Это сделает текущее окно независимой конфигурацией (разорвет связь), и последующие изменения не будут влиять друг на друга.

![convert-popup-to-duplicate-20251228](https://static-docs.nocobase.com/convert-popup-to-duplicate-20251228.png)


## Управление шаблонами

В разделе Системные настройки → `UI шаблоны` вы можете просматривать все шаблоны и управлять ими:

- **Шаблоны блоков (v2)**: управление шаблонами блоков.
- **Шаблоны всплывающих окон (v2)**: управление шаблонами всплывающих окон.

> Шаблоны полей происходят от шаблонов блоков и управляются внутри них.

![block-template-list-20251228](https://static-docs.nocobase.com/block-template-list-20251228.png)

Поддерживаемые операции: просмотр, фильтрация, редактирование, удаление.

> **Примечание**: если шаблон используется по ссылке, его нельзя удалить напрямую. Сначала необходимо использовать функцию `Преобразовать ссылку в копию` во всех местах, где используется этот шаблон, чтобы разорвать связи, а затем удалить сам шаблон.