Исходник ↗Песочница ↗

AppRoot

Обязательный компонент, в который нужно обернуть всё приложение. В нём инкапсулирована логика:

  • режимов встраивания,
  • управления прокруткой,
  • безопасными отступами,
  • и порталами.

Режимы встраивания

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

  • "full" — ваше приложение полностью реализовано с помощью VKUI;
  • "embedded" — ваше приложение реализовано в виде блока, встроенного в основное приложение (например, Марусю или базовое приложение ВКонтакте);
  • "partial" — ваше приложение реализовано с помощью сторонних решений и использует некоторые компоненты библиотеки VKUI.

В чём главные особенности перечисленных режимов и какой режим выбрать?

Full

Этот режим используется по умолчанию и позволяет VKUI полностью контролировать страницы вашего приложения. Предполагается, что root-элемент (точка монтирования приложения) приложения находится непосредственно внутри <body>. VKUI добавит свои классы на html-элемент и на root-элемент. Рекомендуем использовать его для standalone-проектов или при интеграции с платформой VK Mini Apps.

Embedded

Данный режим позволяет вам подключить VKUI не на всю страницу приложения, а только к определенному контейнеру. В отличие от full режима, VKUI добавит свои классы только на корневой контейнер (.vkui__root и .vkui__root--embedded).

По умолчанию, в режиме embedded система координат элементов с position: fixed переносится на свой контейнер через transform: translate3d(0, 0, 0). Это поведение можно отключить с помощью свойства disableParentTransformForPositionFixedElements.

Partial

Данный режим подходит для случаев, когда вам нужно сверстать небольшой блок, а не страницу целиком. В partial режиме не подразумевается использование компонентов из раздела Layout. VKUI не добавляет никаких классов на html или корневой элемент.

Визуальное оформление

Свойство layout глобально задаёт тип оформления макета для компонентов Panel и Group.

  • "card" — карточный дизайн с тенями и скруглениями;
  • "plain" — плоский дизайн без теней и скруглений.

Управление порталами

VKUI использует порталы ↗ для рендеринга всплывающих элементов (модальные окна, тултипы и т.д.). По умолчанию, они рендерятся в document.body.

С помощью свойства portalRoot можно переопределить элемент, в котором будут рендериться всплывающие элементы. Можно указать конкретный DOM-элемент (полученный, например, через document.getElementById) или ссылку на DOM-элемент (ref-объект).

С помощью свойства disablePortal можно отключить рендер всплывающих элементов в отдельном контейнере - они будут рендериться непосредственно по месту определения.

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

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

  • "global" — VKUI-приложение скроллится вместе со страницей;
  • "contain" — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри AppRoot (например, в модалке).

В режимах full и embedded VKUI управляет полосой прокрутки приложения - например, блокирует скролл при поднятии модального окна или запоминает положение скролла при переходе между панелями (Panel).

В случае scroll="global" положение полосы прокрутки рассчитывается относительно глобальных window/document страницы. В случае scroll="contain" положение полосы прокрутки рассчитывается относительно выбранного корневого элемента, это может быть полезно при использовании mode="embedded".

Безопасные отступы (safe-area-inset-*)

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

Иногда приложению может быть доступна не вся область экрана (например, смартфоны с “чёлкой”). Чтобы части приложения не перекрывали нативные элементы, мы используем стандартные safe-area-inset-*. Подробнее можно ознакомиться в документации ↗.

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

const customSafeAreaInsets = {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}
 
// Переопределяем стандартные отступы
<AppRoot safeAreaInsets={customSafeAreaInsets}>
  <App />
</AppRoot>

Вы можете переопределить только часть отступов (например, только bottom или top), остальные значения будут использовать заданные по умолчанию отступы.

Выделение текста

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

Поскольку VKUI мимикрирует под мобильные платформы, мы по умолчанию запрещаем выделять текст в приложениях, запущенных в webview. Для более гибкой настройки поведения используйте следующие значения:

  • "enabled-with-pointer" – разрешается выделять текст, если устройство ввода типа pointer (например, мышь), в остальных случаях запрещается;
  • "disabled" – запрещается выделять текст;
  • "enabled" – разрешается выделять текст.

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

СвойствоОписание
disableParentTransformForPositionFixedElementsboolean

По умолчанию, mode=“embedded” переносит систему координат элементов с position: fixed на свой контейнер через transform: translate3d(0, 0, 0).

Это поведение можно отключить с помощью этого параметра.

По умолчанию: -
disablePortalboolean

Отключает рендер всплывающих компонентов в отдельном контейнере.

По умолчанию: false
disableSettingVKUIClassesInRuntimeboolean

По умолчанию в режиме mode="full" VKUI в рантайме выставляет:

  • класс .vkui на html элемент
  • класс .vkui__root на элемент-контейнер, в который монтируется VKUI С помощью этой опции такое поведение можно отключить.

Для корректной работы SSR рекоммендуется выставлять эти классы самостоятельно и отключить это поведение.

По умолчанию: -
layoutAppRootLayout

Глобально задаёт тип оформления макета для компонентов Panel ↗ и Group ↗.

По умолчанию: -
modeAppRootMode

Режим встраивания.

По умолчанию: full
portalRootHTMLElement | RefObject<HTMLElement | null> | null

Кастомный root-элемент портала.

По умолчанию: -
safeAreaInsetsSafeAreaInsets

См. Документацию mdn web docs | env#values ↗.

По умолчанию: -
scrollAppRootScroll
  • global (по умолчанию) — VKUI-приложение скроллится вместе со страницей.
  • contain — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри AppRoot (например, в модалке).

Полезно при использовании mode="embedded".

По умолчанию: global
userSelectModeAppRootUserSelectMode

Задаёт режим выбора текста (выделения текста) для всего приложения. По умолчанию, если режим не задан, запрещает выбор текста в приложениях, запущенных в webview (по значению свойства isWebView из ConfigProvider ↗).

  • enabled-with-pointer – разрешает выбор текста, если устройство ввода типа pointer (например, мышь), в остальных случаях запрещает;
  • disabled – запрещает выбор текста;
  • enabled – разрешает выбор текста.
По умолчанию: -
Предыдущая
AdaptivityProvider
Следующая
ColorSchemeProvider