Определение и применение классов

Stimulus — это легковесный JavaScript-фреймворк, который ориентирован на организацию поведения HTML-элементов через контроллеры, ассоциированные с DOM. Основной строительный блок Stimulus — это класс контроллера, который расширяет базовый класс Controller из библиотеки @hotwired/stimulus. Работа с классами в Stimulus сочетает объектно-ориентированный подход JavaScript и декларативное связывание с разметкой.

Создание контроллера

Контроллер определяется как класс, экспортируемый по умолчанию, который наследует Controller. Базовая структура выглядит следующим образом:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    console.log("Контроллер подключен");
  }

  disconnect() {
    console.log("Контроллер отключен");
  }
}
  • connect() — вызывается при подключении контроллера к элементу DOM.
  • disconnect() — вызывается при удалении элемента из DOM.
  • initialize() — выполняется перед connect(), позволяет инициализировать внутренние свойства.

Связывание контроллера с элементом

Контроллер связывается с HTML-элементом через атрибут data-controller. Значение атрибута соответствует имени файла контроллера, приведённого к kebab-case:

<div data-controller="example">
  Пример работы контроллера
</div>

Stimulus автоматически создаёт экземпляр класса для каждого элемента с указанным атрибутом.

Применение методов контроллера

Методы класса могут быть использованы как действия (actions) для обработки событий:

<button data-action="click->example#greet">Привет</button>
export default class extends Controller {
  greet() {
    console.log("Привет!");
  }
}

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

  • click->example#greet — событие click на кнопке вызывает метод greet контроллера example.
  • Методы могут принимать объект события event как параметр.

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

Stimulus поддерживает декларативное определение значений, которые автоматически связываются с атрибутами элемента:

export default class extends Controller {
  static values = { count: Number }

  connect() {
    console.log(`Текущее значение: ${this.countValue}`);
  }

  increment() {
    this.countValue++;
  }
}

HTML:

<div data-controller="counter" data-counter-count-value="5">
  <button data-action="click->counter#increment">Увеличить</button>
</div>
  • static values позволяет определить тип и имя значения.
  • Stimulus автоматически создаёт геттеры и сеттеры: countValue для чтения и записи.

Определение целей (Targets)

Targets — способ обозначить дочерние элементы для удобного доступа из контроллера:

export default class extends Controller {
  static targets = ["output"]

  connect() {
    this.outputTarget.textContent = "Контроллер подключен";
  }
}

HTML:

<div data-controller="example">
  <span data-example-target="output"></span>
</div>
  • this.outputTarget автоматически ссылается на указанный элемент.
  • Если необходимо несколько элементов с одинаковым target, создаётся массив: this.outputTargets.

Работа с классами и атрибутами DOM

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

export default class extends Controller {
  static targets = ["box"]

  toggle() {
    this.boxTarget.classList.toggle("active")
  }
}

HTML:

<div data-controller="example">
  <div data-example-target="box">Содержимое</div>
  <button data-action="click->example#toggle">Переключить</button>
</div>
  • classList.toggle() позволяет динамически менять состояние элементов.
  • Контроллеры стимулируют декларативное управление поведением без непосредственного поиска элементов в DOM через querySelector.

Наследование и повторное использование классов

Контроллеры Stimulus могут быть расширены через обычное наследование JavaScript:

import BaseController from "./base_controller"

export default class extends BaseController {
  connect() {
    super.connect()
    console.log("Дополнительная логика в дочернем контроллере");
  }
}
  • Базовый контроллер может содержать общие методы и значения.
  • Дочерний контроллер добавляет специфическую функциональность, сохраняя связь с родительским классом через super.

Организация больших приложений

  • Модульность: каждый контроллер в отдельном файле, именование совпадает с data-controller.
  • Явное связывание: значения и цели определяются статически через static values и static targets.
  • Упрощение событий: методы контроллера привязываются к DOM через data-action, исключая прямую работу с addEventListener.
  • Наследование и переиспользование: общие функции инкапсулируются в базовых контроллерах.

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

Оглавление