DOM Overlay в AR-режиме

В экосистеме WebXR библиотека A-Frame выступает как декларативная надстройка над низкоуровневым API. При работе в AR-режиме A-Frame опирается на возможности WebXR Device API и браузерную реализацию дополнений, в частности механизма DOM Overlay.

DOM Overlay — это расширение WebXR, позволяющее отображать обычные HTML-элементы поверх AR-сцены. В отличие от 3D-объектов внутри <a-scene>, такие элементы рендерятся стандартным движком браузера и остаются частью классического DOM.

В A-Frame AR-функциональность чаще всего используется совместно с:

  • A-Frame
  • AR.js
  • Three.js
  • WebXR

DOM Overlay относится именно к WebXR и поддерживается браузерами, реализующими соответствующее расширение.

Проблема пользовательского интерфейса в AR

В классическом VR-интерфейсе элементы управления часто создаются как 3D-объекты: кнопки, панели, текстовые блоки. Однако в AR такой подход имеет ограничения:

  • сложность реализации привычных UI-компонентов;
  • проблемы с вводом текста;
  • необходимость эмуляции кликов через raycasting;
  • отсутствие нативной интеграции с HTML-формами.

DOM Overlay решает эти проблемы, позволяя:

  • использовать стандартные HTML-формы;
  • применять CSS-анимации;
  • подключать UI-фреймворки (React, Vue и др.);
  • обрабатывать события click, input, submit без 3D-прослоек.

Принцип работы DOM Overlay

DOM Overlay активируется при создании XR-сессии с указанием специальной опции:

navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["dom-overlay"],
  domOverlay: { root: document.getElementById("overlay") }
});

Ключевые параметры:

  • requiredFeatures: ["dom-overlay"] — обязательное указание поддержки расширения;
  • domOverlay.root — DOM-элемент, который будет отображаться поверх AR-сцены.

В A-Frame управление XR-сессией происходит через системный компонент webxr внутри <a-scene>.

Подключение DOM Overlay в A-Frame

В A-Frame активация осуществляется через атрибут webxr:

<a-scene
  webxr="requiredFeatures: dom-overlay;
         overlayElement: #overlay">
</a-scene>

Параметры:

  • requiredFeatures: dom-overlay
  • overlayElement: #overlay — CSS-селектор корневого элемента

HTML-структура:

<div id="overlay">
  <button id="infoBtn">Информация</button>
</div>

<a-scene webxr="requiredFeatures: dom-overlay; overlayElement: #overlay">
  <a-box position="0 0 -1"></a-box>
</a-scene>

После входа в AR-сессию кнопка останется поверх камеры, но будет частью XR-интерфейса.

Жизненный цикл DOM Overlay

1. До запуска AR

Элемент overlay находится в обычном DOM и ведёт себя как стандартный HTML-блок.

2. Во время AR-сессии

  • элемент закрепляется поверх XR-контента;
  • браузер ограничивает взаимодействие за пределами root-элемента;
  • система управления фокусом передаётся WebXR.

3. После выхода из AR

DOM возвращается в стандартный режим отображения.

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

DOM Overlay не требует A-Frame-компонентов для базового взаимодействия:

document.getElementById("infoBtn")
  .addEventListener("click", () => {
    console.log("Кнопка нажата");
  });

События работают нативно:

  • click
  • input
  • change
  • submit
  • keydown

Это принципиальное отличие от 3D UI внутри сцены, где используются cursor и raycaster.

Стилизация интерфейса

Поскольку элементы остаются HTML-узлами, используется стандартный CSS:

#overlay {
  position: fixed;
  bottom: 20px;
  width: 100%;
  text-align: center;
}

button {
  padding: 12px 20px;
  font-size: 18px;
}

Особенности:

  • допустимы медиазапросы;
  • возможны flexbox и grid;
  • поддерживаются анимации transition и animation.

Однако следует учитывать:

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

Взаимодействие DOM и 3D-сцены

Часто требуется синхронизация DOM Overlay с объектами сцены A-Frame.

Пример: переключение видимости 3D-объекта через кнопку.

const box = document.querySelector("a-box");

document.getElementById("infoBtn")
  .addEventListener("click", () => {
    box.setAttribute("visible", false);
  });

DOM-элемент управляет 3D-логикой через стандартные методы A-Frame:

  • setAttribute
  • getAttribute
  • emit
  • addEventListener

Ограничения DOM Overlay

  1. Поддержка браузеров Реализовано не во всех мобильных браузерах.

  2. Один root-элемент Можно указать только один корневой контейнер.

  3. Отсутствие глубины DOM Overlay всегда поверх AR-контента, без возможности частичного перекрытия 3D-объектами.

  4. Производительность Сложные UI-интерфейсы могут влиять на частоту кадров AR-сессии.

Сравнение: 3D UI vs DOM Overlay

Критерий 3D UI DOM Overlay
Рендеринг WebGL HTML/CSS
Ввод текста Сложный Нативный
Анимации Через компоненты Через CSS
Производительность Зависит от сцены Зависит от DOM
Глубина 3D-пространство Поверх сцены

3D UI подходит для иммерсивных панелей, встроенных в мир. DOM Overlay — для системных кнопок, форм и вспомогательных элементов.

Интеграция с внешними фреймворками

Поскольку overlay — это обычный DOM, возможна интеграция с:

  • React
  • Vue
  • Angular

A-Frame остаётся ответственным за 3D-сцену, а фреймворк — за интерфейс.

Архитектурно это разделяет:

  • XR-рендеринг
  • бизнес-логику
  • UI-слой

Доступ к XR-событиям

Иногда требуется реагировать на начало AR-сессии:

const scene = document.querySelector("a-scene");

scene.addEventListener("enter-vr", () => {
  console.log("AR/VR сессия начата");
});

scene.addEventListener("exit-vr", () => {
  console.log("Сессия завершена");
});

В AR-режиме события enter-vr используются аналогично VR, поскольку A-Frame унифицирует обработку XR-сессий.

Безопасность и UX-аспекты

Браузер накладывает ограничения:

  • AR-сессия требует пользовательского действия;
  • DOM Overlay не может перекрывать системные уведомления;
  • запрещены модальные окна alert() во время XR-сессии в некоторых реализациях.

Рекомендуется:

  • избегать всплывающих окон;
  • использовать компактный UI;
  • минимизировать перекрытие камеры.

Практические сценарии применения

  1. Панель управления AR-навигацией.
  2. Кнопки смены режима отображения.
  3. Формы ввода параметров.
  4. Информационные карточки.
  5. Меню выхода из AR.

DOM Overlay особенно эффективен в мобильных AR-приложениях, где пользователю требуется привычный интерфейс поверх изображения камеры.

Расширенная архитектурная схема

Типичная структура проекта:

index.html
├── <div id="overlay">
│     └── UI-компоненты
└── <a-scene webxr="...">
      └── 3D-объекты

Разделение ответственности:

  • HTML + CSS — пользовательский интерфейс;
  • JavaScript — связь между DOM и A-Frame;
  • A-Frame — XR-рендеринг и управление сценой;
  • WebXR — доступ к AR-устройствам.

Такой подход формирует гибридную модель разработки, где WebGL и традиционный DOM сосуществуют в рамках одной XR-сессии.

Оглавление