クリップボードAPIとイベント

1. はじめに

このセクションは規範的ではありません。

この仕様は、システムクリップボードがウェブアプリケーションにどのように公開されるかを定義します。

本仕様で説明されているAPIは、主に2つあります:

• クリップボードイベントAPI - このAPIは、切り取り、コピー、貼り付けなど一般的なクリップボード操作にフックし、ウェブアプリケーションが必要に応じてクリップボードデータを調整できるようにします。

• 非同期クリップボードAPI - このAPIは、クリップボードデータの直接読み書きを提供します。これは強力な機能とみなされるため、このAPIへのアクセスは権限によって制御されます。

2. ユースケース

このセクションは規範的ではありません。

2.1. デフォルトのクリップボード操作の変更

デフォルトのクリップボード操作（切り取り/コピー/貼り付け）を変更したいシナリオは多数存在します。いくつか例を挙げます:

• メタデータ 文書リポジトリからテキストをコピーする際、コピーされたテキストに元のコンテンツのメタデータを含めることが有用です。
• リッチコンテンツ編集 ハイパーリンクなどの構造を含むテキストをコピーする場合、重要な情報を保持するために内容を再フォーマットできると便利です。
• 意味を持つグラフィックス リッチテキストや[SVG11]などのグラフィックコンテンツを操作するウェブアプリケーションのために、描画された内容だけでなく、より多くの情報をコピーできる仕組みがあると便利です。
• 数学情報 数学のような内容では、レンダリングされたテキストをコピーして他のアプリケーションに貼り付けただけでは、ほとんどの意味が失われてしまいます。例えばMathMLは、プレーンテキストとしてコピーする際に「べき乗」をキャレット「^」記号で示すなど、適切な変換が必要です。XMLソースも、貼り付け時に適切に変換されるようクリップボードに配置できます。

2.2. リモートクリップボード同期

リモートデバイスと通信するウェブアプリケーション（例: リモートアクセスやリモートシェルアプリケーション）では、2つのデバイス間でクリップボードデータを同期させる必要がある場合があります。

このユースケースで重要なのは、ユーザーのジェスチャや操作がなくてもクリップボードへアクセスできる必要があることです。

2.3. クリップボードアクションのトリガー

ユーザーエージェントに対して代替インターフェースを提供するアプリケーションでは、ユーザーエージェント内でクリップボードアクションをトリガーできる必要がある場合があります。

例えば、スクリーンリーダーアプリケーションが標準Webブラウザーによりアクセシブルなインターフェースを提供する場合、リーダーはコンテンツを表示し、ユーザーが操作できるようにしますが、コピーなどのクリップボード操作は基盤となるブラウザ内で行う必要があります（コピー時にブラウザが追加するメタデータなども正しく設定されるように）。

3. 用語

編集可能コンテキストとは、編集ホスト、textarea要素、またはtype属性が"text"、"search"、"tel"、"url"、"email"、"password"、"number"のいずれかに設定されているinput要素のいずれかを指します。

4. モデル

プラットフォームはシステムクリップボードを提供します。

システムクリップボードは、システムクリップボードアイテムのリストを持ち、それらをまとめてシステムクリップボードデータと呼びます。

各システムクリップボードアイテムは、システムクリップボード表現のリストを持ちます。

各システムクリップボード表現は、name（文字列）と、data（バイト列）を持ちます。

システムクリップボードは、 クリップボード変更 カウントを持つ。これは、システムクリップボードデータが変更されるたびに変化する値である。

5. クリップボードイベント

5.1. クリップボードイベントインターフェース

ClipboardEventインターフェースはEvent インターフェースを拡張します。

dictionary ClipboardEventInit : EventInit {
  DataTransfer? clipboardData = null;
};

[Exposed=Window]
interface ClipboardEvent : Event {
  constructor(DOMString type, optional ClipboardEventInit eventInitDict = {});
  readonly attribute DataTransfer? clipboardData;
};

このインターフェースはイベントの構築に使用できます。 以下はその例です:

var pasteEvent = new ClipboardEvent('paste');
pasteEvent.clipboardData.items.add('My string', 'text/plain');
document.dispatchEvent(pasteEvent);

注: 合成クリップボードイベントは実際にクリップボードや 文書を変更しません。つまり、上記のスクリプトでpasteイベントは発火しますが、 データが文書内に貼り付けられることはありません。

5.2. クリップボードイベント

5.2.1. clipboardchangeイベント

clipboardchange イベントはシステムクリップボードの内容が変更されたときに発火します。これらの変更には以下のようなもの（例示）があります:

• ユーザーによる切り取りまたはコピー操作

• § 7 非同期クリップボードAPIを使用してスクリプトがクリップボードに書き込んだ場合

• ユーザーエージェント外でクリップボードが更新された場合

ユーザーエージェントは、clipboardchange イベントが配信される前に、より新しい変更によって上書きされたクリップボードの変更については、発火を省略することを選択してもよいです。この最適化は、クリップボードの変更が短時間で連続して発生する場合にパフォーマンスの向上につながります。なぜなら、旧いイベント通知を配信してもウェブアプリケーションに価値がなく、処理リソースを消費するだけだからです。

ネストされた閲覧コンテキスト内の document では、clipboardchange イベントは、それぞれの Document ごとのフォーカス状態に基づき、個別に発火されます。クリップボードの変更が発生すると、システムフォーカスを持つ単一の document でイベントが発火します（該当の document がスティッキーアクティベーションまたは永続的なクリップボード権限を持つ場合）。

注: clipboardchange イベントは、スティッキーアクティベーションの後でのみ利用可能です（document がクリップボードからの読み取りに対する永続的な権限を持つ場合を除く）。 ユーザーエージェントが永続的なクリップボード権限をサポートしている場合、そのような権限を持つサイトはスティッキーアクティベーションなしでもclipboardchangeイベントを受信できます。なぜなら、その許可自体がより機微なクリップボードデータへのアクセスを既に許可しているからです。

changeId は、それぞれのクリップボード変更操作に対する一意識別子を提供します。同じクリップボードの変更について、同じストレージキーを持つすべてのウィンドウおよびタブは、同じ changeId 値を持つイベントを受け取り、複数ウィンドウでのイベントの重複処理を防げます。識別子はストレージキーごとに固有であり、キーをまたぐ相関機能はありません。

