Компонент embedded для встраивания в страницу

Компонент embedded в библиотеке A-Frame предназначен для интеграции 3D/VR-сцены в структуру обычной HTML-страницы без перехода в полноэкранный режим. По умолчанию элемент <a-scene> ведёт себя как самостоятельное полноэкранное приложение: занимает всё окно браузера, управляет стилями документа и перехватывает ввод. Атрибут embedded изменяет эту модель, превращая сцену в обычный блочный элемент, который можно размещать внутри любой разметки.

Это особенно важно при создании:

  • интерактивных лендингов,
  • обучающих порталов,
  • статей с 3D-иллюстрациями,
  • интерфейсов, где WebVR/WebXR является частью общего UI.

Базовый синтаксис

Компонент подключается непосредственно к элементу <a-scene>:

<a-scene embedded>
  <a-box position="0 1 -3" color="#4CC3D9"></a-box>
  <a-sky color="#ECECEC"></a-sky>
</a-scene>

В таком режиме сцена:

  • не переходит автоматически в полноэкранный режим,
  • не растягивается на весь экран,
  • подчиняется CSS-разметке страницы,
  • ведёт себя как обычный HTML-элемент.

Поведение сцены без embedded

Без указания embedded сцена в A-Frame:

  • устанавливает position: fixed,
  • занимает 100% ширины и высоты окна,
  • скрывает прокрутку документа,
  • становится корневым визуальным контейнером приложения.

Это удобно для полноценных VR-приложений, но мешает интеграции в сложную веб-страницу.

Как работает embedded внутри DOM

При добавлении embedded:

  • сцена становится позиционируемой в потоке документа,
  • высота и ширина задаются через CSS,
  • не отключается прокрутка страницы,
  • можно размещать другие HTML-элементы до и после сцены.

Пример встраивания в структуру страницы:

<section>
  <h2>3D-демонстрация</h2>

  <div class="scene-container">
    <a-scene embedded>
      <a-sphere position="0 1.5 -3" radius="1.25" color="#EF2D5E"></a-sphere>
      <a-plane position="0 0 -4" rotation="-90 0 0"
               width="4" height="4"
               color="#7BC8A4"></a-plane>
    </a-scene>
  </div>

  <p>Дополнительный текст после сцены.</p>
</section>

Управление размерами сцены

В режиме embedded размеры сцены полностью контролируются через CSS:

.scene-container {
  width: 600px;
  height: 400px;
}

a-scene {
  width: 100%;
  height: 100%;
}

Важные особенности

  • Если высота не задана, сцена может получить нулевую высоту.
  • Процентные значения работают только при наличии высоты у родительского элемента.
  • Поддерживается адаптивная верстка через vw, vh, flexbox и grid.

Пример адаптивного блока:

.scene-container {
  width: 100%;
  max-width: 800px;
  aspect-ratio: 16 / 9;
}

Взаимодействие с камерой и режимом VR

Компонент embedded не отключает поддержку VR или WebXR. Он лишь изменяет начальное поведение сцены.

Кнопка перехода в VR по-прежнему доступна, если:

  • подключён WebXR,
  • устройство поддерживает VR,
  • активирована соответствующая конфигурация.

Сцену можно дополнительно настроить:

<a-scene embedded vr-mode-ui="enabled: true">

При этом:

  • стандартный режим просмотра остаётся встроенным,
  • при входе в VR происходит переход в полноэкранный режим устройства.

Взаимодействие с CSS и слоями

Поскольку сцена становится обычным DOM-элементом, появляется возможность:

  • накладывать поверх неё HTML-элементы,
  • использовать z-index,
  • применять тени, рамки, фильтры,
  • управлять позиционированием.

Пример наложения интерфейса:

<div class="scene-wrapper">
  <a-scene embedded></a-scene>
  <div class="overlay">Информация поверх сцены</div>
</div>
.scene-wrapper {
  position: relative;
}

