ClipboardItem¶

单个剪贴板条目，将一个或多个带 MIME 类型的负载配对在一起。

进程：主进程

ClipboardItem 以 W3C ClipboardItem 类为模型。每个 ClipboardItem 承载一个或多个带 MIME 类型的负载，这些负载 表示同一个概念上的剪贴板条目——例如，一次复制操作同时暴露所选内容的 纯文本表示和 HTML 表示。

类：ClipboardItem¶

为 clipboard.write() 构造剪贴板条目，或检查 clipboard.read() 返回的条目。

进程：主进程

[!WARNING] Electron 的内置类不能在用户代码中被子类化。 更多信息，请参阅常见问题。

new ClipboardItem(items)¶

• items Record\<string, string | ClipboardBookmark | Blob | Promise\<Blob | string>> - 一个对象，其键为 MIME 类型 且其值为该类型的负载。对应 W3C ClipboardItem(items) 构造函数的 items 参数。每个 MIME 类型都接受 string 或 Blob：string 会按 W3C 规范的要求以 UTF-8 编码为负载字节，而 Blob 提供原始负载字节。electron application/bookmark 自定义格式是唯一例外——它 接受 ClipboardBookmark 对象。 任何非书签值也可以是解析为 Blob 或 string 的 Promise； 在调用 clipboard.write() 时会等待它。

创建一个描述单个剪贴板条目的新 ClipboardItem，该条目具有一个或多个 带 MIME 类型的表示。构造出的条目可以传递给 clipboard.write()。每个 Blob 或 Promise 负载会在调用 clipboard.write() 时异步解析。

[!WARNING] 不要直接使用不可信对象构造 ClipboardItem（例如，通过 IPC 从渲染进程 接收的负载）。MIME 键是一种能力面：text/uri-list 会将真实文件引用 放到操作系统剪贴板上（使文件可以粘贴到另一个应用程序中），而 electron application/osclipboard;format=... 和以 web 为前缀（例如 web application/x.my-format）的格式会写入原始平台数据。在从您未创建的 数据构建 ClipboardItem 之前，请验证 MIME 类型并将其加入允许列表—— 同时验证每个负载的结构。

// Each `ClipboardItem` describes one clipboard entry with one or more
// MIME-typed representations. The bookmark custom format takes a structured
// `{ title, url }` object instead of a Blob.
const { clipboard, ClipboardItem, nativeImage } = require('electron')

const png = nativeImage.createFromPath('/path/to/icon.png').toPNG()

clipboard.write([
  new ClipboardItem({
    'text/plain': 'hello',
    'text/html': '<b>hello</b>',
    'image/png': new Blob([png], { type: 'image/png' }),
    'electron application/bookmark': {
      title: 'Electron',
      url: 'https://electronjs.org'
    }
  })
])

文件：text/uri-list MIME 类型¶

text/uri-list MIME 类型被映射到操作系统的原生“已复制文件”剪贴板格式 （Windows 上的 CF_HDROP、macOS 上的 NSFilenamesPboardType， 以及 Linux 上的 text/uri-list），而不是作为通用文本负载存储。 这使得 Electron 写入的剪贴板条目可以作为文件粘贴到 Finder、 资源管理器或文件管理器等原生应用程序中，并让 Electron 读取 从这些应用程序复制的文件。

负载是一个 RFC 2483 URI 列表：每行一个 file:// URI，以 CRLF 分隔。使用 url.pathToFileURL 将绝对路径转换为 file:// URI。尽管 RFC 2483 允许任何 URI 方案， 但该格式仅限文件——非 file:// URI 会被忽略。

读取时，getType('text/uri-list') 会解析为一个 Blob，其文本是 file:// URI 列表。由于这是一个特权主进程 API，解析出的 URI 包含文件的真实绝对路径——这与渲染进程的 navigator.clipboard 不同，后者出于隐私考虑会对文件路径进行清理。

const { clipboard, ClipboardItem } = require('electron')
const { pathToFileURL } = require('node:url')

// Write two files to the clipboard so they can be pasted into the OS file
// manager.
clipboard.write([
  new ClipboardItem({
    'text/uri-list': [
      pathToFileURL('/path/to/first.txt').href,
      pathToFileURL('/path/to/second.txt').href
    ].join('\r\n')
  })
])

// Read the files currently on the clipboard.
async function readFiles () {
  const [item] = await clipboard.read()
  if (item.types.includes('text/uri-list')) {
    const blob = await item.getType('text/uri-list')
    if (blob instanceof Blob) {
      const uriList = await blob.text()
      return uriList.split(/\r?\n/).filter(Boolean)
    }
  }
  return []
}

实例属性¶

clipboardItem.types 只读¶

一个 string[] 属性——此条目所承载数据的 MIME 类型。 对于构造的 ClipboardItem，这些是传递给构造函数的键； 对于 clipboard.read() 返回的条目， 这些是平台剪贴板当前可用的 MIME 类型。

实例方法¶

clipboardItem.getType(type)¶

• type string - 要检索的 MIME 类型。

返回 Promise<Blob> | Promise<ClipboardBookmark> - 以给定 MIME 类型的负载解析。 以 W3C ClipboardItem.getType 方法为模型。对于大多数 MIME 类型，该 Promise 会解析为 Blob； 唯一例外是 getType('electron application/bookmark')， 它会解析为 ClipboardBookmark 对象。 当 type 不存在于 clipboardItem.types 中时拒绝。

const { clipboard } = require('electron')

async function dumpClipboard () {
  const items = await clipboard.read()
  for (const item of items) {
    for (const type of item.types) {
      const payload = await item.getType(type)
      console.log(type, payload)
    }
  }
}

clipboardItem.getType(bookmark)¶

• bookmark 'electron application/bookmark'

返回 Promise<ClipboardBookmark> - 当剪贴板中存在可用书签时，解析为 ClipboardBookmark 当剪贴板中不存在可用书签时，拒绝。

const { clipboard } = require('electron')

async function dumpClipboard () {
  const bookmarkType = 'electron application/bookmark'
  const items = await clipboard.read()
  for (const item of items) {
    if (item.types.includes(bookmarkType)) {
      const bookmark = await item.getType(bookmarkType)
      console.log('Bookmark found: ', bookmark)
    } else {
      console.log('There is no bookmark present')
    }
  }
}