clipboardchange イベントはバブルせず、キャンセルもできません。なぜなら、これはユーザー操作によってではなく、システムクリップボードの状態変更によって引き起こされるからです。

dictionary ClipboardChangeEventInit : EventInit {
  sequence<DOMString> types = [];
  bigint changeId = 0;
};

[Exposed=Window]
interface ClipboardChangeEvent : Event {
  constructor(DOMString type, optional ClipboardChangeEventInit eventInitDict = {});
  readonly attribute FrozenArray<DOMString> types;
  readonly attribute bigint changeId;
};

5.2.1.4. ChangeId 生成

上記のアルゴリズムは、同じオリジンからの、かつ同じ パーティショニングを持つ文書が、同じクリップボード変更について同一の変更IDを受け取ることを保証し、 複数のウィンドウおよびタブにまたがる適切なイベント重複排除を可能にする一方で、トラッキングに 使用され得るパーティション間の相関付けを防ぐ。クライアント側ストレージパーティショニングの変更が ストレージキー定義に組み込まれるにつれて、この手法はパーティション間で自動的に匿名化を提供する。

changeId はブラウザーの再起動をまたいで永続化されない。これは、ユーザー エージェントが再起動するとglobalChangeIdカウンターがリセットされるためである。 同様に、ユーザーがサイトデータを消去した場合、影響を受けるタブは更新されるべきであり、それによって イベントリスナーが再接続され、新しい変更IDを持つ将来のイベントのみを受け取る。

合成されたcut およびcopy イベントはシステムクリップボードを更新しないため、 それらは「clipboardchange」イベントをトリガーしない。

// 複数のウィンドウを持つアプリケーションでは、重複を避けるために処理済みの変更IDを追跡する
const processedChangeIds = new Set();

// クリップボードの変更をリッスンする
navigator.clipboard.addEventListener('clipboardchange', (e) => {
  // changeIdを使用して複数のウィンドウにまたがるイベントを重複排除する
  if (processedChangeIds.has(e.changeId)) {
    return; // この変更はすでに処理されている
  }
  processedChangeIds.add(e.changeId);

  // クリップボード上で利用可能なデータ型を確認する
  const hasText = e.types.includes('text/plain');
  const hasHTML = e.types.includes('text/html');
  const hasImage = e.types.includes('image/png');

  // 利用可能な形式に基づいてUIを更新する
  document.getElementById('paste-text-btn').disabled = !hasText;
  document.getElementById('paste-html-btn').disabled = !hasHTML;
  document.getElementById('paste-image-btn').disabled = !hasImage;

  // リモートデスクトップアプリでは、変更ごとに一度だけクリップボードをリモートへ同期する
  if (hasText || hasHTML || hasImage) {
    syncClipboardToRemote(e.changeId);
  }
});

// あるいは、onclipboardchangeプロパティを使用できる
// navigator.clipboard.onclipboardchange = (e) => { ... };

5.2.2. copy イベント

ユーザーがコピー操作を開始すると、ユーザーエージェントは クリップボード イベントを発火する。その名前は copyである。

イベントが取り消されなかった場合、現在選択されている データはシステムクリップボードにコピーされる。 現在の文書選択は影響を受けない。

copy イベントはバブルし、取り消し可能であり、composedである。

このイベントの処理モデルの詳細な説明については、§ 8.1 コピー操作を参照。

合成されたcopy イベントは手動で構築してディスパッチできるが、 システムクリップボードの内容には影響しない。

5.2.3. cut イベント

ユーザーが切り取り操作を開始すると、ユーザーエージェントは クリップボード イベントを発火する。その名前は cutである。

編集可能コンテキストでは、 イベントが取り消されなかった場合、この操作は現在選択されているデータを システムクリップボードに置き、 文書からその選択を削除する。 cut イベントは、選択されたデータが削除される前に発火する。切り取り操作が完了すると、 選択は折りたたまれる。

非編集可能 コンテキストでは、clipboardData は 空のリストになる。この場合でもcut イベントは発火されることに注意。

cut イベントはバブルし、取り消し可能であり、composedである。

このイベントの処理モデルの詳細な説明については、§ 8.2 切り取り操作を参照。

合成されたcut イベントは手動で構築してディスパッチできるが、 文書の内容にも、システムクリップボードの内容にも影響しない。

5.2.4. paste イベント

ユーザーが貼り付け操作を開始すると、ユーザーエージェントはpasteという名前のクリップボードイベントを発火します。 このイベントは、クリップボードデータが文書に挿入される前に発火します。

カーソルが編集可能コンテキスト内にある場合、貼り付け操作はそのコンテキストでサポートされている最適な形式（あれば）でクリップボードデータを挿入します。

貼り付け操作は非編集可能コンテキストでは効果がありませんが、paste イベントは必ず発火します。

paste イベントはバブルし、キャンセル可能で、構成可能です。

このイベントの処理モデルの詳細は§ 8.3 貼り付けアクションを参照してください。

合成paste イベントは手動で構築してディスパッチできますが、 文書の内容には影響しません。

5.3. 他のスクリプトやイベントとの統合

5.3.1. クリップボードの変更が許可されているイベントハンドラ

以下のいずれかが真の場合、イベントハンドラはクリップボードへ書き込みできます:

• イベントをトリガーするアクションがユーザーエージェント自身のUI（例:「コピー」メニューやショートカットキー）から呼び出された場合。

• イベントをトリガーするアクションがポップアップ表示が許可されているスクリプトスレッドから呼び出された場合。

実装は、実装者がそのイベントタイプがユーザーの意図を表す可能性が高いと判断した場合、他の信頼できるイベントタイプでもクリップボードの変更を許可してもよいです。また、信頼された特定サイトやアプリがスクリプトスレッドの起源に関係なくクリップボードを変更できるようにする設定をサポートしてもよいです。

合成されたcut およびcopy イベントはシステムクリップボードのデータを変更してはなりません。

5.3.2. クリップボードからの読み取りが許可されているイベントハンドラ

以下のいずれかが真の場合、イベントハンドラはシステムクリップボードからデータを読み取ることができます:

• イベントをトリガーするアクションがユーザーエージェント自身のUI（例:「貼り付け」メニューやショートカットキー）から呼び出された場合。

• アクションをトリガーするスクリプトが、実装依存の仕組みによりクリップボードからデータを読み取る権限を与えられているサイト上で実行されている場合。

