從 Chrome 120 開始,Async Clipboard API 提供新的 unsanitized 選項。在 HTML 的特殊情況下,如果您需要貼上與複製時完全相同的剪貼簿內容,這個選項會很有幫助。也就是說,不經過瀏覽器通常會採用的任何中間淨化步驟 (這是有充分理由的)。請參閱本指南,瞭解如何使用這項功能。
使用 Async Clipboard API 時,在大多數情況下,開發人員不必擔心剪貼簿內容的完整性,並可假設他們寫入剪貼簿 (複製) 的內容與他們從剪貼簿讀取資料 (貼上) 時取得的內容相同。
文字絕對是如此。請嘗試將下列程式碼貼到開發人員工具控制台中,然後立即重新聚焦頁面。(setTimeout() 是必要項目,這樣您才有足夠的時間聚焦在頁面上,這是 Async Clipboard API 的必要條件)。如您所見,輸入內容與輸出內容完全相同。
setTimeout(async () => {
const input = 'Hello';
await navigator.clipboard.writeText(input);
const output = await navigator.clipboard.readText();
console.log(input, output, input === output);
// Logs "Hello Hello true".
}, 3000);
圖片則稍有不同。為防止所謂的壓縮炸彈攻擊,瀏覽器會重新編碼 PNG 等圖片,但輸入和輸出圖片在視覺上完全相同,每個像素都一樣。
setTimeout(async () => {
const dataURL =
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=';
const input = await fetch(dataURL).then((response) => response.blob());
await navigator.clipboard.write([
new ClipboardItem({
[input.type]: input,
}),
]);
const [clipboardItem] = await navigator.clipboard.read();
const output = await clipboardItem.getType(input.type);
console.log(input.size, output.size, input.type === output.type);
// Logs "68 161 true".
}, 3000);
不過,HTML 文字會發生什麼情況?您可能已經猜到,HTML 的情況不同。瀏覽器會清理 HTML 程式碼,防止發生不良情況,例如從 HTML 程式碼中移除 <script> 標記 (以及 <meta>、<head> 和 <style> 等其他標記),並內嵌 CSS。請參考以下範例,並在開發人員工具控制台中試用。您會發現輸出內容與輸入內容有很大的差異。
setTimeout(async () => {
const input = `<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="ProgId" content="Excel.Sheet" />
<meta name="Generator" content="Microsoft Excel 15" />
<style>
body {
font-family: HK Grotesk;
background-color: var(--color-bg);
}
</style>
</head>
<body>
<div>hello</div>
</body>
</html>`;
const inputBlob = new Blob([input], { type: 'text/html' });
await navigator.clipboard.write([
new ClipboardItem({
'text/html': inputBlob,
}),
]);
const [clipboardItem] = await navigator.clipboard.read();
const outputBlob = await clipboardItem.getType('text/html');
const output = await outputBlob.text();
console.log(input, output);
}, 3000);
HTML 清理通常是好事。在大多數情況下,您不希望允許未經清理的 HTML,以免暴露在安全問題中。不過,在某些情況下,開發人員確切知道自己在做什麼,且輸入和輸出 HTML 的完整性對於應用程式的正常運作至關重要。在這種情況下,您有兩種選擇:
- 如果您同時控制複製和貼上端,例如從應用程式內複製,然後同樣在應用程式內貼上,則應使用非同步剪貼簿 API 的網頁自訂格式。請停止閱讀本文,並查看連結的文章。
- 如果您只能控制應用程式中的貼上端,而無法控制複製端 (可能是因為複製作業發生在不支援網頁自訂格式的原生應用程式中),則應使用
unsanitized選項,本文其餘部分將說明這個選項。
清理作業包括移除 script 標記、內嵌樣式,以及確保 HTML 格式正確。這份清單並未列出所有步驟,日後可能會新增更多步驟。
複製及貼上未經清理的 HTML
使用 Async Clipboard API 將 HTML write() (複製) 到剪貼簿時,瀏覽器會透過 DOM 剖析器執行 HTML,並序列化產生的 HTML 字串,確保 HTML 格式正確,但這個步驟不會進行清理。您不需要採取任何行動。當您 read() 其他應用程式放置在剪貼簿上的 HTML,且網頁應用程式選擇加入取得完整擬真內容,並需要在自己的程式碼中執行任何清理作業時,您可以將選項物件傳遞至 read() 方法,並使用屬性 unsanitized 和值 ['text/html']。單獨來看,它看起來像這樣:navigator.clipboard.read({ unsanitized: ['text/html'] })。以下程式碼範例與先前顯示的範例幾乎相同,但這次加入了 unsanitized 選項。在開發人員工具控制台中試用時,您會發現輸入和輸出內容相同。
setTimeout(async () => {
const input = `<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="ProgId" content="Excel.Sheet" />
<meta name="Generator" content="Microsoft Excel 15" />
<style>
body {
font-family: HK Grotesk;
background-color: var(--color-bg);
}
</style>
</head>
<body>
<div>hello</div>
</body>
</html>`;
const inputBlob = new Blob([input], { type: 'text/html' });
await navigator.clipboard.write([
new ClipboardItem({
'text/html': inputBlob,
}),
]);
const [clipboardItem] = await navigator.clipboard.read({
unsanitized: ['text/html'],
});
const outputBlob = await clipboardItem.getType('text/html');
const output = await outputBlob.text();
console.log(input, output);
}, 3000);
瀏覽器支援和功能偵測
由於無法直接檢查是否支援這項功能,因此功能偵測會根據觀察到的行為進行。因此,以下範例會偵測 <style> 標記是否留存 (表示支援) 或內嵌 (表示不支援)。請注意,網頁必須先取得剪貼簿權限,才能執行這項操作。
const supportsUnsanitized = async () => {
const input = `<style>p{color:red}</style><p>a`;
const inputBlob = new Blob([input], { type: 'text/html' });
await navigator.clipboard.write([
new ClipboardItem({
'text/html': inputBlob,
}),
]);
const [clipboardItem] = await navigator.clipboard.read({
unsanitized: ['text/html'],
});
const outputBlob = await clipboardItem.getType('text/html');
const output = await outputBlob.text();
return /<style>/.test(output);
};
示範
如要查看 unsanitized 選項的實際運作情形,請觀看示範並查看原始碼。
結論
如簡介所述,大多數開發人員都不必擔心剪貼簿清理作業,只要使用瀏覽器預設的清理選項即可。在極少數情況下,如果開發人員需要留意,可以使用 unsanitized 選項。
實用連結
特別銘謝
本文由 Anupam Snigdha 和 Rachel Andrew 審查。這個 API 是由 Microsoft Edge 團隊指定及實作。