# Порталы

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

Раздел описывает настройку портальных страниц: как создать портал и выбрать конструктор, добавить и оформить виджеты, задать для них источники данных и фильтры, подключить JS/CSS-вставки и настроить права доступа.

## Механизмы администрирования

### Пользовательская SPA-страница

Форма автоадминистрирования, открывающая SPA-редактор порталов:

| Alias формы | Название | Url | Таблица БД | Папка |
|-------------|----------|-----|-----------|-------|
| `portals` | Порталы | `/administration/portals/editor` | dbo.PortalGridTemplates | Пользовательский интерфейс |

### API администрирования

Маршруты для управления порталами, блоками, фильтрами, includes и правами:

| Маршрут | Методы | Назначение |
|---------|--------|------------|
| `/api/admin/portals` | GET, POST, PUT, DELETE | Список и базовая конфигурация порталов |
| `/api/admin/portals/blocks` | GET, POST, PUT, DELETE | Настройки блоков |
| `/api/admin/portals/blocks/filters` | GET, POST, PUT, DELETE | Фильтры блоков |
| `/api/admin/portals/{portalId}/includes` | GET, POST, PUT, DELETE | Подключаемые JS/CSS includes |
| `/api/portals/{portalId}/view/groups` | GET, POST, DELETE | Ограничение просмотра по группам |

## Управление портальными страницами

### Создание и редактирование

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

**Создание:** кнопка «Добавить портал» → ввести название → ОК. Название должно быть уникальным — при попытке создать дубль выводится сообщение об ошибке.

