Clipboard API is the next-generation clipboard operation method, which is more powerful and reasonable than the traditional Document.execCommand()
method. All its operations are asynchronous and return Promise objects without causing page jams. Moreover, it can put arbitrary content (such as pictures) into the clipboard. The navigator.clipboard
property returns the Clipboard object, and all operations are performed through this object.
const clipboardObj = navigator.clipboard;
If the navigator.clipboard
property returns undefined
, it means that the current browser does not support this API (you can see the full compatibly table on Can I use…). Since users may put sensitive data (such as passwords) on the clipboard, allowing scripts to read them arbitrarily will cause security risks, so this API has more security restrictions. First of all, the Chrome browser stipulates that only HTTPS protocol pages can use this API. However, the development environment (localhost
) allows the use of non-encrypted protocols. Secondly, the user’s permission needs to be clearly obtained when calling. The specific implementation of permissions uses the Permissions API. There are two permissions related to the clipboard: clipboard-write
(write permission) and clipboard-read
(read permission). The “write permission” is automatically granted to the script, and the “read permission” must be explicitly granted by the user. In other words, the script can be automatically completed when writing to the clipboard, but when reading the clipboard, the browser will pop up a dialog box asking whether the user agrees to read.
In addition, it should be noted that what the script reads is always the clipboard of the current page. One problem that this brings is that if you paste the relevant code into the developer tool and run it directly, an error may be reported because the current page at this time is the window of the developer tool, not a web page.
If you paste the above code into the developer tool and run it, an error will be reported. Because when the code is running, the developer tool window is the current page, and there is no DOM interface that the Clipboard API depends on this page. One solution is to put the relevant code in setTimeout() to delay running, and quickly click on the page window of the browser before calling the function to turn it into the current page.
After the above code is pasted into the developer tool to run, quickly click on the page window of the webpage to make it the current page, so that no error will be reported.
Clipboard object
clipboard.readText()
The clipboard.readText()
method is used to copy the text data in the clipboard.
In the above example, after the user clicks on the page, the text in the clipboard will be output. Note that the browser will pop up a dialog box at this time, asking the user whether to agree with the script to read the clipboard.
If the user disagrees, the script will report an error. At this time, you can use the try...catch
structure to handle errors.
clipboard.read()
The clipboard.read()
method is used to copy the data in the clipboard, which can be text data or binary data (such as pictures). This method requires explicit permission from the user. This method returns a Promise object. Once the state of the object becomes resolved, an array can be obtained, and each array member is an instance of a ClipboardItem object.
The ClipboardItem object represents a single clip item and each clip item has a clipboardItem.types
property and a clipboardItem.getType()
method. The clipboardItem.types
property returns an array whose members are the MIME types available for the clip item. For example, a clip item can be pasted in HTML format or in plain text format. Then it has two MIME types (text/html
and text/plain
). The clipboardItem.getType(type)
method is used to read the data of the clip item and returns a Promise object. This method accepts the MIME type of the clip item as a parameter and returns the data of that type. This parameter is required, otherwise, an error will be reported.
clipboard.writeText()
The clipboard.writeText()
method is used to write text content to the clipboard.
The above example is that after the user clicks on the web page, the script writes text data to the clipboard. This method does not require user permission, but it is best to put it in try...catch
to prevent errors.
clipboard.write()
The clipboard.write()
method is used to write arbitrary data to the clipboard, which can be text data or binary data. This method accepts a ClipboardItem instance as a parameter, which represents the data written to the clipboard.
In the above example, the script writes a picture to the clipboard. Note that the Chrome browser currently (until this writer writes this article) only supports writing images in PNG format. clipboardItem()
is a constructor natively provided by the browser to generate an instance of clipboardItem
. It accepts an object as a parameter. The key name of the object is the MIME type of the data, and the key value is the data itself. The following example is to write the value of the same clip item in multiple formats to the clipboard, one is text data, and the other is binary data for pasting on different occasions.