テキストと画像のクリップボード アクセスがより安全でブロックなし
システムのクリップボードにアクセスするための従来の方法は、クリップボード操作用の document.execCommand() を経由する方法でした。広くサポートされていますが、このカット&ペーストの方法には代償が伴いました。クリップボードへのアクセスは同期的であり、DOM に対する読み取りと書き込みしかできませんでした。
小さなテキストであれば問題ありませんが、クリップボードの転送のためにページをブロックすると、エクスペリエンスが低下することがよくあります。コンテンツを安全に貼り付けるには、時間のかかるサニタイズや画像のデコードが必要になることがあります。場合によっては、貼り付けたドキュメントからリンクされたリソースを読み込むか、インライン化する必要があります。この場合、ディスクやネットワークで待機している間、ページがブロックされます。これに権限を追加して、ブラウザでページをブロックしつつ、クリップボードへのアクセスをリクエストできるようにすることを想像してみてください。同時に、クリップボード操作のために document.execCommand() の前後に適用される権限は大まかに定義され、ブラウザによって異なります。
Async Clipboard API を使用すると、ページをブロックしない明確に定義された権限モデルでこれらの問題に対処できます。Async Clipboard API は、ほとんどのブラウザでテキストと画像の処理が制限されますが、サポートは異なります。以下の各セクションで、ブラウザの互換性の概要をよくご確認ください。
コピー: クリップボードへのデータの書き込み
writeText()
テキストをクリップボードにコピーするには、writeText() を呼び出します。この API は非同期のため、writeText() 関数は、渡されたテキストが正常にコピーされたかどうかに応じて解決または拒否する Promise を返します。
async function copyPageUrl() {
try {
await navigator.clipboard.writeText(location.href);
console.log('Page URL copied to clipboard');
} catch (err) {
console.error('Failed to copy: ', err);
}
}
write()
実際には、writeText() は汎用の write() メソッドの便利なメソッドで、クリップボードに画像をコピーすることもできます。writeText() と同様に、非同期で Promise を返します。
クリップボードに画像を書き込むには、画像を blob として提供する必要があります。その方法の一つは、fetch() を使用してサーバーにイメージをリクエストし、レスポンスで blob() を呼び出すことです。
サーバーからの画像のリクエストは、さまざまな理由から望ましくない場合があります。幸いなことに、キャンバスに画像を描画し、キャンバスの toBlob() メソッドを呼び出すこともできます。
次に、ClipboardItem オブジェクトの配列をパラメータとして write() メソッドに渡します。現時点では、一度に 1 つのイメージしか渡せませんが、将来的には複数のイメージのサポートを追加したいと考えています。ClipboardItem は画像の MIME タイプをキーとして、blob を値として持つオブジェクトを受け取ります。fetch() または canvas.toBlob() から取得した blob オブジェクトの場合、blob.type プロパティには画像の正しい MIME タイプが自動的に含まれます。
try {
const imgURL = '/images/generic/file.png';
const data = await fetch(imgURL);
const blob = await data.blob();
await navigator.clipboard.write([
new ClipboardItem({
// The key is determined dynamically based on the blob's type.
[blob.type]: blob
})
]);
console.log('Image copied.');
} catch (err) {
console.error(err.name, err.message);
}
または、ClipboardItem オブジェクトに Promise を書き込むこともできます。このパターンでは、データの MIME タイプを事前に把握しておく必要があります。
try {
const imgURL = '/images/generic/file.png';
await navigator.clipboard.write([
new ClipboardItem({
// Set the key beforehand and write a promise as the value.
'image/png': fetch(imgURL).then(response => response.blob()),
})
]);
console.log('Image copied.');
} catch (err) {
console.error(err.name, err.message);
}
コピーイベント
ユーザーがクリップボードのコピーを開始し、preventDefault() を呼び出さなかった場合、copy イベントには、すでに正しい形式のアイテムを含む clipboardData プロパティが含まれます。独自のロジックを実装する場合は、preventDefault() を呼び出して、独自の実装を優先してデフォルトの動作を回避する必要があります。この場合、clipboardData は空になります。テキストと画像を含むページについて考えてみましょう。ユーザーがすべてを選択してクリップボード コピーを開始した場合、カスタム ソリューションはテキストを破棄し、画像のみをコピーする必要があります。これは、次のコードサンプルのとおりに実現できます。この例では、Clipboard API がサポートされていない場合に、以前の API にフォールバックする方法は説明していません。
<!-- The image we want on the clipboard. -->
<img src="kitten.webp" alt="Cute kitten.">
<!-- Some text we're not interested in. -->
<p>Lorem ipsum</p>
document.addEventListener("copy", async (e) => {
// Prevent the default behavior.
e.preventDefault();
try {
// Prepare an array for the clipboard items.
let clipboardItems = [];
// Assume `blob` is the blob representation of `kitten.webp`.
clipboardItems.push(
new ClipboardItem({
[blob.type]: blob,
})
);
await navigator.clipboard.write(clipboardItems);
console.log("Image copied, text ignored.");
} catch (err) {
console.error(err.name, err.message);
}
});
copy イベントの場合:
ClipboardItem の場合:
貼り付け: クリップボードからデータを読み取っています
readText()
クリップボードからテキストを読み取るには、navigator.clipboard.readText() を呼び出して、返された Promise が解決されるのを待ちます。
async function getClipboardContents() {
try {
const text = await navigator.clipboard.readText();
console.log('Pasted content: ', text);
} catch (err) {
console.error('Failed to read clipboard contents: ', err);
}
}
read()
navigator.clipboard.read() メソッドも非同期で、Promise を返します。クリップボードから画像を読み取るには、ClipboardItem オブジェクトのリストを取得して反復処理します。
各 ClipboardItem は異なる型でコンテンツを保持できるため、ここでも for...of ループを使用して型のリストを反復処理する必要があります。それぞれの型について、現在の型を引数として getType() メソッドを呼び出して、対応する blob を取得します。以前と同様に、このコードは画像に関連付けられていません。今後他のファイル形式でも使用できるようになる予定です。
async function getClipboardContents() {
try {
const clipboardItems = await navigator.clipboard.read();
for (const clipboardItem of clipboardItems) {
for (const type of clipboardItem.types) {
const blob = await clipboardItem.getType(type);
console.log(URL.createObjectURL(blob));
}
}
} catch (err) {
console.error(err.name, err.message);
}
}
貼り付けたファイルの操作
ユーザーがクリップボードのキーボード ショートカット（Ctrl+C、Ctrl+V など）を使用できると便利です。以下で説明するように、Chromium ではクリップボード上の読み取り専用ファイルを公開します。 これは、ユーザーがオペレーティング システムのデフォルトの貼り付けショートカットを押すか、ブラウザのメニューバーで [編集]、[貼り付け] の順にクリックしたときにトリガーされます。これ以上の配管コードは必要ありません。
document.addEventListener("paste", async e => {
e.preventDefault();
if (!e.clipboardData.files.length) {
return;
}
const file = e.clipboardData.files[0];
// Read the file's contents, assuming it's a text file.
// There is no way to write back to it.
console.log(await file.text());
});
貼り付けイベント
前述のように、Clipboard API と連携するイベントを導入する予定ですが、現時点では既存の paste イベントを使用できます。これは、クリップボード テキストを読み取る新しい非同期メソッドとうまく連携します。copy イベントと同様に、必ず preventDefault() を呼び出してください。
document.addEventListener('paste', async (e) => {
e.preventDefault();
const text = await navigator.clipboard.readText();
console.log('Pasted text: ', text);
});
複数の MIME タイプの処理
ほとんどの実装では、1 回の切り取りまたはコピー オペレーションのために、複数のデータ形式をクリップボードに配置します。これには 2 つの理由があります。1 つはアプリ デベロッパーにとって、ユーザーがテキストや画像をコピーするアプリの機能を把握できないことと、多くのアプリが構造化データを書式なしテキストとして貼り付けることをサポートしていることです。これは通常、[編集] メニュー項目の [スタイルを貼り付けて一致させる] や [書式なしで貼り付け] などの名前が付けられたユーザーに表示されます。
次の例はその方法を示しています。この例では、fetch() を使用して画像データを取得しますが、<canvas> や File System Access API から取得することもできます。
async function copy() {
const image = await fetch('kitten.png').then(response => response.blob());
const text = new Blob(['Cute sleeping kitten'], {type: 'text/plain'});
const item = new ClipboardItem({
'text/plain': text,
'image/png': image
});
await navigator.clipboard.write([item]);
}
セキュリティと権限
クリップボードへのアクセスは、ブラウザにとって常にセキュリティ上の懸念事項となっています。適切な権限がないと、ページからユーザーのクリップボードに悪意のあるあらゆるコンテンツが密かにコピーされ、貼り付け時に壊滅的な結果が生じるおそれがあります。たとえば、rm -rf / または解凍爆弾の画像をクリップボードに暗黙的にコピーするウェブページがあるとします。
ウェブページにクリップボードへの自由な読み取りアクセス権を付与することは、さらに厄介です。ユーザーは、パスワードや個人情報などの機密情報を定期的にクリップボードにコピーして、ユーザーの知らないところでどのページからも読み取られる可能性があります。
多くの新しい API と同様に、Clipboard API は HTTPS 経由で提供されるページでのみサポートされます。不正使用を防ぐため、クリップボードへのアクセスは、ページがアクティブなタブの場合にのみ許可されます。アクティブなタブにあるページは、権限をリクエストしなくてもクリップボードに書き込むことができますが、クリップボードから読み取るには、常に権限が必要です。
コピーと貼り付けの権限が Permissions API に追加されました。clipboard-write 権限は、タブがアクティブなページに自動的に付与されます。clipboard-read 権限をリクエストする必要があります。そのためには、クリップボードからデータを読み取ってみます。次のコードは後者を示しています。
const queryOpts = { name: 'clipboard-read', allowWithoutGesture: false };
const permissionStatus = await navigator.permissions.query(queryOpts);
// Will be 'granted', 'denied' or 'prompt':
console.log(permissionStatus.state);
// Listen for changes to the permission state
permissionStatus.onchange = () => {
console.log(permissionStatus.state);
};
また、allowWithoutGesture オプションを使用して、カットまたは貼り付けを起動するためにユーザー操作が必要かどうかを制御できます。この値のデフォルト値はブラウザによって異なるため、必ず指定してください。
ここで、Clipboard API の非同期性が本当に役立ちます。クリップボード データの読み取りまたは書き込みを試行すると、権限がまだ付与されていない場合は、自動的にユーザーに権限の付与を求めるメッセージが表示されます。API は Promise ベースであるため、これは完全に透過的であり、ユーザーがクリップボード権限を拒否すると Promise が拒否され、ページが適切に応答できるようになります。
ブラウザでは、ページがアクティブなタブである場合にのみクリップボードへのアクセスを許可します。デベロッパー ツール自体がアクティブなタブであるため、一部の例はブラウザのコンソールに直接貼り付けると実行されません。ヒント: setTimeout() を使用してクリップボードへのアクセスを延期し、ページ内をすばやくクリックして、関数が呼び出される前にフォーカスします。
setTimeout(async () => {
const text = await navigator.clipboard.readText();
console.log(text);
}, 2000);
権限ポリシーの統合
iframes で API を使用するには、権限ポリシーで API を有効にする必要があります。このポリシーでは、さまざまなブラウザ機能や API を選択的に有効または無効にできるメカニズムが定義されています。具体的には、アプリのニーズに応じて clipboard-read と clipboard-write のいずれかまたは両方を渡す必要があります。
<iframe
src="index.html"
allow="clipboard-read; clipboard-write"
>
</iframe>
機能検出
すべてのブラウザをサポートしながら Async Clipboard API を使用するには、navigator.clipboard をテストして以前のメソッドにフォールバックします。例として、他のブラウザを含めるための貼り付けの実装方法を示します。
document.addEventListener('paste', async (e) => {
e.preventDefault();
let text;
if (navigator.clipboard) {
text = await navigator.clipboard.readText();
}
else {
text = e.clipboardData.getData('text/plain');
}
console.log('Got pasted text: ', text);
});
それだけではありません。Async Clipboard API が登場する前は、ウェブブラウザ間でさまざまなコピーと貼り付けの実装が混在していました。ほとんどのブラウザでは、document.execCommand('copy') と document.execCommand('paste') を使用して、ブラウザ独自のコピーと貼り付けをトリガーできます。コピーするテキストが DOM に存在しない文字列の場合は、DOM に挿入して選択する必要があります。
button.addEventListener('click', (e) => {
const input = document.createElement('input');
input.style.display = 'none';
document.body.appendChild(input);
input.value = text;
input.focus();
input.select();
const result = document.execCommand('copy');
if (result === 'unsuccessful') {
console.error('Failed to copy text.');
}
input.remove();
});
デモ
以下のデモでは、Async Clipboard API を試すことができます。Glitch では、テキストデモまたは画像デモをリミックスして試すことができます。
最初の例では、クリップボード内外へのテキストの移動について説明します。
画像で API を試すには、このデモを使用してください。すでに説明したように、PNG は一部のブラウザでのみサポートされています。
関連リンク
謝辞
Aasync Clipboard API は Darwin Huang 氏と Gary Kachamarchak 氏によって実装されました。また、Darwin もデモを提供しました。この記事の一部にレビューを添えてくれた Kyarik と Gary KaChmarchak に感謝します。
ヒーロー画像（作成者: Markus Winkler、Unsplash）