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

1. はじめに

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

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

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

クリップボードイベントAPI - このAPIは、切り取り、コピー、貼り付けなど一般的なクリップボード操作にフックし、ウェブアプリケーションが必要に応じてクリップボードデータを調整できるようにします。
非同期クリップボードAPI - このAPIは、クリップボードデータの直接読み書きを提供します。これは強力な機能とみなされるため、このAPIへのアクセスは権限によって制御されます。

2. ユースケース

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

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

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

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

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

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

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

リモートデバイスからローカルクリップボードへデータをコピーするには、ウェブアプリケーションがリモートのクリップボードデータを取得し、write()でローカルクリップボードへ書き込みます。

ローカルクリップボードデータをリモートデバイスへコピーするには、ウェブアプリケーションがclipboardchangeイベントを監視し、クリップボードが更新されるたびにread()でクリップボードからデータを取得し、新しいクリップボードデータをリモートデバイスへ送信します。

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;
};

clipboardData: イベントに関連するデータやメタデータを保持するためのDataTransfer オブジェクトです。

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

clipboardData: clipboardData属性はDataTransfer インターフェースのインスタンスであり、ユーザーによるコピー・切り取り・貼り付け操作の間、スクリプトがシステムクリップボード上の値を読み取り・操作できるようにします。関連するドラッグデータストアはシステムクリップボードのライブかつフィルタされたビューであり、スクリプトが安全にアクセスできる必須データ型のみが公開されます。合成イベントの場合、ドラッグデータストアにはイベントを作成したスクリプトが追加したデータのみが含まれます。; clipboardDataオブジェクトのitems やfiles プロパティによって、クリップボードのマルチパートや非テキストデータの処理が可能です。

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

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を使用してスクリプトがクリップボードに書き込んだ場合
ユーザーエージェント外でクリップボードが更新された場合

5.2.1.1. clipboardchange イベントを発火するには

clipboardchange イベントを発火するためには、Document document を与える：

document がスティッキーアクティベーションを持っておらず、かつ document にクリップボードの読み取り許可がない場合、リターンする。
global を document の関連グローバルオブジェクトとする。
document がシステムフォーカスを持つ場合：
1. types を必須データ型のリストとし、システムクリップボードで利用できるものとする。
2. changeId を changeId を生成するを document で実行した結果とする。
3. eventInit を新しい ClipboardChangeEventInit 辞書とし、types メンバーを types に、changeId メンバーを changeId に設定する。
4. イベント発火を clipboardchange という名前で global を対象に、ClipboardChangeEvent を使い、eventInit で行う。
document がシステムフォーカスを持たない場合：
1. documentの clipboardchange 保留フラグを true に設定する。

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

5.2.1.2. Document フォーカス時の手順

Document document がシステムフォーカスを獲得したとき：

document の clipboardchange 保留フラグが true の場合：
1. document の clipboardchange 保留フラグを false に設定する。
2. types を必須データ型のリストとし、システムクリップボードで利用できるものとする。
3. changeId を changeId を生成するを document で実行した結果とする。
4. eventInit を新しい ClipboardChangeEventInit 辞書とし、types メンバーを types に、changeId メンバーを changeId に設定する。
5. global を document の関連グローバルオブジェクトとする。
6. イベント発火を clipboardchange という名前で global を対象に、ClipboardChangeEvent を使い、eventInit で行う。

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

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

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

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

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

types: 必須データ型を表すDOMString のシーケンスで、システムクリップボードで利用できるもの。
changeId: クリップボード変更操作の一意識別子である bigint。

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

types

このイベントが発火したとき、必須データ型を示す DOMString オブジェクトのFrozenArrayを返します。オプションデータ型やカスタム形式は除きます（フィンガープリント防止のため）。

changeId

このクリップボード変更操作の一意識別子である bigint を返します。この識別子は同じストレージキーを持つすべてのウィンドウ・タブで一致し、複数ウィンドウで同じクリップボード通知が複数回届く場合にアプリケーション側で重複排除できます。

changeId は暗号学的に導出された 128 ビット整数です。保証されているのは、クリップボードへの書き込み後は changeId の値が書き込み前と異なることだけです。

5.2.1.3. ClipboardChangeEvent コンストラクタのステップ

ClipboardChangeEvent(type, eventInitDict) コンストラクタの手順は次の通り：

this.types に、eventInitDict["types"] のクローンを設定する。
this.changeId に eventInitDict["changeId"] を設定する。

5.2.1.4. ChangeId 生成

changeId を生成するには、Document document を与える：

globalChangeId を、システムクリップボードの現在状態を表すユーザーエージェント固有の一意識別子とする。この識別子は、システムクリップボードが変更されるたびに変化し、ユーザーエージェントの再起動時にリセットされる。
storageKey を document のストレージ以外の目的でストレージキーを取得を実行した結果とする。
storageKeyBytes を storageKey のユーザーエージェント固有のバイナリ表現とする。
hashedValue を、暗号学的ハッシュ関数（例えばSHA-256）を globalChangeId（バイト列）と storageKeyBytes を連結したものに適用した結果とする。
hashedValue の先頭128ビットなどを利用して、128ビット整数を返す。

上記のアルゴリズムにより、同じオリジンかつ同じパーティションの document は、同じクリップボード変更に対し同じ changeId を受け取り、複数ウィンドウでのイベント重複排除が可能になり、追跡に利用されるようなパーティションをまたぐ相関を防止できます。クライアントサイドのストレージパーティショニングの変更がストレージキー定義に組み込まれると、この方法は自動的にパーティションをまたいだ匿名化を提供します。

changeId は、globalChangeId カウンターがユーザーエージェントの再起動でリセットされるため、ブラウザの再起動後は保持されません。同様に、ユーザーがサイトデータを消去した場合、影響を受けたタブはリロードされ、リスナーが付け直され、今後の新しい changeId のイベントのみ受信します。

合成 cut および copy イベントはシステムクリップボードを更新しないため、 "clipboardchange" イベントは発火しません。

clipboardchange イベントを活用することで、ウェブアプリケーションは効率的にクリップボードの変化を監視し、利用可能なデータ形式に基づいた動的なUIを提供できます：

// 複数ウィンドウを持つアプリケーションで、処理済みの changeId を追跡して重複を回避
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;
				
  // リモートデスクトップアプリでは、各 change ごとに一度だけ同期
  if (hasText || hasHTML || hasImage) {
    syncClipboardToRemote(e.changeId);
  }
});

