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