Clipboard API

概念與用法

系統剪貼簿 是託管瀏覽器的作業系統的一個數據緩衝區，用於短期資料儲存和/或文件或應用程式之間的資料傳輸。它通常實現為一個匿名的、臨時的 資料緩衝區，有時也稱為貼上緩衝區，可以透過定義的程式設計介面從環境中的大多數或所有程式訪問。

剪貼簿 API 允許使用者在安全上下文中以程式設計方式讀寫系統剪貼簿中的文字和其他型別的資料，前提是使用者已滿足安全注意事項中概述的標準。

當剪貼簿因 cut、copy 和 paste 操作而修改時，會觸發事件。事件有預設操作，例如 `copy` 操作預設將當前選區複製到系統剪貼簿。事件處理程式可以覆蓋預設操作——有關更多資訊，請參閱每個事件。

介面

Clipboard 安全上下文

提供一個介面，用於向系統剪貼簿讀寫文字和資料。規範稱之為“非同步剪貼簿 API”。

ClipboardEvent

表示提供與剪貼簿修改相關的資訊的事件，即 cut、copy 和 paste 事件。規範稱之為“剪貼簿事件 API”。

ClipboardItem 安全上下文

表示單個專案格式，用於讀寫資料。

其他介面的擴充套件

剪貼簿 API 擴充套件了以下 API，並添加了列出的功能。

Navigator.clipboard 只讀 安全上下文

返回一個 Clipboard 物件，該物件提供對系統剪貼簿的讀寫訪問。

Element copy 事件

每當使用者發起複製操作時觸發的事件。

Element cut 事件

每當使用者發起剪下操作時觸發的事件。

Element paste 事件

每當使用者發起貼上操作時觸發的事件。

安全注意事項

剪貼簿 API 允許使用者在安全上下文中以程式設計方式讀寫系統剪貼簿中的文字和其他型別的資料。

從剪貼簿讀取時，規範要求使用者最近與頁面進行了互動（臨時使用者啟用），並且呼叫是在使用者與瀏覽器或作業系統“貼上元素”（例如在原生上下文選單中選擇“貼上”）互動的結果下進行的。實際上，瀏覽器通常允許不滿足這些要求的讀取操作，但會施加其他要求（例如許可權或每個操作的提示）。對於寫入剪貼簿，規範期望頁面已獲得 Permissions API 的 `clipboard-write` 許可權，並且瀏覽器也可能需要臨時使用者啟用。瀏覽器可能會對訪問剪貼簿的方法施加額外的限制。

瀏覽器實現已偏離規範。差異已在瀏覽器相容性部分捕獲，並且當前狀態總結如下：

Chromium 瀏覽器

• 如果規範不允許讀取，並且文件具有焦點，它會觸發一個請求使用 `clipboard-read` 許可權的請求，如果許可權被授予（無論是使用者接受了提示，還是許可權已預先授予），則讀取成功。
• 寫入操作需要 `clipboard-write` 許可權或臨時啟用。如果授予了許可權，則該許可權會持久化，並且不再需要臨時啟用。
• 對於訪問剪貼簿的 <iframe> 元素，必須允許 HTTP Permissions-Policy 許可權 `clipboard-read` 和 `clipboard-write`。

Firefox 和 Safari

• 如果規範不允許讀取，但仍然滿足臨時使用者啟用，則會觸發一個臨時上下文選單形式的使用者提示，其中只有一個“貼上”選項（該選項在 1 秒後啟用），如果使用者選擇該選項，則讀取成功。
• 寫入操作需要臨時啟用。
• 如果讀取同源剪貼簿內容，則會抑制貼上提示，但不會抑制讀取跨域內容。
• Firefox 或 Safari 不支援（也不計劃支援）`clipboard-read` 和 `clipboard-write` 許可權。

Firefox Web 擴充套件

• 讀取文字僅對具有 `clipboardRead` Web 擴充套件許可權的擴充套件可用。擁有此許可權後，擴充套件不需要臨時啟用或貼上提示。
• 寫入文字在安全上下文和臨時啟用下可用。擁有 `clipboardWrite` Web 擴充套件許可權後，不需要臨時啟用。

示例

訪問剪貼簿

系統剪貼簿透過 Navigator.clipboard 全域性物件訪問。

此程式碼段從剪貼簿獲取文字並將其附加到找到的第一個類名為 `editor` 的元素。由於 readText() 在剪貼簿不是文字時返回空字串，因此此程式碼是安全的。

navigator.clipboard
  .readText()
  .then(
    (clipText) => (document.querySelector(".editor").innerText += clipText),
  );

規範

瀏覽器相容性

api.Clipboard

api.ClipboardEvent

api.ClipboardItem

另見

• 非同步剪貼簿文章的圖片支援