Схема компонента (schema)

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

Определение schema

Schema создаётся внутри объекта компонента в свойстве schema. Простейший пример:

AFRAME.registerComponent('example-component', {
  schema: {
    color: {type: 'string', default: '#FFF'},
    intensity: {type: 'number', default: 1.0},
    active: {type: 'boolean', default: true}
  },

  init: function () {
    console.log(this.data.color, this.data.intensity, this.data.active);
  }
});

Ключевые моменты:

  • type — определяет тип данных: string, number, boolean, vec2, vec3, color, selector, array, map.
  • default — значение по умолчанию, которое используется, если атрибут не задан.
  • this.data — объект, содержащий текущие значения всех полей schema.

Типы данных schema

  1. Примитивные типы

    • string — строка.
    • number — число, поддерживает дробные значения.
    • boolean — логическое значение true/false.

  2. Векторные типы

    • vec2 — двумерный вектор {x, y}.
    • vec3 — трёхмерный вектор {x, y, z}.

  3. Цвет

    • color — строка с цветом в формате HEX (#RRGGBB) или CSS-имя (red).

  4. Селекторы и массивы

    • selector — CSS-селектор для поиска DOM-элемента.
    • array — массив значений одного типа.
    • map — объект с ключами и значениями, определёнными схемой.

Структуры данных и вложенные schema

Schema позволяет создавать сложные структуры с вложенными объектами и массивами. Например, компонент с массивом позиций и цветами:

AFRAME.registerComponent('lights-array', {
  schema: {
    lights: {type: 'array', default: [], parse: function (value) {
      return value.split(',').map(item => {
        const [x, y, z, color] = item.trim().split(' ');
        return {position: {x: +x, y: +y, z: +z}, color: color};
      });
    }}
  },

  init: function () {
    this.data.lights.forEach(light => {
      const entity = document.createElement('a-entity');
      entity.setAttribute('light', {color: light.color, intensity: 1});
      entity.setAttribute('position', light.position);
      this.el.appendChild(entity);
    });
  }
});

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

  • parse позволяет преобразовать строку из HTML-атрибута в объект сложной структуры.
  • Использование массивов и объектов делает компонент гибким для динамического конфигурирования сцены.

Валидация и ограничения

В schema можно добавлять ограничения с помощью ключа oneOf для выбора допустимых значений:

AFRAME.registerComponent('movement', {
  schema: {
    direction: {type: 'string', default: 'forward', oneOf: ['forward', 'backward', 'left', 'right']},
    speed: {type: 'number', default: 1, min: 0, max: 10}
  }
});
  • oneOf — список допустимых значений для строки или числа.
  • min и max — ограничивают числовые значения.

При неверном значении A-Frame использует значение по умолчанию и выводит предупреждение в консоль.

Методы работы с данными schema

Компонент автоматически обновляет this.data при изменении атрибутов. Для реактивного поведения используется метод update:

update: function (oldData) {
  if (oldData.color !== this.data.color) {
    this.el.setAttribute('material', 'color', this.data.color);
  }
}
  • update(oldData) вызывается при инициализации и каждом изменении атрибутов.
  • oldData содержит предыдущие значения schema, что позволяет оптимизировать обновления.

Динамическое изменение и доступ к schema

Schema можно использовать для динамического изменения поведения компонентов через Jav * aScript:

const entity = document.querySelector('#myEntity');
entity.setAttribute('example-component', {color: '#F00', intensity: 2});
console.log(entity.components['example-component'].data);
  • setAttribute автоматически обновляет this.data.
  • components['example-component'].data предоставляет доступ к текущим параметрам компонента.

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

  • Всегда определять default для каждого поля schema.
  • Для сложных объектов использовать parse для корректного преобразования данных.
  • Включать ограничения (oneOf, min, max) для предотвращения некорректных значений.
  • Использовать update для реактивного управления сценой при изменении данных.

Schema является основой конфигурируемых и расширяемых компонентов в A-Frame, позволяя строить гибкую и поддерживаемую архитектуру VR-сцен. Она обеспечивает строгую типизацию, автоматическое управление данными и удобный интерфейс для разработчика и HTML.

Оглавление