useClipboard

將文本複製到用戶的剪貼板

useClipboard 使用 Clipboard API 提供讀取和寫入系統剪貼簿的簡單介面。它回傳最近複製的文字、copy 函式，以及 Clipboard API 是否可用。Clipboard API 不可用時，複製會降級到 document.execCommand("copy")；copy 和 cut 事件會讀取目前文字選取範圍。

使用場景

  • 為程式碼片段、URL 或分享連結新增「複製到剪貼簿」按鈕
  • 在表單或編輯器中建構從剪貼簿貼上的功能
  • 在資料表格或儀表板中實作複製功能

注意事項

  • SSR 安全：在伺服器端渲染時回傳空字串、複製函式和 false。伺服器上不會存取 navigator。
  • 瀏覽器支援：isSupported 只表示 navigator.clipboard 是否可用。沒有 Clipboard API 時，複製仍會嘗試使用 document.execCommand("copy") 降級。
  • 權限：某些瀏覽器需要使用者授權才能存取 Clipboard API。可搭配 usePermission 檢查 clipboard-read 和 clipboard-write 狀態。

Usage

Live Editor
function Demo() {
  const [value, setValue] = useState("");
  const [text, copy, isSupported] = useClipboard();
  const permissionRead = usePermission("clipboard-read");
  const permissionWrite = usePermission("clipboard-write");
  return (
    <div>
      <p>
        剪貼板權限：讀取 <b>{permissionRead}</b> | 寫入&nbsp;
        <b>{permissionWrite}</b>
      </p>
      <p>
        Clipboard API 支援: <b>{isSupported ? "是" : "否"}</b>
      </p>
      <p>
        當前複製的內容：<code>{text || "無"}</code>
      </p>
      <input
        value={value}
        onChange={(event) => {
          setValue(event.currentTarget.value);
        }}
      />
      <button onClick={() => copy(value)}>複製</button>
    </div>
  );
};
Result

API

useClipBoard

Returns

readonly [string, (txt: string) => Promise<void>, boolean]: 返回包含剪貼簿文字、複製函式和支援狀態的唯讀元組.

Arguments