clipboard

History

Version(s)	Changes
None	Using the `clipboard` API directly in the renderer process is deprecated.

在系统剪贴板上执行复制和粘贴操作。

进程：主进程

🌐 Process: Main

clipboard 模块是仿照 W3C 剪贴板 API 设计的：clipboard.read() 返回一个 Promise，它会解析为一组 ClipboardItem 对象，而 clipboard.write() 接受一个 ClipboardItem 实例数组，这些实例映射 MIME 类型到 Blob 数据。

🌐 The clipboard module is modeled after the W3C Clipboard API: clipboard.read() returns a Promise that resolves with a list of ClipboardItem objects, and clipboard.write() accepts an array of ClipboardItem instances that map MIME types to Blob payloads.

除了标准的 MIME 类型（text/plain、text/html、text/rtf、image/png、image/jpeg……）之外，Electron 还提供了一小部分自定义格式，让剪贴板可以携带特定于桌面的内容。这些遵循 W3C 的自定义格式提案，使用 electron 前缀而不是 web 来避免冲突。Electron 暴露的自定义格式包括：

🌐 In addition to the standard MIME types (text/plain, text/html, text/rtf, image/png, image/jpeg, …), Electron exposes a small set of custom formats so the clipboard can carry desktop-specific payloads. These follow the W3C custom format proposal, using an electron prefix instead of web to avoid collisions. The custom formats Electron exposes are:

electron application/bookmark — 一个 URL 书签。与其他所有 MIME 类型/自定义格式不同，它的有效负载在写入和读取端都是一个 ClipboardBookmark 对象，而不是 Blob，所以 getType('electron application/bookmark') 会解析为 { title: string, url: string }。
electron application/findtext（macOS）——活动应用的查找剪贴板内容。
electron application/osclipboard;format="<name>" —— 一个针对特定平台剪贴板格式的原始载荷。<name> 是平台格式（例如 Windows 上的 HTML Format 或 macOS 上的 public.utf8-plain-text）。clipboard.read() 还会显示任何在这个自定义格式下没有标准 MIME 映射的剪贴板格式，因此原始操作系统格式在写入和读取时都可以通过同一个字符串完整地传输回来。

除了众所周知的 MIME 类型外，clipboard.read() 和 clipboard.write() 都接受任意 MIME 类型，包括以 web 前缀开头（后跟一个空格，例如 web application/x.my-format）的自定义格式，这些格式遵循 W3C 的网页自定义格式提案。

🌐 Beyond the well-known MIME types, both clipboard.read() and clipboard.write() accept arbitrary MIME types including custom formats starting with the web prefix (followed by a space, e.g. web application/x.my-format) that follow the W3C web custom format proposal.

const { clipboard, ClipboardItem } = require('electron')

async function writeClipboard () {
  await clipboard.write([
    new ClipboardItem({
      'web application/x.my-app-clip': new Blob(['arbitrary payload'])
    })
  ])
}

writeClipboard()

在 Linux 上也有一个 selection 剪贴板。它通过 clipboard.selection 子命名空间暴露出来，这个子命名空间镜像了顶层 clipboard 接口。selection 剪贴板作用于选择剪贴板而不是系统剪贴板。

🌐 On Linux there is also a selection clipboard. It is exposed via the clipboard.selection sub-namespace, which mirrors the top-level clipboard interface. The selection clipboard operates against the selection clipboard instead of the system clipboard.

它暴露了与顶层 clipboard 模块相同的界面，但每个方法都是针对选择剪贴板而不是系统剪贴板。这两个剪贴板是独立的：通过 clipboard.selection 写入不会影响 clipboard.read() 返回的数据（反之亦然）。

🌐 It exposes the same surface as the top-level clipboard module, but each method targets the selection clipboard rather than the system clipboard. The two clipboards are independent: writing via clipboard.selection does not affect the data returned by clipboard.read() (and vice versa).

note

selection 剪贴板不支持 W3C 网页自定义格式。

const { clipboard } = require('electron')

async function run () {
  await clipboard.selection.writeText('Example string')
  console.log(await clipboard.selection.readText())
}

