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.
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
write() は Clipboard インターフェイスのメソッドで、画像やテキストなどの任意の ClipboardItem データをクリップボードに書き込み、完了時に返された Promise を解決します。
これを使用して、切り取りやコピー機能を実装することができます。
このメソッドは、理論上、任意のデータを書き込むことができます（テキストしか書き込めない writeText() とは異なります）。
ブラウザーでは一般的に、テキスト、HTML、PNG 画像データの書き込みに対応しています。
構文
write(data)
引数
data-
クリップボードに書き込むデータを含む
ClipboardItemオブジェクトの配列です。
返値
クリップボードにデータが書き込まれたときに解決される Promise です。
なお、基盤となる OS がシステムクリップボード上のネイティブの複数クリップボードアイテムに対応していない場合、配列内の最初の ClipboardItem のみが書き込まれます。
クリップボードへの書き込みができない場合、そのプロミスは拒否されます。
例外
NotAllowedErrorDOMException-
クリップボードへ書き込みをすることができない場合に発生します。
セキュリティの注意事項
クリップボードからの読み取りは、保護されたコンテキストでのみ行うことができます。
その他のセキュリティ要件は、API の概要トピックにあるセキュリティの注意事項の節で網羅されています。
例
テキストをクリップボードへ書き込む
この例の関数は、ボタンが押された際に、クリップボードの現在の内容を指定された文字列に置き換えます。
なお、このような特定のケースでは、Clipboard.writeText() を使用することもできます。
button.addEventListener("click", () => setClipboard("<empty clipboard>"));
async function setClipboard(text) {
const type = "text/plain";
const clipboardItemData = {
[type]: text,
};
const clipboardItem = new ClipboardItem(clipboardItemData);
await navigator.clipboard.write([clipboardItem]);
}
setClipboard() 関数は "text/plain" MIME タイプを type 定数に指定し、次に単一のプロパティを持つ clipboardItemData オブジェクトを指定します。このプロパティのキーは MIME タイプであり、値はクリップボードに書き込みたい、渡されたテキストです。次に、新しい ClipboardItem オブジェクトを作成し、そこに clipboardItemData オブジェクトを渡します。
最後に、write() を await 付きで呼び出し、データをクリップボードに書き込みます。
キャンバスのコンテンツをクリップボードへ書き込む
この例では、キャンバスに青い矩形を描画します。 矩形をクリックすると、キャンバスのコンテンツを画像としてクリップボードにコピーできます。その後、別の要素を選択し、クリップボードからそのコンテンツを貼り付けることができます。
HTML
HTML は、<canvas> 要素と、キャンバスの画像を張り付ける ID が target の <div> 要素を定義しているだけです。
<canvas id="canvas" width="100" height="100"></canvas>
<div id="target">ここに貼り付けてください。</div>
const logElement = document.querySelector("#log");
function log(text) {
logElement.innerText = `${logElement.innerText}${text}\n`;
logElement.scrollTop = logElement.scrollHeight;
}
JavaScript
まず、キャンバスを Blob にコピーする非同期 (async) 関数を定義します。
これは、従来のコールバック形式の HTMLCanvasElement.toBlob() メソッドを、より直感的な Promise ベースの関数にラップしたものです。
// toBlob() コールバックを置き換える async/await 版メソッド
async function getBlobFromCanvas(canvas) {
return new Promise((resolve, reject) => {
canvas.toBlob((blob) => {
if (blob) {
resolve(blob);
} else {
reject(new Error("キャンバスの toBlob に失敗しました"));
}
});
});
}
次に、キャンバスを設定し、click イベントのイベントリスナーを追加します。
青い矩形をクリックすると、その矩形を表示しているキャンバスの内容を blob にコピーし、その blob を ClipboardItem に追加された後、クリップボードに書き込みます。
const canvas = document.getElementById("canvas");
// Set up canvas
const ctx = canvas.getContext("2d");
ctx.fillStyle = "cornflowerblue";
ctx.fillRect(0, 0, 100, 100);
canvas.addEventListener("click", copyCanvasContentsToClipboard);
const target = document.getElementById("target");
async function copyCanvasContentsToClipboard() {
// キャンバスを blob へコピー
try {
const blob = await getBlobFromCanvas(canvas);
// blob とその型をつけて ClipboardItem を作成し、配列に追加します
const data = [new ClipboardItem({ [blob.type]: blob })];
// データをクリップボードに書き込む
await navigator.clipboard.write(data);
log("コピーしました");
} catch (error) {
log(error);
}
}
あまり一般的ではないファイル形式や、事前に形式が分からないリソースを取得する場合は、ClipboardItem.supports() を使用してファイル形式が対応しているかを調べ、対応していない場合にはユーザーに適切なエラーメッセージを示すことをお勧めします。
次に、クリップボードのコンテンツを画像として表示させたい要素に対して、paste イベントのイベントリスナーを定義します。
FileReader API を使用すると、readAsDataUrl メソッドで Blob を読み取り、そのコンテンツを <img> 要素として生成することができます。
target.addEventListener("paste", (event) => {
const items = (event.clipboardData || window.clipboardData).items;
const blob = items[0].getAsFile();
const reader = new FileReader();
reader.addEventListener("load", (event) => {
const img = new Image();
img.src = event.target.result;
target.appendChild(img);
});
reader.readAsDataURL(blob);
});
結果
結果は以下に示します。
まず青い四角をクリックし、次に「ここに貼り付け」というテキストを選択して、お使いの OS に応じたキーボードショートカット（Windows の場合は Ctrl+V など）を使用して、クリップボードから貼り付けてください。
仕様書
| Specification |
|---|
| Clipboard API and events # dom-clipboard-write |