Краткое руководство по Invoker Commands API

Если вы когда-либо связывали кнопку с открытием элемента <dialog>, вы знаете процедуру: запросить элемент, добавить обработчик клика, вызвать showModal(). Это работает, но это шаблонный код, который вы пишете снова и снова. Invoker Commands API меняет это, позволяя объявлять такую связь непосредственно в HTML — JavaScript не требуется для наиболее распространённых случаев.

По состоянию на конец 2025 года Invoker Commands API достиг статуса Baseline и доступен в Chrome/Edge, Firefox и Safari, что делает его практичным выбором для современных проектов. Вы можете проверить текущую поддержку браузерами на webstatus.dev или caniuse.com.

Что такое атрибуты command и commandfor?

Invoker Commands API вводит два HTML-атрибута для элементов <button>:

• commandfor — id целевого элемента, которым вы хотите управлять
• command — действие, которое нужно выполнить над целевым элементом при активации кнопки

Вместе они формируют декларативную связь между вызывающей кнопкой и её целью. Когда кнопка нажимается, активируется через клавиатуру или иным образом, браузер отправляет CommandEvent на целевой элемент и — для встроенных команд — автоматически выполняет соответствующее поведение.

Важно: Всегда добавляйте type="button" к любой кнопке, использующей эти атрибуты. Без этого кнопки внутри форм по умолчанию имеют type="submit", что вызывает неожиданное поведение.

Управление диалогами и всплывающими окнами с помощью HTML

Именно здесь API предоставляет наиболее непосредственную ценность. Ранее для управления элементом <dialog> требовался JavaScript. Теперь вы можете делать это декларативно:

<button type="button" commandfor="my-dialog" command="show-modal">
  Open Dialog
</button>

<dialog id="my-dialog">
  <p>Hello from the dialog!</p>
  <button type="button" commandfor="my-dialog" command="request-close">
    Close
  </button>
</dialog>

Никакого JavaScript. Браузер обрабатывает размещение на верхнем слое, захват фокуса и восстановление фокуса при закрытии диалога.

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

Для всплывающих окон это служит аналогичной цели, что и более старый атрибут popovertarget. Invoker Commands API — это более общий механизм для декларативных действий UI, но оригинальные атрибуты popover всё ещё существуют и остаются поддерживаемыми. См. руководство MDN по Popover API для подробностей.

Доступность встроена изначально

Для встроенных команд браузер автоматически обрабатывает ключевые аспекты доступности и поведения взаимодействия. Команды диалога интегрируются с нативной обработкой <dialog> браузером, включая поведение верхнего слоя и восстановление фокуса при закрытии диалога. Эти поведения на уровне платформы помогают обеспечить согласованные паттерны взаимодействия и лучшую доступность без необходимости дополнительных ARIA-атрибутов.

Пользовательские команды всё ещё требуют JavaScript

API также поддерживает пользовательские команды для ваших собственных компонентов. Любое значение command, начинающееся с --, рассматривается как пользовательская команда. Браузер отправляет CommandEvent на целевой элемент, а ваш JavaScript обрабатывает остальное:

<button type="button" commandfor="color-box" command="--toggle-highlight">
  Highlight
</button>
<div id="color-box"></div>

<script>
  document.getElementById('color-box').addEventListener('command', (e) => {
    if (e.command === '--toggle-highlight') {
      e.target.classList.toggle('highlighted');
    }
  });
</script>

Префикс -- — это зарезервированное пространство имён — браузеры гарантируют, что никогда не будут использовать его для встроенных команд, поэтому он безопасен для пользовательского использования. CommandEvent предоставляет как e.command (строку команды), так и e.source (кнопку, которая её вызвала), давая вам всё необходимое для реагирования на событие.

Заключение

Invoker Commands API делает декларативное управление UI в HTML реальностью для наиболее распространённых паттернов. Используйте встроенные команды для диалогов и всплывающих окон, чтобы получить доступность, управление фокусом и нулевое количество JavaScript бесплатно. Используйте пользовательские команды с --, когда вам нужно поведение на JavaScript, но вы хотите более чистый, более декларативный паттерн связывания. Это небольшой API с чёткой областью применения — и именно это делает его полезным.

Часто задаваемые вопросы

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.