dlsjs 文档站

Chinese

English

Chinese

English

夜间模式

copyText / isClipboardSupported / readClipboardText ​

copyText 方法用于将文本复制到剪贴板，优先使用现代 Clipboard API，不可用时降级到 execCommand 传统方法。isClipboardSupported 方法用于检查当前环境是否支持剪贴板 API。readClipboardText 方法用于读取剪贴板中的文本内容，需要 HTTPS 安全上下文和用户授权。

语法 ​

javascript
copyText(text)
isClipboardSupported()
readClipboardText()

参数 ​

  • text string
    • copyText 要复制的文本内容，必须为非空字符串。

isClipboardSupported 和 readClipboardText 无参数。

返回值 ​

copyText Promise<boolean>

  返回一个 Promise，复制成功时 resolve 为 true，失败时 resolve 为 false。

isClipboardSupported boolean

  返回 true 表示当前环境支持 Clipboard API（navigator.clipboard 且处于安全上下文），false 表示不支持。

readClipboardText Promise<string>

  返回一个 Promise，resolve 为剪贴板中的文本内容。若当前环境不支持或读取失败，Promise 会被 reject。

描述 ​

三个函数围绕浏览器剪贴板能力提供封装：

  • copyText(text)：

    • 入参校验：非字符串或空字符串直接 resolve(false)，并在控制台输出 dlsjs 警告。
    • 优先使用 navigator.clipboard.writeText（需 window.isSecureContext 为 true）。
    • 现代 API 失败时，自动降级调用 fallbackCopyText：创建临时 textarea，调用 document.execCommand('copy') 完成复制。
    • 复制成功 resolve(true)，失败 resolve(false)。

  • isClipboardSupported()：返回 !!(navigator.clipboard && window.isSecureContext)，用于在调用 readClipboardText 前预检。

  • readClipboardText()：

    • 先调用 isClipboardSupported() 检查环境，不支持时直接 reject。
    • 通过 navigator.clipboard.readText() 读取剪贴板，失败时 reject 并输出 dlsjs 错误日志。

注意事项 ​

  1. 安全上下文要求：现代 Clipboard API（navigator.clipboard）仅在安全上下文（HTTPS 或 localhost）下可用，HTTP 环境下 isClipboardSupported() 返回 false，copyText 会自动降级到 execCommand。
  2. 用户授权：readClipboardText 读取剪贴板需要用户授予剪贴板权限，首次调用时浏览器会弹出授权提示；若用户拒绝，Promise 会 reject。
  3. execCommand 已废弃：document.execCommand('copy') 已被规范标记为废弃，但作为降级方案仍被广泛支持。在新版浏览器中应优先使用 Clipboard API。
  4. 用户手势要求：部分浏览器要求 Clipboard API 的调用必须由用户手势（如点击）触发，否则可能被拒绝。
  5. 空字符串处理：copyText('') 会直接 resolve(false) 并输出警告，不会真正写入剪贴板。
  6. 非字符串入参：copyText 传入非字符串（如数字、对象）时，会 resolve(false)，需调用方自行转换为字符串。
  7. 降级方案的局限：execCommand('copy') 在部分移动端浏览器或无 DOM 环境（如 Web Worker）中不可用。

示例 ​

复制文本 ​

读取剪贴板 ​

检查支持并降级处理 ​

浏览器兼容性 ​

功能ChromeFirefoxSafariEdgeIE
navigator.clipboard.writeText66+63+13.1+79+不支持
navigator.clipboard.readText66+63+13.1+79+不支持
document.execCommand('copy')（降级）全版本全版本全版本全版本9+

安全上下文要求

现代 Clipboard API 必须在 HTTPS 或 localhost 环境下才能使用。HTTP 环境下 isClipboardSupported() 返回 false，copyText 会自动降级到 execCommand 方案。

性能考虑 ​

  • 时间复杂度: O(1) - 直接调用浏览器 API，无循环操作。
  • 异步调用: copyText 与 readClipboardText 返回 Promise，不会阻塞主线程。
  • 降级开销: execCommand 方案会创建并移除临时 DOM 节点，单次开销可忽略，但应避免在循环中高频调用。
  • 权限检查: isClipboardSupported 仅做属性存在性判断，开销极低，可在调用前频繁预检。

相关函数 ​