Синтаксис определения действий

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

Формат определения действий

События в Stimulus определяются в атрибуте data-action элемента. Общий синтаксис:

<button data-action="event->controller#method">Нажать</button>

Где:

  • event — событие DOM, которое нужно отслеживать (например, click, input, submit).
  • controller — имя контроллера, с которым связано действие.
  • method — метод контроллера, который будет вызван при наступлении события.

Пример базового действия:

<button data-action="click->hello#greet">Приветствие</button>

Здесь при клике на кнопку будет вызван метод greet контроллера hello.

Множественные действия на одном элементе

На один элемент можно назначить несколько действий, разделяя их пробелами:

<button data-action="click->hello#greet mouseover->hello#highlight">Действия</button>
  • click->hello#greet — срабатывает при клике.
  • mouseover->hello#highlight — срабатывает при наведении курсора.

При этом порядок событий в data-action не влияет на работу, но рекомендуется придерживаться логической последовательности для удобочитаемости.

Действия с несколькими контроллерами

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

<button data-action="click->hello#greet click->analytics#trackClick">Клик и аналитика</button>

При клике одновременно вызываются greet контроллера hello и trackClick контроллера analytics.

Использование дополнительных параметров событий

Stimulus позволяет использовать псевдонимы событий для управления поведением, таких как once (однократное выполнение) или prevent (отмена стандартного поведения):

<form data-action="submit->form#save submit->form#validate.prevent">Сохранить</form>
  • .prevent предотвращает стандартное поведение события (event.preventDefault()).
  • .stop останавливает дальнейшее распространение события (event.stopPropagation()).
  • .once гарантирует вызов метода только один раз.

Псевдонимы могут комбинироваться, например:

<button data-action="click->hello#greet.prevent.once">Приветствие</button>

Динамическая привязка действий

Внутри контроллера можно программно добавлять или удалять действия через методы this.element.setAttribute() или библиотеку Element.dataset. Пример:

this.element.dataset.action = "click->hello#greet";

Это позволяет изменять поведение элементов без изменения HTML.

События нестандартных элементов

Stimulus поддерживает любые события, которые возникают на DOM-элементе, включая пользовательские. Пример пользовательского события:

<div data-action="custom:event->hello#customHandler"></div>

В контроллере hello должен быть метод customHandler, который принимает объект события.

Контекст вызова методов

Все методы, указанные в data-action, вызываются с привязкой this к контроллеру. Это позволяет напрямую работать с методами и свойствами контроллера без дополнительных привязок через bind:

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

export default class extends Controller {
  greet() {
    console.log("Привет!", this.element);
  }
}

Метод greet будет иметь доступ к this.element, к которому привязан контроллер.

Делегирование событий

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

Особенности синтаксиса

  1. Только один # между именем контроллера и методом. Ошибка в синтаксисе делает действие недоступным.
  2. Без пробелов внутри каждого действия, пробелы только между разными действиями.
  3. Чувствительность к регистру: имена контроллеров и методов должны совпадать с определением в JavaScript.
  4. Поддержка стандартных и пользовательских событий без ограничения набора событий.

Примеры сложных комбинаций

<div data-action="
  mouseover->menu#open
  mouseout->menu#close
  click->analytics#trackClick.once
  keyup->search#filter.prevent
">
  Меню и поиск
</div>
  • mouseover и mouseout управляют раскрытием меню.
  • click регистрируется в аналитике, только один раз.
  • keyup фильтрует данные и предотвращает стандартное поведение.

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

Оглавление