// または onclipboardchange プロパティも利用可
// navigator.clipboard.onclipboardchange = (e) => { ... };

このイベント駆動方式は、read() や readText() などによるポーリングより効率的であり、クリップボードアクセスにユーザーアクティベーションが必要なブラウザでも動作します。UIはタイマーを待たず、クリップボード変化に即応できます。 changeId は特に複数ウィンドウのあるアプリで有用で、同じストレージキーを持つすべてのウィンドウでクリップボード変更を一度だけ処理できます。

5.2.2. `copy` イベント

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

イベントがキャンセルされない場合、現在選択されているデータがシステムクリップボードへコピーされます。現在のドキュメントの選択範囲は変化しません。

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

このイベントの処理モデルの詳細は§ 8.1 コピーアクションを参照してください。

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

5.2.3. `cut` イベント

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

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

非編集可能コンテキストの場合、clipboardData は空リストになります。この場合でもcut イベントは発火します。

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

このイベントの処理モデルの詳細は§ 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からコピー・切り取り・貼り付けアクションをトリガーする際の手順:

対応するアクションを同期的に実行する。
アクションの戻り値を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() を呼び出してイベントをキャンセルする必要があります。

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.1.1. clipboard

これはシステムクリップボードからの読み書き操作を実行するために使用されます。 clipboard のgetter手順は、thisの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を返します。

クリップボードアイテムは、ユーザーが「切り取り」や「コピー」コマンドを実行することで共有可能にしたいデータを概念的に表します。クリップボードアイテムには2つの役割があります。1つ目は、ウェブサイトがユーザーによってシステムクリップボードにコピーされたデータを読み取れるようにすること。2つ目は、ウェブサイトがシステムクリップボードへデータを書き込めるようにすることです。

例えばユーザーがネイティブアプリのスプレッドシートからセル範囲をコピーした場合、1つのクリップボードアイテムになります。ユーザーがデスクトップから複数のファイルをコピーした場合は、そのファイルリストは複数のクリップボードアイテムとして表現されます。

プラットフォームによっては、クリップボード上に複数のクリップボードアイテムを同時に保持できる場合もあれば、新しいもので前のクリップボードアイテムを置き換える場合もあります。

クリップボードアイテムは、表現のリストを持ち、それぞれの表現には、関連付けられたmimeタイプ（MIME タイプ）、isCustomフラグ（初期値はfalseで、この表現をシステムクリップボードの既知フォーマットではなく、Webカスタムフォーマットとして扱うかを示す）、およびdata（ClipboardItemData）がある。

webカスタムフォーマットはisCustomがtrueに設定されたものです。

スプレッドシートからセル範囲をコピーした場合、image（image/png）、HTMLテーブル（text/html）、プレーンテキスト（text/plain）、webカスタムフォーマット（web text/csv）として表現されることがあります。

これらのMIMEタイプは、同じクリップボードアイテムを異なる忠実度レベルで表現し、貼り付け時にターゲットアプリがより扱いやすくなります。

セル範囲を画像として利用可能にすることで、ユーザーは画像編集アプリに貼り付けることができますし、text/plainはテキストエディタアプリで利用できます。

クリップボードアイテムは表示スタイル（PresentationStyle）を持ちます。これは、アプリがクリップボードアイテムの適切な表現内容を貼り付け時にインライン挿入するか、添付ファイルとして扱うかを区別するために使われます。

1つのクリップボードアイテムのみ貼り付け可能なWebアプリは、最初のクリップボードアイテムを使うべきです。

write() は最後のクリップボードアイテムを選択します。

複数のクリップボードアイテムを貼り付け可能なWebアプリは、例えば各クリップボードアイテムの内容をプレビューするUIを提供し、ユーザーがどれを貼り付けるか選択できるようにしてもよいです。また、アプリは貼り付けるMIMEタイプを列挙し、アプリ独自のアルゴリズムで最適なものを選んでもよいです。あるいは、ユーザーに「画像として貼り付け」「書式付きテキストとして貼り付け」等の選択肢を提示することもできます。

ClipboardItem オブジェクトには対応するクリップボードアイテム（clipboard item）が関連付けられています。

ClipboardItem オブジェクトには対応するtypes array（FrozenArray<DOMString）が関連付けられています。

ClipboardItem オブジェクトを作成するには、clipboard item clipboardItemとRealm realmが与えられたとき、以下の手順を実行します:

clipboardItemObjectをnew ClipboardItemで realmを使って作成する。
clipboardItemObjectのクリップボードアイテムをclipboardItemに設定する。

new ClipboardItem(items, options) のコンストラクタ手順:

itemsが空の場合、TypeErrorをスローする。
optionsが空の場合、options["presentationStyle"] = "unspecified"とする。
thisの clipboard itemを新しいclipboard itemに設定する。
thisの clipboard itemのpresentation styleを options["presentationStyle"]で設定する。
typesをDOMStringのリストとして作成する。
itemsの各(key, value)について:
1. representationを新しいrepresentationとして作成する。
2. isCustomをfalseとする。
3. keyが"web "で始まる場合、
  1. "web "のプレフィックスを取り除き、残りをkeyに代入する。
  2. isCustomをtrueに設定する。
4. representationのisCustomフラグをisCustomで設定する。
5. mimeTypeをkeyに対してMIME型のパースの結果で設定する。
6. mimeTypeが失敗の場合、TypeErrorをスローする。
7. thisのclipboard itemのlist of representationsが、mimeTypeと[representation/isCustom]がisCustomであるrepresentationを含む場合、TypeErrorをスローする。
上記のステップは、ユーザーエージェントがよく知るmime-typeと著者がカスタム型として扱う意図があるものとの衝突を防ぎます。例えば、著者のitemsリストに"text/html"と"web text/html"の両方のrepresentationを含めることが可能です。
1. representationのMIME typeをmimeTypeで設定する。
2. representationのdataをvalueで設定する。
3. representationをthisのclipboard itemのlist of representationsに追加する。
4. mimeTypeStringをmimeTypeでMIME型をシリアライズした結果で設定する。
5. isCustomがtrueの場合、mimeTypeStringの先頭に"web "を付与する。
6. mimeTypeStringをtypesに追加する。
thisの types arrayをtypesから凍結配列を作成した結果で設定する。