• イベントをトリガーするアクションが、クリップボードの読み取り権限を持つアプリでトリガーされた場合。

合成されたpaste イベントは実際のシステムクリップボード上のデータへのアクセスをスクリプトに与えてはなりません。

5.3.3. リッチテキスト編集APIとの統合

実装がスクリプトからクリップボードコマンドを実行する方法（例: document.execCommand() メソッドで "cut"、"copy"、"paste" コマンドを呼び出す）をサポートしている場合、実装は必ず対応するアクションをトリガーし、それに応じたクリップボードイベントをディスパッチします。

スクリプトAPIからコピー・切り取り・貼り付けアクションをトリガーする際の手順:

1. 対応するアクションを同期的に実行する。

2. アクションの戻り値をAPI呼び出しの戻り値として使用する。

注: スクリプトAPI経由でトリガーされたコピーや切り取りコマンドは、イベントが信頼できユーザーによってトリガーされた場合、または実装がそれを許可するように設定されている場合のみ、実際のクリップボードの内容に影響します。スクリプトAPI経由の貼り付けコマンドは、実装がそれを許可するよう設定されている場合のみ、貼り付けイベントを発火しクリップボード内容へのアクセスを許可します。クリップボードの読み書きアクセスを許可する実装設定方法は本仕様の範囲外です。

5.3.4. 他のイベントとの相互作用

クリップボード操作がキーボード入力でトリガーされた場合、実装は必ずその操作を開始するイベントを発火しなければなりません。イベントは非同期ですが、関連するキーのkeyupイベントの前にディスパッチされなければなりません。

切り取り・貼り付け操作は、実装がサポートする他のイベント（textInput、input、change、検証イベント、DOMCharacterDataModified、DOMNodeRemoved/DOMNodeInsertedなど）をディスパッチする場合があります。これらのイベントは、切り取り・貼り付けイベントの処理が完了した後に発火するようキューされます。

実装はコピー操作に応じて、textInput、input、change、検証イベントなど、他の入力関連イベントをディスパッチしてはなりません。

5.3.5. 選択やフォーカスを変更するイベントリスナー

イベントリスナーが選択やフォーカス可能領域を変更した場合、クリップボード操作は 必ず変更後の選択に対して完了しなければなりません。

6. クリップボードイベントAPI

クリップボードイベントAPIを使用すると、ユーザーエージェントのデフォルトの切り取り、コピー、貼り付け動作を上書きできます。

クリップボードへのアクセスは、標準のDataTransfer のメソッドを使って、items をClipboardEventの clipboardData 属性で操作します。 この結果、これらのクリップボードAPIはClipboardEvent ハンドラのコンテキスト内でのみクリップボードデータにアクセスできます。

注: クリップボードイベントハンドラの外部でクリップボードにアクセスしたい場合は、§ 7 非同期クリップボードAPIを参照してください。

注: クリップボードイベントAPIは同期的であり、できることに制限があります。権限取得や画像のトランスコードなど、ブロッキングの可能性がある操作はこれらのAPIではサポートされていません。ブロッキングや時間のかかる操作に対応するより強力なAPIについては§ 7 非同期クリップボードAPIを参照してください。

6.1. copyイベントの上書き

デフォルトのcopy イベントの動作を上書きするには、copy イベントハンドラを追加し、そのイベントハンドラ内でpreventDefault() を呼び出してイベントをキャンセルする必要があります。

イベントをキャンセルすることで、システムクリップボードが clipboardData のデータで更新されます。 ClipboardEvent がキャンセルされない場合は、現在のドキュメント選択のデータがコピーされます。

// クリップボードにコピーされる内容を上書きする例
document.addEventListener('copy', function(e) {
  // e.clipboardDataは初期状態では空ですが、コピーしたいデータを設定できます。
  e.clipboardData.setData('text/plain', 'Hello, world!');
  e.clipboardData.setData('text/html', '<b>Hello, world!</b>');

  // ドキュメント選択範囲がクリップボードに書き込まれるのを防ぐために必要です。
  e.preventDefault();
});

6.2. cutイベントの上書き

デフォルトのcut イベントの動作を上書きするには、cut イベントハンドラを追加し、そのイベントハンドラ内でpreventDefault() を呼び出してイベントをキャンセルする必要があります。

イベントをキャンセルすることで、システムクリップボードが clipboardData のデータで更新されます。 ClipboardEvent がキャンセルされない場合は、現在のドキュメント選択のデータがコピーされます。

cut イベントをキャンセルすると、ドキュメントが更新されなくなります（つまり、現在選択されているテキストは削除されません）。選択されたテキストを削除するには、イベントハンドラ内で手動でドキュメントを更新する必要があります。

// クリップボードにコピーされる内容を上書きする例
document.addEventListener('cut', function(e) {
  // e.clipboardDataは初期状態では空ですが、切り取り時にコピーしたいデータを設定できます。
  // クリップボードにコピーしたいデータを書き込みます。
  e.clipboardData.setData('text/plain', 'Hello, world!');
  e.clipboardData.setData('text/html', '<b>Hello, world!</b>');

  // cut操作をキャンセルするため、選択されたテキストを手動で削除する必要があります。
  deleteCurrentDocumentSelection();

  // ドキュメント選択範囲がクリップボードに書き込まれるのを防ぐために必要です。
  e.preventDefault();
});

6.3. pasteイベントの上書き

デフォルトのpaste イベントの動作を上書きするには、paste イベントハンドラを追加し、そのイベントハンドラ内でpreventDefault() を呼び出してイベントをキャンセルする必要があります。

イベントをキャンセルすることで、ユーザーエージェントがシステムクリップボードのデータでドキュメントを更新しなくなります。

paste イベントをキャンセルすると、ドキュメントが更新されなくなります（つまり、何も貼り付けられません）。データをドキュメントに貼り付けるには、イベントハンドラ内で手動で貼り付け処理を行う必要があります。

また、貼り付け時にはドラッグデータストアモードのフラグが読み取り専用になるため、setData() をpaste イベントハンドラ内で呼び出しても、挿入されるデータやクリップボード上のデータは変更されません。

