一、简介
浏览器允许 JavaScript 脚本读写剪贴板,自动复制或粘贴内容。
一般来说,脚本不应该改动用户的剪贴板,以免不符合用户的预期。但是,有些时候这样做确实能够带来方便,比如"一键复制"功能,用户点击一下按钮,指定的内容就自动进入剪贴板。
目前,一共有三种方法可以实现剪贴板操作。
Document.execCommand()
方法- 异步的 Clipboard API
copy
事件和paste
事件
本文逐一介绍这三种方法。
二、Document.execCommand() 方法
Document.execCommand()
是操作剪贴板的传统方法,各种浏览器都支持。
它支持复制、剪切和粘贴这三个操作。
document.execCommand('copy')
(复制)document.execCommand('cut')
(剪切)document.execCommand('paste')
(粘贴)
(1)复制操作
复制时,先选中文本,然后调用document.execCommand('copy')
,选中的文本就会进入剪贴板。
const inputElement = document.querySelector('#input'); inputElement.select(); document.execCommand('copy');
上面示例中,脚本先选中输入框inputElement
里面的文字(inputElement.select()
),然后document.execCommand('copy')
将其复制到剪贴板。
注意,复制操作最好放在事件监听函数里面,由用户触发(比如用户点击按钮)。如果脚本自主执行,某些浏览器可能会报错。
(2)粘贴操作
粘贴时,调用document.execCommand('paste')
,就会将剪贴板里面的内容,输出到当前的焦点元素中。
const pasteText = document.querySelector('#output'); pasteText.focus(); document.execCommand('paste');
(3)缺点
Document.execCommand()
方法虽然方便,但是有一些缺点。
首先,它只能将选中的内容复制到剪贴板,无法向剪贴板任意写入内容。
其次,它是同步操作,如果复制/粘贴大量数据,页面会出现卡顿。有些浏览器还会跳出提示框,要求用户许可,这时在用户做出选择前,页面会失去响应。
为了解决这些问题,浏览器厂商提出了异步的 Clipboard API。
三、异步 Clipboard API
Clipboard API 是下一代的剪贴板操作方法,比传统的document.execCommand()
方法更强大、更合理。
它的所有操作都是异步的,返回 Promise 对象,不会造成页面卡顿。而且,它可以将任意内容(比如图片)放入剪贴板。
navigator.clipboard
属性返回 Clipboard 对象,所有操作都通过这个对象进行。
const clipboardObj = navigator.clipboard;
如果navigator.clipboard
属性返回undefined
,就说明当前浏览器不支持这个 API。
由于用户可能把敏感数据(比如密码)放在剪贴板,允许脚本任意读取会产生安全风险,所以这个 API 的安全限制比较多。
首先,Chrome 浏览器规定,只有 HTTPS 协议的页面才能使用这个 API。不过,开发环境(localhost
)允许使用非加密协议。
其次,调用时需要明确获得用户的许可。权限的具体实现使用了 Permissions API,跟剪贴板相关的有两个权限:clipboard-write
(写权限)和clipboard-read
(读权限)。"写权限"自动授予脚本,而"读权限"必须用户明确同意给予。也就是说,写入剪贴板,脚本可以自动完成,但是读取剪贴板时,浏览器会弹出一个对话框,询问用户是否同意读取。
另外,需要注意的是,脚本读取的总是当前页面的剪贴板。这带来的一个问题是,如果把相关的代码粘贴到开发者工具中直接运行,可能会报错,因为这时的当前页面是开发者工具的窗口,而不是网页页面。
(async () => { const text = await navigator.clipboard.readText(); console.log(text); })();
如果你把上面的代码,粘贴到开发者工具里面运行,就会报错。因为代码运行的时候,开发者工具窗口是当前页,这个页面不存在 Clipboard API 依赖的 DOM 接口。一个解决方法就是,相关代码放到setTimeout()
里面延迟运行,在调用函数之前快速点击浏览器的页面窗口,将其变成当前页。
setTimeout(async () => { const text = await navigator.clipboard.readText(); console.log(text); }, 2000);
上面代码粘贴到开发者工具运行后,快速点击一下网页的页面窗口,使其变为当前页,这样就不会报错了。
四、Clipboard 对象
Clipboard 对象提供了四个方法,用来读写剪贴板。它们都是异步方法,返回 Promise 对象。
4.1 Clipboard.readText()
Clipboard.readText()
方法用于复制剪贴板里面的文本数据。
document.body.addEventListener( 'click', async (e) => { const text = await navigator.clipboard.readText(); console.log(text); } )
上面示例中,用户点击页面后,就会输出剪贴板里面的文本。注意,浏览器这时会跳出一个对话框,询问用户是否同意脚本读取剪贴板。
如果用户不同意,脚本就会报错。这时,可以使用try...catch
结构,处理报错。
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); } }
4.2 Clipboard.read()
Clipboard.read()
方法用于复制剪贴板里面的数据,可以是文本数据,也可以是二进制数据(比如图片)。该方法需要用户明确给予许可。
该方法返回一个 Promise 对象。一旦该对象的状态变为 resolved,就可以获得一个数组,每个数组成员都是 ClipboardItem 对象的实例。
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); } }
ClipboardItem 对象表示一个单独的剪贴项,每个剪贴项都拥有ClipboardItem.types
属性和ClipboardItem.getType()
方法。
ClipboardItem.types
属性返回一个数组,里面的成员是该剪贴项可用的 MIME 类型,比如某个剪贴项可以用 HTML 格式粘贴,也可以用纯文本格式粘贴,那么它就有两个 MIME 类型(text/html
和text/plain
)。
ClipboardItem.getType(type)
方法用于读取剪贴项的数据,返回一个 Promise 对象。该方法接受剪贴项的 MIME 类型作为参数,返回该类型的数据,该参数是必需的,否则会报错。
4.3 Clipboard.writeText()
Clipboard.writeText()
方法用于将文本内容写入剪贴板。
document.body.addEventListener( 'click', async (e) => { await navigator.clipboard.writeText('Yo') } )
上面示例是用户在网页点击后,脚本向剪贴板写入文本数据。
该方法不需要用户许可,但是最好也放在try...catch
里面防止报错。
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); } }
4.4 Clipboard.write()
Clipboard.write()
方法用于将任意数据写入剪贴板,可以是文本数据,也可以是二进制数据。
该方法接受一个 ClipboardItem 实例作为参数,表示写入剪贴板的数据。
try { const imgURL = 'https://dummyimage.com/300.png'; const data = await fetch(imgURL); const blob = await data.blob(); await navigator.clipboard.write([ new ClipboardItem({ [blob.type]: blob }) ]); console.log('Image copied.'); } catch (err) { console.error(err.name, err.message); }
上面示例中,脚本向剪贴板写入了一张图片。注意,Chrome 浏览器目前只支持写入 PNG 格式的图片。
ClipboardItem()
是浏览器原生提供的构造函数,用来生成ClipboardItem
实例,它接受一个对象作为参数,该对象的键名是数据的 MIME 类型,键值就是数据本身。
下面的例子是将同一个剪贴项的多种格式的值,写入剪贴板,一种是文本数据,另一种是二进制数据,供不同的场合粘贴使用。
function copy() { const image = await fetch('kitten.png'); 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]); }
五、copy 事件,cut 事件
用户向剪贴板放入数据时,将触发copy
事件。
下面的示例是将用户放入剪贴板的文本,转为大写。
const source = document.querySelector('.source'); source.addEventListener('copy', (event) => { const selection = document.getSelection(); event.clipboardData.setData('text/plain', selection.toString().toUpperCase()); event.preventDefault(); });
上面示例中,事件对象的clipboardData
属性包含了剪贴板数据。它是一个对象,有以下属性和方法。
Event.clipboardData.setData(type, data)
:修改剪贴板数据,需要指定数据类型。Event.clipboardData.getData(type)
:获取剪贴板数据,需要指定数据类型。Event.clipboardData.clearData([type])
:清除剪贴板数据,可以指定数据类型。如果不指定类型,将清除所有类型的数据。Event.clipboardData.items
:一个类似数组的对象,包含了所有剪贴项,不过通常只有一个剪贴项。
下面的示例是拦截用户的复制操作,将指定内容放入剪贴板。
const clipboardItems = []; document.addEventListener('copy', async (e) => { e.preventDefault(); try { let clipboardItems = []; for (const item of e.clipboardData.items) { if (!item.type.startsWith('image/')) { continue; } clipboardItems.push( new ClipboardItem({ [item.type]: item, }) ); await navigator.clipboard.write(clipboardItems); console.log('Image copied.'); } } catch (err) { console.error(err.name, err.message); } });
上面示例中,先使用e.preventDefault()
取消了剪贴板的默认操作,然后由脚本接管复制操作。
cut
事件则是在用户进行剪切操作时触发,它的处理跟copy
事件完全一样,也是从Event.clipboardData
属性拿到剪切的数据。
六、paste 事件
用户使用剪贴板数据,进行粘贴操作时,会触发paste
事件。
下面的示例是拦截粘贴操作,由脚本将剪贴板里面的数据取出来。
document.addEventListener('paste', async (e) => { e.preventDefault(); const text = await navigator.clipboard.readText(); console.log('Pasted text: ', text); });
七、参考链接
- Unblocking clipboard access
- Interact with the clipboard
- Multi-MIME Type Copying with the Async Clipboard API
(完)
前端小学生 说:
兼容性咋样
2021年1月21日 10:10 | # | 引用
潘泽涛 说:
一个技术, 既可以一键复制,也可以禁止复制
世界真美好
2021年1月22日 09:20 | # | 引用
然殿下 说:
Document.execCommand()这个方法的兼容性相对较好,但是问题也是相当的多,恰巧前段时间遇到这样的需求。
列出几个问题:
对于需要复制的文本,
如果不是文本输入标签,需要主动创建一个可输入文本的标签(input和textarea)然后将待复制的文本赋值给这个标签,再调用.select()方法选中这个标签才能继续执行document.execCommand('copy');去复制。
如果是文本输入标签,标签不可以赋予disable或者readonly,这会影响select()方法。
移动端ios在选中输入框的时候会有自动调整页面缩放的问题,如果没有对这个进行处理,调用select()方法时(其实就是让标签处于focus状态)会出现同样的问题,(解决办法是input输入框的文字大小>=16px和
)双管齐下即可。
个人建议阮一峰老师所列方法中的Clipboard API,虽然浏览器兼容性没第一种广泛但相较后面几种应该好一点。但一家之言或许有些偏颇,欢迎指正,下次改正。
2021年1月22日 16:35 | # | 引用
Rigyoku 说:
第五节的Event.clipboardData..getData(type)多了个.
2021年1月25日 14:09 | # | 引用
阮一峰 说:
@Rigyoku:
谢谢指出,已经改正。
2021年1月25日 15:28 | # | 引用
余畅 说:
出一篇selection对象的教程吧
2021年1月25日 16:16 | # | 引用
未闻瓜名 说:
阮老师的教程看着舒服
2021年2月 5日 14:53 | # | 引用
flyboy 说:
const pasteText = document.querySelector('#output');
pasteText.focus();
document.execCommand('paste');
阮老师你好,这个我在chrome浏览器中测试了很多次都不行,在ie中是可以的,是浏览器兼容性问题吗?
2021年2月 6日 12:17 | # | 引用
余畅 说:
请问下老师,复制的word中的一段内容,文本中间插入了图片,粘贴的时候如何保持原来的顺序,我用上面的方法,都是先拿到所有的文本再拿到图片,所以图片永远都在最后
2021年2月23日 20:32 | # | 引用
vp 说:
老师的课程对我这个小白来说难度大~~~
2021年3月19日 15:39 | # | 引用
程小毓 说:
大神,什么时候可以讲一下uniapp使用mqtt协议的内容
2021年4月21日 14:32 | # | 引用
云冲 说:
刚好最近要搞这个东西就看见了
2021年6月 9日 09:12 | # | 引用
钱 说:
阮老师考虑考虑出个ES7、ES8教程把
2021年6月15日 14:42 | # | 引用
SilkyHeart 说:
最近使用了ClipboardJS但是遇到了很多坑,源生的接口又不是很兼容
2021年7月14日 14:33 | # | 引用
未知 说:
那如果我想复制一段dom结构该怎么操作,这个dom里包含了图片和视频
2021年7月16日 16:42 | # | 引用
bighb 说:
希望阮老师可以出一个webpack的教程
2021年8月12日 14:18 | # | 引用
123 说:
在火狐浏览器,一切paste的尝试都失败了
2021年8月14日 11:47 | # | 引用
路人A 说:
在Document.execCommand()前加await something()的话就会在safari浏览器里失败,暂时还不清楚原因
2021年10月24日 19:27 | # | 引用
路过 说:
writeText在线上直接undefine报错,也没有弹窗,开发环境是OK的,试着获取permission,Chrome在开发环境直接是granted,但是线上denied,也不会有任何弹窗提示,咋整呢,没有获取写剪切板的方法么~~
navigator.permissions.query({name:'clipboard-write'})
2021年11月 2日 16:49 | # | 引用
pippo 说:
最后的past事件回调里,
navigator.clipboard.readText();
还是会触发那个权限弹框
目前我们项目弄了一个div,直接设置contentediable:true, 事件触发后focus这个div,
然后在读取这个div的innerHTML或者dom对象,最后解析出来,当然也有局限性。
不知道有没问有问题
2021年11月11日 19:49 | # | 引用
大凯 说:
针对navigator.clipboard.writeText这个复制功能而言,在chrome中是没有问题的。但是在safira浏览器以及其他手机浏览器中有权限问题,用户没有开启权限的话,是不会拷贝内容的。同样execCommand('copy')也会因为权限问题,不能执行拷贝。
解决方案是将execCommand('copy')放到点击的监听事件函数中去执行。
或者使用clipboard这个库,看了下源码,他也是将execCommand('copy')放到点击的监听事件函数中去执行
2021年11月19日 17:18 | # | 引用
晴晴子衿 说:
最近在做一个需求,网页内的文字只能粘贴到网页内,不能粘贴到网页外;但是网页外的文字要可以粘贴到网页内。需要对粘贴事件进行拦截,一开始就用的这个 navigator.clipboard.readText()
但是这个方法有一定的局限性:1、必须在https协议的页面使用,不少内网系统仍然采用http协议; 2、每次粘贴都会调用navigator.clipboard.readText(),每次都会弹出提示框,用户体验很差。
粘贴的event事件里,使用event.clipboardData.items属性,也可以判断剪贴板里面有没有值,如果长度为0就代表为空,这种方法拦截粘贴事件,不会触发弹窗,也不需要https协议访问
2022年3月10日 21:09 | # | 引用
Sign 说:
如何复制一个桌面图片呢?虽然通过 paste 方法中,e.clipboardData.files 可以拿到图片内容,但下次粘贴如何清空该值呢?
2022年3月15日 13:53 | # | 引用
马超 说:
我这边是app的壳子,用webview嵌入的这个的页面,在该页面调用navigator.clipboard.writeText()
这个方法的时候,报错:The request is not allowedoby the user agent or the platform in the current context, possibly because the user denied permission
请问下这个大概是什么原因?用户没有开放权限吗?
2022年5月 6日 10:37 | # | 引用
Drylong 说:
最近的谷歌还是不支持write写入"text/html"格式的内容 唉-_-
2022年6月28日 11:07 | # | 引用
Jeremy 说:
Clipboard.write 能一次写入多个 image/png 吗? 怎么操作
2022年8月22日 18:13 | # | 引用
liliangrong777 说:
4.4 Clipboard.write()第二个事例少了个async
2022年9月 6日 17:42 | # | 引用
nowLetsToGO 说:
使用readText() 复制,总是出现默认的粘贴图标怎么解决?使用e.preventDefault没效果
2022年10月31日 18:24 | # | 引用
鬼魂灵动 说:
document.execCommand('copy');和readText() 这些方法从别的应用复制到本应用的时候,移动端都会多一个自带的粘贴标签?就不能只是返回文本信息自己设置? 因为在input标签中有自带的复制的功能,但是我是在一个div上复制粘贴的。所以感觉卡bug了。
2022年11月 4日 15:41 | # | 引用
半引号 说:
加了参数后缀的图片,例如:5991.png?watermark/4/text/6aOe6ZuA572R,这种图片路径,复制就出错了,这个怎么解决呀
2022年11月 8日 14:02 | # | 引用
曦灵 说:
在 WebView 中,Clipboard API 会抛出:NotAllowedError: Write permission denied.
2022年12月16日 23:46 | # | 引用
zaozaoya 说:
@晴晴子衿:
navigator.clipboard.readText()方法确实受协议影响,如果是使用event.clipboardData.items属性,触发事件还要用户主动触发吗,有实现一键复制粘贴的功能吗
2023年1月17日 17:42 | # | 引用
TangChony 说:
应该是异步链式调用Clipboard API 导致的,可以把请求URL的api和Clipboard API分开,参考飞书文档的分享
--个人愚见,有问题希望指出
2023年2月15日 09:44 | # | 引用
kyrie 说:
阮老师,这个帖子我可以转发一下吗?在我的博客里,我会标注出处,我要写一个类似的需求。
2023年8月 1日 15:48 | # | 引用