7.2.1. presentationStyle

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

7.2.2. types

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

7.2.3. getType(type)

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

realmをthisの関連レルムとする。
isCustomをfalseとする。
typeが"web "で始まる場合、
1. "web "を取り除き、残りの文字列をtypeに代入する。
2. isCustomをtrueにする。
mimeTypeをtypeに対してMIME型のパースの結果とする。
mimeTypeが失敗なら、TypeErrorをスローする。
itemTypeListをthisのclipboard itemのlist of representationsとする。
pをrealm内の新しいPromiseとする。
itemTypeListの各representationについて：
1. representationのMIME typeがmimeTypeであり、 representationのisCustomがisCustomなら：
  1. representationDataPromiseをrepresentationのdataとする。
  2. Promiseが解決されたときの反応：
    1. representationDataPromiseが値vでfulfilledされた場合：
      1. vがDOMStringなら：
        
        dataAsBytesをvをUTF-8エンコードした結果とする。
        
        blobDataをdataAsBytesで作成したBlobとし、 typeをmimeType（シリアライズ済み）で設定する。
        
        pをblobDataでresolveする。
      2. vがBlobなら：
        
        pをvでresolveする。
    2. representationDataPromiseがrejectされた場合：
      1. pをrejectし、"NotFoundError" DOMException をrealmで返す。
        
        ウェブ開発者は根本的なreject理由に関心があるかもしれません。
  3. pを返す。
pをrejectし、"NotFoundError" DOMException をrealmで返す。
pを返す。

7.2.4. supports(type)

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

typeが必須データ型または任意データ型に含まれる場合、trueを返す。
そうでなければ、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つのクリップボードアイテムのみ取得されます。

クリップボードアイテムズ（clipboard items）オブジェクトは、シーケンス（配列）のクリップボードアイテムです。

ウェブ著者はシステムクリップボードにコンテンツを書き込むために、write(data) メソッドを使う際、dataとしてClipboardItem の配列を作成する必要があります。read() は、システムクリップボードデータの内容を表すクリップボードアイテムズオブジェクトを返す Promise です。

unsanitized は、著者がオプション非サニタイズデータ型として扱ってほしいMIMEタイプに対応するDOMStringのシーケンスです。

unsanitized オプションは、ユーザーエージェントでサポートされていない場合もあります。ウェブ著者は、unsanitized に記載されたMIMEタイプの内容が非サニタイズされると仮定すべきではありません。なぜなら、プライバシーモードなど、このオプションが許可されない場合があるためです。

クリップボードタスクソース（clipboard task source）は、システムクリップボードデータの読み書きに反応してトリガーされます。

7.3.1. read(`formats`)

read(formats) メソッドは次の手順を実行しなければなりません：

realm を this の関連Realmとする。
p を realm 内の新しい promiseとする。
formats が空でない場合：
1. formats["unsanitized"]の各formatについて：
  1. formatがオプション非サニタイズデータ型に含まれていなければ、pを formatを理由に、"NotAllowedError" DOMException でrealm内でrejectする。
以下の手順を並列で実行する：
1. r をクリップボード読み取り許可の確認を実行した結果とする。
2. r がfalseの場合：
  1. グローバルタスクをキューする。permission task source上で、 realmのグローバルオブジェクトを与えて、pを"NotAllowedError" DOMException で拒否する。
  2. これらの手順を中止する。
3. data をシステムクリップボードデータのコピーとする。
4. items をsequence<クリップボードアイテム>とする。
5. data中の各systemClipboardItemについて：
  1. item を新しいクリップボードアイテムとする。
  2. systemClipboardItemの各systemClipboardRepresentationについて：
    1. mimeType を OS固有フォーマットから既知MIMEタイプを決定するアルゴリズムにsystemClipboardRepresentationのname を与えて得た結果とする。
    2. mimeType が null の場合、このループを継続する。
    3. representation を新しい表現とする。
    4. representationのMIMEタイプにmimeTypeを設定する。
    5. isUnsanitized をfalseとする。
    6. formats が空でない場合：
      1. formats["unsanitized"]の各formatについて：
        
        formatがMIMEタイプと等しければ、isUnsanitizedをtrueにする。
    7. representationのdataをsystemClipboardRepresentationのdataでresolveする。
      
      著者がgetTypeを呼び出した後、システムクリップボードから非同期でデータを読み取れるようにすべきだが、この手順では読取時にデータが提供されることを示唆している。
    8. ユーザーエージェントは、representationのdataをサニタイズしてもよい。ただし、 representationのMIMEタイプのesenceが "image/png" ならメタデータを保持するため非サニタイズ、または以下の条件を満たすときも非サニタイズ：
      1. representationのMIMEタイプが非サニタイズデータ型リストにある場合。
      2. isUnsanitized が true の場合。
    9. representationをitemの表現のリストに追加する。
    10. isUnsanitized をfalseに戻す。
  3. itemの表現のリストのサイズが0より大きければitemをitemsに追加する。
6. itemsのサイズが0より大きければ：
  1. firstItemをitems[0]とする。
  2. Webカスタムフォーマットの読取アルゴリズムをfirstItemで実行する。
7. それ以外の場合：
  1. customItemを新しいクリップボードアイテムとする。
  2. Webカスタムフォーマットの読取アルゴリズムをcustomItemで実行する。
  3. customItemの表現のリストのサイズが0より大きければcustomItemをitemsに追加する。
8. グローバルタスクをキューする。クリップボードタスクソース上で、realmのグローバルオブジェクトを与え、下記のステップを実行：
  1. clipboardItems を sequence<ClipboardItem> とする。
  2. itemsの各クリップボードアイテム underlyingItemについて：
    1. clipboardItemをClipboardItem オブジェクト生成手順に underlyingItemと realm を与えて実行した結果とする。
    2. clipboardItemを clipboardItemsに追加する。
  3. p をclipboardItemsでresolveする。
p を返す。

const items = await navigator.clipboard.read();
const textBlob = await items[0].getType("text/plain");
const text = await (new Response(textBlob)).text();

7.3.2. readText()

readText() メソッドは次の手順を実行しなければならない：

realm を this の関連Realmとする。
p を realm の新しい promiseとする。
以下の手順を並列で実行する：
1. r をクリップボード読み取り権限の確認を実行した結果とする。
2. r が false の場合：
  1. グローバルタスクをキューする。permission task source 上に、 realm のグローバルオブジェクトを与え、 p を"NotAllowedError" DOMException で拒否する。
  2. これらの手順を中止する。