// クリップボードから貼り付けられる内容を上書きする例
document.addEventListener('paste', function(e) {
  // e.clipboardDataは貼り付け直前のデータを含みます。
  if (e.clipboardData.types.indexOf('text/html') > -1) {
    var oldData = e.clipboardData.getData('text/html');
    var newData = '<b>Ha Ha!</b> ' + oldData;

    // 貼り付け操作をキャンセルするため、手動でデータをドキュメントに貼り付けます。
    pasteClipboardData(newData);

    // デフォルトの貼り付け動作を防ぐために必要です。
    e.preventDefault();
  }
});

6.4. 必須データ型

実装は、以下のデータ型についてOSのクリップボード形式の説明を認識し、DataTransferItemList やClipboardItem を適切に記述することで、貼り付けイベント時に正しい内容を提供し、コピー・切り取りイベント時にはOSクリップボード上に正しいデータ形式を設定しなければなりません。

6.4.1. クリップボードからの読み取り

これらのデータ型は、クリップボード上に対応するネイティブ型が存在する場合、pasteイベントで公開されなければなりません:

• text/plain

• text/html

• image/png

6.4.2. クリップボードへの書き込み

これらのデータ型は、copy・cutイベント時にDataTransfer オブジェクトに追加された場合、対応するネイティブ型の説明と共にクリップボードへ配置されなければなりません。

• text/plain

• text/html

• image/png

警告！信頼されていないスクリプトがクリップボードへ書き込めるデータ型は、セキュリティ対策として制限されています。信頼されていないスクリプトは、ローカルソフトウェアの脆弱性を引き起こす既知のデータをクリップボードに配置しようとする場合があります。

6.5. 任意データ型

実装は、以下のデータ型についてOSのクリップボード形式の説明を認識してもよく、ClipboardItem を貼り付けイベント時に適切に記述し、コピー・切り取りイベント時にはOSクリップボード上に正しいデータ形式を設定してもよいです。

これらのデータ型は、クリップボード上に対応するネイティブ型が存在する場合、UAによって公開されることがあります:

• text/uri-list

• image/svg+xml

• カスタムフォーマットで、"web "（"web"の後にU+0020 スペース）で始まり、末尾（"web "除去後）がMIME型のパースチェックをパスするもの。

6.6. 未サニタイズデータ型

以下のデータ型はUAによってサニタイズされてはなりません:

• image/png

以下のデータ型はUAによってサニタイズされない場合があります:

• 任意未サニタイズデータ型

任意未サニタイズデータ型とは、ウェブ著者が指定するもので、UAによってサニタイズされない場合があるmime typeです。 有効な任意未サニタイズデータ型は以下の通りです:

• text/html

任意未サニタイズデータ型は、UAのプライバシー要件によってサポートされない場合があります。

7. 非同期クリップボードAPI

7.1. Navigatorインターフェース

partial interface Navigator {
  [SecureContext, SameObject] readonly attribute Clipboard clipboard;
};

7.2. ClipboardItemインターフェース

typedef Promise<(DOMString or Blob)> ClipboardItemData;

[SecureContext, Exposed=Window]
interface ClipboardItem {
  constructor(record<DOMString, ClipboardItemData> items,
              optional ClipboardItemOptions options = {});

  readonly attribute PresentationStyle presentationStyle;
  readonly attribute FrozenArray<DOMString> types;

  Promise<Blob> getType(DOMString type);

  static boolean supports(DOMString type);
};

enum PresentationStyle { "unspecified", "inline", "attachment" };

dictionary ClipboardItemOptions {
  PresentationStyle presentationStyle = "unspecified";
};

clipboardItem = new ClipboardItem([items, options])

新しいClipboardItem オブジェクトを作成します。itemsは表現のリストを表し、各表現はmime typeと、対応するPromise とBlobまたはDOMStringを持ちます。optionsは ClipboardItemOptions の値を設定するために使います。下記の例を参照してください。

const format1 = 'text/plain';
const promise_text_blob = Promise.resolve(new Blob(['hello'], {type: format1}));
const clipboardItemInput = new ClipboardItem(
  {[format1]: promise_text_blob},
  {presentationStyle: "unspecified"});

clipboardItem.getType(type)

mime type typeに対応するPromise をBlobとして返します。

clipboardItem.types

このクリップボードアイテムオブジェクト内のmime typeのリストを返します。

ClipboardItem.supports(type)

typeが必須データ型または任意データ型に含まれていればtrue、そうでなければfalseを返します。

クリップボード項目は、 概念的には、ユーザーが「cut」または「copy」 コマンドを呼び出すことによって共有可能にしたいという意思を示したデータである。クリップボード項目は 2つの目的を果たす。第一に、ユーザーによってシステムクリップボードにコピーされたデータをウェブサイトが読み取れるようにする。第二に、 ウェブサイトがシステムクリップボードへデータを書き込めるようにする。

たとえば、ユーザーがネイティブアプリケーションのスプレッドシートからセル範囲をコピーした場合、それは 1つのクリップボード項目になる。ユーザーが デスクトップからファイルの集合をコピーした場合、そのファイル一覧は複数のクリップボード項目として表される。

一部のプラットフォームでは、クリップボード上に一度に複数のクリップボード項目を持つことをサポートする場合がある一方で、他のプラットフォームでは 以前のクリップボード 項目が新しいものに置き換えられる。

クリップボード項目は、表現の リストを持ち、各表現は、関連付けられたMIME 型（MIME 型）、初期値が falseであるisCustomフラグを持ち、このフラグは この表現を（システムクリップボードの よく知られた形式ではなく）ウェブカスタム形式として扱うべきかどうかを示し、さらにデータ（ClipboardItemData）を持つ。

ウェブカスタム形式は、 isCustomがtrueに設定されている。

ユーザーがスプレッドシートからセル範囲をコピーする例では、それは画像 （image/png）、HTML表（text/html）、プレーンテキスト（text/plain）、またはウェブカスタム形式（web text/csv）として表される場合がある。

これらのMIME 型はそれぞれ、同じクリップボード項目の異なる 忠実度レベルの表現を記述し、貼り付け時に対象アプリケーションが クリップボード項目をより利用しやすくする。

セル範囲を画像として利用可能にすると、ユーザーはそのセルを写真編集 アプリに貼り付けられるようになり、一方でtext/plain形式はテキストエディターアプリで使用できる。

クリップボード項目は、表示スタイル （PresentationStyle）を持つ。 これは、クリップボード項目を「貼り付ける」アプリが、適切な表現の内容を 貼り付け位置にインラインで挿入すべきか、それとも添付ファイルとして扱うべきかを区別するのに役立つ。

