Turbo Stream Actions: интерактивный атлас DOM-операций

Turbo Stream - это маленькая декларативная команда над уже существующим DOM: найти цель, взять HTML из <template> и выполнить одну операцию. Чтобы понять эту механику, не нужны Rails-контроллер, WebSocket или даже сетевой запрос. Достаточно увидеть, какие именно узлы остаются, перемещаются и исчезают.

Ниже - интерактивный атлас всех восьми стандартных действий из Turbo Handbook. Лаборатория симулирует DOM-эффект прямо в статье. Она намеренно не объясняет доставку сообщений, broadcasting и серверный рендеринг: только формат элемента и результат его встраивания в страницу.

Одна команда состоит из четырёх частей

<turbo-stream
  action="append"
  target="messages">
  <template>
    <article>Новое сообщение</article>
  </template>
</turbo-stream>

Лаборатория: что визуально делает каждое action

Выберите действие, затем одиночную или множественную цель и нажмите «Применить». Синяя рамка показывает узлы, которые Turbo найдёт до операции. Команда слева меняется вместе с настройками.

Восемь действий, сгруппированные по геометрии

Названия легче запомнить не списком, а по тому, где находится граница изменения.

Тонкость append и prepend: совпавший ID заменяется

Если первый элемент шаблона имеет ID, который уже принадлежит прямому ребёнку целевого контейнера, Turbo заменит существующего ребёнка вместо добавления дубликата. Это делает повторное добавление записи идемпотентнее, но проверка относится именно к прямым children.

Actions With Multiple Targets

target="message_2" означает поиск одного элемента по DOM ID. targets=".pending" означает querySelectorAll(".pending"): одна и та же операция применяется ко всем найденным элементам, а содержимое шаблона клонируется для каждой цели.

Попробуйте селекторы .pending, .priority, [data-owner="me"] или .task:not(.done). Селектор вычисляется в момент выполнения команды. Если совпадений нет, DOM просто не изменится. Если CSS-селектор синтаксически неверен, команда не сможет разрешить цели.

Несколько команд выполняются по порядку

Одно stream-сообщение может содержать несколько соседних <turbo-stream>. Turbo исполняет их в порядке появления. Это отдельная ось композиции: targets размножает одну операцию, а несколько stream-элементов описывают сценарий из разных операций.

<turbo-stream action="prepend"
  target="wishlist_items">
  <template>...Работа...</template>
</turbo-stream>

<turbo-stream action="update"
  target="quick_create">
  <template>Список создан</template>
</turbo-stream>

Первая команда добавляет только новую строку. Вторая меняет только содержимое формы быстрого создания. Уже существующие строки не перерисовываются, поэтому несохранённый выбор чекбокса остаётся в браузере. Это и есть преимущество маленьких DOM-операций: граница изменения видна прямо в разметке сообщения.

Как выбирать действие

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

Короткая проверка перед использованием

1. Стабилен ли ID цели между рендерами?
2. Нужно сохранить сам элемент или только его место? Это выбор между update и replace.
3. Есть ли внутри цели несохранённое браузерное состояние?
4. Нужна одна операция для набора элементов или разные операции для разных мест?
5. Останется ли новая разметка доступной для следующей команды по тому же ID или селектору?

Для общей картины о навигационных областях вернитесь к статье «Turbo Frames с нуля». Там Frame рассматривается как контекст перехода, а Stream - как точечная DOM-команда. Здесь мы намеренно разобрали только вторую половину.