3. data をシステムクリップボードデータのコピーとする。
  
  一部のOSは複数のクリップボードを持つ（例：Linux、「primary」、「secondary」、「selection」など）。どれからデータを読むか定義すること。
  
  サニタイズ済みコピーの定義を追加すること。
4. グローバルタスクをキューする。クリップボードタスクソース上で、realm のグローバルオブジェクトを与え、下記の手順を実行：
  1. data中の各systemClipboardItemについて：
    1. systemClipboardItem 中の各 systemClipboardRepresentation について：
      1. mimeType を OS固有フォーマットから既知のMIMEタイプを決定するアルゴリズムに systemClipboardRepresentation の name を与えて得た結果とする。
      2. mimeType が null の場合、このループを継続する。
      3. representation を新しい表現とする。
      4. representation の MIME type の essence が "text/plain" なら、以下を行う：
        
        representationのMIME typeに mimeType を設定する。
        
        representationDataPromise を representation の data とする。
        
        Promise 解決後の反応を representationDataPromise で行う：
        
        representationDataPromise が v で fulfill された場合：
        
        v が DOMString の場合、下記の手順を行う：
        
        p を v でresolveする。
        
        p を返す。
        
        v が Blob の場合、下記の手順を行う：
        
        string を UTF-8 デコードにより、 v のバイト列から求める。
        
        p を string でresolveする。
        
        p を返す。
        
        representationDataPromise がrejectedされた場合：
        
        Reject p を "NotFoundError" DOMException でrealm内で拒否する。
        
        p を返す。
  2. Reject p を "NotFoundError" DOMException で realm 内で拒否する。
  3. p を返す。

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

7.3.3. write(`data`)

write(data) メソッドは以下の手順を実行する：

realm を this の関連Realmとする。
p を realm の新しいpromise とする。
以下の手順を並列で実行する：
1. r をクリップボード書き込み権限の確認を実行した結果とする。
  
  clipboard-write は https://github.com/w3c/clipboard-apis/pull/164 で削除されました。
2. r が false の場合：
  1. グローバルタスクをキューする。permission task source 上に、 realmのグローバルオブジェクトを与えて、p を "NotAllowedError" DOMException で拒否する。
  2. これらの手順を中止する。
3. グローバルタスクをキューする。クリップボードタスクソース上で、 realmのグローバルオブジェクトを与えて、以下の手順を実行する：
  1. itemListおよびcleanItemListを空のsequence<Blob>とする。
  2. dataListをsequence<ClipboardItem>とする。
  3. もしdataのサイズが1より大きく、かつ現在のOSがシステムクリップボードで複数のネイティブクリップボードアイテムをサポートしない場合は data[0]をdataListに追加する。そうでなければ、dataListをdataとする。
    
    dataが複数アイテムを含み、かつOSが複数ネイティブクリップボードアイテムをサポートする場合、現行アルゴリズムはそれらをまとめて書き込むのではなく逐次書き込んでいる。
  4. dataList中の各clipboardItemについて：
    1. clipboardItemのクリップボードアイテムの表現のリストそれぞれのrepresentationについて：
      1. representationDataPromiseをrepresentationのdataとする。
      2. Promise解決後の反応をrepresentationDataPromiseで行う：
        
        representationDataPromiseがvでfulfillされた場合：
        
        vがDOMStringの場合、次を実施：
        
        dataAsBytesをUTF-8エンコードでvから得る。
        
        blobDataをdataAsBytesから Blob として生成し、そのtype をrepresentationのMIMEタイプに設定する。
        
        blobDataをitemListに追加する。
        
        vがBlobの場合、vをitemListに追加する。
        
        representationDataPromiseがrejectedなら：
        
        Reject p を "NotAllowedError" DOMException でrealm内で拒否する。
        
        これらの手順を中止する。
    2. itemListの各blobについて：
      1. typeをblobのtypeとする。
      2. もしtypeが必須データ型やオプションデータ型に含まれていなければ、reject p を "NotAllowedError" DOMException でrealm内で拒否し、以後の手順を中止する。
      3. cleanItemをblobの（必要に応じてサニタイズされた）コピーとする。
        
        サニタイズ済みコピーの定義を追加すること。
      4. サニタイズが試みられ、正常に完了しなかった場合は、下記を実行：
        
        Reject p を "NotAllowedError" DOMException でrealm内で拒否する。
        
        これらの手順を中止する。
      5. cleanItemをcleanItemListに追加する。
    3. optionをclipboardItemのクリップボードアイテムの presentation styleとする。
    4. blobsとoptionをクリップボードへ書き込むを cleanItemList と option で実行する。
  5. p をresolveする。
p を返す。

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("クリップボードへの書き込みに失敗しました :-(");
});

7.3.4. writeText(`data`)

writeText(data) メソッドは以下の手順を実行する：

realm を this の関連レルムとする。
p を realm 内の新しい promise とする。
以下の手順を並列で実行する：
1. r をクリップボード書き込み権限の確認を実行した結果とする。
  
  clipboard-write は https://github.com/w3c/clipboard-apis/pull/164 で削除されました。
2. r が false の場合：
  1. グローバルタスクをキューする。permission task source 上に、 realm のグローバルオブジェクトを与え、 p を "NotAllowedError" DOMException で拒否する。
  2. これらの手順を中止する。
3. グローバルタスクをキューする。clipboard task source 上に、 realm のグローバルオブジェクトを与え、下記の手順を実行：
  1. itemList を空の sequence<Blob> とする。
  2. textBlob を新しい Blob とし、 type 属性は "text/plain;charset=utf-8"、基礎となるバイト列は data を UTF-8 エンコーディングしたものとする。
    
    注記: Windows の場合は textBlob を作成する前に data の `\n` を `\r\n` に置換すること。
  3. textBlob を itemList に追加する。
  4. option を "unspecified" に設定する。
  5. itemList と option をクリップボードに書き込む。
  6. p を resolve する。
p を返す。

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

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

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

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

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

script-may-access-clipboardフラグは、以下のように設定されます：

アクションがcopyまたはcutであり、スクリプトスレッドがクリップボードの変更が許可されている場合、
1. アクションのscript-may-access-clipboardフラグをセットする
アクションがpasteであり、スクリプトスレッドがクリップボードからの読み取りが許可されている場合、
1. アクションのscript-may-access-clipboardフラグをセットする。