単一のクリップボード項目のみの貼り付けをサポートするウェブアプリは、最初のクリップボード項目を使用するべきである。

write() は最後のクリップボード 項目を選択する。

複数のクリップボード項目の貼り付けをサポートするウェブアプリは、たとえば、 各クリップボード項目の内容をプレビューし、どれを貼り付けるかを ユーザーが選択できるユーザーインターフェイスを提供できる。さらに、アプリは貼り付けるクリップボード項目のMIME 型を列挙し、 何らかのアプリ固有のアルゴリズムに従って、そのアプリに最も適したものを選択することが期待される。 あるいは、アプリはクリップボード項目をどのように貼り付けるか、たとえば「画像として貼り付け」や「書式付きテキストを貼り付け」などの選択肢をユーザーに提示できる。

ClipboardItem オブジェクトには、関連付けられたクリップボード項目があり、これはクリップボード項目である。

ClipboardItem オブジェクトには、関連付けられたtypes 配列があり、これはFrozenArray<DOMString>である。

ClipboardItem オブジェクトには、関連付けられた読み取り時のクリップボード変更 カウントがあり、これは初期値がnullである。

ClipboardItem オブジェクトには、関連付けられた元のシステムクリップボード 項目があり、これはシステムクリップボード項目またはnullであり、初期値はnullである。

ClipboardItem オブジェクトには、関連付けられたサニタイズされていないMIME型があり、これはsequence<DOMString>で、 初期値は空である。

ClipboardItem オブジェクトには、関連付けられたリゾルバー付き表現があり、 これは文字列（getType()に渡されたMIME 型で、 存在する場合は`"web "`接頭辞を含む）からPromise<Blob>へのmapで、 初期値は空である。各エントリーは、その型について完了済みまたは現在進行中のOSクリップボード読み取りを表す。

Note: このmapは、read() から取得したClipboardItemに対する、同じMIME型の同時getType() 呼び出しが、単一のOSクリップボード読み取りを共有することを保証する。最初の呼び出しは保留中のPromise をmapに挿入して読み取りを開始し、同じMIME型に対する後続の呼び出しは、システムクリップボードを再読み取りすることなく既存のPromise を返す。

read()によってClipboardItem が作成された場合、それはデータスナップショットではなく遅延フェッチャーとして機能する。そのtypes 配列は、read() 呼び出し時点でシステムクリップボード上で利用可能な 形式を反映するが、実際のペイロードバイトはgetType() が呼び出されるまで読み取られない。read() 呼び出しと後続のgetType() 呼び出しの間にシステム クリップボードの内容が変更された場合、getType() 呼び出しは拒否される。ClipboardItem(items, options) コンストラクターを介して直接構築されたClipboardItem は、この挙動の対象ではない。

クリップボード項目 clipboardItemおよびRealm realmが与えられたとき、ClipboardItem オブジェクトを作成するには、次の手順を実行する：

1. clipboardItemObjectを、realmを伴う新しいClipboardItem とする。

2. clipboardItemObjectのクリップボード項目をclipboardItemに設定する。

new ClipboardItem(items, options) コンストラクター手順は次のとおり：

1. itemsが空である場合、TypeErrorを投げる。

2. optionsが空である場合、options["presentationStyle"] = "unspecified"に設定する。

3. thisの クリップボード項目を、新しいクリップボード項目に設定する。

4. thisの クリップボード項目の表示スタイルを、 options["presentationStyle"]に設定する。

5. typesをDOMStringのリストとする。

6. items内の各（key, value）について：

   1. representationを新しい表現とする。

   2. isCustomをfalseとする。

   3. keyが`"web "`接頭辞で始まる場合、

      1. `"web "`接頭辞を削除し、残りの文字列をkeyに代入する。

      2. isCustomをtrueに設定する

   4. representationのisCustomフラグをisCustomに設定する。

   5. mimeTypeを、keyを与えてMIME 型を解析する結果とする。

   6. mimeTypeがfailureである場合、TypeErrorを投げる。

   7. thisのクリップボード項目の表現の リストが、MIME 型が mimeTypeであり、かつ[representation/isCustom]がisCustomである表現を含む場合、TypeErrorを投げる。

   上記の手順は、ユーザー エージェントによく知られているMIME型と、作者がカスタム型として扱うことを意図したものとの衝突を防ぐ。たとえば、 作者の項目リストに"text/html"と "web text/html"の両方の表現を含めることが可能である。

   1. representationのMIME 型をmimeTypeに設定する。

   2. representationのデータをvalueに設定する。

   3. representationをthisのクリップボード項目の表現の リストに追加する。

   4. mimeTypeStringを、mimeTypeでMIME 型を直列化する結果とする。

   5. isCustomがtrueである場合、mimeTypeStringの前に`"web "`を付加する。

   6. mimeTypeStringをtypesに追加する。

7. thisの types 配列を、typesから凍結配列を作成するを実行した結果に設定する。

7.2.1. presentationStyle

presentationStyle ゲッターの手順は、thisのclipboard itemのpresentation styleを返すこと。

7.2.2. types

types ゲッターの手順は、thisのtypes arrayを返すこと。

7.2.3. getType(type)

このメソッドは以下の手順を実行する：

1. realmを、thisの関連Realmとする。

2. isCustomをfalseとする。

3. typeが`"web "`接頭辞で始まる場合：

   1. `"web "`接頭辞を削除し、残りの文字列をtypeに代入する。

   2. isCustomをtrueに設定する。

4. mimeTypeを、typeを与えてMIME 型を解析する結果とする。

5. mimeTypeがfailureである場合、TypeErrorを投げる。

6. itemTypeListを、thisのクリップボード項目の表現の リストとする。

7. pを、realm内の新しいpromiseとする。

