Clipboard.write()

Baseline 2024

Newly available

Since June 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Clipboard の write() メソッドは、画像などの任意のデータをクリップボードに書き込みます。切り取りやコピーの機能を実装するのに利用することができます。

権限 API の "clipboard-write" 権限は、ページがアクティブなタブにあるときに自動的に付与されます。

メモ: 非同期クリップボード API に対するブラウザーの対応は、まだ実装の途上にあります。詳しくは、互換性一覧表とクリップボードの可用性 を必ずチェックしてください。

構文

js
write(data);

引数

data

クリップボードに書き込むデータを含む ClipboardItem オブジェクトの配列です。

返値

クリップボードにデータが書き込まれたときに解決されるPromise。クリップボードアクセスを完了できない場合、プロミスは拒否される。

例

この関数は、クリップボードの現在の内容を指定された文字列に置き換えます。

js
function setClipboard(text) {
  const type = "text/plain";
  const blob = new Blob([text], { type });
  const data = [new ClipboardItem({ [type]: blob })];

  navigator.clipboard.write(data).then(
    () => {
      /* success */
    },
    () => {
      /* failure */
    },
  );
}

このコードでは、まず新しい Blob オブジェクトを作成します。このオブジェクトは、クリップボードに送信される ClipboardItem オブジェクトを構築するために必要です。 Blob のコンストラクターはコピーしたいコンテンツとそのタイプを受け取ります。この Blob オブジェクトは、例えばCanvasなど多くのソースから派生させることができます。

次に、クリップボードに送信するために Blob が配置される新しい ClipboardItem オブジェクトを作成します。 domxref("ClipboardItem")}} コンストラクターに渡されるオブジェクトのキーはコンテンツの種類を、値はコンテンツを表します。次に write() が呼ばれ、履行関数とエラー関数の両方が指定されます。

キャンバスの内容をクリップボードにコピーする例

js
function copyCanvasContentsToClipboard(canvas, onDone, onError) {
  canvas.toBlob((blob) => {
    let data = [new ClipboardItem({ [blob.type]: blob })];

    navigator.clipboard.write(data).then(
      () => {
        onDone();
      },
      (err) => {
        onError(err);
      },
    );
  });
}

メモ: 一度に渡すことができるクリップボードの項目は 1 つだけです。

仕様書

Specification
Clipboard API and events
# dom-clipboard-write

ブラウザーの互換性

BCD tables only load in the browser

関連情報