electron/docs/api/clipboard.md

183 lines
5.3 KiB
Markdown
Raw Normal View History

2013-09-09 07:35:57 +00:00
# clipboard
2013-08-14 22:43:35 +00:00
2016-04-21 22:39:12 +00:00
> Perform copy and paste operations on the system clipboard.
2016-11-23 19:20:56 +00:00
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
2015-08-25 12:16:20 +00:00
The following example shows how to write a string to the clipboard:
2013-08-14 22:43:35 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { clipboard } = require('electron')
clipboard.writeText('Example String')
2013-08-14 22:43:35 +00:00
```
On Linux, there is also a `selection` clipboard. To manipulate it
you need to pass `selection` to each method:
```javascript
2018-09-13 16:10:51 +00:00
const { clipboard } = require('electron')
clipboard.writeText('Example String', 'selection')
console.log(clipboard.readText('selection'))
```
2015-08-24 21:35:43 +00:00
## Methods
2015-08-26 23:28:44 +00:00
The `clipboard` module has the following methods:
2015-08-24 21:35:43 +00:00
2015-08-28 17:34:48 +00:00
**Note:** Experimental APIs are marked as such and could be removed in future.
2015-08-24 21:35:43 +00:00
### `clipboard.readText([type])`
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2013-08-14 22:43:35 +00:00
Returns `String` - The content in the clipboard as plain text.
2013-08-14 22:43:35 +00:00
2015-08-24 21:35:43 +00:00
### `clipboard.writeText(text[, type])`
2013-08-14 22:43:35 +00:00
* `text` String
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2013-08-14 22:43:35 +00:00
Writes the `text` into the clipboard as plain text.
2013-08-14 22:43:35 +00:00
2016-05-26 21:26:12 +00:00
### `clipboard.readHTML([type])`
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
Returns `String` - The content in the clipboard as markup.
2016-05-26 21:26:12 +00:00
### `clipboard.writeHTML(markup[, type])`
* `markup` String
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2015-08-24 21:35:43 +00:00
Writes `markup` to the clipboard.
2015-08-24 21:35:43 +00:00
### `clipboard.readImage([type])`
2015-03-26 04:53:48 +00:00
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2015-03-26 04:53:48 +00:00
2016-12-19 17:40:07 +00:00
Returns [`NativeImage`](native-image.md) - The image content in the clipboard.
2015-03-26 04:53:48 +00:00
2015-08-24 21:35:43 +00:00
### `clipboard.writeImage(image[, type])`
2015-03-26 04:53:48 +00:00
* `image` [NativeImage](native-image.md)
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2015-08-24 21:35:43 +00:00
Writes `image` to the clipboard.
2015-03-26 04:53:48 +00:00
2016-05-26 21:26:12 +00:00
### `clipboard.readRTF([type])`
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
Returns `String` - The content in the clipboard as RTF.
2016-05-26 21:26:12 +00:00
### `clipboard.writeRTF(text[, type])`
* `text` String
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
Writes the `text` into the clipboard in RTF.
### `clipboard.readBookmark()` _macOS_ _Windows_
2016-06-24 22:20:49 +00:00
Returns `Object`:
2016-10-25 03:35:18 +00:00
* `title` String
* `url` String
2016-06-24 22:35:30 +00:00
Returns an Object containing `title` and `url` keys representing the bookmark in
the clipboard. The `title` and `url` values will be empty strings when the
bookmark is unavailable.
2016-06-24 22:20:49 +00:00
### `clipboard.writeBookmark(title, url[, type])` _macOS_ _Windows_
2016-06-24 22:20:49 +00:00
* `title` String
* `url` String
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2016-06-24 22:20:49 +00:00
Writes the `title` and `url` into the clipboard as a bookmark.
**Note:** Most apps on Windows don't support pasting bookmarks into them so
you can use `clipboard.write` to write both a bookmark and fallback text to the
clipboard.
```js
clipboard.write({
text: 'https://electronjs.org',
bookmark: 'Electron Homepage'
})
```
2016-10-25 05:09:42 +00:00
### `clipboard.readFindText()` _macOS_
Returns `String` - The text on the find pasteboard. This method uses synchronous
IPC when called from the renderer process. The cached value is reread from the
find pasteboard whenever the application is activated.
### `clipboard.writeFindText(text)` _macOS_
* `text` String
Writes the `text` into the find pasteboard as plain text. This method uses
synchronous IPC when called from the renderer process.
2015-08-24 21:35:43 +00:00
### `clipboard.clear([type])`
2015-03-26 04:53:48 +00:00
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2015-08-24 21:35:43 +00:00
Clears the clipboard content.
2013-08-14 22:43:35 +00:00
2015-08-24 21:35:43 +00:00
### `clipboard.availableFormats([type])`
2013-08-14 22:43:35 +00:00
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2013-08-14 22:43:35 +00:00
Returns `String[]` - An array of supported formats for the clipboard `type`.
2013-08-14 22:43:35 +00:00
### `clipboard.has(format[, type])` _Experimental_
2013-08-14 22:43:35 +00:00
* `format` String
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2013-08-14 22:43:35 +00:00
Returns `Boolean` - Whether the clipboard supports the specified `format`.
2015-05-27 08:05:51 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { clipboard } = require('electron')
console.log(clipboard.has('<p>selection</p>'))
2015-05-27 08:05:51 +00:00
```
### `clipboard.read(format)` _Experimental_
2015-05-27 08:05:51 +00:00
* `format` String
Returns `String` - Reads `format` type from the clipboard.
### `clipboard.readBuffer(format)` _Experimental_
* `format` String
2015-05-27 08:05:51 +00:00
Returns `Buffer` - Reads `format` type from the clipboard.
2013-08-14 22:43:35 +00:00
2017-04-21 07:26:57 +00:00
### `clipboard.writeBuffer(format, buffer[, type])` _Experimental_
2017-04-21 07:23:25 +00:00
* `format` String
* `buffer` Buffer
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
2017-04-21 07:23:25 +00:00
2017-04-21 07:30:23 +00:00
Writes the `buffer` into the clipboard as `format`.
2017-04-21 07:23:25 +00:00
2015-08-24 21:35:43 +00:00
### `clipboard.write(data[, type])`
* `data` Object
2016-10-30 10:46:20 +00:00
* `text` String (optional)
* `html` String (optional)
* `image` [NativeImage](native-image.md) (optional)
* `rtf` String (optional)
* `bookmark` String (optional) - The title of the url at `text`.
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
```javascript
2018-09-13 16:10:51 +00:00
const { clipboard } = require('electron')
clipboard.write({ text: 'test', html: '<b>test</b>' })
```
2015-08-24 21:35:43 +00:00
Writes `data` to the clipboard.