取消屏蔽剪贴板访问权限

更安全、更安全地访问文字和图片剪贴板

Jason Miller
Thomas Steiner

传统上，访问系统剪贴板的方法是通过 document.execCommand() 进行剪贴板交互。虽然这种剪切和粘贴方法受到广泛支持，但存在一定的代价：剪贴板访问是同步的，并且只能读取和写入 DOM。

对于少量文本，这样做没问题，但在许多情况下，阻止页面进行剪贴板传输会带来糟糕的体验。在安全地粘贴内容之前，可能需要进行耗时的清理或图片解码。浏览器可能需要从粘贴的文件中加载或内嵌关联的资源。这会导致在等待磁盘或网络时阻塞网页。假设您在其中添加了权限，要求浏览器在请求剪贴板访问权限时屏蔽网页。同时，围绕 document.execCommand() 设置用于剪贴板互动的权限定义宽松，并且因浏览器而异。

Async Clipboard API 可解决这些问题，提供一个定义明确且不会屏蔽网页的权限模型。Async Clipboard API 仅限于在大多数浏览器上处理文本和图片，但支持情况因浏览器而异。请务必仔细研究以下各部分的浏览器兼容性概览。

复制：将数据写入剪贴板

writeText()

如需将文本复制到剪贴板，请调用 writeText()。由于此 API 是异步的，因此 writeText() 函数会返回一个 promise，该 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);
  }
}

浏览器支持

  • Chrome：66。
  • Edge：79。
  • Firefox：63。
  • Safari：13.1。

来源

write()

实际上，writeText() 只是通用 write() 方法的便捷方法，您还可以使用该方法将图片复制到剪贴板。与 writeText() 一样，它也是异步的，并返回 Promise。

如需将图片写入剪贴板，您需要该图片作为 blob。实现此目的的一种方法是使用 fetch() 从服务器请求图片，然后对响应调用 blob()。

由于各种原因，从服务器请求图片可能不合适或不可行。幸运的是，您还可以将图片绘制到画布并调用画布的 toBlob() 方法。

接下来，将 ClipboardItem 对象的数组作为参数传递给 write() 方法。目前，您一次只能传递一张图片，但我们希望未来能够支持多张图片。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);
}

浏览器支持

  • Chrome：76.
  • Edge：79。
  • Firefox：127.
  • Safari：13.1。

来源

复制事件

如果用户发起了剪贴板复制操作，但未调用 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 事件：

浏览器支持

  • Chrome：1.
  • Edge：12.
  • Firefox：22.
  • Safari：3.

来源

对于 ClipboardItem：

浏览器支持

  • Chrome：76.
  • Edge：79。
  • Firefox：127.
  • Safari：13.1。

来源

粘贴：从剪贴板读取数据

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);
  }
}

浏览器支持

  • Chrome：66.
  • Edge：79。
  • Firefox：125.
  • Safari：13.1。

来源

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);
  }
}

浏览器支持

  • Chrome：76.
  • Edge：79。
  • Firefox：127.
  • Safari：13.1。

来源

处理粘贴的文件

让用户能够使用剪贴板键盘快捷键（例如 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());
});

浏览器支持

  • Chrome：3.
  • Edge：12.
  • Firefox：3.6.
  • Safari：4.

来源

粘贴事件

如前所述，我们计划引入事件来与 Clipboard API 配合使用，但目前您可以使用现有的 paste 事件。它与用于读取剪贴板文本的新异步方法配合使用效果非常出色。与 copy 事件一样，别忘了调用 preventDefault()。

document.addEventListener('paste', async (e) => {
  e.preventDefault();
  const text = await navigator.clipboard.readText();
  console.log('Pasted text: ', text);
});

浏览器支持

  • Chrome：1.
  • Edge：12.
  • Firefox：22.
  • Safari：3.

来源

处理多种 MIME 类型

大多数实现都会在一次剪切或复制操作中将多种数据格式放入剪贴板。原因有二：作为应用开发者，您无法得知用户想要将文本或图片复制到哪个应用中，而且许多应用都支持将结构化数据粘贴为纯文本。通常，系统会通过修改菜单项向用户显示此功能，该菜单项的名称可能为粘贴并匹配样式或粘贴而不加格式。

以下示例展示了如何执行此操作。此示例使用 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 / 或解压缩炸弹图片复制到您的剪贴板。

浏览器提示，要求用户授予剪贴板权限。
Clipboard API 的权限提示。

向网页授予对剪贴板的无限制读取权限会带来更大的麻烦。用户经常将密码和个人信息等敏感信息复制到剪贴板，而任何网页都可以在用户不知情的情况下读取这些信息。

与许多新 API 一样，只有通过 HTTPS 提供的网页支持 Clipboard API。为了防止滥用，仅当页面是活动标签页时，才允许访问剪贴板。使用中的标签页中的页面可以在未请求权限的情况下向剪贴板中写入内容，但从剪贴板读取数据始终需要权限。

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);

权限政策集成

如需在 iframe 中使用该 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 格式受支持，而且仅在少数浏览器中受支持。

致谢

Async Clipboard API 由 Darwin Huang 和 Gary Kačmarčík 实现。Darwin 还提供了演示。 感谢 Kyarik 和 Gary Kačmarčík 审核本文的部分内容。

主打图片由 Unsplash 用户 Markus Winkler 提供。