clipboard.js 介绍

这是著名开源项目 clipboard.js 的 README.md，我把它翻译成中文。发出来，方便本身和他人阅读。
项目地址：https://github.com/zenorocha/clipboard.js

现代化的“复制到剪切板”插件。不包含 Flash。gzip 压缩后仅 3kb。

为何使用它

复制文字到剪切板不该该很难去实现。它不须要配置几十个步骤或者加载几百 KB 的文件。最重要的是，它不该该依赖 Flash 或其余臃肿的框架。

这是 clipboard.js 诞生的缘由。

安装

你能够经过 npm 来安装它。

npm install clipboard --save

若是你不使用包管理，仅须要下载一个 ZIP 文件。

开始

首先，引入位于 dist 目录下的脚本文件，或者引入一个第三方CDN。

<script src="dist/clipboard.min.js"></script>

而后，你须要经过传入一个DOM 选择器, HTML 元素, 或者 HTML 元素数组做为参数，来实例化对象。

new Clipboard('.btn');

本质上，咱们须要获取全部选择器匹配到的元素，并为每个选择器设置监听事件。但仔细想一想，若是有成百上千个匹配到的元素，这样作会耗费大量内存。

所以，咱们使用事件代理，经过一个事件监听器来取代多个事件监听。毕竟，性能是问题。

使用

咱们正在经历一场声明式的复兴，这就是为何咱们决定利用 HTML5 data 属性 来提升可用性的缘由。

从另外一个元素复制文本

一个很常见的用例是从另外一个元素复制内容。你能够给目标元素添加一个 data-clipboard-target 属性来实现这个功能。

这个属性的值就是能匹配到另外一个元素的选择器。

<!-- Target -->
<input id="foo" value="https://github.com/zenorocha/clipboard.js.git">

<!-- Trigger -->
<button class="btn" data-clipboard-target="#foo">
    <img src="assets/clippy.svg" alt="Copy to clipboard">
</button>

从另外一个元素剪切文本

此外，你能够定义一个 data-clipboard-action 属性来指明你想要复制（copy）仍是剪切（cut）内容。

若是你省略这个属性，则默认为复制（copy）。

<!-- Target -->
<textarea id="bar">Mussum ipsum cacilds...</textarea>

<!-- Trigger -->
<button class="btn" data-clipboard-action="cut" data-clipboard-target="#bar">
    Cut to clipboard
</button>

正如你所预料的，剪切（cut）动做只在 <input> 或 <textarea> 元素起做用。

从属性复制文本

事实上，你甚至不须要从另外一个元素来复制内容。你仅须要给目标元素设置一个 data-clipboard-text 属性就能够了。

<!-- Trigger -->
<button class="btn" data-clipboard-text="Just because you can doesn't mean you should — clipboard.js">
    Copy to clipboard
</button>

事件

若是你想要展现一些用户反馈，或者在用户复制/剪切后获取已经选择的文字，这里有个示例供你参考。

咱们经过触发自定义事件，例如 success 和 error，让你能够设置监听并实现自定义逻辑。

var clipboard = new Clipboard('.btn');

clipboard.on('success', function(e) {
    console.info('Action:', e.action);
    console.info('Text:', e.text);
    console.info('Trigger:', e.trigger);

    e.clearSelection();
});

clipboard.on('error', function(e) {
    console.error('Action:', e.action);
    console.error('Trigger:', e.trigger);
});

你能够访问这个网站，打开控制台，查看演示示例。

工具提示（Tooltips）

每一个应用有着不一样的设计需求，这是为何 clipboard.js 没有包含任何 CSS 或内置的工具提示解决方案。

你在示例网站看到的工具提示是经过 GitHub's Primer 构建的。若是你正在寻找一个外观和体验相似的库，你能够去看看这个项目。

高级选项

若是你不想修改 HTML，咱们提供了一个很是方面的命令式的 API 给你使用。你须要作的就是声明一个函数，作一些处理，并返回一个值。

例如，若是你但愿动态设置 target，你须要返回一个节点（Node）.

new Clipboard('.btn', {
    target: function(trigger) {
        return trigger.nextElementSibling;
    }
});

若是你但愿动态设置 text，你须要返回一个字符串。

new Clipboard('.btn', {
    text: function(trigger) {
        return trigger.getAttribute('aria-label');
    }
});

若是在 Bootstrap 模态框（Modals）中使用，或是在其余修改焦点的类库中使用，你会但愿将得到焦点的元素设置为 container 属性的值。

new Clipboard('.btn', {
    container: document.getElementById('modal')
});

一样地，若是你使用单页应用，你可能想要更加精确地管理 DOM 的生命周期。你能够清理事件以及建立的对象。

var clipboard = new Clipboard('.btn');
clipboard.destroy();

浏览器支持

这个库依赖于 Selection 和 execCommand 的 API。前者 兼容全部的浏览器，后者兼容如下浏览器。

42+ ✔	12+ ✔	41+ ✔	9+ ✔	29+ ✔	10+ ✔

好消息是，若是你须要支持旧浏览器，clipboard.js 能够优雅降级。你所要作的就是在 success 事件触发时提示用户“已复制！”，error 事件触发时提示用户“按 Ctrl+C 复制文字”（此时用户要复制的文字已经选择了）。

你也能够经过运行 Clipboard.isSupported() 来检查浏览器是否支持 clipboard.js，若是不支持，你能够隐藏复制/剪切按钮。

福利

一个浏览器拓展程序，能够添加一个“复制到剪切板”按钮到全部的代码块，支持 GitHub，MDN，Gist，StackOverflow，StackExchange，npm，甚至 Medium。

安装：谷歌浏览器、火狐浏览器。

协议

MIT 协议 © Zeno Rocha