Invoker Commands API クイックガイド

<dialog> 要素を開くためにボタンを配線したことがあれば、その手順はご存知でしょう。要素をクエリし、クリックリスナーをアタッチし、showModal() を呼び出す。これは機能しますが、何度も繰り返し書くボイラープレートコードです。Invoker Commands API は、この関係性を HTML で直接宣言できるようにすることで、この問題を解決します。最も一般的なケースでは JavaScript が不要になります。

2025年後半の時点で、Invoker Commands API は Chrome/Edge、Firefox、Safari 全体で Baseline 対応に達しており、モダンなプロジェクトで実用的な選択肢となっています。現在のブラウザサポート状況は webstatus.dev または caniuse.com で確認できます。

command および commandfor 属性とは?

Invoker Commands API は、<button> 要素に2つの HTML 属性を導入します。

• commandfor — 制御したいターゲット要素の id
• command — ボタンがアクティブ化されたときにターゲットに対して実行するアクション

これらを組み合わせることで、呼び出し元のボタンとそのターゲット間の宣言的なリンクが形成されます。ボタンがクリックされたり、キーボードで押されたり、その他の方法でアクティブ化されると、ブラウザはターゲット要素に CommandEvent をディスパッチし、組み込みコマンドの場合は対応する動作を自動的に実行します。

重要: これらの属性を使用するボタンには、常に type="button" を追加してください。これがないと、フォーム内のボタンはデフォルトで type="submit" となり、予期しない動作を引き起こします。

HTML でダイアログとポップオーバーを制御する

ここが API が最も即座に価値を提供する部分です。以前は、<dialog> 要素を制御するには JavaScript が必要でした。今では宣言的に実現できます。

<button type="button" commandfor="my-dialog" command="show-modal">
  ダイアログを開く
</button>

<dialog id="my-dialog">
  <p>ダイアログからこんにちは!</p>
  <button type="button" commandfor="my-dialog" command="request-close">
    閉じる
  </button>
</dialog>

JavaScript は不要です。ブラウザがトップレイヤー配置、フォーカストラップ、ダイアログが閉じたときのフォーカス復元を処理します。

組み込みコマンドリファレンス

ポップオーバーについては、これは古い popovertarget 属性と同様の目的を果たします。Invoker Commands API は宣言的な UI アクションのためのより汎用的なメカニズムですが、元のポップオーバー属性も依然として存在し、サポートされています。詳細については、MDN の Popover API ガイドを参照してください。

アクセシビリティは組み込み済み

組み込みコマンドの場合、ブラウザは主要なアクセシビリティと対話動作を自動的に処理します。ダイアログコマンドは、トップレイヤー動作やダイアログが閉じたときのフォーカス復元を含む、ブラウザのネイティブ <dialog> 処理と統合されています。これらのプラットフォームレベルの動作により、追加の ARIA 属性を必要とせずに、一貫した対話パターンとより良いアクセシビリティが保証されます。

カスタムコマンドには依然として JavaScript が必要

この API は、独自のコンポーネント用のカスタムコマンドもサポートしています。-- で始まる command 値はカスタムコマンドとして扱われます。ブラウザはターゲットに CommandEvent をディスパッチし、残りは JavaScript で処理します。

<button type="button" commandfor="color-box" command="--toggle-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 は、最も一般的なパターンに対して、HTML での宣言的な UI 制御を現実のものにします。ダイアログとポップオーバーには組み込みコマンドを使用して、アクセシビリティ、フォーカス管理、そして JavaScript ゼロを無料で入手できます。JavaScript の動作が必要だが、よりクリーンで宣言的な配線パターンが必要な場合は、カスタム -- コマンドを使用します。これは明確なスコープを持つ小さな API です。そしてそれこそが、この 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.