【Web API系列】使用异步剪贴板API（async clipboard）的图像的编程复制和粘贴

---

前言

访问系统剪贴板的传统方法是通过 document.execCommand() 进行剪贴板交互。虽然这种剪切和粘贴方法受到广泛支持，但还是有代价的：剪贴板访问是同步的，并且只能对 DOM 执行读写操作。

这对于少量文字来说没什么问题，但在很多情况下，阻止相应网页以进行剪贴板传输会带来糟糕的体验。可能需要耗时的清理或图片解码，才能安全粘贴内容。浏览器可能需要从粘贴的文档加载或内嵌链接的资源。这样会在等待磁盘或网络时阻塞网页。想象一下，向混合中添加权限，要求浏览器在请求剪贴板访问权限时屏蔽网页。同时，针对剪贴板交互的 document.execCommand() 设置的权限较为宽松，并且因浏览器而异。

但是 Chrome 从 104 版开始支持网页自定义格式，可让开发者将任意数据写入剪贴板。

如果你仍然对该技术知之甚少，建议看看过去大佬 Matt Gaunt 的文章是怎么实现怎么实现的。

现在，主流的浏览器已经原生支持这种功能。那就是Async Clipboard: Read and Write Images。

我所指的现在是指

浏览器	最低版本号	是否支持
Chrome	86	是
Edge	79	是
Firefox	63	不完整
Safari	13.1	是

接下来我将从官方提供的几个示例来介绍这个API。

---

一、将数据写入剪切板

1. WriteText()

如果只是想要将文本内容复制到剪切板，可以使用writeText()。由于此 API 是异步的，因此writeText()函数会返回一个根据传递的文本是否成功复制来解析或拒绝的 Promise：

async function copyPageUrl() {
  try {
    await navigator.clipboard.writeText(location.href);
    console.log('页面URL已经复制到剪切板');
  } catch (err) {
    console.error('复制失败: ', err);
  }
}

2. Write()

如果你想要把剪切板中写入图片，那就使用Write()方法，但是要注意需要用 blob 格式的图片作为参数，或者fetch()等请求服务器图片，调用blob()方法转换成为合适的格式。也可以将图片绘制到canvas里面，然后调用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({
      // 键“blob.type”动态决定blob的文件格式
      [blob.type]: blob
    })
  ]);
  console.log('图片复制完毕');
} catch (err) {
  console.error(err.name, err.message);
}

或者你可以规定复制的文件格式

try {
  const imgURL = '/images/generic/file.png';
  await navigator.clipboard.write([
    new ClipboardItem({
      'image/png': fetch(imgURL).then(response => response.blob()),
    })
  ]);
  console.log('图片复制完毕');
} catch (err) {
  console.error(err.name, err.message);
}

3. 监听复制事件

如果用户复制到剪贴板，但未调用 preventDefault()，则 copy 事件会包含一个 clipboardData 属性，其中包含的内容已采用正确的格式。

document.addEventListener("copy", async (e) => {
  // 阻止事件冒泡
  e.preventDefault();
  try {
    // 准备clipboardItems对象数组
    let clipboardItems = [];
    // 将图片放到剪切板
    clipboardItems.push(
      new ClipboardItem({
        [blob.type]: blob,
      })
    );
    await navigator.clipboard.write(clipboardItems);
    console.log("图片已被复制，文字已省略");
  } catch (err) {
    console.error(err.name, err.message);
  }
});

二、从剪切板读取数据

1.readText()

从剪切板读取文本数据，调用navigator.clipboard.readText()代码如下

async function getClipboardContents() {
  try {
    const text = await navigator.clipboard.readText();
    console.log('粘贴内容: ', text);
  } catch (err) {
    console.error('内容读取失败: ', err);
  }
}

2.read()

从剪贴板读取图片，需要获取 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);
  }
}

3. 处理粘贴的文件

让用户能够使用剪贴板键盘快捷键（例如 ctrl + c 和 ctrl + v）非常有用。Chromium 会在剪贴板上公开只读文件，如下所述。 当用户点击操作系统的默认粘贴快捷方式，或当用户点击浏览器菜单栏中的修改，然后再点击粘贴时，就会触发此事件。

document.addEventListener("paste", async e => {
  e.preventDefault();
  if (!e.clipboardData.files.length) {
    return;
  }
  const file = e.clipboardData.files[0];
  // 加入读取的文件是文本文件
  // note： 只能读，不能写
  console.log(await file.text());
});

4. 监听读剪切板事件

处理粘贴的文件其实就是通过监听度剪切板的功能来实现的，看下面用例

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

三、申请权限

这类原生API对于跨端应用会非常有用，申请权限就是为了这个做准备的。当你需要使用剪切板的功能的时候，必须申请权限才能使用，此处调用代码与其他API基本一致，直接给出代码供大家参考。

const queryOpts = { name: 'clipboard-read', allowWithoutGesture: false };
const permissionStatus = await navigator.permissions.query(queryOpts);
// 结果是 'granted'（已授权）, 'denied'（已拒绝） or 'prompt'（询问）:
console.log(permissionStatus.state);

// 监听权限状态改变
permissionStatus.onchange = () => {
  console.log(permissionStatus.state);
};

allowWithoutGesture 选项控制是否需要用户手势才能调用剪切或粘贴。

由于浏览器仅允许页面为活动标签页时访问剪贴板，您会发现，如果直接粘贴到浏览器的控制台中，此处的部分示例不会运行，因为开发者工具本身就是活跃标签页。有一种技巧：使用 setTimeout() 延迟对剪贴板的访问，然后在页面内快速点击使其成为焦点，然后再调用函数：

setTimeout(async () => {
  const text = await navigator.clipboard.readText();
  console.log(text);
}, 2000);

政策集成

在iframe中使用剪切板API的时候用的，用例如下

<iframe
    src="index.html"
    allow="clipboard-read; clipboard-write"
>
</iframe>

四、功能检测

在使用剪切板API的时候可以提前检测浏览器是否支持这个API，如果不支持则使用过去浏览器的方案，会让你的功能变得更加可靠，提供高用户体验。官方给出样例

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('从剪切板获取到的文本: ', text);
});

五、处理多个 MIME 类型

对于一次剪切或复制操作，大多数实现都会将多种数据格式放到剪贴板中。这有两个原因：作为应用开发者，您无法知道用户想要将文本或图片复制到的应用的功能，并且许多应用支持将结构化数据粘贴为纯文本。这通常通过修改菜单项向用户显示，对应的名称为粘贴和匹配样式或粘贴（不带格式）。

下面示例中使用的是fetch()得到的数据，这是因为读取本地文件需要获取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]);
}