AFRAME.registerPrimitive: структура и параметры

В A-Frame AFRAME.registerPrimitive используется для создания собственных HTML-примитивов на основе компонентов. Это позволяет разработчику создавать новые теги, которые инкапсулируют набор стандартных компонентов и их конфигураций, упрощая повторное использование и управление сценой.

Синтаксис функции выглядит следующим образом:

AFRAME.registerPrimitive('имя-тега', {
  defaultComponents: {},
  mappings: {}
});
  • имя-тега — строка, задающая имя нового HTML-элемента, которое будет использоваться в сцене A-Frame. Должно начинаться с буквы и содержать только строчные латинские буквы и дефисы.
  • defaultComponents — объект, задающий компоненты, которые будут автоматически применены к примитиву при его создании.
  • mappings — объект, связывающий атрибуты HTML-тега с параметрами компонентов, позволяя настраивать поведение примитива через HTML.

defaultComponents

defaultComponents определяет набор компонентов, которые будут включены в примитив по умолчанию. Каждый ключ объекта — это имя компонента, значение — его конфигурация.

Пример:

AFRAME.registerPrimitive('my-box', {
  defaultComponents: {
    geometry: { primitive: 'box', width: 1, height: 1, depth: 1 },
    material: { color: 'red' }
  }
});

В этом примере создается тег <my-box> с коробкой красного цвета и стандартными размерами.

Особенности использования defaultComponents:

  • Компоненты можно комбинировать. Например, добавление position или rotation задает начальное положение и ориентацию объекта.
  • Значения могут быть простыми (строки, числа) или объектами с набором параметров, что обеспечивает гибкость конфигурации.
  • Если компонент уже указан при использовании примитива в HTML, он переопределяет значение из defaultComponents.

mappings

mappings позволяет связывать HTML-атрибуты нового тега с конкретными свойствами компонентов. Это делает примитив настраиваемым через обычные HTML-атрибуты.

Пример:

AFRAME.registerPrimitive('my-sphere', {
  defaultComponents: {
    geometry: { primitive: 'sphere', radius: 1 },
    material: { color: 'blue' }
  },
  mappings: {
    color: 'material.color',
    radius: 'geometry.radius'
  }
});

Использование в сцене:

<my-sphere color="green" radius="2"></my-sphere>

В этом случае сферу создадут зеленого цвета с радиусом 2, переопределив значения по умолчанию.

Принципы работы mappings:

  • Путь к свойству компонента записывается через точку: componentName.propertyName.
  • Можно указывать несколько атрибутов, чтобы управлять разными компонентами одновременно.
  • Если в defaultComponents не задано свойство, оно все равно может быть установлено через mappings.

Совмещение defaultComponents и mappings

Часто используется комбинация: defaultComponents задает базовую конфигурацию, а mappings обеспечивает гибкость. Это позволяет создавать повторно используемые теги с настраиваемыми свойствами, сохраняя читаемость HTML-кода.

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

AFRAME.registerPrimitive('interactive-box', {
  defaultComponents: {
    geometry: { primitive: 'box', width: 1, height: 1, depth: 1 },
    material: { color: 'yellow' },
    position: { x: 0, y: 1, z: -3 },
    'animation__rotate': { property: 'rotation', to: '0 360 0', loop: true, dur: 5000 }
  },
  mappings: {
    color: 'material.color',
    width: 'geometry.width',
    height: 'geometry.height',
    depth: 'geometry.depth',
    posX: 'position.x',
    posY: 'position.y',
    posZ: 'position.z'
  }
});

HTML:

<interactive-box color="orange" width="2" posY="2"></interactive-box>

В результате будет создана оранжевая коробка размером 2 по ширине, расположенная на высоте Y=2, с анимацией вращения.

Важные рекомендации по использованию

  1. Именование тегов: новые примитивы должны начинаться с префикса, например my- или custom-, чтобы избежать конфликтов с встроенными тегами A-Frame.
  2. Минимизация повторов: для объектов с повторяющимися компонентами лучше создавать примитивы вместо копирования <a-entity> с одинаковыми настройками.
  3. Сложные компоненты: для компонентов с вложенными объектами в defaultComponents использовать полные структуры данных, чтобы корректно применялись значения по умолчанию.
  4. Совместимость: примитивы совместимы со всеми стандартными системами A-Frame, включая animation, event-set и пользовательские компоненты.

AFRAME.registerPrimitive — мощный инструмент для создания структурированных и настраиваемых объектов, повышающий удобство работы с A-Frame, позволяющий выносить повторяющиеся шаблоны в отдельные элементы и упрощать взаимодействие с HTML-сценой.

Оглавление