Unblocking Clipboard Access

Over the past few years, browsers have converged on using document.execCommand for clipboard interactions. It's great to have a single widely-supported way to integrate copy and paste into web apps, but this came at a cost: clipboard access is synchronous, and can only read & write to the DOM.

Synchronous copy & paste might seem fine for small bits of text, but there are a number of cases where blocking the page for clipboard transfer leads to a poor experience. Time consuming sanitization or decoding might be needed before content can be safely pasted. The browser may need to load linked resources from a pasted document - that would block the page while waiting on the disk or network. Imagine adding permissions into the mix, requiring that the browser block the page while asking the user if an app can access the clipboard.

At the same time, the permissions put in place around document.execCommand for clipboard interaction are loosely defined and vary between browsers. So, what might a dedicated clipboard API look like if we wanted to address blocking and permissions problems?

That's the new Async Clipboard API, the text-focused portion of which we're shipping in Chrome 66. It's a replacement for execCommand-based copy & paste that has a well-defined permissions model and doesn't block the page. This new API also Promises (see what I did there?) to simplify clipboard events and align them with the Drag & Drop API.

Copy: Writing Text to the Clipboard

Text can be copied to the clipboard by calling writeText(). Since this API is asynchronous, the writeText() function returns a Promise that will be resolved or rejected depending on whether the text we passed is copied successfully:

navigator.clipboard.writeText('Text to be copied') .then(()  =>  {
	 // This can happen if the user denies clipboard permissions:
    console.log('Text copied to clipboard'); }) .catch(err =>  { 
    console.error('Could not copy text: ', err); });

Similarly, we can write this as an async function, then await the return of writeText():

async function copyPageUrl()  { try  {
    await navigator.clipboard.writeText(location.href);
    console.log('Page URL copied to clipboard'); }  catch  (err)  {
    console.error('Failed to copy: ', err); }
}

Paste: Reading Text from the Clipboard

Much like copy, text can be read from the clipboard by calling readText() and waiting for the returned Promise to resolve with the text:

navigator.clipboard.readText() .then(text =>  {
    console.log('Pasted content: ', text); }) .catch(err =>  {
    console.error('Failed to read clipboard contents: ', err); });

For consistency, here's the equivalent async function:

async function getClipboardContents()  { try  { const text = await navigator.clipboard.readText();
    console.log('Pasted content: ', text); }  catch  (err)  {
    console.error('Failed to read clipboard contents: ', err); }
}

Handling Paste Events

There are plans to introduce a new event for detecting clipboard changes, but for now it's best to use the "paste" event. It works nicely with the new asynchronous methods for reading clipboard text:

document.addEventListener('paste',  event  =>  { event.preventDefault();
  navigator.clipboard.readText().then(text =>  {
    console.log('Pasted text: ', text); });
});

Security and Permissions

Clipboard access has always presented a security concern for browsers. Without proper permissions in place, a page could silently copy all manner of malicious content to a user's clipboard that would produce catastrophic results when pasted. Imagine a web page that silently copies rm -rf / or a decompression bomb image to your clipboard.

Giving web pages unfettered read access to the clipboard is even more troublesome. Users routinely copy sensitive information like passwords and personal details to the clipboard, which could then be read by any page without them ever knowing.

As with many new APIs, navigator.clipboard is only supported for pages served over HTTPS. To help prevent abuse, clipboard access is only allowed when a page is the active tab. Pages in active tabs can write to the clipboard without requesting permission, but reading from the clipboard always requires permission.

To make things easier, two new permissions for copy & paste have been added to the Permissions API. The clipboard-write permission is granted automatically to pages when they are the active tab. The clipboard-read permission must be requested, which you can do by trying to read data from the clipboard.

{ name:  'clipboard-read'  }
{ name:  'clipboard-write'  }

As with anything using the Permissions API, it's possible to check if your app has permission to interact with the clipboard:

navigator.permissions.query({
  name:  'clipboard-read'
}).then(permissionStatus =>  { // Will be 'granted', 'denied' or 'prompt':
  console.log(permissionStatus.state); // Listen for changes to the permission state
  permissionStatus.onchange =  ()  =>  {
    console.log(permissionStatus.state); };
});

Here's where the "async" part of the Clipboard API really comes in handy though: attempting to read or write clipboard data will automatically prompt the user for permission if it hasn't already been granted. Since the API is promise-based this is completely transparent, and a user denying clipboard permission rejects the promise so the page can respond appropriately.

Since Chrome only allows clipboard access when a page is the current active tab, you'll find some of the examples here don't run quite right if pasted directly into DevTools, since DevTools itself is the active tab. There's a trick: we need to defer the clipboard access using setTimeout, then quickly click inside the page to focus it before the functions are called:

setTimeout(async ()  =>  { const text = await navigator.clipboard.readText();
  console.log(text);
},  2000);

Looking Back

Prior to the introduction of the Async Clipboard API, we had a mix of different copy & paste implementations across web browsers.

In most browsers, the browser's own copy and paste can be triggered using document.execCommand('copy') and document.execCommand('paste'). If the text to be copied is a string not present in the DOM, we have to inject and select it:

button.addEventListener('click', e =>  { const input = document.createElement('input');
  document.body.appendChild(input);
  input.value = text;
  input.focus();
  input.select(); const result = document.execCommand('copy'); if  (result ===  'unsuccessful')  {
    console.error('Failed to copy text.'); }
})

Similarly, here's how you can handle pasted content in browsers that don't support the new Async Clipboard API:

document.addEventListener('paste', e =>  { const text = e.clipboardData.getData('text/plain');
  console.log('Got pasted text: ', text);
})

In Internet Explorer, we can also access the clipboard through window.clipboardData. If accessed within a user gesture such as a click event - part of asking permission responsibly - no permissions prompt is shown.

Detection and Fallback

It's a good idea to use feature detection to take advantage of Async Clipboard while still supporting all browsers. You can detect support for the Async Clipboard API by checking for the existence of navigator.clipboard:

document.addEventListener('paste', async e =>  {
  let text; if  (navigator.clipboard)  {text = await navigator.clipboard.readText() } else  {text = e.clipboardData.getData('text/plain'); }
  console.log('Got pasted text: ', text);
});

What's Next for the Async Clipboard API?

As you may have noticed, this post only covers the text part of navigator.clipboard. There are more generic read() and write() methods in the specification, but these come with additional implementation complexity and security concerns (remember those image bombs?). For now, Chrome is rolling out the simpler text parts of the API.

感谢原作者，博客转自：https://developers.google.com/web/updates/2018/03/clipboardapi