--- description: Обязательный компонент, в который нужно обернуть всё приложение. В нём инкапсулирована логика режимов встраивания, управления прокруткой, безопасными отступами и порталами. tags: provider --- # AppRoot [tag:component] [Обязательный компонент](/overview/install#step4), в который нужно обернуть всё приложение. В нём инкапсулирована логика: - режимов встраивания, - управления прокруткой, - безопасными отступами, - и порталами. ## Режимы встраивания Задаётся свойством `mode`. - `"full"` — ваше приложение полностью реализовано с помощью VKUI; - `"embedded"` — ваше приложение реализовано в виде блока, встроенного в основное приложение (например, Марусю или базовое приложение ВКонтакте); - `"partial"` — ваше приложение реализовано с помощью сторонних решений и использует некоторые компоненты библиотеки VKUI. В чём главные особенности перечисленных режимов и какой режим выбрать? ### Full Этот режим используется по умолчанию и позволяет VKUI полностью контролировать страницы вашего приложения. Предполагается, что `root`-элемент (точка монтирования приложения) приложения находится непосредственно внутри ``. VKUI добавит свои классы на `html`-элемент и на `root`-элемент. Рекомендуем использовать его для `standalone`-проектов или при [интеграции с платформой VK Mini Apps](/integrations/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`](/components/panel) и [`Group`](/components/group). - `"card"` — карточный дизайн с тенями и скруглениями; - `"plain"` — плоский дизайн без теней и скруглений. ## Управление порталами VKUI использует [порталы](https://react.dev/reference/react-dom/createPortal) для рендеринга всплывающих элементов (модальные окна, тултипы и т.д.). По умолчанию, они рендерятся в `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-\*) [#safe-area-insets] Задаётся свойством `safeAreaInsets`. Иногда приложению может быть доступна не вся область экрана (например, смартфоны с "чёлкой"). Чтобы части приложения не перекрывали нативные элементы, мы используем стандартные `safe-area-inset-*`. Подробнее можно ознакомиться в [документации](https://developer.mozilla.org/en-US/docs/Web/CSS/env#safe-area-inset-top). Если вы разрабатываете мини-приложение или встраиваетесь в интерфейс, который требует использования специфичных отступов, то используйте свойство `safeAreaInsets`, которое позволяет переопределять значения по умолчанию: ```jsx const customSafeAreaInsets = { top?: number; right?: number; bottom?: number; left?: number; } // Переопределяем стандартные отступы ``` Вы можете переопределить только часть отступов (например, только `bottom` или `top`), остальные значения будут использовать заданные по умолчанию отступы. ## Выделение текста Задаётся свойством `userSelectMode`. Поскольку VKUI мимикрирует под мобильные платформы, мы по умолчанию запрещаем выделять текст в приложениях, запущенных в `webview`. Для более гибкой настройки поведения используйте следующие значения: - `"enabled-with-pointer"` – разрешается выделять текст, если устройство ввода типа `pointer` (например, мышь), в остальных случаях запрещается; - `"disabled"` – запрещается выделять текст; - `"enabled"` – разрешается выделять текст. ## Свойства и методы [#api] | Свойство | Тип | По умолчанию | Описание | | --- | --- | --- | --- | | `disableParentTransformForPositionFixedElements` | `boolean` | `-` | По умолчанию, mode="embedded" переносит систему координат элементов с `position: fixed` на свой контейнер через `transform: translate3d(0, 0, 0)`. Это поведение можно отключить с помощью этого параметра. | | `disablePortal` | `boolean` | `false` | Отключает рендер всплывающих компонентов в отдельном контейнере. | | `disableSettingVKUIClassesInRuntime` | `boolean` | `-` | По умолчанию в режиме `mode="full"` VKUI в рантайме выставляет: - класс .vkui на html элемент - класс .vkui__root на элемент-контейнер, в который монтируется VKUI С помощью этой опции такое поведение можно отключить. Для корректной работы SSR рекоммендуется выставлять эти классы самостоятельно и отключить это поведение. | | `layout` | `AppRootLayout` | `-` | Глобально задаёт тип оформления макета для компонентов [Panel](https://vkui.io/components/panel) и [Group](https://vkui.io/components/group). | | `mode` | `AppRootMode` | `full` | Режим встраивания. | | `portalRoot` | `HTMLElement \| RefObject \| null` | `-` | Кастомный root-элемент портала. | | `safeAreaInsets` | `SafeAreaInsets` | `-` | См. Документацию [mdn web docs \| env#values](https://developer.mozilla.org/en-US/docs/Web/CSS/env#values). | | `scroll` | `AppRootScroll` | `global` | - `global` (по умолчанию) — VKUI-приложение скроллится вместе со страницей. - `contain` — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри `AppRoot` (например, в модалке). Полезно при использовании `mode="embedded"`. | | `userSelectMode` | `AppRootUserSelectMode` | `-` | Задаёт режим выбора текста (выделения текста) для всего приложения. По умолчанию, если режим не задан, запрещает выбор текста в приложениях, запущенных в webview (по значению свойства `isWebView` из [ConfigProvider](https://vkui.io/components/config-provider)). - `enabled-with-pointer` – разрешает выбор текста, если устройство ввода типа `pointer` (например, `мышь`), в остальных случаях запрещает; - `disabled` – запрещает выбор текста; - `enabled` – разрешает выбор текста. |