ActionSheet

При использовании данного компонента отталкивайтесь от контекста и количества действий. Использование ActionSheet хорошо подходит для отображения вариантов в ответ на осознанное действие. Например, при отмене редактирования электронного письма среди доступных вариантов могут быть такие действия как “Удалить изменения”, “Сохранить черновик” и “Вернуть к редактированию”.

Обязательные свойства

onClose

Свойство onClose принимает функцию, которая вызовется после завершения анимации закрытия компонента. Обязательно удаляйте из DOM-дерева компонент ActionSheet в обработчике onClose, иначе в верстке останется прозрачный элемент, который будет мешать дальнейшему взаимодействию с элементами и повторному открытию компонента.

Функция принимает объект с информацией о причине закрытия:

function handleClose({ closedBy }) {
  if (closedBy === 'action-item') {
    // закрытие произошло по выбору действия из списка
  } else if (closedBy === 'cancel-item') {
    // закрытие произошло по нажатию на кнопку отмены
  } else if (closedBy === 'cancel-item') {
    // закрытие произошло по другим причинам (например, клик вне области всплывающего окна)
  }
}

toggleRef (якорный элемент)

В данное свойство следует передавать элемент, относительно которого будет позиционироваться компонент в mode="menu" (учитывая автоматическое определение режима). В качестве значения лучше передавать ref-объект ↗.

Режимы отображения

Задаётся свойством mode. По умолчанию отображение определяется в зависимости от размеров экрана.

• "sheet" — отображение снизу экрана в виде всплывающего окна (по умолчанию для мобильных устройств)
• "menu" — отображение в виде всплывающего элемента относительно якорного элемента (по умолчанию для десктопа)

Шапка

В компоненте есть возможность задать заголовок и описание для списка с помощью свойств title и description соответственно.

<ActionSheet title="Выберите действие" description="Это описание для списка действий">
  <ActionSheetItem>Действие 1</ActionSheetItem>
  <ActionSheetItem>Действие 2</ActionSheetItem>
  <ActionSheetItem>Действие 3</ActionSheetItem>
</ActionSheet>

Позиционирование

placement

Свойство placement отвечает за направление положения относительно якорного элемента. Оно поддерживается только для mode="menu" (учитывая автоматическое определение режима).

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

В качестве вариантов положения ориентируйтесь на значения из библиотеки floating-ui ↗.

popupOffsetDistance

Свойство popupOffsetDistance позволяет задать отступ (в пикселях) от якорного элемента.

Браузерные события

Click Event

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

Управление фокусом

autoFocus

Данное свойство позволяет автоматически устанавливать фокус на первом интерактивном элементе при открытии всплывающего элемента. По умолчанию это поведение включено, но можно его отключить, передав autoFocus={false}.

Также есть возможность установить фокус на контейнере всплывающего меню, передав autoFocus="root". Это может быть полезно, когда первый интерактивный элемент имеет подсказку, которая активируется при фокусе. В таком случае появление подсказки сразу после открытия всплывающего меню может быть нежелательным. Значение "root" позволяет поддержать данный сценарий, не ломая доступность.

restoreFocus

Данное свойство позволяет восстанавливать фокус после закрытия всплывающего меню на последний активный элемент. По умолчанию данное поведение включено, но можно его отключить, передав restoreFocus={false}.

Также есть возможность передать в restoreFocus функцию, которая возвращает HTMLElement или boolean. Если возвращается HTMLElement, то фокус будет возвращен на этот элемент, при false — фокус не восстанавливается, при true — поведение по умолчанию.

timeout

Свойство позволяет задать задержку (в миллисекундах) при установке и восстановлении фокуса.

Кнопка “Отмена”

Согласно рекомендациям Apple в ActionSheet должен быть вариант действия “Отмена”, который бы позволял закрывать всплывающее окно без выполнения дополнительных действий.

Используя свойство iosCloseItem, можно передать свой вариант элемента “Отмена”, по умолчанию используется компонент ActionSheetDefaultIosCloseItem.

import { ActionSheet, ActionSheetDefaultIosCloseItem } from '@vkontakte/vkui';
 
<ActionSheet
  iosCloseItem={<ActionSheetDefaultIosCloseItem>{cancelLabel}</ActionSheetDefaultIosCloseItem>}
>
  {/* ActionSheetItem */}
  {/* ActionSheetItem */}
  {/* ActionSheetItem */}
</ActionSheet>;

ActionSheetItem

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

Цвет

Задаётся свойством mode.

"default"

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

"destructive"

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

"cancel"

Цвет действия отмены.

Кнопка “Отмена”

Свойство isCancelItem позволяет пометить пункт действия как “Отмена”.

Согласно рекомендациям Apple в ActionSheet должен быть вариант действия “Отмена”, который бы позволял закрывать всплывающее окно без выполнения дополнительных действий.

Подробнее с использованием можно ознакомиться на странице ActionSheet.

Текстовые элементы

Основной контент компонента (заголовок) можно задать, передав в свойство children необходимый текст:

Свойство subtitle позволяет отобразить дополнительный текст под заголовком:

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

Многострочный режим

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

Контент в начале/в конце

В компоненте доступна возможность добавления дополнительного контента слева и/или справа от текста, задаётся свойством before и after соответственно. Наиболее частый вариант использования свойств before/after - иконки или аватары.

В соответствии с рекомендациями дизайн-системы, для десктопного представления (compact-режим) следует использовать иконки размером 20px, для мобильного представления (regular-режим) — 28px. Проще всего это сделать, используя компонент AdaptiveIconRenderer.

Состояния

disabled

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

selectable

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

• name — имя группы для радиокнопок;
• value — значение радиокнопки;
• defaultChecked — установить выбранным по умолчанию;
• checked и onChange — для контролируемого извне использования выбранного значения;

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

Обработчики событий

onClick/ onImmediateClick

Нажатие на пункт меню можно обработать с помощью свойств onClick и onImmediateClick.

По умолчанию onClick будет вызван после завершения анимации скрытия всплывающего меню и после вызова onClose. Из этого следует, что в объекте события значение поля currentTarget будет не определено. Если вам нужен объект события именно на момент нажатия, воспользуйтесь onImmediateClick.

onChange

Если задано свойство selectable={true}, то выбор пункта следует обрабатывать с помощью свойства onChange. Пример можно увидеть выше.

Ссылки

Если указать свойство href, компонент будет рендериться как ссылка <a>. Также можно задать стандартное свойство target:

<ActionSheetItem href="https://vk.com" target="_blank">
  Перейти на vk.com
</ActionSheetItem>

Доступность (a11y)

• у ActionSheet уже заданы атрибуты role="dialog" и aria-modal="true", потому что по умолчанию он появляется как диалог и, пока он не закроется, нельзя взаимодействовать с другими элементами на странице. Эти атрибуты можно переопределить, явно передавая их компоненту;
• у целевого элемента обязательно должен быть выставлен атрибут aria-expanded.
• при задании параметра selectable={true} для корректной работы важно задать всем ActionSheetItem одинаковое значение параметра name. Обусловлено это тем, что в реализации используется нативный input[type='radio'] и по пунктам можно навигировать как по обычным radio-кнопкам;
• при задании selectable={true} в реализации используется тег "label". В остальных случаях используется тег "div".

Свойства и методы