Сайдпанель — это окно, которое выезжает из-за границы экрана и располагается поверх основного контента страницы.

Когда использовать

Сайдпанель похожа на модальное окно. Она хорошо подходит, когда нужно показать большое количество данных.

Структура компонента

• Заголовок (шапка)
• Кнопка «Закрыть» (крестик)
• Тело. Может содержать текст, элементы управления и поля ввода
• Футер с терминальными кнопками

Описание работы

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

Модальный режим (с блокировкой страницы)

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

Сайдпанель закрывается только кликом левой кнопкой мыши: правая и средняя вызывают контекстное меню браузера или его собственные действия и панель не трогают. Модальное окно ведёт себя так же.

Запрет закрытия по клику на подложку

Параметр disableClose в KbqSidepanelConfig запрещает закрытие сайдпанели по клику на подложку или нажатию Escape. Это полезно, когда пользователь должен явно подтвердить или закрыть сайдпанель действием внутри неё, например, чтобы не потерять несохранённые изменения.

Немодальный режим (без блокировки страницы)

Сайдпанель при появлении выезжает из-за границы экрана, при этом основной экран не затемняется и со всеми элементами на нем можно взаимодействовать.

Друг над другом

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

Использовать этот режим нужно тогда, когда вы хотите сделать переходы внутри сайдпанели.

Клик на вертикальную область, оставшуюся от нижней панели, закрывает одну верхнюю.

Отличия режимов

Фокус и работа с клавиатурой

При открытой модальной сайдпанели фокус перемещается только по элементам внутри окна, включая крестик и кнопки в футере, и не выходит за его пределы. Немодальная сайдпанель оставляет страницу за собой интерактивной и поэтому фокус не удерживает; если ловушка фокуса нужна и в немодальном режиме, задайте trapFocus: true в KbqSidepanelConfig.

Фокус при открытой сайдпанели

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

• Фокус устанавливается на первый доступный элемент внутри тела сайдпанели, если нет особых предписаний
• Если в сайдпанели есть форма, то нужно ставить фокус в первое поле ввода
• Если сайдпанель содержит важное необратимое действие, то лучше поставить фокус на другое, менее деструктивное
• Если в сайдпанели есть только терминальные кнопки, то будет полезно поставить фокус на кнопку, которую пользователь вероятнее всего нажмет («OK» или «Отмена», в зависимости от ситуации)
• Если внутри модального окна много контента, есть прокрутка, то установка фокуса на первый доступный элемент может автоматически промотать содержимое окна и убрать его начальные части из поля зрения. В этому случае надо добавить статическому элементу, расположенному в начале контента (заголовку, первому абзацу), атрибут tabindex=-1 и установить фокус на нем.

Фокус после закрытия сайдпанели

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

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

Управление с клавиатуры

Компонент сам обрабатывает только Esc. Остальные две строки — рекомендация для содержимого сайдпанели: повесьте эти сочетания на свою форму или кнопки в футере.

Ограничения верстки

Открытая сайдпанель — это position: fixed с постоянным transform (именно он и обеспечивает выезд), поэтому она становится содержащим блоком для всех потомков с position: fixed. Все, что внутри панели ожидает привязки к границам вьюпорта, привяжется к самой панели. Для декоративных элементов внутри сайдпанели используйте position: absolute или position: sticky, а настоящие оверлеи выводите через контейнер оверлеев CDK.

Сохранение состояния

Сайдпанель может запомнить, была ли она открыта, и вернуться после перезагрузки страницы. Чтобы это включить, передайте stateSavingKey в KbqSidepanelConfig; без ключа не сохраняется ничего.

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

private readonly sidepanel = inject(KbqSidepanelService);
 
constructor() {
    afterNextRender(() => {
        if (this.sidepanel.wasOpen('filters')) this.openFilters();
    });
}
 
protected openFilters(): void {
    this.sidepanel.open(this.filters(), { stateSavingKey: 'filters', hasBackdrop: false });
}

Записывается закрытие панели по её собственному поводу — крестиком, кликом по подложке, по Escape или через KbqSidepanelRef.close(). closeAll() и уничтожение сервиса флаг не трогают, поэтому открытая панель возвращается. Давайте каждой панели свой ключ, а забыть сохранённое — clearSavedState(key).

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

Ключи, хранилище и срок жизни записи одинаковы у всех компонентов, которые сохраняются, — см. Сохранение состояния компонентов.

Дизайн и анимация

Размер

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

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

При выборе размера сайдпанели обратите внимания на эти моменты:

• Размер содержимого. Слишком большая или недостаточная ширина панели выглядят плохо.
• Сетка страницы. Хорошо, когда сайдпанель на странице смотрится пропорционально и соответствует каким-то другим блокам. Удачные пропорции для сайдпанели: 1/4, 1/3, 1/2, 2/3, 3/4 основного окна.
• Сценарии использования. Если немодальная панель используется для просмотра какого-то объекта из списка, то лучше, чтобы она не закрывала список целиком: сохранится возможность быстрого переключения между объектами. Если немодальная панель используется для организации параллельных рабочих областей, проверьте, что области не мешают друг другу и основному сценарию работы.
• Унификация. Продукт будет выглядеть аккуратней и целостней, если в нем не будет большого количества сайдпанелей разной ширины. Лучше, если размер будет один, максимум два.