8.1. コピーアクション

コピーアクションは次の手順で構成されます：

script-triggered フラグが設定されている場合、
1. script-may-access-clipboard フラグが未設定の場合、
  1. コピー操作から false を返し、このアルゴリズムを終了する
クリップボードイベントを発火する。イベント名は copy。
もしイベントがキャンセルされなかった場合、
1. 選択されている内容があれば、それをクリップボードにコピーする。実装は 可能なら、ウェブページ内の選択内容に対し text/html および text/plain の代替クリップボードフォーマットを作成するべきである。
2. クリップボードイベントを発火する。イベント名は clipboardchange。
さもなければ、イベントがキャンセルされた場合、
1. クリップボードへ内容を書き込むアルゴリズムを呼び出す。その際、DataTransferItemList リスト items、clear-was-called フラグおよび types-to-clear リストを渡す。
コピー操作から true を返す

8.2. 切り取りアクション

切り取りアクションは次の手順で構成されます：

script-triggered フラグが設定されている場合、
1. script-may-access-clipboard フラグが未設定の場合、
  1. カットアクションから false を返し、このアルゴリズムを終了する
クリップボードイベントを発火する。イベント名は cut。
イベントがキャンセルされなかった場合、
1. もし編集可能コンテキストかつカットが有効な箇所に選択範囲がある場合、
  1. 選択された内容があればそれをクリップボードにコピーする。実装は 可能なら、ウェブページで選択された内容について text/html および text/plain の代替クリップボード形式を生成するべきである。
  2. 選択内容をドキュメントから削除し、選択範囲を折りたたむ。
  3. クリップボードイベントを発火する。イベント名は clipboardchange。
  4. この修正によって発火すべき他のイベントを発火させるためのタスクをキューする。詳細は § 5.3 他のスクリプトやイベントとの統合を参照。
2. そうでない場合（選択がない、またはコンテキストが編集不可の場合）、
  1. false を返す
さもなければ、イベントがキャンセルされた場合、
1. クリップボードに内容を書き込むアルゴリズムを呼び出す。その際、DataTransferItemList リスト items、clear-was-called フラグ、types-to-clear リストを渡す。
2. クリップボードイベントを発火する。イベント名は clipboardchange。
カットアクションから true を返す

8.3. 貼り付けアクション

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

貼り付けアクションは次の手順で構成されます：

script-triggeredフラグがセットされている場合、
1. script-may-access-clipboardが未セットの場合、
  1. 貼り付けアクションからfalseを返し、このアルゴリズムを終了する
pasteという名前のクリップボードイベントを発火する
イベントがキャンセルされなかった場合、
1. 編集可能コンテキスト内で貼り付けが有効な選択やカーソルがある場合、
  1. クリップボード上の最適な内容（あれば）をそのコンテキストに挿入する。
  2. 変更によって発火すべきイベントをキューに追加する。詳細は§ 5.3 他のスクリプトやイベントとの統合を参照。
2. それ以外の場合、
  1. falseを返す
イベントがキャンセルされた場合
1. falseを返す
アクションからtrueを返す

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 を必ずサポートしなければなりませんが、デフォルト設定やユーザーへの表示方法（あるいは表示しない方法）については完全に制御できます。

ユーザーエージェントがクリップボードへの書き込みを個別にユーザーが設定でき、常にユーザー操作が必要となるよう制御したい場合、各ディスクリプタは以下のように扱われます：

{ "clipboard-write" + false }はユーザーが制御可能として公開される
{ "clipboard-write" + true }は常にdeniedとなる

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

9.1.1. クリップボード読み取り権限の確認

hasGesture を、this の関連グローバルオブジェクトが一時的アクティベーションを持つ場合 true、そうでない場合は false とする。
もしhasGestureなら、
1. 現在のスクリプトがユーザーエージェントまたはOSが作成した「貼り付け」要素のユーザー操作により実行されている場合trueを返す。
falseを返す。

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

9.2.1. クリップボード書き込み権限の確認

writeWithoutGestureを{ name: "clipboard-write", allowWithoutGesture: true }権限の権限状態とする。
writeWithoutGestureがgrantedならtrueを返す。
hasGesture を、this の関連グローバルオブジェクトが一時的アクティベーションを持つ場合 true、そうでない場合は false とする。

もしhasGestureなら、
1. 現在のスクリプトがユーザーエージェントまたはOSが作成した「cut」または「copy」要素のユーザー操作により実行されている場合systemCopyをtrueとする。
2. systemCopyがtrueならtrueを返す。
3. 権限の利用要求を{ name: "clipboard-write", allowWithoutGesture: false }権限に対して実行した結果を返す。
  
  注: ユーザーエージェントは、より強い権限を要求し、暗黙的にこの権限を更新する選択も可能です。
権限の利用要求を{ name: "clipboard-write", allowWithoutGesture: true }権限に対して実行した結果を返す。

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

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

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

ユーザーがリンクを選択してコピーしたのに、異なるリンクがクリップボードにコピーされる。これは、貼り付け時に予期しない結果を招く場合からフィッシング攻撃の試みまで、影響が及ぶ可能性があります。
(Self-XSS) シェルコマンドや実行可能なスクリプトがクリップボードに置かれ、ユーザーが貼り付けた内容を実行することを意図している。
OSの画像処理コードのバグを悪用するために細工された画像がクリップボードに書き込まれる。

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

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

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

ユーザーが隠れたデータを気付かず貼り付けてしまう可能性があります。例えば、マークアップに<input type="hidden">タグやHTMLコメントが含まれている場合です。こうした隠れたデータには機密情報が含まれていることがあります。
ユーザーが信頼されたページに悪意のあるJavaScriptを貼り付けてしまう可能性があります。
実装が、ユーザーが意図していないローカルファイルへのスクリプトのアクセスを許可する可能性があります。

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

貼り付けるデータのオリジン
画像など参照されているデータのサブパーツのオリジン
実行中のスクリプトのオリジン

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

データのオリジン	スクリプトのオリジン	ルール
オンラインソース由来	データと同じ	HTMLをサニタイズしない。ローカルファイルへのアクセスはしない。
オンラインソース由来	異なるオリジン	コンテンツをサニタイズする場合がある。ローカルファイルへのアクセスはしない。
ローカルアプリケーション由来	任意	HTMLをサニタイズしない。ローカルファイルへのアクセスを許可。

