clipboard¶

-->

> 对系统剪贴板执行复制和粘贴操作。

进程：[主进程](../glossary.md#main-process)

`clipboard` 模块以 [W3C Clipboard API](https://w3c.github.io/clipboard-apis/#clipboard-interface) 为模型：
`clipboard.read()` 返回一个 `Promise`，解析为 [`ClipboardItem`](clipboard-item.md) 对象列表，而 `clipboard.write()`
接受一个 `ClipboardItem` 实例数组，这些实例将 [MIME 类型](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types)
映射到 [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) 负载。

除了标准 MIME 类型（`text/plain`、`text/html`、
`text/rtf`、`image/png`、`image/jpeg`、…）之外，Electron 还暴露了一组
自定义格式，以便剪贴板可以承载桌面特定的负载。这些格式遵循 W3C
[自定义格式提案](https://github.com/w3c/editing/blob/gh-pages/docs/clipboard-pickling/explainer.md#custom-formats)，
使用 `electron` 前缀而不是 `web` 以避免冲突。Electron
暴露的自定义格式包括：

* `electron application/bookmark` — URL 书签。与其他所有
  MIME 类型/自定义格式不同，其负载在写入和读取两侧都是 [ClipboardBookmark](structures/clipboard-bookmark.md) 对象，
  而不是 `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 [web 自定义格式提案](https://github.com/w3c/editing/blob/gh-pages/docs/clipboard-pickling/explainer.md#custom-formats) 的自定义格式。

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

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

writeClipboard()

const { clipboard } = require('electron')

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

run()

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()

const { clipboard } = require('electron')

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

writeClipboardText()

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()

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://electronjs.org'
      }
    })
  ])
}

writeClipboard()

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()