8. itemTypeList内の各representationについて：

   1. representationのMIME 型がmimeTypeであり、かつ representationのisCustomがisCustomである場合：

      1. thisの読み取り時のクリップボード変更 カウントがnullでなく、かつ現在のクリップボード 変更カウントがthisの読み取り時のクリップボード変更 カウントと等しくない場合、realm内の"InvalidStateError" DOMException でpを拒否し、 pを返す。

         Note: これにより、古くなった データが返されないことが保証される。read() が呼び出されてからシステムクリップボードの内容が変更されている場合、 現在のシステムクリップボード状態に対応しないデータを返すのではなく、 これは失敗しなければならない。

         Note: nullの読み取り時のクリップボード変更 カウントは、このClipboardItem が作者によって直接構築された（たとえばClipboardItem(items, options)を介して） ものであり、read() から取得されたものではないことを示す。その場合、データはシステムクリップボードに由来しないため、古いデータかどうかのチェックは不要である。

      2. thisの読み取り時のクリップボード変更 カウントがnullでない場合：

         Note: この分岐は、ClipboardItemのうち、 read() から取得されたものを扱う。この場合、OSクリップボードの読み取りはこの時点まで遅延される。同じMIME型に対してgetType() が複数回同時に呼び出された場合でも、読み取りが型ごとに高々一度だけ発生するようにするため、結果のPromise は、正規化された型文字列をキーとしてthisのリゾルバー付き 表現mapにキャッシュされる。これにより、`"text/html"`と `"web text/html"`は別々に追跡される一方で、同じ型の大文字小文字の異なる表記 （たとえば`"text/HTML"`と`"text/html"`）は単一のエントリーにまとめられる。

         1. keyを、mimeTypeのessenceとする。isCustomが trueである場合、keyの前に`"web "`を付加する。

         2. thisのリゾルバー付き 表現[key]が存在する場合、thisのリゾルバー付き 表現[key]を返す。

         3. 設定する：thisのリゾルバー付き 表現[key]をpに。

         4. 以下の手順を並列に実行する：

            1. clipboardItemを、thisの元の システムクリップボード項目とする。

            2. clipboardItemがnullである場合、realmのグローバルオブジェクトを与えて、グローバルタスクをキューに入れる。これは クリップボードタスクソース上で、 realm内の"InvalidStateError" DOMException でpを拒否するためのものであり、その後これらの手順を中止する。

            3. isCustomがtrueである場合：

               1. mapNameを、OS固有の カスタムマップ名とする。

               2. mapRepresentationを、clipboardItemのシステム クリップボード表現のリスト内にあるシステム クリップボード表現であって、その名前 がmapNameであるものとする。そのようなシステム クリップボード表現がない場合、realmのグローバルオブジェクトを与えて、 グローバル タスクをキューに入れる。これはクリップボードタスク ソース上で、realm内の "NotFoundError" DOMException でpを拒否するためのものであり、その後これらの手順を中止する。

               3. webCustomFormatMapStringを、mapRepresentationのデータから逆シリアル化されたJSON文字列とする。

               4. osFormatNameを、直列化されたmimeTypeと一致するキーを持つ、 webCustomFormatMapString内の値とする。

               5. osFormatNameが見つからない場合、realmのグローバルオブジェクトを与えて、 グローバル タスクをキューに入れる。これはクリップボードタスク ソース上で、realm内の "NotFoundError" DOMException でpを拒否するためのものであり、その後これらの手順を中止する。

            4. そうでなければ、osFormatNameを、mimeTypeを与えてOS固有の 既知形式を実行した結果とする。

            5. clipboardRepresentationを、clipboardItemのシステムクリップボード 表現のリスト内にあるシステムクリップボード 表現であって、その名前が osFormatNameであるものとする。そのようなシステムクリップボード 表現がない場合、realmのグローバルオブジェクトを与えて、グローバルタスクをキューに入れる。これは クリップボードタスクソース上で、 realm内の"NotFoundError" DOMException でpを拒否するためのものであり、その後これらの手順を中止する。

            6. rawDataを、clipboardRepresentationのデータとする。

            7. cleanDataを、rawDataのコピーとする。

            8. mimeTypeのessenceがthisのサニタイズされていない MIME 型内にあり、かつmimeTypeのessenceが任意の サニタイズされていないデータ型リスト内にある場合、何もしない。

            9. そうでなく、mimeTypeのessenceが"image/png"でない場合、 ユーザーエージェントはcleanDataをサニタイズしてもよい。

            10. blobを、Blob とする。そのtype は直列化されたmimeTypeであり、その 基になるバイト列はcleanDataである。

            11. realmのグローバルオブジェクトを与えて、グローバルタスクをキューに入れる。これは クリップボードタスクソース上で、 pをblobで解決するためのものである。

         Note: pが settledになると、それはthisのリゾルバー付き 表現map内に残る。同じMIME型に対する後続のgetType() 呼び出しは、システムクリップボードを再読み取りすることなく、 キャッシュされたsettledのPromise を返す。ただし、上記の古いデータかどうかのチェックは、すべての呼び出しに引き続き適用される。すなわち、read() が呼び出されてからシステムクリップボード が変更されている場合、このClipboardItem上のすべてのgetType() 呼び出しは、以前にキャッシュされたデータであっても、"InvalidStateError" で拒否される。

         1. pを返す。

      3. representationDataPromiseを、representationのデータとする。

      4. representationDataPromiseに反応する：

         1. representationDataPromiseが値 vで履行された場合：

            1. vがDOMStringである場合、 以下の手順に従う：

               1. dataAsBytesを、vをUTF-8符号化 した結果とする。

               2. blobDataを、dataAsBytesを用いて作成されたBlob とし、そのtype は直列化されたmimeTypeに設定される。

               3. pをblobDataで解決する。

            2. vがBlobである場合、 以下の手順に従う：

               1. pをvで解決する。

         2. representationDataPromiseが拒否された場合：

            1. realm内の"NotFoundError" DOMException でpを拒否する。

               ウェブ開発者は、 根本的な拒否理由に関心を持つ可能性がある。

      5. pを返す。

9. realm内の"NotFoundError" DOMException でpを拒否する。

10. pを返す。

7.2.4. supports(type)

このメソッドは以下の手順を実行する：

1. typeが必須データ型または任意データ型に含まれる場合、trueを返す。

2. そうでなければ、falseを返す。

7.3. Clipboardインターフェース

typedef sequence<ClipboardItem> ClipboardItems;

[SecureContext, Exposed=Window]
interface Clipboard : EventTarget {
  Promise<ClipboardItems> read(optional ClipboardUnsanitizedFormats formats = {});
  Promise<DOMString> readText();
  Promise<undefined> write(ClipboardItems data);
  Promise<undefined> writeText(DOMString data);
};

dictionary ClipboardUnsanitizedFormats {
  sequence<DOMString> unsanitized;
};