一部の実装は、リッチテキスト貼り付け時に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: アルゴリズム

クリップボードに内容を書き込む

入力: items: DataTransferItemList の書き込むアイテムリスト; clear-was-called: boolean型; types-to-clear: リスト型
出力: なし

itemsリストが空でない場合、
1. クリップボードをクリアする
2. リスト内の各パートについて、
  1. データ型がtext/plainの場合、
    1. OSやロケールの規則に従ってエンコーディングが正しいことを保証する
    2. プラットフォームの規則に従って改行コードを正規化する
    3. テキストを適切なOSクリップボード形式記述子でクリップボードに配置する
  2. それ以外でデータ型が必須データ型リストに含まれている場合、
    1. パートを適切なOSクリップボード形式記述子でクリップボードに配置する
  3. その他
    1. この部分は実装依存・・・
      
      実装依存にするのは好ましくありません。どうすべきか？
      
      注: OSクリップボードの実装制限により、スクリプトはカスタムフォーマットが他のアプリケーションで利用可能になると仮定すべきではありません。例えばMicrosoft Windowsでは、登録できるカスタムクリップボードフォーマット数に制限があります。setData()のtype引数には任意の文字列が使えますが、必須データ型を使うのが強く推奨されます。
それ以外の場合（itemsリストが空の場合）、クリップボードをクリアするかどうか以下の手順で判断する：
1. アイテムリストが空で、clear-was-calledフラグがtrueの場合、
  1. types-to-clearリストが空なら、
    1. クリップボードをクリアする
  2. それ以外の場合、
    1. OS・実装依存の方法でtypes-to-clearリストに含まれる型をクリップボードから削除する
      
      「クリップボードから特定の型のみ削除する」機能はリスクがある。重要性が低く、主要プラットフォームで簡易に実装できるか疑問です。

BLOBとoptionをクリップボードに書き込む

入力: items：sequence<Blob>; presentationStyle：クリップボードアイテムのpresentation style
出力: なし

webCustomFormats を sequence<Blob> とする。
items の各 item について:
1. formatString を item の type を与えて OS固有の既知フォーマットアルゴリズムを実行した結果とする。
2. もし formatString が空なら、次を行う：
  1. webCustomFormatString を item の type とする。
  2. webCustomFormat を空の type とする。
  3. もし webCustomFormatString が "web " プレフィックスで始まる場合、"web " を取り除き、残りの文字列を webMimeTypeStringに格納する。
  4. webMimeType を MIMEタイプをパースでwebMimeTypeStringを与えて得る。
  5. webMimeType が失敗であれば、すべての手順を中止する。
  6. webCustomFormat の type の essence に webMimeType を設定する。
  7. item の type に webCustomFormat を設定する。
  8. webCustomFormat を webCustomFormats に追加する。
3. payload を UTF-8デコードで item の基礎バイト列から作成する。
4. payload と presentationStyle を formatString をOSのクリップボードフォーマットとして使い、システムクリップボードに挿入する。
一部のOSは複数のクリップボード（例：Linux, "primary", "secondary", "selection"）を持つ。それらのどこにデータを書き込むか定義すること。
Webカスタムフォーマットを書き込むを webCustomFormats で実行する。

OS固有のよく知られたフォーマット

入力: mimeType: type
出力: wellKnownFormat: プラットフォーム固有の文字列型。MacではNSPasteboardType、WindowsではLPCWSTR、Linuxではconst char*。

Windowsの詳細は https://docs.microsoft.com/en-us/windows/win32/dataxchg/standard-clipboard-formats および https://docs.microsoft.com/en-us/windows/win32/dataxchg/about-atom-tables?redirectedfrom=MSDN Macの詳細は https://developer.apple.com/documentation/appkit/nspasteboardtype

wellKnownFormatを空文字列とする。
mimeTypeの本質が"text/plain"の場合、

Windowsの場合：
1. CF_UNICODETEXTをwellKnownFormatに代入する。
MacOSの場合：
1. NSPasteboardTypeStringをwellKnownFormatに代入する。
Linux・ChromeOS・Androidの場合：
1. "text/plain"をwellKnownFormatに代入する。
それ以外でmimeTypeの本質が"text/html"の場合、

Windowsの場合：
1. CF_HTMLをwellKnownFormatに代入する。
MacOSの場合：
1. NSPasteboardTypeHTMLをwellKnownFormatに代入する。
Linux・ChromeOS・Androidの場合：
1. "text/html"をwellKnownFormatに代入する。
それ以外でmimeTypeの本質が"image/png"の場合、

Windowsの場合：
1. "PNG"をwellKnownFormatに代入する。
MacOSの場合：
1. NSPasteboardTypePNGをwellKnownFormatに代入する。
Linux・ChromeOS・Androidの場合：
1. "image/png"をwellKnownFormatに代入する。
それ以外でmimeTypeの本質が"image/svg+xml"の場合、

Windowsの場合：
1. CFSTR_MIME_SVG_XMLをwellKnownFormatに代入する。
MacOSの場合：
1. UTTypeSVGをwellKnownFormatに代入する。
Linux・ChromeOS・Androidの場合：
1. "image/svg+xml"をwellKnownFormatに代入する。
wellKnownFormatを返す。

OS固有フォーマットからよく知られたMIME型を得る

入力: osFormatName: プラットフォーム固有の文字列型。MacではNSPasteboardType、WindowsではLPCWSTR、Linuxではconst char*。
出力: mimeType: MIME型

Windowsの場合：

osFormatNameが"UnicodeText"なら、mimeTypeStringを"text/plain"に設定する。
それ以外でosFormatNameが"HTML Format"なら、mimeTypeStringを"text/html"に設定する。
それ以外でosFormatNameが"PNG"なら、mimeTypeStringを"image/png"に設定する。
それ以外でosFormatNameがCFSTR_MIME_SVG_XMLなら、mimeTypeStringを"image/svg+xml"に設定する。

MacOSの場合：

osFormatNameがNSPasteboardTypeStringなら、mimeTypeStringを"text/plain"に設定する。
それ以外でosFormatNameがNSPasteboardTypeHTMLなら、mimeTypeStringを"text/html"に設定する。
それ以外でosFormatNameがNSPasteboardTypePNGなら、mimeTypeStringを"image/png"に設定する。
それ以外でosFormatNameがUTTypeSVGなら、mimeTypeStringを"image/svg+xml"に設定する。

