Преобразование типов данных

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

Атрибуты data-* и их типизация

В HTML любые data-* атрибуты передаются как строки. Например:

<div data-controller="example" data-example-count="42" data-example-active="true"></div>

Здесь data-example-count и data-example-active на уровне DOM являются строками "42" и "true". При получении их в контроллере Stimulus необходимо преобразовывать значения к соответствующим типам, иначе логика приложения будет некорректной.

Декларация значений в Stimulus

Stimulus поддерживает систему значений (values), которая позволяет автоматически преобразовывать данные из data-* атрибутов в нужный тип. Для этого в контроллере объявляются свойства с указанием типа:

import { Controller } from "@hotwired/stimulus"

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

  connect() {
    console.log(this.countValue)  // число
    console.log(this.activeValue) // булево значение
    console.log(this.nameValue)   // строка
    console.log(this.settingsValue) // объект
  }
}
Поддерживаемые типы
  • String — преобразует любое значение в строку.
  • Number — строка "42" преобразуется в число 42.
  • Boolean — строка "true" или "false" преобразуется в булево значение.
  • Object — JSON-строка автоматически парсится в объект.
  • Array — JSON-строка с массивом преобразуется в JavaScript-массив.

Пример с массивом и объектом:

<div 
  data-controller="example"
  data-example-items-value='["apple","banana"]'
  data-example-config-value='{"theme":"dark"}'>
</div>
static values = {
  items: Array,
  config: Object
}

connect() {
  console.log(this.itemsValue)  // ["apple", "banana"]
  console.log(this.configValue) // { theme: "dark" }
}

Встроенные методы для проверки типов

Stimulus автоматически добавляет методы проверки наличия значения:

  • hasCountValue() — возвращает true, если атрибут data-example-count-value задан.
  • hasActiveValue() — проверка для булевых значений.
  • hasSettingsValue() — проверка для объектов.

Эти методы позволяют безопасно работать с данными без риска возникновения undefined.

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

Stimulus позволяет отслеживать изменения значений через наблюдатели (valueChanged):

countValueChanged(newValue, oldValue) {
  console.log(`Старое значение: ${oldValue}, новое значение: ${newValue}`)
}

Метод countValueChanged автоматически вызывается при изменении data-example-count-value. При этом newValue и oldValue уже преобразованы к типу Number.

Преобразование данных без values

В некоторых случаях использование values невозможно, и требуется ручное преобразование строковых атрибутов:

const element = document.querySelector("[data-example-count]")
const count = Number(element.dataset.exampleCount)
const active = element.dataset.exampleActive === "true"

Такой подход полезен для динамически создаваемых элементов или когда тип значения заранее неизвестен.

Особенности работы с Boolean

Булевы значения требуют особого внимания. Любая непустая строка в JavaScript считается true, поэтому прямое использование element.dataset.exampleActive может привести к ошибкам. Рекомендуется всегда явно сравнивать строки с "true" или "false".

Преобразование сложных объектов

JSON-объекты в data-* атрибутах должны быть корректно экранированы:

<div data-controller="example" data-example-config-value='{"theme":"light","options":["a","b"]}'></div>

Stimulus автоматически парсит строку и превращает её в объект JavaScript с массивами и вложенными объектами.

Итоговые рекомендации

  • Всегда использовать values для автоматического преобразования типов.
  • Для булевых значений проверять наличие атрибута и явное соответствие "true".
  • Для сложных объектов и массивов использовать JSON-строку.
  • Использовать методы has*Value() для безопасной работы с необязательными атрибутами.
  • Наблюдатели valueChanged позволяют реагировать на изменения данных без дополнительной логики парсинга.

Понимание и правильное использование преобразования типов данных в Stimulus обеспечивает корректное поведение контроллеров и снижает риск ошибок при работе с динамическими элементами DOM.

Оглавление