クリップボード API

システムクリップボードは、ブラウザーが動作しているオペレーティングシステムに属するデータバッファーであり、短期間のデータ保存や文書またはアプリケーション間のデータ転送に使用します。 通常、無名で一時的なデータバッファーとして実装されており、ペーストバッファーと呼ばれることもあります。環境内のほとんどまたはすべてのプログラムから定義されたプログラミングインターフェイスを通じてアクセス可能です。

クリップボード API を使うと、ユーザーは安全なコンテキストの中で、セキュリティに関する考慮事項で指定された条件が成立する限り、テキストや他にも様々な種類のデータをクリップボードにプログラムで読み書きすることができます。

イベントは切り取り (cut)、コピー (copy)、貼り付け (paste) 操作がクリップボードを変更した結果として発行されます。 イベントには既定のアクションがあり、例えば copy アクションは既定では現在の選択部分をシステムクリップボードにコピーします。 既定のアクションはイベントハンドラーで上書きすることができます。詳細は各イベントを参照してください。

Clipboard 安全なコンテキスト用

システムクリップボードに対してテキストやデータを読み書きするインターフェイスを提供します。 これは仕様書では「非同期クリップボード API」と呼ばれています。

ClipboardEvent

クリップボードの変更に関する情報を提供するイベント、すなわち cut, copy, paste イベントを表します。これは仕様書では「クリップボードイベント API」と呼ばれています。

ClipboardItem 安全なコンテキスト用

データの読み書きの際に使用する単一項目形式を表します。

クリップボード API は以下の API を拡張し、掲載されている機能を追加しています。

Navigator.clipboard 読取専用 安全なコンテキスト用

システムクリップボードへの読み書きアクセスを提供する Clipboard オブジェクトを返します。

Element: copy イベント

ユーザーがコピー操作を行うたびに発行されるイベントです。

Element: cut イベント

ユーザーが切り取り操作を行うたびに発行されるイベントです。

Element: paste イベント

ユーザーが貼り付け操作を行うたびに発行されるイベントです。

クリップボード API は、ユーザーが安全なコンテキストのシステムクリップボードとの間で、テキストや他の種類のデータをプログラムで読み書きすることをできるようにします。

この仕様では、クリップボードから読み取るために、ユーザーが最近ページを操作したことが要求されます（単発のユーザーの活性化が必要です）。 読み取り処理がブラウザーやOSの「貼り付け要素」（コンテキストメニューなど）とのユーザー対話によって発生した場合、ブラウザーはユーザーに確認を促すことが期待されます。 クリップボードに書き込む場合、詳細度はページが権限 API の clipboard-write 権限を持つことを期待し、ブラウザーは単発のユーザー活性化も要求されるかもしれません。 ブラウザーはクリップボードにアクセスするメソッドを使用する際に、さらに制限を加えるかもしれません。

ブラウザーの実装は仕様から乖離しています。 その違いはブラウザーの互換性の節にまとめられており、現在の状態の概要は下記の通りです。

Chromium 系のブラウザー:

• 読み取りには権限 API の clipboard-read 権限が要求されます。 単発の活性化は要求されません。
• 書き込みには clipboard-read 権限または単発の活性化が要求されます。 権限が付与された場合、その権限は維持され、それ以上の単発の活性化は要求されません。
• クリップボードにアクセスする <iframe> 要素には、HTTP のPermissions-Policy の clipboard-read と clipboard-write の権限を許可しなければなりません。
• ブラウザーや OS の「貼り付け要素」によって読み取り処理が発生した場合、持続的な貼り付けプロンプトは表示されません。

Firefox および Safari:

• 読み書きには単発の活性化が要求されます。
• 同じオリジンのクリップボードのコンテンツを読み込む場合、paste-prompt は抑制されますが、オリジン間のコンテンツは抑制されません。
• clipboard-read と clipboard-write 権限は Firefox や Safari では対応していません（対応する予定もありません）。

Firefox の Web Extensions:

• テキストの読み込みは、Web Extension clipboardRead 権限を持つ拡張機能でのみ利用できます。 その権限があれば、拡張機能は単発の活性化や貼り付けのプロンプトを要求されません。
• テキストの書き込みは、安全なコンテキストと単発の活性化で利用できます。 Web Extension の clipboardWrite 権限では、単発の活性化は要求されません。

システムクリップボードには、グローバルの Navigator.clipboard を通してアクセスします。

このスニペットはクリップボードからテキストを読み取り、最初に見つかった editor クラスを持つ要素に追加します。 readText() (および場合によっては read()) はクリップボードにテキストがないときには空文字列を返すので、このコードは安全です。

navigator.clipboard
  .readText()
  .then(
    (clipText) => (document.querySelector(".editor").innerText += clipText),
  );

• Image support for Async Clipboard article