run()

方法

🌐 Methods

clipboard 模块有以下方法。

🌐 The clipboard module has the following methods.

`clipboard.readText()`

返回 Promise<string> - 一个承诺，会以纯文本形式解析剪贴板的内容。模仿 W3C navigator.clipboard.readText API。

🌐 Returns Promise<string> - A promise that resolves with the content of the clipboard as plain text. Modeled after the W3C navigator.clipboard.readText API.

const { clipboard } = require('electron')

async function readText () {
  await clipboard.writeText('hello i am a bit of text!')
  const text = await clipboard.readText()
  console.log(text)
  // 'hello i am a bit of text!'
}

readText()

`clipboard.writeText(text)`

text 字符串

返回 Promise<void> - 一个在文本写入剪贴板后就会解决的 Promise。模仿 W3C navigator.clipboard.writeText API。

🌐 Returns Promise<void> - A promise that resolves once the text has been written to the clipboard. Modeled after the W3C navigator.clipboard.writeText API.

const { clipboard } = require('electron')

async function writeClipboardText () {
  await clipboard.writeText('hello i am a bit of text!')
}

writeClipboardText()

`clipboard.read()`

返回 Promise<ClipboardItem[]> - 一个 Promise，它会解析为一个包含剪贴板内容的 ClipboardItem 对象数组。

🌐 Returns Promise<ClipboardItem[]> - A promise that resolves with an array of ClipboardItem objects containing the clipboard's contents.

const { clipboard } = require('electron')

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

dumpClipboard()

`clipboard.write(data)`

data ClipboardItem[] - 通过 new ClipboardItem({ [mime]: payload }) 构建的 ClipboardItem 实例数组。

返回 Promise<void> - 一旦数据已写入剪贴板就会解决。所有在单个 write() 调用中提供的条目会原子性地提交到系统剪贴板。

🌐 Returns Promise<void> - Resolves once the data has been written to the clipboard. All entries supplied in a single write() call are committed to the system clipboard atomically.

const { clipboard, ClipboardItem, nativeImage } = require('electron')

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

async function writeClipboard () {
  await 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'
      }
    })
  ])
}

writeClipboard()

`clipboard.has(mimetype)`

mimetype string - 要检查的 MIME 类型

返回 Promise<boolean> - 一个承诺，如果剪贴板包含指定的 mimetype 数据，则解析为 true，否则为 false。要检查原始格式，例如 public/utf8-plain-text，请使用 electron application/osclipboard 自定义格式（electron application/osclipboard;format="public/utf8-plain-text"）。

🌐 Returns Promise<boolean> - A promise that resolves with true if the clipboard contains data of the specified mimetype, otherwise false. To check for a raw format, eg public/utf8-plain-text, use the electron application/osclipboard custom format (electron application/osclipboard;format="public/utf8-plain-text").

const { clipboard } = require('electron')

async function check () {
  const hasFormat = await clipboard.has('text/html')
  console.log(hasFormat)
  // 'true' or 'false'
  const rawFormat = 'electron application/osclipboard;format="public/utf8-plain-text"'
  const hasRawFormat = await clipboard.has(rawFormat)
}

check()

`clipboard.clear()`

清除剪贴板内容。

🌐 Clears the clipboard content.

属性

🌐 Properties

`clipboard.selection` Linux 只读

🌐 clipboard.selection Linux Readonly

Clipboard 属性——在 Linux 上是一个 Clipboard 对象，它作用于选择剪贴板而不是系统剪贴板，而在所有其他平台上是 undefined。它暴露了与顶层 clipboard 模块相同的 read、write、readText、writeText、has 和 clear 方法。

🌐 A Clipboard property — a Clipboard object on Linux that operates against the selection clipboard instead of the system clipboard, and undefined on all other platforms. It exposes the same read, write, readText, writeText, has, and clear methods as the top-level clipboard module.

方法​

clipboard.readText()​

clipboard.writeText(text)​

clipboard.read()​

clipboard.write(data)​

clipboard.has(mimetype)​

clipboard.clear()​

属性​

clipboard.selection Linux 只读​

方法