从 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 的完整性对于应用的正常运行至关重要。在这种情况下,您有两种选择:
- 如果您同时控制复制和粘贴端,例如,如果您从应用内复制,然后同样在应用内粘贴,则应使用适用于 Async Clipboard API 的 Web 自定义格式。无需再继续阅读下文,请参阅链接的文章。
- 如果您只能控制应用中的粘贴端,而无法控制复制端(可能是因为复制操作发生在不支持 Web 自定义格式的原生应用中),则应使用
unsanitized选项,本文的其余部分将对此进行说明。
清理包括移除 script 标记、内嵌样式以及确保 HTML 格式正确等操作。此列表并不详尽,未来可能会添加更多步骤。
复制并粘贴未经排查的 HTML
当您使用 Async Clipboard API 将 HTML write()(复制)到剪贴板时,浏览器会通过 DOM 解析器运行 HTML 并序列化生成的 HTML 字符串,以确保其格式正确,但此步骤不会进行排查。您无需执行任何操作。当您read()其他应用放置在剪贴板上的 HTML,并且您的 Web 应用选择启用接收完整保真度的内容并需要在您自己的代码中执行任何清理时,您可以将一个选项对象传递给 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 团队指定和实现。