访问系统剪贴板的传统方法是通过 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。
如果只是想要将文本内容复制到剪切板,可以使用writeText()
。由于此 API 是异步的,因此writeText()
函数会返回一个根据传递的文本是否成功复制来解析或拒绝的 Promise:
async function copyPageUrl() {
try {
await navigator.clipboard.writeText(location.href);
console.log('页面URL已经复制到剪切板');
} catch (err) {
console.error('复制失败: ', err);
}
}
如果你想要把剪切板中写入图片,那就使用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);
}
如果用户复制到剪贴板,但未调用 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);
}
});
从剪切板读取文本数据,调用navigator.clipboard.readText()
代码如下
async function getClipboardContents() {
try {
const text = await navigator.clipboard.readText();
console.log('粘贴内容: ', text);
} catch (err) {
console.error('内容读取失败: ', err);
}
}
从剪贴板读取图片,需要获取 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];
// 加入读取的文件是文本文件
// note: 只能读,不能写
console.log(await file.text());
});
处理粘贴的文件其实就是通过监听度剪切板的功能来实现的,看下面用例
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);
});
对于一次剪切或复制操作,大多数实现都会将多种数据格式放到剪贴板中。这有两个原因:作为应用开发者,您无法知道用户想要将文本或图片复制到的应用的功能,并且许多应用支持将结构化数据粘贴为纯文本。这通常通过修改菜单项向用户显示,对应的名称为粘贴和匹配样式或粘贴(不带格式)。
下面示例中使用的是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]);
}