Определение и использование таргетов

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

Объявление таргетов

Таргеты объявляются в контроллере через статическое свойство targets, которое является массивом строк. Каждая строка — это имя таргета:

import { Controller } from "@hotwired/stimulus"

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

В этом примере контроллер имеет два таргета: input и output. Имена таргетов должны быть уникальными в пределах одного контроллера.

Привязка таргетов в HTML

Для привязки таргета к элементу используется атрибут data-<имя-контроллера>-target. Если контроллер называется example, таргеты будут указываться так:

<div data-controller="example">
  <input data-example-target="input" type="text">
  <span data-example-target="output"></span>
</div>

Каждый элемент с соответствующим атрибутом автоматически становится частью коллекции таргетов контроллера.

Доступ к таргетам в контроллере

После объявления таргетов, к ним можно обращаться через автоматически создаваемые свойства контроллера:

  • Одиночный таргет Если таргет встречается в DOM один раз, к нему можно обращаться через свойство this.<имя>Target:
connect() {
  this.inputTarget.focus()
}
  • Множественные таргеты Если один и тот же таргет встречается несколько раз, Stimulus создаёт массив this.<имя>Targets:
static targets = ["item"]

addClassToItems() {
  this.itemTargets.forEach(el => el.classList.add("highlight"))
}

Таким образом, таргеты удобно использовать как одиночные элементы, так и коллекции.

Проверка наличия таргета

Stimulus предоставляет методы для проверки, присутствует ли элемент на странице:

  • has<Имя>Target — возвращает true, если одиночный таргет найден.
  • has<Имя>Targets — возвращает true, если массив таргетов не пустой.
if (this.hasOutputTarget) {
  this.outputTarget.textContent = "Таргет найден"
}

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

Таргеты можно применять для динамического управления интерфейсом:

  • Показ/скрытие элементов
toggleVisibility() {
  this.outputTarget.classList.toggle("hidden")
}
  • Обновление содержимого элементов
updateText(value) {
  this.outputTarget.textContent = value
}
  • Работа с формами
clearInput() {
  this.inputTarget.value = ""
}

Особенности именования

  • Имена таргетов должны использовать camelCase.
  • В HTML-атрибутах используется kebab-case:
static targets = ["userName"]
<input data-example-target="user-name">

Stimulus автоматически конвертирует user-name в userName для обращения из JavaScript.

Взаимодействие нескольких контроллеров с таргетами

Если несколько контроллеров используют один и тот же элемент, необходимо соблюдать уникальность атрибутов data-*-target. Таргеты работают только внутри своего контроллера, поэтому пересечение логики контроллеров не приводит к конфликтам.

Резюме ключевых возможностей

  • Таргеты связывают DOM-элементы с контроллером без поиска через querySelector.
  • Одиночные и множественные таргеты обрабатываются различными свойствами (this.<name>Target и this.<name>Targets).
  • Методы has<Имя>Target(s) позволяют безопасно проверять наличие элементов.
  • Имена таргетов в контроллере и HTML синхронизируются через camelCase ↔︎ kebab-case.
  • Таргеты позволяют легко управлять динамическим содержимым и состоянием элементов интерфейса.

Использование таргетов упрощает архитектуру контроллеров и делает код более декларативным и удобочитаемым.

Оглавление