Clipboard インターフェイスの一部のメソッドは、複数のClipboardItem オブジェクトを受け取る、または返す。しかし、すべてのプラットフォームが複数のクリップボード項目をサポートしているわけではない。そのようなプラットフォームでは、以下のアルゴリズムは write()に渡された、最初のものを超える ClipboardItem オブジェクトを無視し、 read() およびreadText() はOSから1つのクリップボード項目のみを取得する。

クリップボード項目群 オブジェクトは、クリップボード項目のsequenceである。

ウェブ作者は、write(data) メソッドを使用してシステムクリップボードに内容を書き込むために、ClipboardItemの配列である dataを作成する必要がある。 read() は、システムクリップボードデータの内容を表す クリップボード項目群オブジェクトへのPromise を返す。

unsanitized は、作者が任意のサニタイズされていないデータ型として扱われることを望むMIME型に対応する、DOMStringの sequenceである。

unsanitized オプションはユーザーエージェントによってサポートされない場合がある。プライバシーモードなど、このオプションが許可されない場合があり得るため、 ウェブ作者は、unsanitized に列挙されたMIME型の内容がサニタイズされないと仮定すべきではない。

クリップボードタスク ソースは、システムクリップボードデータの読み取りまたは書き込みに応答してトリガーされる。

// clipboard.read() は型メタデータのみを含むClipboardItemを返す。
// この時点ではOSクリップボードデータは読み取られない。
const items = await navigator.clipboard.read();

// getType()が呼び出されると、この時点でOSクリップボードの読み取りが遅延して行われる。
const textBlob = await items[0].getType("text/plain");
const text = await (new Response(textBlob)).text();

navigator.clipboard.readText().then(function(data) {
  console.log("取得した文字列: ", data);
});

var data = [new ClipboardItem({ "text/plain": Promise.resolve(new Blob(["Text data"], { type: "text/plain" })) })];
navigator.clipboard.write(data).then(function() {
  console.log("クリップボードへのコピーに成功しました！");
}, function() {
  console.error("クリップボードへの書き込みに失敗しました :-(");
});

await navigator.clipboard.writeText("こんにちは！");

8. クリップボードアクション

このセクションでは、クリップボードアクションおよびイベント発火の処理モデルについて定義します。

各クリップボードアクションには、script-triggeredとscript-may-access-clipboardという2つのフラグがあります。

script-triggeredフラグは、例えばdocument.execCommand()の呼び出しなど、スクリプトによってアクションが実行された場合にセットされます。今後クリップボードと連携するスクリプトAPIもこれらのアクションを利用し、script-triggeredフラグを適切にセットする必要があります。

8.1. コピーアクション

8.2. 切り取りアクション

8.3. 貼り付けアクション

貼り付けアクションについては、script-may-access-clipboardフラグは、クリップボードから読み取れるサイトやアプリを決定する実装依存の権限機構に依存します。スクリプトによって貼り付けアクションがトリガーされた場合、実装はユーザーの許可なしにクリップボードの内容を利用可能にしてはなりません。権限が未付与の場合、許可ダイアログにはスクリプトスレッドに関連付けられたドキュメントのホスト名を含めなければなりません。

9. Permissions APIとの統合

[permissions] APIは、ウェブサイトが強力な機能（クリップボードなど）へアクセスするための統一的な方法を提供します。これにより、ウェブサイトはユーザーから権限を要求したり、どの権限があるかを照会できます。

クリップボードについては、1つの権限が定義されています："clipboard-write"

注: クリップボード権限は現在、非同期クリップボードAPIのみに適用されます。将来の本仕様のバージョンでは、他のクリップボード操作にもこの権限が適用される可能性があります。

これらのクリップボード権限は強力な機能であり、権限関連のアルゴリズムと型は以下のように定義されます：

permission descriptor type

dictionary ClipboardPermissionDescriptor : PermissionDescriptor {
  boolean allowWithoutGesture = false;
};

クリップボード権限は4種類あります：

• { name: "clipboard-write", allowWithoutGesture: false }

• { name: "clipboard-write", allowWithoutGesture: true }

それぞれの関係は次の通りです：

• { "clipboard-write" + true }は{ "clipboard-write" + false }より強い権限です。

ユーザーエージェントは本仕様で記載されたClipboardPermissionDescriptor を必ずサポートしなければなりませんが、デフォルト設定やユーザーへの表示方法（あるいは表示しない方法）については完全に制御できます。

9.1. クリップボード読み取り権限

9.2. クリップボード書き込み権限

10. セキュリティに関する考慮事項

著者がユーザーによってコピーされる内容を変更したり、選択されたことのないデータを自動的にコピーしたり、情報の貼り付けを無制限に許可することは、様々なセキュリティ上の懸念を引き起こす可能性があります。

例えば以下のようなシナリオがあります：

• ユーザーがリンクを選択してコピーしたのに、異なるリンクがクリップボードにコピーされる。これは、貼り付け時に予期しない結果を招く場合からフィッシング攻撃の試みまで、影響が及ぶ可能性があります。

• (Self-XSS) シェルコマンドや実行可能なスクリプトがクリップボードに置かれ、ユーザーが貼り付けた内容を実行することを意図している。

• OSの画像処理コードのバグを悪用するために細工された画像がクリップボードに書き込まれる。

10.1. HTMLやマルチパートデータの貼り付け

このセクションは規範的ではありません。

フォーマット済みデータやマルチパートデータの貼り付けには特定のセキュリティリスクがあります。

• ユーザーが隠れたデータを気付かず貼り付けてしまう可能性があります。例えば、マークアップに<input type="hidden">タグやHTMLコメントが含まれている場合です。こうした隠れたデータには機密情報が含まれていることがあります。

• ユーザーが信頼されたページに悪意のあるJavaScriptを貼り付けてしまう可能性があります。

• 実装が、ユーザーが意図していないローカルファイルへのスクリプトのアクセスを許可する可能性があります。

どのようなポリシーを採用するかは、以下の要素を考慮して判断します：

• 貼り付けるデータのオリジン

• 画像など参照されているデータのサブパーツのオリジン

• 実行中のスクリプトのオリジン

シナリオと考えられるセキュリティポリシーの概要：

