项目代码:github.com/Haixiang612…预览地址:yanhaixiang.com/my-copy-to-…参考轮子:www.npmjs.com/package/cop…
用 JS 来复制文本在网页应用里十分常见,比如 github 里复制 remote 地址的功能:
今天就来带大家一起写一个 JS 复制文本的轮子吧~
从零开始
关于 JS 做复制功能的文章还挺多的,这里列举一篇 阮一峰的《剪贴板操作 Clipboard API 教程》 作为例子。
大部分文章的做法是这样:创建一个输入框(input 或者 textarea),将复制文本赋值到元素的 value 值,JS 选中文本内容,最后使用 document.exec('copy')
完成复制。
这里的问题是,在某些环境下文本输入框会存在一些怪异的行为,比如:
- 如果不是文本输入标签,需要主动创建一个可输入文本的标签(input和textarea)然后将待复制的文本赋值给这个标签,再调用.select()方法选中这个标签才能继续执行
document.execCommand('copy')
去复制。 - 如果是文本输入标签,标签不可以赋予 disable 或者 readonly,这会影响
select()
方法。 - 移动端 iOS 在选中输入框的时候会有自动调整页面缩放的问题,如果没有对这个进行处理,调用
select()
方法时(其实就是让标签处于focus状态)会出现同样的问题。
听起来就很麻烦。为了去掉这些兼容问题,可以使用 <span>
元素作为复制文本的容器,那先按上面的思路,造一个最简单的轮子吧。
const copy = (text: string) => { const range = document.createRange() const selection = document.getSelection() const mark = document.createElement('span') mark.textContent = text // 插入 body 中 document.body.appendChild(mark) // 选中 range.selectNodeContents(mark) selection.addRange(range) const success = document.execCommand('copy') if (success) { alert('复制成功') } else { alert('复制失败') } if (mark) { document.body.removeChild(mark) } } 复制代码
这里用到 Selection 和 Range 两个对象。关于 Selection 表示用户选择的文本范围或插入符号的当前位置。它代表页面中的文本选区,可能横跨多个元素;而 Range 表示一个包含节点与文本节点的一部分的文档片段。一个 Selection 可以有多个 Range 对象。
上面逻辑很简单,创建 span
元素,从 textContent
加入复制文本。这里有人就问了:为啥不用 innerText
呢?他们有什么区别呢?区别详见 Stackoverflow: Difference between textContent vs innerText。
好的我知道你不会看的,这里就简单列一下吧:
- 首先
innerText
是非标准的,textContent
是标准的 innerText
非常容易受 CSS 的影响,textContent
则不会:innerText
只返回可见的文本,而textContent
返回全文本。比如 "Hello Wold" 文本,用 display: none 把 "Hello" 变成看不见了,那么innerText
会返回 "World",而textContent
返回 "Hello World"。innerText
性能差一点,因为需要等到渲染完了之后通过页面布局信息来获取文本innerText
通过 HTMLElement 拿到,而textContent
可以通过所有 Node 拿到,获取范围更广一些
回到代码,把创建好的 span 放入 document.body 里,并选中元素,把 range 加入 selection 中,document.exec
执行复制操作,最后一步把 mark 元素移除,收工了。
复制时好时坏
如果你弄了个按钮并绑定 copy('Hello')
,点击后会发现:咦?怎么时好时坏的?一会可以复制一会又不行了。
刚刚提到 Selection 有可能是插入符号的当前位置,啥意思?想一想鼠标点一下算不算选区呢?算的,只是长度为 0 你看不见而已。
这时它被标记为 Collapsed,这表示选区被压缩至一点,即光标位置。—— Selection
长度为 0 好像也没什么问题嘛,刚刚代码不是 addRange
了么?然而 addRange
并不会添加新 Range 到 Selection 中!
Currently only Firefox supports multiple selection ranges, other browsers will not add new ranges to the selection if it already contains one. —— Selection.addRange()
总结一下复制不成功的问题:
- 当鼠标无意地点击到页面时(比如按钮),Selection 会加入一个看不见的 Range(变成光标的位置,而不是一个选中的区域了)
- 在我们代码中
selection.addRange
后并不会把 span 里的选中文本作为新的 Range 加入 Selection - 执行
document.exec('copy')
的时候,由于选区是个光标位置,复制了个寂寞,粘贴板还是原来的复制内容,不会改变,如果原来是空,那粘贴出来的还是空 - 既然执行了个寂寞,为啥 success 不为
false
呢?因为 MDN 说了执行成功或者失败和返回值毛关系没有,只有document.exec
不被浏览器支持或未被启用才会返回false
。
Note:
document.execCommand()
only returnstrue
if it is invoked as part of a user interaction. You can't use it to verify browser support before calling a command. From Firefox 82, nesteddocument.execCommand()
calls will always returnfalse
. —— Document.execCommand()
解决方法是:使用 selection.removeAllRanges
,在 selection.addRange
之前把原有的 Range 清干净就可以了。
const copy = (text: string) => { const range = document.createRange() const selection = document.getSelection() const mark = document.createElement('span') mark.textContent = text document.body.appendChild(mark) range.selectNodeContents(mark) selection.removeAllRanges() // 移除调用前已经存在 Range selection.addRange(range) const success = document.execCommand('copy') if (success) { console.log('复制成功') } else { console.log('复制失败') } if (mark) { document.body.removeChild(mark) } } 复制代码
上面使用 selection.removeAllRanges
移除当前的 Range,这样就可以把要复制的 Range 加入到 Selection 中了。
toggle-selection
上面虽然解决了不能复制的问题,但是会把原来选中的区域也整没了。比如用户选了一段文字,执行了 copy
导致原来的文字没有选中了。copy
函数就会有 side-effect 了,对应用不友好。
解决方法也很简单:执行 copy
前移除当前选区,执行过后再恢复原来选区。
export const deselectCurrent = () => { const selection = document.getSelection() // 当前没有选中 if (selection.rangeCount === 0) { return () => {} } let $active = document.activeElement // 获取当前选中的 ranges const ranges: Range[] = [] for (let i = 0; i < selection.rangeCount; i++) { ranges.push(selection.getRangeAt(i)) } // deselect selection.removeAllRanges(); return () => { // 如果是插入符则移除 ranges if (selection.type === 'Caret') { selection.removeAllRanges() } // 没有选中,就把之前的 ranges 加回来 if (selection.rangeCount === 0) { ranges.forEach(range => { selection.addRange(range) }) } } } 复制代码
deselectCurrent
函数将当前选区存在 ranges
里,最后返回一个函数,该函数可用于恢复当前选区。
另外,我们还要考虑到如果 activeElement
为 input 或 textarea 的情况,deselect 时要 blur,reselect 时则要 focus 回来。
export const deselectCurrent = () => { const selection = document.getSelection() if (selection.rangeCount === 0) { return () => {} } let $active = document.activeElement const ranges: Range[] = [] for (let i = 0; i < selection.rangeCount; i++) { ranges.push(selection.getRangeAt(i)) } // 如果为输入元素先 blur 再 focus switch ($active.tagName.toUpperCase()) { case 'INPUT': case 'TEXTAREA': ($active as HTMLInputElement | HTMLTextAreaElement).blur() break default: $active = null } selection.removeAllRanges(); return () => { if (selection.type === 'Caret') { selection.removeAllRanges() } if (selection.rangeCount === 0) { ranges.forEach(range => { selection.addRange(range) }) } // input 或 textarea 要再 focus 回来 if ($active) { ($active as HTMLInputElement | HTMLTextAreaElement).focus() } } } 复制代码
在 copy
里就可以愉快 deselect 和 reselect 了:
const copy = (text: string) => { const reselectPrevious = deselectCurrent() // 去掉当前选区 ... const success = document.execCommand('copy') if (mark) { document.body.removeChild(mark) } reselectPrevious() // 恢复以前的选区 return success } 复制代码
onCopy
复制的时候将触发 copy 事件,因此这里还可以给调用方提供 onCopy
的回调,自定义 listener。
interface Options { onCopy?: (copiedText: DataTransfer | null) => unknown } const copy = (text: string, options: Options = {}) => { const {onCopy} = options const reselectPrevious = deselectCurrent() const range = document.createRange() const selection = document.getSelection() const mark = document.createElement('span') mark.textContent = text // 自定义 onCopy mark.addEventListener('copy', (e) => { if (onCopy) { e.stopPropagation() e.preventDefault() onCopy(e.clipboardData) } }) document.body.appendChild(mark) range.selectNodeContents(mark) selection.addRange(range) const success = document.execCommand('copy') if (mark) { document.body.removeChild(mark) } reselectPrevious() return success } 复制代码
这里添加了 "copy" 事件的监听。e.stopPropagation
阻止 copy 事件冒泡,e.prevenDefault
禁止默认响应,然后用 onCopy
函数接管复制事件的响应。同时,onCopy
里传入 e.clipbaordData
,调用方可以随意处理复制的数据。
比如:
$myCopy.onclick = () => { const myText = 'my text' copy('xxx', { onCopy: (clipboardData) => clipboardData.setData('text/plain', myText), // 复制 'my-text' }) } 复制代码
有人就会问了:这个 setData
好理解,不就设置复制文本嘛,那要这个 “text/plain" 干嘛用?
DataTransfer 里的 format
不知道大家有没有关注过 clipboardData
类型呢?它其实是一个 DataTransfer
的类型,那 DataTransfer
又是干啥的?一般是拖拽时,用于存放拖拽内容的。复制也算是数据转移的一种,所以 clipboardData
也为 DataTransfer 类型。
复制本质上是复制内容而非单一的文本,也有格式的。我们可能学时一般就复制几个文字,但是在一些情况下,比如复制一个链接、一个 <h1>
标签的元素、甚至一张图片后,当粘贴到 docs 文件的时候,会发现这些元素的样式和图片全都带过来了。
为什么发生这样的事?因为在复制的时候系统会设定 format,而 World 正好可以识别这些 format,所以可以直接展示出带样式的复制内容。
目前我们的函数仅支持纯文本的复制,应该再加一个 format
,让调用方自定义复制的格式。
interface Options { onCopy?: (copiedText: DataTransfer | null) => unknown format?: Format } const copy = (text: string, options: Options = {}) => { const {onCopy} = options const reselectPrevious = deselectCurrent() const range = document.createRange() const selection = document.getSelection() const mark = document.createElement('span') mark.textContent = text mark.addEventListener('copy', (e) => { e.stopPropagation(); // 带格式去复制内容 if (format) { e.preventDefault() e.clipboardData.clearData() e.clipboardData.setData(format, text) } if (onCopy) { e.preventDefault() onCopy(e.clipboardData) } }) document.body.appendChild(mark) range.selectNodeContents(mark) selection.addRange(range) const success = document.execCommand('copy') if (mark) { document.body.removeChild(mark) } reselectPrevious() return success } 复制代码
在刚刚代码基础上,我们可以在 copy 事件里判断是否有 format,如果有则直接接管 copy listener,clearData
清除复制内容,然后 setData(format, text)
来复制内容。
兼容 IE
前端工程师们都会有一个共通的一生之敌——IE。目前查了文档,有以下兼容问题:
- 在 IE 11 下,format 这里只有
Text
和Url
两种 - 在 IE 下,copy 事件中
e.clipboardData
为undefined
,但是会有window.clipboardData
- 在 IE 9 以下,
document.execCommand
可能不被支持(有些贴子说可以,有些贴子说有问题)
针对上面的问题,我们要为 format
、e.clipboardData
和 document.execCommand
做好兜底兼容操作。
首先是 format
,提供一个 format 的转换 Mapper:
type Format = 'text/plain' | 'text/html' | 'default' type IE11Format = 'Text' | 'Url' const clipboardToIE11Formatting: Record<Format, IE11Format> = { "text/plain": "Text", "text/html": "Url", "default": "Text" } 复制代码
接下来是 e.clipboardData
做兼容,这里有个知识点是在 IE 下,window
会有一个 clipboardData
,我们可以把要复制的内容存到 window.clipboardData
。注意:这个全局变量只有 IE 下才会有,普通情况下还是使 e.clipboardData
。
const copy = (text: string, options: Options = {}) => { ... mark.addEventListener('copy', (e) => { e.stopPropagation(); if (format) { e.preventDefault() if (!e.clipboardData) { // 只有 IE 11 里 e.clipboardData 一直为 undefined // 这里 format 要转为 IE 11 里指定的 format const IE11Format = clipboardToIE11Formatting[format || 'default'] // @ts-ignore clearData 只有 IE 上有 window.clipboardData.clearData() // @ts-ignore setData 只有 IE 上有 window.clipboardData.setData(IE11Format, text); } else { e.clipboardData.clearData() e.clipboardData.setData(format, text) } } if (onCopy) { e.preventDefault() onCopy(e.clipboardData) } }) ... } 复制代码
最后一步是对 document.execCommand
做兼容。目前我自己搜到的是会出现不生效的问题,以及 execCommand
不支持的问题,为了应对 IE 下绝大多的问题,我们可以祭出 try-catch 大法,只要有 error,通通走 IE 的老路子去做复制。
const copy = (text: string, options: Options = {}) => { ...… try { // execCommand 有些浏览器可能不支持,这里要 try 一下 success = document.execCommand('copy') if (!success) { throw new Error("Can't not copy") } } catch (e) { try { // @ts-ignore window.clipboardData 这鬼玩意只有 IE 上有 window.clipboardData.setData(format || 'text', text) // @ts-ignore window.clipboardData 这鬼玩意只有 IE 上有 onCopy && onCopy(window.clipboardData) } catch (e) { // 最后兜底方案,让用户在 window.prompt 的时候输入 window.prompt('输入需要复制的内容', text) } } finally { if (selection.removeRange) { selection.removeRange(range) } else { selection.removeAllRanges() } if (mark) { document.body.removeChild(mark) } reselectPrevious() } return success } 复制代码
上面加了好几个 try-catch,第一个兼容 document.execCommand
,有问题走 window.clipboardData.setData
的方式来复制。第二个为兜底方案,使用 window.prompt
作为兜底。
最后 finally 里对 selection.removeRange
做了兼容,优先使用 removeRange
,失败再使用 removeAllRanges
清除所有 Range。
兼容样式
在创建和添加 mark 时还要对其样式进行处理,防止页面出现 side-effect,比如:
- 添加和删除 mark 不能造成页面滚动
- span 元素的 space 和 line-break 要为
pre
,复制时可以把换行等特殊符号也带上 - 外部有可能会被设置成 "none",所以 user-select 一定要为 "text",不然连选都选不中
const updateMarkStyles = (mark: HTMLSpanElement) => { // 重置用户样式 mark.style.all = "unset"; // 放在 fixed,防止添加元素后触发滚动行为 mark.style.position = "fixed"; mark.style.top = '0'; mark.style.clip = "rect(0, 0, 0, 0)"; // 保留 space 和 line-break 特性 mark.style.whiteSpace = "pre"; // 外部有可能 user-select 为 'none',因此这里设置为 text mark.style.userSelect = "text"; } const copy = (text: string, options: Options = {}) => { ... const mark = document.createElement('span') mark.textContent = text updateMarkStyles(mark) mark.addEventListener('copy', (e) => { ... }) ... } 复制代码
在创建 span 元素之后应该马上更新样式,确保不会有页面变化(副作用)。
总结
目前已经完成 copy-to-clipboard 这个库的所有功能了,主要做了以下几件事:
- 完成复制功能
- 复制后会恢复原来选区
- 提供 onCopy,调用方可自己定义复制 listener
- 提供 format,可多格式复制
- 兼容了 IE
- 对样式做了兼容,在不对页面产生副作用情况下完成复制功能
最后
JS 复制这个需求应该不少人都会遇到过。然而真正研究起来,要考虑的东西还是很多的。
如果仅仅只是扫一眼源码可能只会做出”从零开始“这一版,后面的兼容、format、回调等功能真的特别难想到。
最后再来说一下 Clipboard API。Clipboard API 是下一代的剪贴板操作方法,比传统的 document.execCommand() 方法更强大、更合理。它的所有操作都是异步的,返回 Promise 对象,不会造成页面卡顿。而且,它可以将任意内容(比如图片)放入剪贴板。
不过,目前还是 document.execCommand
使用的比较广泛。虽然上面也说了 IE 对 document.execCommand
不好,但是 Clipboard API 的兼容性更差,FireFox 和 Chome 在某些版本可能都会有问题。另外还有一个问题,使用 clipboard API 需要从权限 Permissions API 获取权限之后,才能访问剪贴板内容,这样会严重影响用户体验。用户:你让我开权限,是不是又想偷我密码???