Linux・ChromeOS・Androidの場合：

osFormatNameが"text/plain"なら、mimeTypeStringを"text/plain"に設定する。
それ以外でosFormatNameが"text/html"なら、mimeTypeStringを"text/html"に設定する。
それ以外でosFormatNameが"image/png"なら、mimeTypeStringを"image/png"に設定する。
それ以外でosFormatNameが"image/svg+xml"なら、mimeTypeStringを"image/svg+xml"に設定する。

mimeTypeをmimeTypeStringに対してMIME型のパースを実行した結果とする。
mimeTypeを返す。

Webカスタムフォーマットの読み取り

入力: item、クリップボードアイテム

webCustomFormatMapをOS固有のカスタムマップ名とする。
webCustomFormatMapをシステムクリップボードから読み取る。

webCustomFormatMapの読み取り処理をより詳細に規定すべき。
webCustomFormatMapが空なら、itemを返す。
webCustomFormatMapStringをwebCustomFormatMapからデシリアライズしたJSON文字列とする。

注: webCustomFormatMapの内容デシリアライズにはJSONリーダーが必要。
webCustomFormatMapString内の各(key, value)について：
1. mimeTypeをkeyに対してMIME型のパースの結果とする。
2. mimeTypeが失敗なら、ループを継続する。
3. representationを新しいrepresentationとして作成する。
4. representationのMIME typeをmimeTypeに設定する。
5. representationのisCustomフラグをtrueに設定する。
6. webCustomFormatをvalueを使ってシステムクリップボードから読み取る。
7. 読み取りが成功した場合、representationのdataをシステムクリップボードの取得データに設定し、失敗ならループを継続する。
8. representationをitemのlist of representationsに追加する。

Webカスタムフォーマットの書き込み

入力: items、sequence<Blob>

idxを0で初期化する。
webCustomFormatMapをOS固有のカスタムマップ名とする。
webCustomFormatMapStringを空のJSON文字列とする。
itemsの各itemについて：
1. webCustomFormatをOS固有のカスタム名とする。
2. webCustomFormatIdxをwebCustomFormatにidxを結合した結果とする。
3. itemのtypeをキー、webCustomFormatIdxを値として webCustomFormatMapStringにJSONシリアライザーで追加する。
  
  注: webCustomFormatMapStringへのシリアライズにはJSONライターが必要。
4. itemをwebCustomFormatIdxをフォーマットとしてシステムクリップボードに挿入する。
5. idxをインクリメントする。
6. idxが100を超えたら、このループを終了する。
webCustomFormatMapStringをwebCustomFormatMapをフォーマットとしてシステムクリップボードに挿入する。

OS固有のカスタムマップ名

出力: webCustomFormatMap、文字列

Windowsの場合：

webCustomFormatMapに"Web Custom Format Map"を代入する。
webCustomFormatMapを返す。

MacOSの場合：

webCustomFormatMapに"org.w3.web-custom-format.map"を代入する。
webCustomFormatMapを返す。

Linux、ChromeOS、Androidの場合：

webCustomFormatMapに"application/web;type=\"custom/formatmap\""を代入する。
webCustomFormatMapを返す。

OS固有のカスタム名

出力: webCustomFormat、文字列

Windowsの場合：

webCustomFormatに"Web Custom Format"を代入する。
webCustomFormatを返す。

MacOSの場合：

webCustomFormatに"org.w3.web-custom-format.type-"を代入する。
webCustomFormatを返す。

Linux、ChromeOS、Androidの場合：

webCustomFormatに"application/web;type=\"custom/format\""を代入する。
webCustomFormatを返す。

クリップボードイベントの発火

入力: e、発火するClipboardEvent
出力: なし

clear-was-calledをfalseとする。
types-to-clearを空リストとする。
clipboard-event-dataを空のDataTransfer オブジェクト（itemsリストは空）とする。
clipboard-entryを現在のクリップボード内容のシーケンス番号、またはOSクリップボードがシーケンス番号をサポートしない場合はnullとする。
trustedをイベントがユーザーエージェントによって生成された場合true、それ以外はfalseとする。
targetを次のように設定する：
1. コンテキストが編集可能な場合：
  1. targetを、ドキュメント順で可視選択範囲またはカーソルの開始位置を含む要素、なければbody要素とする。
2. コンテキストが編集不可の場合：
  1. targetをフォーカスされているノード、なければbody要素とする。
イベントを次のように処理する：
1. eが"paste"の場合：
  1. clipboard-event-dataの内部drag data store modeフラグをread-onlyに設定する。
  2. trustedがtrue、または実装がスクリプト生成イベントにOSクリップボードの読み取り権限を与えるよう設定されている場合：
    1. OSクリップボード上の各clipboard-partについて以下を実行：
      1. clipboard-partがプレーンテキストの場合：
        
        テキストがスクリプトエンジン内部のエンコーディングであることを保証する。
        
        new-dataを新しいDataTransferItem とし、drag data item kindはstring、drag data item type stringはtext/plain。
        
        new-dataのデータをプレーンテキストに設定する。
        
        new-dataをclipboard-event-dataのitemsリストに追加する。
      2. clipboard-partがファイル参照の場合、その各ファイル参照について：
        
        参照ファイルのMIME型を判定する。
        
        new-dataを新しいDataTransferItem とし、drag data item kindはfile、drag data item type stringはMIME型（不明ならapplication/octet-stream）。
        
        new-dataのデータをファイル参照データに設定する。
        
        new-dataをclipboard-event-dataのitemsリストに追加する。
      3. clipboard-partがOSの規則によるHTMLまたはXHTML形式テキストの場合：
        
        実装がHTML貼り付けをサポートしていれば、HTML貼り付けイベントの処理をclipboard-partとclipboard-event-dataで実行する。
      4. clipboard-partが他のサポートされたバイナリまたはテキスト型（必須データ型参照）の場合：
        
        データのMIME型を判定する。
        
        new-dataを新しいDataTransferItem とし、drag data item kindはfile、drag data item type stringはMIME型。
        
        new-dataのデータをバイナリまたはテキストデータに設定する。
        
        new-dataをclipboard-event-dataのitemsリストに追加する。
  3. clipboard-event-dataのfiles プロパティをitemsリストに合わせて更新する。
  4. clipboard-event-dataのtypes プロパティをitemsリストに合わせて更新する。