一部の実装は、リッチテキスト貼り付け時にSCRIPT要素やjavascript:リンクなど悪意のある可能性のある内容をデフォルトで除去することでリスクを軽減しますが、pasteイベントハンドラで元の未サニタイズデータを取得・処理できるようにしています。

10.2. 一般的なセキュリティポリシー

実装は、参照されたオンラインリソースをダウンロードしたり、その内容をfiles リストやDataTransferItemListで公開してはなりません。

クリップボード上のデータがローカルアプリケーション由来でない場合、実装は参照されているローカルファイルへのアクセスを許可してはなりません。例えば、データに<img src="file://localhost/example.jpg">が含まれていても、データのオリジンがオンラインリソースであれば、example.jpgのエントリをclipboardData.itemsリストに追加してはなりません。

10.3. 画像のトランスコード

悪意のある画像データがクリップボードに置かれるのを防ぐため、画像データは安全なバージョンにトランスコードされる場合があります。これによって、ウェブサイトが他のアプリケーションの脆弱性を悪用するのを防止します。

実装は、クリップボードから画像を読み取る場合はトランスコードすべきではありません。画像のトランスコードは、画像の物理的な解像度など重要なメタデータを失う可能性があります。 これは、画像がウェブサイトと共有される他の方法（たとえば`<input type=file>`）とも一貫しています。

10.4. 迷惑行為対策

スクリプトはDataTransfer APIを使って、コピーや切り取りイベントでシステムクリップボード上のデータを変更し、ユーザーを困惑・混乱させる場合があります。本仕様はこうした迷惑行為の防止までは意図していませんが、実装は追加の制限を設けてもかまいません。

実装は、スクリプトが過剰な量のデータをクリップボードに置こうとした場合も、適切に処理しなければなりません。

11. プライバシーに関する考慮事項

これらのAPIはユーザーのクリップボードデータへのアクセスを提供するため、クリップボードに氏名や住所、パスワードなど個人を特定できる情報（PII）が含まれている可能性があり、重大なプライバシー上の懸念があります。

一般的に、ユーザーエージェントは信頼されていないスクリプトがこれらのAPIを使ってユーザーのクリップボードデータに無制限にアクセスすることを許可してはなりません。

11.1. プライバシーとクリップボードイベントAPI

Clipboard Event APIは、クリップボードイベントハンドラのコンテキスト内で実行されているスクリプトに、システムクリップボードのコピーへのアクセスと、クリップボードに書き込まれるデータの変更の可能性を提供します。

ユーザーエージェントは、Clipboard Event APIでアクセスできるデータのセキュリティを確保するため、以下の点に注意すべきです：

• DataTransfer インターフェースを実装するオブジェクトでクリップボードデータを返す場合、そのオブジェクトはデータが提供されたClipboardEventイベントハンドラの外部では利用可能であってはなりません。

• スクリプトがDataTransfer インターフェースを実装したオブジェクトへの参照をClipboardEventイベントハンドラ外部で利用しようとした場合、すべてのメソッドはそのコンテキスト外で呼び出されたとき何もしない（no-op）ようにしなければなりません。

• 実装は、スクリプトが合成クリップボードイベントを作成して本物のクリップボードデータにアクセスできるようにしてはなりません（ユーザーがそう設定した場合を除く）。

Clipboard Event APIはClipboard permissionの対象ではありませんが、ユーザーエージェントはこのAPI自体を無効化したり、アクセスを許可するサイトを設定できる方法を提供してもかまいません。

11.2. プライバシーと非同期クリップボードAPI

非同期クリップボードAPIは強力な機能であり、すべてのスクリプトからクリップボードデータにアクセスできる（Clipboard Eventハンドラに限定されない）上に、ユーザー操作なしでもデータにアクセス可能となる場合があります。

悪用防止のため、このAPIはスクリプトがフォーカスを持つ文書のコンテキスト内で実行されている場合にのみ利用可能でなければなりません。

11.2.1. プライバシーとクリップボード権限

クリップボード権限はこのAPIへのアクセスを制御しますが、ユーザーエージェントは権限のデフォルト値やユーザーが設定可能な権限項目を選択できます。例えば、ユーザーエージェントはユーザー操作がある場合のみ非同期クリップボードAPIへのアクセスを許可し、操作なしの場合はスクリプトからのアクセス要求を常に拒否するようにできます。

ユーザーエージェントは、ユーザーが権限を与えてから一定時間が経過した後や、ユーザーがサイトを最後に訪問してから一定時間が経過した後、あるいはユーザーがページから離れた場合などに、権限を自動的に失効させる選択も可能です：

• 権限付与から一定時間経過後

• ユーザーがサイトを最後に訪問してから一定時間経過後

• ユーザーがページから離脱したとき

11.3. その他のプライバシー懸念

ユーザーエージェントがdocument.execCommand("paste")を使ってクリップボードデータの読み取りを許可する場合、ユーザーが明示的にそのアクセスを許可したことを必ず確認しなければなりません。

12. 謝辞

このセクションは規範的ではありません

編集者は本仕様の現行状態に導くため、様々な会議やメーリングリストで支えてくださった前任編集者の貢献に感謝します。

• Hallvord R. M. Steen

編集者はまた、MicrosoftによるData Transfer機能のドキュメント[MICROSOFT-CLIP-OP]や[HTML5]仕様の初期ドラフトから得られた知的財産にも謝意を表します。Paul Libbrecht氏によるドラフト「安全なコピー＆ペースト」にも感謝します（このドラフトはWeb上から入手できなくなっています）。

最後に、下記の方々の貢献にも感謝いたします：

Adam Barth, Shawn Carnell, Daniel Cheng, Daniel Dardailler, Domenic Denicola, Al Gilman, James Graham, James Greene, Ian Hickson, Darwin Huang, Lachlan Hunt, Philip Jägenstedt, Anne van Kesteren, Marijn Kruisselbrink, Aaron Leventhal, Jim Ley, Paul Libbrecht, "Martijn", Glenn Maynard, Chris Mills, ms2ger, Ryosuke Niwa, Robert O’Callahan, Dave Poehlman, "ROBO Design", Janina Sajka, Rich Schwerdtfeger, Jonas Sicking, Maciej Stachowiak, Mihai Sucan, Dmitry Titov, Ojan Vafai, Tarquin Wilton-Jones, Tom Wlodkowski, Bo Cupp, mbrodesser および Boris Zbarsky.

付録A: アルゴリズム