Модификаторы действий

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

Основные принципы

Действие в Stimulus описывается через атрибут data-action, который связывает событие DOM с методом контроллера:

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

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

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

В данном примере модификатор prevent автоматически вызывает event.preventDefault(), предотвращая стандартное поведение кнопки.

Список встроенных модификаторов

  1. prevent – предотвращает стандартное поведение события.
  2. stop – вызывает event.stopPropagation(), останавливая распространение события.
  3. once – метод вызывается только один раз для данного элемента.
  4. self – метод вызывается только если целевой элемент события совпадает с элементом, к которому привязан обработчик.
  5. debounce – задержка вызова метода на указанное время.
  6. throttle – ограничивает частоту вызова метода в указанный интервал времени.
  7. capture – событие обрабатывается на фазе захвата, а не всплытия.

Применение prevent и stop

Модификаторы prevent и stop особенно полезны для управления поведением форм и ссылок:

<form data-action="submit.prevent#form#submitForm">
  <input type="text">
  <button type="submit">Отправить</button>
</form>
  • prevent отменяет стандартную отправку формы.
  • stop может применяться для предотвращения дальнейшего всплытия события к родительским элементам.
<div data-action="click.stop#parent#handleClick">
  <button data-action="click#child#handleClick">Кнопка</button>
</div>

В этом примере клик по кнопке вызовет метод child#handleClick, но событие не достигнет родительского элемента.

Модификаторы once и self

  • once гарантирует однократный вызов метода, полезен для кнопок типа «Загрузить файл»:
<button data-action="click.once#controller#upload">Загрузить</button>
  • self позволяет игнорировать клики по дочерним элементам:
<div data-action="click.self#controller#toggle">
  <p>Текст внутри</p>
</div>

Клик по <p> не вызовет метод toggle, только клик по самому <div>.

Динамические модификаторы: debounce и throttle

Модификаторы debounce и throttle управляют частотой вызова методов:

<input type="text" data-action="input.debounce-300#controller#search">
  • debounce-300 откладывает вызов метода на 300 миллисекунд после последнего события.
  • throttle-500 ограничивает вызовы метода до одного раза каждые 500 миллисекунд.
<input type="text" data-action="input.throttle-500#controller#update">

Такие модификаторы полезны для автопоиска, валидации и работы с событиями scroll или resize.

Комбинирование модификаторов

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

<button data-action="click.prevent.stop.once#controller#save">
  Сохранить
</button>
  • Событие click не будет всплывать (stop), стандартное поведение отменено (prevent), метод вызовется один раз (once).

Кастомные модификаторы

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

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

const application = Application.start();

application.actionModifiers.set("log", (event, element) => {
  console.log("Событие сработало на элементе:", element);
});
<button data-action="click.log#controller#method">Клик</button>

Такой подход расширяет возможности стандартного набора, сохраняя декларативный стиль описания действий.

Рекомендации по использованию

  • Применять prevent для ссылок и форм, чтобы управлять поведением без лишнего JavaScript.
  • Использовать once и self для оптимизации обработки кликов и предотвращения нежелательных срабатываний.
  • Для событий, вызываемых часто (input, scroll, mousemove), применять debounce или throttle, чтобы снизить нагрузку на браузер.
  • Комбинировать модификаторы для комплексного контроля над событиями, но избегать излишней вложенности, чтобы не ухудшать читаемость.

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

Оглавление