2. eが"copy"または"cut"の場合：
  1. 関連DataTransfer オブジェクトの内部drag data store modeフラグをread/writeに設定する。
eのclipboardData をclipboard-event-dataに設定する。
eのisTrusted をtrustedに設定する。
eのcomposed をtrueに設定する。
イベントeをバブル・キャンセル可能として、ClipboardEvent インターフェースを使用しtargetで発火する。

イベント発火中のデータアクセス要件は[HTML]で定義されています。追加のクリップボードイベント固有の処理規則は下記の通りです：

なぜここに？なぜHTML仕様に記載しない？
1. スクリプトがclearData()またはclear() を呼び出し、かつDataTransfer オブジェクトの内部drag data store modeフラグがread/writeの場合：
  1. clear-was-calledフラグをtrueに設定する。引数が指定されている場合はその引数をtypes-to-clearリストに追加する。
2. スクリプトがsetData()を呼び出すかitemsを変更し、clear-was-calledフラグがtrueの場合：
  1. types-to-clearリストが空なら：
    1. clear-was-calledフラグをfalseに設定する。
  2. それ以外の場合、setData()のtype引数または新規アイテムのdrag data item type stringが types-to-clearリストに含まれていれば：
    1. それをリストから除去し、リストが空になったらclear-was-calledフラグをfalseに設定する。
3. スクリプトがgetData()を呼び出すかDataTransferItemList のitemsにアクセスし、clipboard-entryがセットされている場合：
  1. クリップボードデータのシーケンス番号がclipboard-entryと一致するか確認し、一致しない場合はDataTransferItemList オブジェクトの内部drag data store modeをprotectedに設定する。
警告！pasteイベントを監視する悪意のあるスクリプトは、ユーザーが今後クリップボードに置く内容を読み取るため、無限ループを仕掛ける可能性があります。クリップボードのシーケンス番号が取得できないプラットフォームでは、他の制限を実装すべきです。

HTML貼り付けイベントの処理

入力: clipboard-part、処理対象のクリップボードパート; clipboard-event-data、このイベント用のDataTransferオブジェクト
出力: なし

new-dataを新しいDataTransferItem とし、drag data item kindはPlain Unicode string、drag data item type stringは適宜text/htmlまたはapplication/xhtml+xml。
clipboard-partからマークアップを抽出し、適切なパーサーでDOMツリーを構築する。
マークアップのソースURLが判明している場合、HREFやSRC属性の相対URLをソースURLを基準に絶対URLに解決し、属性値を絶対URLにする。
マークアップのオリジンがローカルアプリケーションの場合、ローカルファイルやOSクリップボード内の他パート参照があるか確認し、参照があればsub-part参照はcid:URLスキーム[RFC2392]でcontent-id参照に必ず置換する。各属性について下記手順で処理：

これらの手順は必要か？内部参照を持つネイティブ（プラットフォーム）クリップボード実装の存在を把握しているか？

この機能は要件不明かつクロスプラットフォームで検証困難なためリスクあり。
1. clipboard-event-dataのitems に参照されたファイルまたはクリップボード部品のエントリが既に存在する場合、
  1. itemNumberに既存エントリのインデックスを設定する。
2. それ以外の場合、
  1. new-file-dataを新しいDataTransferItem （drag data item kindは"file"、drag data item type stringはファイルまたはクリップボード部品のMIME型（不明ならapplication/octet-stream））として作成する。
  2. file-infoを新しいFile オブジェクト（nameはHTML属性内容の名前部分、lastModifiedは参照ファイルのタイムスタンプまたはクリップボード部品参照なら0）として作成する。
  3. new-file-dataの内部File オブジェクトにfile-infoを設定する。
  4. new-file-dataをclipboard-event-dataのitems に追加し、そのエントリのインデックスをitemNumberとする（DataTransferItemList内）。
3. ローカルファイルやクリップボード部品を参照していたDOM属性を 'cid:'＋itemNumber の文字列に更新する。
処理後のDOMをシリアライズし、そのHTMLコードでnew-dataを更新する。
new-dataをclipboard-event-dataのitems に追加する。

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

概要

この文書のステータス

1. はじめに

2. ユースケース

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

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

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

3. 用語

4. モデル

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

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

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

5.2.1. clipboardchangeイベント

5.2.1.1. clipboardchange イベントを発火するには

5.2.1.2. Document フォーカス時の手順

5.2.1.3. ClipboardChangeEvent コンストラクタのステップ

5.2.1.4. ChangeId 生成

5.2.2. copy イベント

5.2.3. cut イベント

5.2.4. paste イベント

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

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

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

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

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

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

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

6.1. copyイベントの上書き

6.2. cutイベントの上書き

6.3. pasteイベントの上書き

6.4. 必須データ型

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

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

6.5. 任意データ型

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

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

7.1. Navigatorインターフェース

7.1.1. clipboard

7.2. ClipboardItemインターフェース

7.2.1. presentationStyle

7.2.2. types

7.2.3. getType(type)

7.2.4. supports(type)

7.3. Clipboardインターフェース

7.3.1. read(formats)

7.3.2. readText()

7.3.3. write(data)

7.3.4. writeText(data)

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

8.1. コピーアクション

8.2. 切り取りアクション

8.3. 貼り付けアクション

9. Permissions APIとの統合

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

9.1.1. クリップボード読み取り権限の確認

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

9.2.1. クリップボード書き込み権限の確認

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

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

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

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

10.4. 迷惑行為対策

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

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

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

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

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

12. 謝辞

付録A: アルゴリズム

クリップボードに内容を書き込む

BLOBとoptionをクリップボードに書き込む

OS固有のよく知られたフォーマット

OS固有フォーマットからよく知られたMIME型を得る

Webカスタムフォーマットの読み取り

Webカスタムフォーマットの書き込み

OS固有のカスタムマップ名

OS固有のカスタム名

クリップボードイベントの発火

HTML貼り付けイベントの処理

5.2.1. `clipboardchange`イベント

5.2.2. `copy` イベント

5.2.3. `cut` イベント

5.2.4. `paste` イベント

7.3.1. read(`formats`)

7.3.3. write(`data`)

7.3.4. writeText(`data`)