Типы значений и их валидация

Stimulus использует концепцию значений контроллера для передачи данных из HTML в JavaScript. Значения позволяют декларативно связывать атрибуты DOM с переменными контроллера, а также обеспечивают автоматическое управление типами и возможность их валидации.

Определение значений

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

  • String
  • Number
  • Boolean
  • Array
  • Object

Пример объявления значений:

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

export default class extends Controller {
  static values = {
    count: Number,
    name: String,
    active: Boolean,
    items: Array,
    config: Object
  }
}

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

Для связывания значений используется синтаксис атрибутов data-<имя-контроллера>-<имя-значения>-value. Например:

<div 
  data-controller="example" 
  data-example-count-value="42" 
  data-example-name-value="Stimulus" 
  data-example-active-value="true" 
  data-example-items-value='["a","b","c"]' 
  data-example-config-value='{"theme":"dark"}'>
</div>

Stimulus автоматически конвертирует строки из HTML в соответствующие типы значений. Если тип значения Number, строка "42" будет преобразована в число 42; для Boolean "true" или "false" — в логическое значение; для Array и Object используется парсинг JSON.

Доступ к значениям в контроллере

После объявления значений их можно использовать внутри контроллера через свойства с суффиксом Value. Для каждого значения автоматически создаются следующие свойства и методы:

  • <имя>Value — текущее значение
  • <имя>ValueChanged — вызывается при изменении значения
  • <имя>Value с get и set — возможность программно получить или установить значение

Пример использования:

connect() {
  console.log(this.countValue); // 42
  console.log(this.activeValue); // true

  this.nameValue = "Updated";
}

Валидация типов

Stimulus выполняет автоматическую валидацию значений при инициализации. Если значение не соответствует объявленному типу, выбрасывается ошибка:

data-example-count-value="not-a-number"

В этом случае при подключении контроллера будет ошибка:

Uncaught TypeError: `not-a-number` is not a valid Number value

Для сложных сценариев можно использовать кастомные методы проверки внутри контроллера через connect или valueChanged:

countValueChanged(newValue, oldValue) {
  if (newValue < 0) {
    console.warn("countValue не может быть отрицательным");
    this.countValue = 0;
  }
}

Динамическое изменение значений

Значения можно менять не только через свойства контроллера, но и через DOM. Stimulus отслеживает изменения атрибутов data-*-value и автоматически обновляет свойства:

document.querySelector('[data-controller="example"]').dataset.exampleCountValue = "100";

После этого сработает соответствующий метод countValueChanged с новым значением 100.

Расширение типов

Хотя Stimulus предоставляет стандартные типы, можно создавать собственные методы парсинга, если требуется поддержка специфических форматов данных. Для этого обычно используют вспомогательные функции при установке значения:

set dateValue(val) {
  this._dateValue = new Date(val);
}

get dateValue() {
  return this._dateValue;
}

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

  • Использовать встроенные типы для простых данных: числа, строки, булевы значения.
  • Для сложных структур — массивы и объекты через JSON.
  • Всегда проверять корректность данных при изменении значений динамически.
  • Использовать методы <имя>ValueChanged для валидации и реакции на изменения.

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

Оглавление