.overlay {
  position: absolute;
  top: 10px;
  left: 10px;
  background: white;
  padding: 10px;
}

Такой подход позволяет комбинировать 3D-контент с традиционными UI-элементами.

Производительность и ограничения

Встроенный режим имеет ряд особенностей:

1. Ограничение размеров

Большая сцена внутри страницы может вызывать:

  • высокую нагрузку на GPU,
  • снижение FPS при прокрутке,
  • увеличение потребления памяти.

2. Поведение при прокрутке

Если сцена находится вне зоны видимости:

  • рендеринг продолжается,
  • анимации не останавливаются автоматически.

Для оптимизации используется:

document.querySelector('a-scene').pause();
document.querySelector('a-scene').play();

Это позволяет управлять жизненным циклом сцены вручную.

Интеграция с другими библиотеками

Компонент embedded облегчает совместное использование с:

  • фреймворками интерфейсов (React, Vue),
  • системами управления состоянием,
  • обычными DOM-скриптами,
  • библиотеками анимации.

Поскольку сцена остаётся частью DOM-дерева, её можно:

  • динамически создавать,
  • удалять,
  • скрывать через display: none,
  • перемещать внутри страницы.

Работа с несколькими встроенными сценами

В одном документе возможно размещение нескольких сцен:

<a-scene embedded class="mini-scene"></a-scene>
<a-scene embedded class="mini-scene"></a-scene>

При этом следует учитывать:

  • каждая сцена создаёт собственный WebGL-контекст,
  • браузер ограничивает количество активных контекстов,
  • чрезмерное количество сцен может привести к ошибкам и потере рендеринга.

Оптимальной практикой считается:

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

Влияние на пользовательский ввод

В режиме embedded:

  • мышь и тач-события обрабатываются только внутри границ сцены,
  • остальная часть страницы сохраняет стандартное поведение,
  • прокрутка документа работает корректно.

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

Сочетание с атрибутами сцены

Компонент embedded можно комбинировать с другими параметрами <a-scene>:

<a-scene
  embedded
  renderer="antialias: true"
  background="color: #222"
  device-orientation-permission-ui="enabled: false">
</a-scene>

Он не конфликтует с:

  • настройками рендерера,
  • освещением,
  • системой компонентов,
  • пользовательскими компонентами.

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

Интерактивные иллюстрации

3D-модель встроена между текстовыми блоками статьи и реагирует на действия пользователя.

Конфигураторы товаров

Сцена размещается рядом с формами выбора характеристик и обновляется при изменении параметров.

Образовательные модули

Несколько встроенных сцен демонстрируют разные этапы процесса без перезагрузки страницы.

Внутренняя архитектура

Компонент embedded реализован как логическая настройка сцены. Он:

  • изменяет CSS-классы,
  • отключает принудительное полноэкранное позиционирование,
  • корректирует обработку resize-событий.

Фактически это модификация поведения корневого контейнера <a-scene>, а не отдельная визуальная сущность внутри сцены.

Отладка встроенной сцены

Типичные проблемы:

Сцена не отображается

Причина: не задана высота контейнера.

Сцена перекрывает другие элементы

Причина: неправильное позиционирование или z-index.

Появляются чёрные полосы

Причина: несоответствие пропорций камеры и CSS-контейнера.

Проверка выполняется через инструменты разработчика браузера: анализ размеров элемента <canvas>, создаваемого внутри <a-scene>.

Ключевые свойства компонента

  • Применяется только к <a-scene>.
  • Не требует значений (булевый атрибут).
  • Совместим со всеми стандартными компонентами.
  • Управляет поведением сцены на уровне документа.

Компонент embedded является основным механизмом интеграции 3D-контента на основе A-Frame в традиционные веб-страницы, позволяя строить гибридные интерфейсы, сочетающие HTML, CSS и WebGL-графику в едином документе.

Оглавление