クリップボード 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-write 権限または単発の活性化が要求されます。 権限が付与された場合、その権限は維持され、それ以上の単発の活性化は要求されません。
• クリップボードにアクセスする <iframe> 要素には、HTTP の Permissions-Policy の clipboard-read と clipboard-write の権限を許可しなければなりません。

Firefox および Safari:

• 仕様上読み取りが許されていないが、単発の活性化が行われた場合は、(1 秒後に有効化される)「貼り付け」の選択肢のみを持つ一時的なコンテキストメニューの形でユーザーに確認を行い、ユーザーがこの選択肢を選択すると読み取りに成功します。
• 書き込みには単発の活性化が要求されます。
• 同じオリジンのクリップボードのコンテンツを読み込む場合、paste-prompt は抑制されますが、オリジン間のコンテンツでは抑制されません。
• clipboard-read と clipboard-write 権限は Firefox や Safari では対応していません (対応する予定もありません)。

Firefox の Web Extensions:

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

例

クリップボードへのアクセス

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

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

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

仕様書

ブラウザーの互換性

api.Clipboard

api.ClipboardEvent

api.ClipboardItem

関連情報

• Image support for Async Clipboard article