Значения как props для контроллеров

Stimulus — это легковесный JavaScript-фреймворк, который расширяет возможности HTML через декларативное связывание данных и поведения. Одной из центральных концепций является использование значений (values), которые позволяют передавать параметры в контроллеры, аналогично props в других фреймворках. Значения делают код контроллеров более гибким, читаемым и переиспользуемым.

Объявление и использование значений

Для начала значения объявляются внутри контроллера с помощью статического свойства values. Это объект, в котором ключи — это имена значений, а значения — их типы:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static values = {
    count: Number,
    name: String,
    visible: Boolean
  }

  connect() {
    console.log(this.countValue);   // Получение значения count
    console.log(this.nameValue);    // Получение значения name
    console.log(this.visibleValue); // Получение значения visible
  }
}

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

  • Каждое значение автоматически создаёт геттер и сеттер с суффиксом Value.
  • Тип значения (Number, String, Boolean, Array, Object) позволяет Stimulus автоматически приводить данные из HTML к нужному типу.
  • Если значение не задано в HTML, оно получает значение по умолчанию для своего типа (0 для Number, "" для String, false для Boolean, [] для Array, {} для Object).

Связывание значений с HTML

Для передачи значений контроллеру используются атрибуты data-<controller>-<value>-value:

<div data-controller="example"
     data-example-count-value="5"
     data-example-name-value="Stimulus"
     data-example-visible-value="true">
</div>

Здесь:

  • data-example-count-value → this.countValue
  • data-example-name-value → this.nameValue
  • data-example-visible-value → this.visibleValue

Stimulus автоматически парсит строки и конвертирует их в нужные типы на основе объявленного в контроллере типа.

Реакция на изменения значений

Stimulus позволяет отслеживать изменения значений через методы с суффиксом ValueChanged. Это полезно для динамических интерфейсов:

countValueChanged(oldValue, newValue) {
  console.log(`Count изменился с ${oldValue} на ${newValue}`);
}

При изменении this.countValue этот метод автоматически вызывается, что позволяет контроллеру реагировать на динамические изменения данных без ручного подписывания на события.

Использование значений для конфигурации компонентов

Значения делают контроллеры полностью настраиваемыми через HTML:

static values = {
  color: String,
  size: Number
}

updateStyle() {
  this.element.style.color = this.colorValue;
  this.element.style.fontSize = `${this.sizeValue}px`;
}
<div data-controller="style"
     data-style-color-value="red"
     data-style-size-value="20">
  Пример текста
</div>

Такой подход позволяет использовать один контроллер для множества элементов с различной конфигурацией без дублирования кода.

Комплексные типы значений

Stimulus поддерживает не только примитивы, но и сложные структуры:

static values = {
  settings: Object,
  tags: Array
}

connect() {
  console.log(this.settingsValue.theme); // доступ к объекту
  console.log(this.tagsValue.join(", ")); // работа с массивом
}

HTML может содержать JSON для сложных значений:

<div data-controller="config"
     data-config-settings-value='{"theme":"dark","layout":"grid"}'
     data-config-tags-value='["news","sports"]'>
</div>

Stimulus автоматически преобразует строки JSON в объекты и массивы, что упрощает передачу сложных конфигураций через HTML.

Преимущества использования значений

  1. Декларативность — параметры контроллера полностью видны в HTML.
  2. Переиспользуемость — один контроллер может управлять множеством элементов с разными настройками.
  3. Безопасное приведение типов — автоматическая конвертация значений снижает ошибки.
  4. Реактивность — методы ValueChanged позволяют реагировать на изменения без лишней логики событий.

Резюме по использованию значений

  • Объявление через static values.
  • Передача через атрибуты data-<controller>-<value>-value.
  • Доступ через this.<name>Value.
  • Реакция на изменение через <name>ValueChanged(oldValue, newValue).
  • Поддержка сложных типов: Object, Array.

Значения делают Stimulus мощным инструментом для создания динамичных интерфейсов, сохраняя простоту и декларативность. Контроллеры становятся конфигурируемыми и легко расширяемыми, что идеально подходит для масштабируемых проектов.

Оглавление