Skip to main content

ClipboardItem

一个剪贴板条目，搭配一个或多个 MIME 类型的载荷。

进程：主进程

🌐 Process: Main

ClipboardItem 是以 W3C ClipboardItem 类为模型的。每个 ClipboardItem 都包含一个或多个 MIME 类型的负载，这些负载表示同一个概念上的剪贴板条目——例如，一个复制操作可以同时提供选中内容的纯文本和 HTML 表示。

类：ClipboardItem​

🌐 Class: ClipboardItem

为 clipboard.write() 创建一个剪贴板条目 或查看从 clipboard.read() 返回的条目。

进程：主进程

🌐 Process: Main

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 对象。任何非书签的值也可以是一个 Promise，它会解析为 Blob 或 string；当调用 clipboard.write() 时会被等待。

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

🌐 Creates a new ClipboardItem describing one clipboard entry with one or more MIME-typed representations. The constructed item can be passed to clipboard.write(). Each Blob or Promise payload is resolved asynchronously when clipboard.write() is called.

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://electron.nodejs.cn'
    }
  })
])

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

🌐 Files: the text/uri-list MIME type

text/uri-list MIME 类型被映射到操作系统本地的“已复制文件”剪贴板格式（在 Windows 上是 CF_HDROP，在 macOS 上是 NSFilenamesPboardType，在 Linux 上是 text/uri-list），而不是以通用文本负载的形式存储。这让 Electron 写入的剪贴板内容可以作为文件粘贴到原生应用中，比如 Finder、资源管理器或文件管理器，同时 Electron 也可以读取从这些应用复制的文件。

🌐 The text/uri-list MIME type is mapped to the operating system's native "copied files" clipboard format (CF_HDROP on Windows, NSFilenamesPboardType on macOS, and text/uri-list on Linux) rather than being stored as a generic text payload. This lets clipboard entries written by Electron be pasted as files into native applications such as Finder, Explorer, or a file manager, and lets Electron read files that were copied from those applications.

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

🌐 The payload is an RFC 2483 URI list: one file:// URI per line, separated by CRLF. Use url.pathToFileURL to convert an absolute path into a file:// URI. Although RFC 2483 permits any URI scheme, this format is files-only — non-file:// URIs are ignored.

在阅读时，getType('text/uri-list') 会解析为一个 Blob，其文本是 file:// URI 列表。因为这是一个特权主进程 API，解析后的 URI 包含文件的真实绝对路径——不像渲染进程的 navigator.clipboard，它会为了隐私对文件路径进行处理。

🌐 When reading, getType('text/uri-list') resolves to a Blob whose text is the file:// URI list. Because this is a privileged main-process API, the resolved URIs contain the real absolute paths of the files — unlike the renderer's navigator.clipboard, which sanitizes file paths for privacy.

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 []
}

实例属性​

🌐 Instance Properties

clipboardItem.types 只读​

🌐 clipboardItem.types Readonly

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

🌐 A string[] property — the MIME types of the data carried by this entry. For a constructed ClipboardItem these are the keys passed to the constructor; for an item returned by clipboard.read() these are the MIME types the platform clipboard currently makes available.

实例方法​

🌐 Instance Methods

clipboardItem.getType(type)​

  • type string - 要获取的 MIME 类型。

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

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应用/书签'

返回 Promise<ClipboardBookmark> - 当剪贴板中有书签时，返回一个 ClipboardBookmark。当剪贴板中没有书签时会拒绝。

🌐 Returns Promise<ClipboardBookmark> - Resolves with a ClipboardBookmark when a bookmark is available in the clipboard. Rejects when a bookmark is not available in the clipboard.

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')
    }
  }
}