剪貼簿操作 Clipboard API 教程

阮一峰發表於2021-01-20

一、簡介

瀏覽器允許 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/htmltext/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

(完)

相關文章