clipboard.js

将文本复制到剪贴板的现代方法

没有 Flash。没有框架。只有 3kb gzip 压缩包

当前版本 v2.0

为什么

将文本复制到剪贴板应该不难。它不需要几十个步骤来配置或加载数百 KB。但最重要的是，它不应该依赖于 Flash 或任何臃肿的框架。

这就是 clipboard.js 存在的原因。

安装

你可以在 npm 上获取它。

npm install clipboard --save

或者，如果你不需要包管理，只需 下载一个 ZIP 文件。

设置

首先，引入位于 dist 文件夹中的脚本或从 第三方 CDN 提供商 加载它。

<script src="https://lf3-cdn-tos.bytecdntp.com/cdn/expire-1-M/clipboard.js/2.0.10/clipboard.min.js"></script>

现在，你需要通过 传递 DOM 选择器、HTML 元素 或 HTML 元素列表 来实例化它。

new ClipboardJS('.btn');

在内部，我们需要获取与你的选择器匹配的所有元素，并为每个元素附加事件监听器。但猜怎么着？如果你有数百个匹配项，此操作会消耗大量内存。

因此我们使用 事件委托，用单个事件监听器取代多个事件监听器。毕竟 #性能很重要。

用法

我们正处于 声明式复兴 的时代，这就是为什么我们决定利用 HTML5 数据属性 来提高可用性。

从另一个元素复制文本

一个相当常见的用例是从另一个元素复制内容。你可以通过在触发器元素中添加 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。

<!-- 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 ClipboardJS('.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);
});

如需现场演示，只需打开控制台 :)

工具提示

每个应用都有不同的设计需求，这就是为什么 clipboard.js 不包含任何 CSS 或内置工具提示解决方案。

你在此演示网站上看到的工具提示是使用 GitHub 的 Primer 构建的。如果你正在寻找类似的外观和感觉，你可能需要查看它。

高级用法

如果你不想修改 HTML，可以使用非常方便的命令式 API。你需要做的就是声明一个函数，执行操作，然后返回一个值。

例如，如果你想动态设置 target，则需要返回一个 Node。

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

如果你想动态设置 text，则返回一个字符串。

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

为了在 Bootstrap Modals 或任何其他改变焦点的库中使用，你需要将焦点元素设置为 container 值。

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

此外，如果你使用的是单页应用，你可能希望更精确地管理 DOM 的生命周期。以下是清理我们创建的事件和对象的方法。

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

浏览器支持

此库依赖于 Selection 和 execCommand API。第一个 API 受所有浏览器支持，而第二个 API 受以下浏览器支持。

好消息是，如果你需要支持旧版浏览器，clipboard.js 会优雅降级。你所要做的就是在调用 success 事件时显示一个工具提示，提示 Copied!，并在调用 error 事件时显示 Press Ctrl+C to copy，因为文本已被选中。

你还可以通过运行 ClipboardJS.isSupported() 来检查 clipboard.js 是否受支持，这样你就可以从 UI 中隐藏复制/剪切按钮。