![Создание портальной страницы: кнопка «Добавить портал» и поле названия](https://help.1forma.ru/help-images/portal/portals-editor-3.png)

**Меню управления страницей:**

| Кнопка | Описание |
|--------|----------|
| Добавить портал | Новая портальная страница |
| Добавить виджет | Новый виджет |
| Создать раздел | Раздел для группировки виджетов (тематический: СЭД, Маркетинг, ServiceDesk и т.п.) |
| Переименовать | Переименовать портал |
| Дизайнер | Выбрать режим верстки: Flex, Dashboard, CSS Grid, Board |
| Настроить вставки (js и css) | Редактор JS/CSS инклудов для конкретного портала |
| Доступ | Ограничение видимости портала по группам пользователей |
| Удалить | Удалить портальную страницу |
| Сохранить модуль | Привязать портал к модулю (если модуль не выбран — портал относится к глобальному) |

⚠️ **Порталы в дизайне Flex и в дизайне Dashboard/CSS Grid имеют разный синтаксис адресной строки.** Добавление портала в избранное и назначение стартового портала выполняются через РМГ (Реестры/Масштабируемые группы), не через интерфейс редактора портала — кнопка «Добавить в избранное» в редакторе была удалена как нерабочая. Если ссылка на портал в РМГ была настроена, а потом режим отображения портала изменился — нужно удалить прежнюю ссылку и добавить новую.

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

**Редактирование.** Чтобы изменить портал, выберите его в выпадающем списке редактора — рядом с названием в скобках показаны уникальный ID портала и тип дизайнера.

![Выбор портала из выпадающего списка: рядом с названием — ID и тип дизайнера](https://help.1forma.ru/help-images/portal/portals-editor-1.png)

Откроется интерфейс редактирования: рабочая область с сеткой и панель инструментов.

![Интерфейс редактирования портала: рабочая область и панель инструментов](https://help.1forma.ru/help-images/portal/portals-editor-2.png)

Для смены конструктора нажмите кнопку выбора типа дизайнера (Flex, Dashboard, CSS Grid, Board).

![Выбор типа конструктора при редактировании портальной страницы](https://help.1forma.ru/help-images/portal/portals-editor-6.png)

**Доступ и видимость.** Доступ к порталу выдаётся группам пользователей — **не более 30 групп** на портал. В режиме редактирования администратору доступны все виджеты независимо от прав; в пользовательском режиме видны только порталы и виджеты, на которые у пользователя есть права. Виджет без назначенных групп недоступен никому, кроме администратора: пустой список групп — это отсутствие доступа, а не публичность виджета. Виджетам, у которых групп не было, при обновлении проставляется группа из настройки «Группа по умолчанию для новых пользователей» (system/admin.md); у виджетов, созданных после обновления, группы нужно назначать явно, иначе их не увидит никто, кроме администратора. Если все виджеты внутри секции или блока скрыты для пользователя, сама секция/блок тоже не отображается и не занимает места в сетке.

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

**Что возвращает чтение списка групп.** Кнопка «Доступ» в редакторе показывает группы, которым портал открыт, — их же отдаёт чтение списка групп по API. Этот список доступен только тому, кому виден сам портал: у пользователя без права на портал ответ не содержит перечня групп, поэтому имена групп и то, кому портал открыт, наружу не уходят. Для администратора состав списка и порядок работы не меняются.

### Стартовая страница

Чтобы портальная страница отображалась при входе в систему и при нажатии на логотип — в «Общих настройках приложения» (`sys_general_settings`) в параметре «Стартовая страница» указать ссылку на портальную страницу (`1` — это ID портальной страницы).

![Параметр «Стартовая страница» в общих настройках приложения](https://help.1forma.ru/help-images/portal/portals-editor-7.png)

### Разделы виджетов

При создании виджета указывается его принадлежность одному или нескольким разделам. Разделы нужны для организации и удобного поиска. На любой портал можно добавить виджеты из любых разделов. Виджет без раздела отображается в разделе «Без раздела».

⚠️ **При удалении раздела удаляются также все принадлежащие ему виджеты.** Если виджет принадлежит нескольким разделам — при удалении одного виджет сохраняется в остальных.

### Различие «удалить с портала» и «полное удаление»

Два способа убрать виджет с портала:

- **Удалить с портала** — виджет продолжает существовать и принадлежать своим разделам. В любой момент его можно снова добавить.
- **Полное удаление** — виджет перестает существовать, восстановить нельзя. Полностью удалить виджет нельзя, пока он размещён хотя бы на одном портале: в ответ на попытку выводится сообщение «Виджет используется на следующих порталах» с перечнем этих порталов и выводом «Удаление невозможно». Чтобы удалить виджет, сначала снимите его с перечисленных порталов.

### Реестр виджетов (v2.268+)

Реестр виджетов — единый список всех виджетов (блоков порталов) системы, независимо от того, на каких порталах они размещены. Раньше управлять виджетами можно было только внутри конкретного портала: общего списка всех виджетов и удаления неиспользуемых через интерфейс не было. Раздел нужен для наведения порядка — обзора и чистки неиспользуемых виджетов. Доступен только администратору.

**Как открыть.** Администрирование → пункт меню «Виджеты». Также в редакторе порталов есть кнопка «Все виджеты», открывающая реестр.

**Колонки грида:** ID, Название, Активен (признак включённости), Тип, Модуль, Секции, Группы доступа (группы, которым выдан доступ к виджету). Над гридом — поиск по названию.

**Действия со строкой** (клик или правая кнопка мыши):

- **Открыть** — переход в настройки виджета.
- **Где используется** — окно со списком порталов, на которых размещён виджет (если нигде не размещён — «—»).
- **Удалить** — полное удаление виджета. Если виджет размещён хотя бы на одном портале, удаление блокируется, а в уведомлении выводится причина и перечень порталов: «Виджет используется на следующих порталах», список порталов и вывод «Удаление невозможно». Сначала снимите виджет с перечисленных порталов в редакторе портала, затем повторите удаление. То же уведомление выводится при удалении виджета из окна его настроек. Если виджет нигде не используется — запрашивается подтверждение, после чего виджет удаляется и список обновляется. Это та же логика полного удаления, что описана выше.

### Переход к настройкам из пользовательского режима

К настройкам можно перейти прямо из пользовательского интерфейса — администратору доступны пункты контекстного меню (правая кнопка мыши).

Клик правой кнопкой по пустой области портала открывает пункт «Настроить портал».

![Пункт «Настроить портал» в контекстном меню пустой области портала](https://help.1forma.ru/help-images/portal/admin-settings-mtf-010.png)

Клик правой кнопкой по виджету открывает пункт «Настроить виджет» — он ведёт в дополнительные настройки виджета.

![Пункт «Настроить виджет» в контекстном меню виджета](https://help.1forma.ru/help-images/portal/admin-settings-mtf-009.png)

## Конструкторы портальных страниц

Платформа поддерживает четыре режима верстки: Dashboard, CSS Grid, Flex и Board. Dashboard, CSS Grid и Flex — самостоятельные типы раскладки страницы; Board собирается поверх Dashboard: это портал из вкладок, каждая вкладка состоит из секций со встроенными Dashboard-порталами. Виджеты, добавленные в одном режиме, **не отображаются** при переключении на другой.

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

### Конструктор Dashboard

Портальная страница состоит из сетки, на которой расположены виджеты. Пользователи могут самостоятельно добавлять/удалять виджеты, менять местами и изменять размеры.

![Интерфейс портальной страницы в режиме Dashboard](https://help.1forma.ru/help-images/portal/portal_page_edit_dashboard-0.png)

**Кнопки управления:**

| Кнопка | Действие |
|--------|----------|
| Добавить виджет | Открыть окно добавления виджета (по умолчанию — поиск по всем разделам, включая «Без раздела», с поиском по ID виджета; ID виджета отображается рядом с его названием в списке результатов) |
| Сохранить | Сохранить изменения |
| Сбросить пользовательские настройки | Удалить все пользовательские переопределения — портал вернётся к административному виду |
| Очистить шаблон | Удалить все виджеты с сетки (кнопка на панели инструментов справа) |
| Убрать выделение | Снять выбор виджета на сетке |
| Скрыть/отобразить правую панель | Переключение панели инструментов |

Добавление существующего виджета — кнопка в правом верхнем углу сетки; уже добавленные в текущий портал виджеты отмечены галочкой.

**Поддержка типов.** В раскладке Dashboard доступны все типы виджетов, кроме «Навигации» и «Мини-опроса»: эти два типа работают только в CSS Grid и в Dashboard выводят «Виджет не поддерживается». Полная таблица по режимам — [Виджеты](https://help.1forma.ru/domains/portal/admin-widgets.md#поддержка-типов-по-режимам-вёрстки).

![Окно добавления виджетов на портал в режиме Dashboard](https://help.1forma.ru/help-images/portal/portal_page_edit_dashboard-1.png)

**Типы сетки (6):**

| Тип | Описание |
|-----|----------|
| На весь экран | Сетка занимает всю доступную область |
| Вертикальная прокрутка | Прокрутка по вертикали |
| Горизонтальная прокрутка | Прокрутка по горизонтали |
| Фиксированная | Фиксированный размер |
| Фиксированная по вертикали | Фиксирована по вертикали |
| Фиксированная по горизонтали | Фиксирована по горизонтали |

**Параметры сетки:**

| Параметр | Описание |
|----------|----------|
| Отступ (px) | Расстояние между ячейками по горизонтали и вертикали |
| Внешний отступ | Внешние отступы со всех сторон (размер = отступ между ячейками) |
| Показывать сетку | Всегда / При изменении размеров / Никогда |
| Мобильный экран (px) | Ширина при отображении на мобильном экране |
| Ширина колонки (px) | Ширина одной колонки |
| Высота строки (px) | Высота одной строки |
| Макс. число колонок | Максимальное число колонок (задаётся для каждого размера экрана) |
| Мин. число колонок | Минимальное число колонок (задаётся для каждого размера экрана) |
| Поведение при перемещении | «Менять местами» или «Толкать» |

**Параметры виджета на уровне сетки:**

| Параметр | Описание |
|----------|----------|
| Перетаскивание | Разрешить пользователям перетаскивать виджет |
| Изменение размеров | Разрешить пользователям изменять размеры |
| Колонок макс./мин. | Макс./мин. число колонок, которые может занимать виджет |
| Строк макс./мин. | Макс./мин. число строк, которые может занимать виджет |

После добавления виджета его настройки открываются по кнопке в правом верхнем углу блока, удаление с портала — по кнопке в правом нижнем углу.

![Виджет на портальной странице в режиме Dashboard](https://help.1forma.ru/help-images/portal/portal_page_edit_dashboard-2.png)

⚠️ **КРИТИЧНО: 5 контрольных точек адаптивности.** Расположение виджетов настраивается **отдельно для каждого размера экрана**:

| Точка | Колонки по умолчанию |
|-------|---------------------|
| Не выбран | — |
| xs | 1 колонка |
| sm | 2 колонки |
| md | 4 колонки |
| lg | 8 колонок |
| xl | 12 колонок |

⚠️ **Если для одного из размеров экрана расположение виджетов не настроено — на соответствующем устройстве виджеты НЕ будут отображаться.** Для вертикального расположения экрана в большинстве случаев используется размер xs.

Те же пять раскладок входят в выгрузку портала при переносе конфигурации: блок, размещённый только на одном размере экрана, остаётся в этой раскладке и на приёмнике.

### Конструктор CSS Grid (v2.266+)

Дизайнер CSS Grid используется для создания адаптивных портальных страниц с разнородными виджетами. В отличие от Dashboard и Board, CSS Grid позволяет комбинировать несколько стратегий в рамках одной страницы.

**Поддержка типов.** CSS Grid поддерживает все типы блоков, включая «Навигацию» и «Мини-опрос», которые в Dashboard недоступны.

![Интерфейс портальной страницы в режиме CSS Grid](https://help.1forma.ru/help-images/portal/portal_page_edit_cssgrid-0001.png)

**Кнопки управления:** добавление блока, сохранение, удаление выделенного блока, перемещение блока на уровень выше/ниже.

**Подсветка сетки.** В режиме редактирования зазоры между ячейками сетки подсвечиваются тонкими линиями по вертикали и горизонтали; линии проходят по фактическим границам рядов и колонок, в том числе у рядов разной высоты. Линии рисует браузер: если он не поддерживает такое оформление сетки, страница редактируется как обычно, но без линий.

**Типы блоков:**

| Тип | Описание |
|-----|----------|
| **Виджет** | Элемент с фиксированными размерами. Не растягивается. При изменении ширины экрана автоматически занимает место в плотной плиточной сетке. Виджет может быть только один. |
| **Секция** | Занимает всю ширину строки, делит её на пропорциональные части. Шаблоны: `1/1`, `1/full`, `full/1`. В секцию можно добавить множество виджетов. |
| **Контейнер** | Решает проблему динамического контента. Помещаются виджеты с ролевой видимостью. При скрытии виджета для конкретного пользователя в макете не образуется пустых мест. |
| **Ряд** | Полоса, в которой элементы располагаются горизонтально или вертикально и делят её пропорционально коэффициентам. Задаются ширина и высота ряда и признак «с новой строки». |

![Блок-контейнер в режиме CSS Grid](https://help.1forma.ru/help-images/portal/portal_page_edit_cssgrid-004.png)

**Настройки ряда.** Ширина и высота выбираются из значений 2, 4, 6, 8 и 12; флаг «С новой строки» переносит ряд на следующую строку сетки. Направление — горизонтальное или вертикальное. В ряд можно добавить не больше четырёх элементов; у каждого задаётся коэффициент 2, 4 или 6, и сумма коэффициентов не должна превышать 12 — иначе настройки ряда считаются некорректными и не сохраняются. Одним из четырёх элементов может быть вложенный ряд: в ряду он допускается только один, вкладывать ряд в ряд глубже одного уровня нельзя, и у вложенного ряда задаётся только направление и состав элементов — собственные размеры и «с новой строки» ему недоступны. Элементы, недоступные пользователю по правам, из ряда выпадают, не оставляя пустых мест: оставшиеся виджеты занимают всю ширину ряда. Вложенный ряд, в котором не осталось доступных виджетов, не отображается, а ряд без единого доступного элемента не выводится на портал вовсе.

**Автоматическое расположение элементов:**

| Правило | Описание |
|---------|----------|
| По строкам | Элементы заполняются построчно (по умолчанию) |
| По колонкам | Элементы заполняются по колонкам |
| По строкам + принудительное складывание | Построчное с принудительным складыванием |

![Настройка автоматического расположения элементов (режим CSS Grid)](https://help.1forma.ru/help-images/portal/portal_page_edit_cssgrid-button-1.png)

**Режимы заполнения пространства:**

| Режим | Описание |
|-------|----------|
| По контенту | Элементы распределяются без пустых областей (по умолчанию) |
| Пустотой | Сохраняется пустое место до появления достаточного пространства для нового элемента |

![Режимы заполнения пространства (режим CSS Grid)](https://help.1forma.ru/help-images/portal/portal_page_edit_cssgrid-button-2.png)

**Предпросмотр вёрстки на разных размерах экрана.** В панели «Структура» конструктора есть выпадающий список масштаба зоны просмотра: 100% (по умолчанию), UltraWide (2100 px), Laptop (1360 px), Tablet (768 px), Phone (400 px). Если целевая ширина меньше рабочей области — зона заужается, содержимое остаётся в масштабе 100%; если больше — контент рисуется на целевой ширине и пропорционально уменьшается. Выбор Phone/Tablet **не включает мобильную раскладку сетки** (правила сетки завязаны на ширину окна браузера): режим годится для примерки взаимного расположения блоков, но не для точной проверки мобильного вида.

**Размеры виджетов в CSS Grid:**

| Параметр | Описание |
|----------|----------|
| **Шаблон** | Предустановленный размер из дизайна конкретного виджета. Размеры, нарушающие вёрстку, в список не включаются. |
| **Во всю ширину** | Виджет занимает всю ширину сетки. Параметр «Начать с новой строки» не применяется. |
| **Кастом** | Произвольный размер. Допустимые значения колонок и строк: 2, 4, 6, 8, 12. Исключение: Баннер-кнопка в режиме Кастом — высота 1 строка. |

Для секций и для виджетов с шириной «во всю ширину» дополнительно доступен явный выбор **фиксированной высоты** из списка (2, 4, 6, 8, 12).

**Таблица размеров 13 типов виджетов:**

| Тип виджета | Доступные варианты | Шаблоны (колонки × строки) | По умолчанию |
|---|---|---|---|
| Кнопка-тикер | Шаблон | 1×2, 2×1, 2×2, 4×1, 4×2, 2×4, 4×4 | 2×2 |
| Баннер-кнопка | Шаблон | 1×2, 2×1, 2×2, 4×1, 4×2, 2×4, 4×4, 6×4, 4×6, 6×6 | Из настроек виджета |
| Календарь New | Шаблон | 2×2, 4×2, 4×4 | Из настроек виджета |
| Контакты | Шаблон | Из настроек виджета | Из настроек виджета |
| Счётчики | Шаблон | Из настроек виджета | Из настроек виджета |
| Список задач | Шаблон | 4×2, 4×4, 4×6, 6×4, 6×6 | 4×4 |
| Избранное | Шаблон | 4×2, 4×4, 4×6, 6×4, 6×6 | 4×4 |
| Новости | Шаблон, Кастом | 4×4, 6×6, 12×6, 12×8 | 12×8 |
| Лента социальной сети | Шаблон, Кастом | 4×6, 6×8, 6×12, 8×12 | — |
| Фильтр | Во всю ширину | — | — |
| Группа виджетов | Кастом, Во всю ширину | — | 4×4 |
| Все остальные | Кастом, Во всю ширину | — | 4×4 |

**Параметр «Начать с новой строки»** — доступен для виджетов с фиксированной шириной (не «во всю ширину»). При включении виджет всегда начинает отрисовываться с первой колонки строки сетки.

![Виджет, добавленный в портальную страницу (режим CSS Grid)](https://help.1forma.ru/help-images/portal/portal_page_edit_cssgrid-002.png)

**Адаптивные контрольные точки:**

| Ширина экрана | Поведение |
|---------------|-----------|
| ≥ 960px | Стандартная сетка (12 колонок) |
| < 960px | Ширина 6 колонок (для секций с шириной 6) |
| < 600px | Ширина 2/4 колонки (для секций с шириной 2 или 4) |

⚠️ **Секции с шаблоном 1/1 на мобильных:** при перестроении на малых экранах виджеты встают один под другим и каждый наследует высоту, заданную для всей секции.

![Секция с шаблоном 1/1 (режим CSS Grid)](https://help.1forma.ru/help-images/portal/portal_page_edit_cssgrid-02.png)

Подробнее: [Portal API (cookbook)](https://help.1forma.ru/domains/portal/portal-api-cookbook.md) (таблица TypeId), [Паттерны дашбордов](https://help.1forma.ru/domains/portal/academy-dashboards.md) (краткие описания типов).

### Конструктор Board

Board-дизайнер позволяет создавать портальные страницы с вкладками, в которых располагаются объединённые в секции дашборды.

![Интерфейс портальной страницы в режиме Board: рабочая область и боковая панель структуры](https://help.1forma.ru/help-images/portal/board-01.png)

**Структура (боковая панель):**

| Элемент | Описание |
|---------|----------|
| **Портал** | Корневой элемент. Название редактируется. Недоступен для удаления. |
| **Страницы** | Вкладки на уровне портала. Каждая отображает Board-портал. В списке недоступны порталы типа Flex и другие Dashboard-порталы. |
| **Навигация** | Ссылки-«хлебные крошки» над заголовком портала. Несколько ссылок разделяются символом `/`. Поля: текст ссылки, URL. |
| **Секции** | Встраивают Dashboard-порталы. Поля: название, фиксированная высота, показ заголовка, ссылка в заголовке, выбор Dashboard-портала, категория для создания задачи (добавляет кнопку «+»). |
| **Группы** | Содержат секции и становятся внутренними вкладками. Имена групп **НЕ видны на портале** — только в конструкторе. Удаление группы удаляет все её секции. |

Страница-вкладка создаётся вводом названия в поле «Добавить страницу» (Enter); в её списке порталов доступны только Board-порталы.

![Пример настроенных страниц-вкладок в режиме Board](https://help.1forma.ru/help-images/portal/board9.png)

Ссылка навигации добавляется вводом названия в поле «Добавить ссылку» (Enter); у каждой задаются текст и адрес.

![Добавление ссылок навигации на портал в режиме Board](https://help.1forma.ru/help-images/portal/board10.png)

Секция настраивается выбором Dashboard-портала, фиксированной высоты, показа заголовка и — опционально — категории для кнопки «+» создания задачи.

При переносе конфигурации между площадками блоки секций Board выгружаются вместе с порталом (см. [перенос конфигурации](https://help.1forma.ru/domains/migration/README.md), правило 14). Секция — отдельный дашборд: её виджеты едут со своим шаблоном и в корневую сетку родителя не копируются.

![Настройки новой секции в режиме Board](https://help.1forma.ru/help-images/portal/board4.png)

Сгруппированные секции отображаются как внутренние вкладки портала. Секция внутри группы также поддерживает кнопку «+» создания задачи — она показывается на активной вкладке группы.

![Секции, объединённые в группы (с дашбордами), в режиме Board](https://help.1forma.ru/help-images/portal/board11.png)

⚠️ **Ограничения Board:**

- Виджет **нельзя** добавить напрямую в Board — сначала добавить в Dashboard, потом встроить секцией.
- Секцию **нельзя** переместить в группу — нужно создать группу, затем создать секцию внутри.
- В секции Board виджеты «Навигация» и «Мини-опрос» не отображаются: секция — встроенный Dashboard-портал, а эти типы работают только в CSS Grid.

При настройке секций учитывайте, что пользователи без доступа к встроенному Dashboard-порталу увидят в этой вкладке сообщение «Нет доступа» вместо содержимого — остальные вкладки портала при этом остаются доступны и загружаются штатно.

### Flex-конструктор (устаревший)

⚠️ **Устаревший режим.** Адаптивная верстка контейнерами. Основной элемент — родительский контейнер с дочерними. Управление через контекстное меню (ПКМ). Не поддерживается в новом конструкторе. Упомянут для полноты — новые порталы рекомендуется создавать в CSS Grid или Dashboard.

## Типы портальных блоков (виджетов)

Полный каталог типов виджетов и их настроек вынесен в отдельный документ: **[Виджеты](https://help.1forma.ru/domains/portal/admin-widgets.md)**. Набор доступных типов зависит от режима вёрстки страницы: часть типов отображается не везде.

Разделы каталога:

- [Поддержка типов по режимам вёрстки](https://help.1forma.ru/domains/portal/admin-widgets.md#поддержка-типов-по-режимам-вёрстки)
- [Создание и общие настройки виджета](https://help.1forma.ru/domains/portal/admin-widgets.md#создание-и-общие-настройки-виджета)
- [Общие свойства контейнера виджета](https://help.1forma.ru/domains/portal/admin-widgets.md#общие-свойства-контейнера-виджета)
- [Блок поиска задач](https://help.1forma.ru/domains/portal/admin-widgets.md#блок-поиска-задач)
- [Список задач (v2.262+)](https://help.1forma.ru/domains/portal/admin-widgets.md#список-задач-v2262)
- [Таблица](https://help.1forma.ru/domains/portal/admin-widgets.md#таблица)
- [Фильтры (v2.265+)](https://help.1forma.ru/domains/portal/admin-widgets.md#фильтры-v2265)
- [Диаграмма Ганта](https://help.1forma.ru/domains/portal/admin-widgets.md#диаграмма-ганта)
- [Smart HTML](https://help.1forma.ru/domains/portal/admin-widgets.md#smart-html)
- [Новости](https://help.1forma.ru/domains/portal/admin-widgets.md#новости)
- [Группа виджетов (v2.265+)](https://help.1forma.ru/domains/portal/admin-widgets.md#группа-виджетов-v2265)
- [Навигация (v2.266+)](https://help.1forma.ru/domains/portal/admin-widgets.md#навигация-v2266)
- [Избранное (v2.263+)](https://help.1forma.ru/domains/portal/admin-widgets.md#избранное-v2263)
- [Кнопка-тикер (v2.261+)](https://help.1forma.ru/domains/portal/admin-widgets.md#кнопка-тикер-v2261)
- [Счётчики (v2.262+)](https://help.1forma.ru/domains/portal/admin-widgets.md#счётчики-v2262)
- [Баннер-кнопка (v2.261+)](https://help.1forma.ru/domains/portal/admin-widgets.md#баннер-кнопка-v2261)
- [Баннер (с 2.268)](https://help.1forma.ru/domains/portal/admin-widgets.md#баннер-с-2268)
- [Контакты (v2.262+)](https://help.1forma.ru/domains/portal/admin-widgets.md#контакты-v2262)
- [Лента социальной сети](https://help.1forma.ru/domains/portal/admin-widgets.md#лента-социальной-сети)
- [Календарь](https://help.1forma.ru/domains/portal/admin-widgets.md#календарь)
- [Календарь New (v2.262+)](https://help.1forma.ru/domains/portal/admin-widgets.md#календарь-new-v2262)
- [Календарь по задачам](https://help.1forma.ru/domains/portal/admin-widgets.md#календарь-по-задачам)
- [График (диаграмма)](https://help.1forma.ru/domains/portal/admin-widgets.md#график-диаграмма)
- [Меню](https://help.1forma.ru/domains/portal/admin-widgets.md#меню)
- [Мини-опрос (с 2.267)](https://help.1forma.ru/domains/portal/admin-widgets.md#мини-опрос-с-2267)
- [Сторис (с 2.268)](https://help.1forma.ru/domains/portal/admin-widgets.md#сторис-с-2268)
- [Паттерн: несколько блоков-отчётов с разными фильтрами](https://help.1forma.ru/domains/portal/admin-widgets.md#паттерн-несколько-блоков-отчётов-с-разными-фильтрами)

## JS API порталов и портальных блоков

### JS/CSS Includes

**Создание вставки:** описание → тип (js/css) → содержимое → сохранить.

**Привязка:**

- К порталу — вставка работает на всех страницах портала
- К блоку — вставка работает только в конкретном блоке

Список вставок отображается в таблице с колонками **ID**, **Описание** и **Настройки вставки**; колонка «Настройки вставки» показывает тип вставки: **Js**, **Css** или **JsUrl**. Тот же экран используется в настройках виджета — на вкладке «JS и CSS вставки» таблица выглядит одинаково.

⚠️ **Добавленные ранее вставки не будут корректно работать при переходе из старого МТФ/НТФ в новый SPA.**

Методы JS API для работы с порталами и портальными блоками описаны ниже.

### JS API портальных блоков

Основные методы для работы с портальными блоками из JS-вставок:

| Метод | Описание |
|-------|----------|
| `portal.block(blockId)` | Получить объект портального блока |
| `onLoaded` | Событие загрузки блока |
| `refresh()` | Обновить данные блока |
| `spaCommand` | Выполнить SPA-команду |
| `fileViewer` | Открыть просмотрщик файлов |
| `setFilters()` | Установить фильтры блока |
| `filters()` | Получить текущие фильтры |
| `freeze()` / `unfreeze()` | Блокировка/разблокировка рендера блока |

## Ключевые настройки

### Порталы (PortalGridTemplates)

**Где настраивается:** SPA-страница `/administration/portals/editor` (пункт `portals` в дереве автоадминки) или API администрирования
**Таблица БД:** `dbo.PortalGridTemplates`

6 полей: страницы порталов и типы layout (dashboard, board, cssgrid).

**Как применяется:** определяет набор доступных портальных страниц и их тип отображения.

### Блоки порталов (PortalGridBlocks)

**Где настраивается:** API администрирования (блоки порталов)
**Таблица БД:** `dbo.PortalGridBlocks`

Набор виджетов на портальной странице: тип блока, параметры, источник данных, позиционирование.

| Группа полей | Что контролирует |
|-------------|------------------|
| Тип блока | Виджет (задачи, отчёт, HTML, iframe и т.д.) |
| Параметры блока | Источник данных и конфигурация |
| Позиция, размер | Расположение на странице |

**Как применяется:** данные блока загружаются через `POST /api/portals/block/data/{blockId}`.

**Действия с несуществующим блоком.** Если блока с таким идентификатором нет, чтение, обновление и удаление блока, а также чтение и запись его параметров типа завершаются ответом «не найдено» с идентификатором блока в теле ошибки. Если блок существует, но в запросе указан несуществующий вторичный идентификатор — например, чужой hint или чужой узел оргструктуры, — ответ остаётся отказом по данным запроса: это ошибка в параметрах, а не отсутствие блока.

Виджет можно вывести и вне портала — на отдельной странице по адресу `~/spa/portal/block/{BlockID}` (например, `~/spa/portal/block/123`).

**Окно настроек виджета — отдельная страница и открытие в новой вкладке.** Настройки виджета открываются в окне (модалке) поверх редактора портала; внутри окно показывает страницу настроек во встроенном фрейме. В заголовке окна есть кнопка с иконкой 🔗 (**«Открыть в новой вкладке»**) — она открывает те же настройки как отдельную страницу AdminSPA по адресу `~/spa/administration/widget-settings/{BlockID}` (по Id блока). Так можно дать прямую ссылку на настройки конкретного виджета или работать с настройками нескольких виджетов в разных вкладках одновременно. Не путать с `~/spa/portal/block/{BlockID}` выше: там выводится сам виджет, а здесь — его настройки.


### Фильтры блоков

**Где настраивается:** API администрирования (фильтры блоков)
**Таблицы БД:** `dbo.PortalGridBlocksFilters`, `dbo.PortalGridBlockFilters`, `dbo.PortalGridFilterParams`, `dbo.PortalGridFilterParamBlockValues`

Фильтрация данных виджетов: параметры фильтров привязываются к блокам и определяют, какие данные отображаются.

Ключевые правила:

1. На одной портальной странице может быть несколько независимых виджетов фильтров, но запрещены дубли с одинаковым набором фильтров.
2. Значения фильтров синхронизируются между связанными блоками (`Фильтры`, `График`, `Таблица`) в обе стороны.
3. Список параметров виджета строится из настройки фильтрации (`filters_spa`): что включено в фильтр, то доступно в виджете.
4. Если на одной странице несколько экземпляров виджета фильтра смотрят на один и тот же фильтр, их значения синхронизируются: изменение или очистка значения в любом из них сразу отражается в остальных — и в вертикальном представлении полями, и в горизонтальном наборе чипов. Ограничение «запрещены дубли» касается виджетов с одинаковым набором параметров в разных фильтрах; несколько экземпляров одного фильтра — поддерживаемый сценарий, а не дубль.
5. Значения фильтра каждый виджет хранит в браузере отдельно для себя. Поэтому синхронизация действует в пределах открытой страницы портала, а после перезагрузки каждый экземпляр восстанавливает своё сохранённое состояние; чтобы все виджеты открывались с одним набором значений, у них должен быть включён флажок «Сохранять значения фильтров».

Настройки фильтрации виджета задаются на вкладке «Настройки фильтрации» в окне настроек виджета. Фильтрация поддерживается для виджетов Smart HTML, График, Таблица, Блок поиска задач и Фильтр — для остальных типов вкладка неактивна. Там же флажок «Сохранять значения фильтров» определяет, запоминается ли выбор пользователя между открытиями портала.

Если сохранение включено, при открытии виджета подставляются последние выбранные пользователем значения — они хранятся в браузере. Если выключено, портал открывается с исходного состояния фильтра: у параметров, где в настройках задано «Значение по умолчанию», подставляется оно, остальные остаются пустыми. Выбор, сделанный на уже открытой странице, при этом не сбрасывается — он действует до перезагрузки.

![Вкладка «Настройки фильтрации» в окне настроек виджета](https://help.1forma.ru/help-images/portal/widget_filter.png)

Параметры отображения виджета фильтров:

| Параметр | Что контролирует |
|---|---|
| `Представление` | Режим: `Горизонтальный` (чипы) или `Вертикальный` (поля) |
| `Количество колонок` | Число колонок для вертикального режима |
| `Количество колонок в модальном окне` | Разметка окна `Все фильтры/Еще фильтры` |

Параметры отдельных фильтров:

| Параметр | Что контролирует |
|---|---|
| `Видимость` | `Всегда видимые` / `Только если выбрано значение` / `Всегда свернуто` |
| `Подсказка` | Подсказка по фильтру (чип/поле) |
| `Скрыть имя` | В горизонтальном режиме при выбранном значении показывать только значение без подписи |
| `Колонка доступности` | Только для смарт-набора с заданными зависимостями. Имя столбца в результате смарт-выражения, содержащего признак доступности элемента. Бэкенд вычитывает эту колонку и включает значение в ответ (`avalible` на каждом элементе). |
| `Недоступные значения` | Для смарт-набора с заданной «Колонкой доступности»: как показывать значения, помеченные недоступными. **Пусто** (по умолчанию) и **Скрывать** — недоступные значения убираются из списка; **Блокировать** — остаются видимыми, но неактивными (серыми, выбрать нельзя). |
| `Ключ родителя` | Только для **статического набора** (Свой). Значение поля каждого элемента, по которому он привязывается к значению родительского параметра при каскадной зависимости. |
| `Колонка родителя` | Только для **смарт-набора**. Имя столбца в результате смарт-выражения, содержащего ключ привязки к родительскому значению. Значения выводятся деревом: узлы раскрываются и сворачиваются, выбор родителя отмечает всю ветку, частичный выбор показывается промежуточным состоянием. Бэкенд вычитывает эту колонку и включает значение в ответ (`parent` на каждом элементе). |
| `Локализация названия` | Перевод названия параметра на языки интерфейса. Пользователю на портале показывается перевод для его языка, при отсутствии перевода — исходное название |

У элемента выпадающего списка два поля: значение, которое уходит в отбор, и название, которое видит пользователь. В панели применённых фильтров при одиночном выборе показывается название элемента, а если название не задано — его значение. Правило одинаково для статического набора и смарт-набора. На отбор подпись не влияет: в запрос данных уходит значение элемента.

#### Каскадные выпадающие списки

Dropdown-параметр типа «Смарт-набор» может зависеть от другого параметра через настройку **«Зависит от параметров»**:

1. При изменении значения в родительском параметре фронтенд вызывает `POST /api/v10/filters/config/dropdown/items` с `otherValuesJson` — выбранным значением родителя.
2. Смарт-выражение дочернего параметра получает это значение через `@eventParam2` и возвращает отфильтрованный список.
3. Если задана **«Колонка родителя»** — бэкенд дополнительно вычитывает эту колонку из каждой строки результата смарт-выражения и включает её в ответ (поле `parent`).
4. Если задана **«Колонка доступности»** — бэкенд аналогично вычитывает её и включает в ответ (поле `avalible`), позволяя управлять доступностью элементов на стороне клиента.

Для **статического набора** каскад настраивается иначе: у каждого элемента вручную задаётся **«Ключ родителя»** — значение из родительского параметра, при котором этот элемент доступен.

С версии **2.268.349**: если у dropdown-параметра набор значений пуст (например, по выбранному родителю каскад вернул 0 строк), плейсхолдер показывает `Нет данных: <Название параметра>` вместо общего `Нет данных` — видно, какой именно фильтр оказался пустым, без необходимости разворачивать список.

Поведение:

- в горизонтальном режиме фильтр применяется сразу после изменения значения и закрытия редактора;
- кнопка `Очистить` появляется только при наличии активных фильтров;
- для свернутых фильтров используется модальное окно, на кнопке показывается счетчик выбранных значений.

### Includes (JS/CSS)

**Где настраивается:** API администрирования (includes)
**Таблицы БД:** `dbo.PortalIncludes`, `dbo.PortalBlockIncludes`

Дополнительные JS/CSS файлы, влияющие на рендер и поведение портала или отдельного блока.

### Права просмотра

**Где настраивается:** API администрирования (права просмотра)
**Таблица БД:** `dbo.PortalGridTemplateGroups`

Ограничение видимости портала по группам пользователей.

### Пользовательские переопределения раскладки

**Таблица БД:** `dbo.PortalGridUserTemplates`

Персональные настройки расположения блоков для каждого пользователя. Перезаписывают раскладку по умолчанию.

## Типичные ошибки настройки

Частые проблемы настройки порталов и способы их диагностики:

| Симптом | Причина | Где проверить | SQL-диагностика |
|---------|---------|---------------|-----------------|
| Портал не виден части пользователей | Ограничения по группам | `dbo.PortalGridTemplateGroups` | `select * from dbo.PortalGridTemplateGroups where PortalGridTemplateId = {portalId}` |
| Блок на странице пустой | Некорректный конфиг блока или фильтры | `dbo.PortalGridBlocks`, фильтры | `select * from dbo.PortalGridBlocks where PortalGridTemplateId = {portalId}` |
| Фильтры не влияют на график/таблицу | Блоки не связаны через общий filter-config или рассинхронизированы параметры | Конфиг фильтров блока + набор параметров в фильтре (`filters_spa`) | `select * from dbo.PortalGridBlocksFilters where PortalGridBlockId = {blockId}` |
| Пользователь не видит часть фильтров | Параметр фильтра отмечен как `Всегда свернуто` / `Только если выбрано значение` | Настройки параметров фильтра (`PortalGridFilterParams`) | `select * from dbo.PortalGridFilterParams where PortalGridFilterId = {filterId}` |
| Над виджетом показывается старое название | `Name` блока — это заголовок виджета для пользователей, не внутреннее имя | `POST /api/portals/block/{blockId}/update` с `{"Name":"..."}` | `select Name from dbo.PortalGridBlocks where Id = {blockId}` |
| После изменений интерфейс показывает старое | Кэш в интерфейсе | Фактическое сохранение | `select * from dbo.PortalGridBlocks where Id = {blockId}` |
| Страница ломается после включения include | Ошибка в JS/CSS include | `dbo.PortalIncludes` | `select * from dbo.PortalIncludes where PortalGridTemplateId = {portalId}` |
| Пользовательское переопределение конфликтует с новой раскладкой | Старый `PortalGridUserTemplates` | `dbo.PortalGridUserTemplates` | `select * from dbo.PortalGridUserTemplates where PortalGridTemplateId = {portalId} and UserId = {userId}` |
| При сохранении портала не назначается модуль | В сохраняемой раскладке есть виджет другого модуля | Параметр «Модуль» у виджетов портала в окне настроек виджета и привязка портала к модулю | — |

## Работа с API порталов — ключевые правила

Практические примеры и правила работы с API порталов (создание блоков, Advsets, SmartHtml, серии графика, JS/CSS Includes, типичные ошибки) — в [API Cookbook порталов](https://help.1forma.ru/domains/portal/portal-api-cookbook.md).

## Связанные документы

Смежные разделы:

- [API Cookbook порталов](https://help.1forma.ru/domains/portal/portal-api-cookbook.md) — практический cookbook с полными примерами
- [Дашборды — паттерны настройки](https://help.1forma.ru/domains/portal/academy-dashboards.md) — паттерны настройки дашбордов

## Ряд (spans): контейнер без своей карточки

Ряд — технический контейнер: он занимает место во внешней сетке и раскладывает элементы, но сам ничего не рисует — ни фона, ни рамки, ни скругления. Каждый виджет внутри ряда оформлен так же, как если бы стоял прямо в сетке: у него своя карточка, а если у виджета выбран прозрачный цвет или это виджет навигации — карточки у него нет. Поэтому ряд из трёх счётчиков выглядит как три отдельные карточки, а не как одна общая. Расстояние между виджетами внутри ряда равно зазору сетки, тени крайних виджетов не обрезаются. У вложенного ряда своего оформления нет — карточек ровно столько, сколько виджетов.