Acesso mais seguro e desbloqueado à área de transferência para textos e imagens
A forma tradicional de acessar a área de transferência do sistema era usando
document.execCommand()
para interações com a área de transferência. Embora tenha ampla compatibilidade, esse método de recortar e
colar teve um custo: o acesso à área de transferência era síncrono e só podia ler
e gravar no DOM.
Isso é bom para pequenos trechos de texto, mas há muitos casos em que bloquear a página para transferência da área de transferência é uma experiência ruim. Uma limpeza ou
decodificação de imagens demoradas pode ser necessária para que o conteúdo possa ser colado com segurança. O navegador
pode precisar carregar recursos vinculados inline de um documento colado. Isso bloquearia a página enquanto aguardava o disco ou a rede. Imagine adicionar permissões à mistura, exigindo que o navegador bloqueie a página ao solicitar acesso à área de transferência. Ao mesmo tempo, as permissões aplicadas em torno de
document.execCommand()
para a interação da área de transferência são definidas vagamente e variam
de acordo com o navegador.
A API Async Clipboard resolve esses problemas, fornecendo um modelo de permissões bem definido que não bloqueia a página. A API Async Clipboard é limitada ao processamento de texto e imagens na maioria dos navegadores, mas o suporte varia. Analise com atenção a visão geral da compatibilidade do navegador para cada uma das seções a seguir.
Copiar: gravar dados na área de transferência
writeText()
Para copiar o texto para a área de transferência, chame writeText()
. Como essa API é
assíncrona, a função writeText()
retorna uma promessa que é resolvida ou
rejeitada dependendo se o texto transmitido foi copiado ou não:
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);
}
}
write()
Na verdade, writeText()
é apenas um método conveniente para o método write()
genérico, que também permite copiar imagens para a área de transferência. Como writeText()
, ele é assíncrono e retorna uma promessa.
Para gravar uma imagem na área de transferência, você precisa dela como
blob
. Uma maneira de fazer
isso é solicitar a imagem de um servidor usando fetch()
e, em seguida, chamar
blob()
na
resposta.
Solicitar uma imagem do servidor pode não ser desejável ou possível por vários motivos. Felizmente, também é possível desenhar a imagem em uma tela e
chamar o método
toBlob()
da tela.
Em seguida, transmita uma matriz de objetos ClipboardItem
como um parâmetro para o método
write()
. Atualmente, só é possível transmitir uma imagem por vez, mas esperamos adicionar
suporte para várias imagens no futuro. ClipboardItem
usa um objeto com o tipo MIME da imagem como a chave e o blob como o valor. Para objetos blob
recebidos de fetch()
ou canvas.toBlob()
, a propriedade blob.type
contém automaticamente o tipo MIME correto de uma imagem.
try {
const imgURL = '/images/generic/file.png';
const data = await fetch(imgURL);
const blob = await data.blob();
await navigator.clipboard.write([
new ClipboardItem({
// The key is determined dynamically based on the blob's type.
[blob.type]: blob
})
]);
console.log('Image copied.');
} catch (err) {
console.error(err.name, err.message);
}
Como alternativa, escreva uma promessa no objeto ClipboardItem
.
Para esse padrão, é preciso conhecer o tipo MIME dos dados com antecedência.
try {
const imgURL = '/images/generic/file.png';
await navigator.clipboard.write([
new ClipboardItem({
// Set the key beforehand and write a promise as the value.
'image/png': fetch(imgURL).then(response => response.blob()),
})
]);
console.log('Image copied.');
} catch (err) {
console.error(err.name, err.message);
}
O evento de cópia
Quando um usuário inicia uma cópia da área de transferência
e não chama preventDefault()
, o
evento copy
inclui uma propriedade clipboardData
com os itens já no formato correto.
Caso queira implementar sua própria lógica, chame preventDefault()
para
evitar o comportamento padrão e favorecer sua própria implementação.
Nesse caso, clipboardData
vai estar vazio.
Considere uma página com texto e uma imagem. Quando o usuário selecionar tudo e
iniciar uma cópia da área de transferência, sua solução personalizada precisará descartar o texto e copiar
apenas a imagem. É possível fazer isso conforme mostrado no exemplo de código abaixo.
Este exemplo não aborda como retornar a APIs
anteriores quando não há suporte para a API Clipboard.
<!-- The image we want on the clipboard. -->
<img src="kitten.webp" alt="Cute kitten.">
<!-- Some text we're not interested in. -->
<p>Lorem ipsum</p>
document.addEventListener("copy", async (e) => {
// Prevent the default behavior.
e.preventDefault();
try {
// Prepare an array for the clipboard items.
let clipboardItems = [];
// Assume `blob` is the blob representation of `kitten.webp`.
clipboardItems.push(
new ClipboardItem({
[blob.type]: blob,
})
);
await navigator.clipboard.write(clipboardItems);
console.log("Image copied, text ignored.");
} catch (err) {
console.error(err.name, err.message);
}
});
Para o evento copy
:
Para ClipboardItem
:
Colar: lendo dados da área de transferência
readText()
Para ler o texto da área de transferência, chame navigator.clipboard.readText()
e aguarde
a resolução da promessa retornada:
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);
}
}
read()
O método navigator.clipboard.read()
também é assíncrono e retorna uma promessa. Para ler uma imagem da área de transferência, acesse uma lista de
objetos ClipboardItem
e itere por eles.
Cada ClipboardItem
pode conter o conteúdo em tipos diferentes. Portanto, será necessário
iterar a lista de tipos, novamente usando uma repetição for...of
. Para cada tipo,
chame o método getType()
com o tipo atual como argumento para receber o
blob correspondente. Como antes, esse código não está vinculado a imagens e funcionará
com outros tipos de arquivo futuros.
async function getClipboardContents() {
try {
const clipboardItems = await navigator.clipboard.read();
for (const clipboardItem of clipboardItems) {
for (const type of clipboardItem.types) {
const blob = await clipboardItem.getType(type);
console.log(URL.createObjectURL(blob));
}
}
} catch (err) {
console.error(err.name, err.message);
}
}
Como trabalhar com arquivos colados
Os usuários podem utilizar atalhos do teclado da área de transferência, como ctrl+c e ctrl+v. O Chromium expõe arquivos somente leitura na área de transferência, conforme descrito abaixo. Isso é acionado quando o usuário clica no atalho padrão do sistema operacional ou em Editar e depois em Colar na barra de menus do navegador. Nenhum outro código de encanamento é necessário.
document.addEventListener("paste", async e => {
e.preventDefault();
if (!e.clipboardData.files.length) {
return;
}
const file = e.clipboardData.files[0];
// Read the file's contents, assuming it's a text file.
// There is no way to write back to it.
console.log(await file.text());
});
O evento de colar
Conforme observado anteriormente, há planos de introduzir eventos para trabalhar com a API Clipboard,
mas, por enquanto, você pode usar o evento paste
já existente. Isso funciona bem com os novos
métodos assíncronos para ler o texto da área de transferência. Assim como no evento copy
, não
se esqueça de chamar preventDefault()
.
document.addEventListener('paste', async (e) => {
e.preventDefault();
const text = await navigator.clipboard.readText();
console.log('Pasted text: ', text);
});
Gerenciamento de vários tipos MIME
A maioria das implementações coloca vários formatos de dados na área de transferência para uma única operação de corte ou cópia. Há dois motivos para isso: como desenvolvedor de apps, você não tem como conhecer os recursos do app para os quais um usuário quer copiar texto ou imagens, e muitos aplicativos oferecem suporte à colagem de dados estruturados como texto simples. Geralmente, isso é apresentado aos usuários com um item de menu Editar com um nome, como Colar e corresponder estilo ou Colar sem formatação.
O exemplo abaixo mostra como fazer isso. Esse exemplo usa fetch()
para receber
dados de imagem, mas também pode vir de uma
<canvas>
ou da API File System Access.
async function copy() {
const image = await fetch('kitten.png').then(response => response.blob());
const text = new Blob(['Cute sleeping kitten'], {type: 'text/plain'});
const item = new ClipboardItem({
'text/plain': text,
'image/png': image
});
await navigator.clipboard.write([item]);
}
Segurança e permissões
O acesso à área de transferência sempre foi uma preocupação de segurança para os navegadores. Sem as permissões adequadas, uma página pode copiar silenciosamente todo tipo de conteúdo malicioso para a área de transferência de um usuário e produzir resultados catastróficos quando colada.
Imagine uma página da Web que copia silenciosamente rm -rf /
ou uma
imagem de bomba de descompactação
para a área de transferência.
Oferecer acesso irrestrito de leitura à área de transferência é ainda mais difícil. Os usuários sempre copiam informações sensíveis, como senhas e detalhes pessoais, para a área de transferência, que podem ser lidas por qualquer página sem o conhecimento do usuário.
Assim como em muitas APIs novas, a API Clipboard só oferece suporte a páginas exibidas por HTTPS. Para evitar abusos, o acesso à área de transferência só é permitido quando uma página é a guia ativa. As páginas em guias ativas podem gravar na área de transferência sem solicitar permissão, mas a leitura da área de transferência sempre exige permissão.
Adicionamos permissões para copiar e colar à API Permissions.
A permissão clipboard-write
é concedida automaticamente às páginas quando elas são
a guia ativa. A permissão clipboard-read
precisa ser solicitada, o que você pode
fazer tentando ler os dados da área de transferência. O código abaixo mostra a segunda opção:
const queryOpts = { name: 'clipboard-read', allowWithoutGesture: false };
const permissionStatus = await navigator.permissions.query(queryOpts);
// Will be 'granted', 'denied' or 'prompt':
console.log(permissionStatus.state);
// Listen for changes to the permission state
permissionStatus.onchange = () => {
console.log(permissionStatus.state);
};
Também é possível controlar se um gesto do usuário é necessário para invocar o gesto de cortar ou
colar usando a opção allowWithoutGesture
. O padrão para esse valor varia de acordo com o navegador, portanto, sempre inclua-o.
É aqui que a natureza assíncrona da API Clipboard realmente ajuda: tentar ler ou gravar dados da área de transferência solicita automaticamente a permissão do usuário, caso isso ainda não tenha sido concedida. Como a API é baseada em promessas, isso é completamente transparente, e um usuário que nega a permissão da área de transferência faz com que a promessa seja rejeitada para que a página possa responder de forma adequada.
Como os navegadores só permitem acesso à área de transferência quando uma página está na guia ativa, alguns dos exemplos aqui não são executados se forem colados diretamente no console do navegador, já que as próprias ferramentas para desenvolvedores são a guia ativa. Há um truque: adie
o acesso à área de transferência usando setTimeout()
e clique rapidamente dentro da página para
focá-la antes que as funções sejam chamadas:
setTimeout(async () => {
const text = await navigator.clipboard.readText();
console.log(text);
}, 2000);
Integração com a política de permissões
Para usar a API em iframes, é necessário ativá-la com a
Política de permissões,
que define um mecanismo que permite ativar e
desativar vários recursos do navegador e APIs. Concretamente, você precisa transmitir
clipboard-read
ou clipboard-write
, dependendo das necessidades do app.
<iframe
src="index.html"
allow="clipboard-read; clipboard-write"
>
</iframe>
Detecção de recursos
Para usar a API Async Clipboard e oferecer suporte a todos os navegadores, teste o
navigator.clipboard
e volte aos métodos anteriores. Por exemplo, veja como
implementar a ação de colar para incluir outros navegadores.
document.addEventListener('paste', async (e) => {
e.preventDefault();
let text;
if (navigator.clipboard) {
text = await navigator.clipboard.readText();
}
else {
text = e.clipboardData.getData('text/plain');
}
console.log('Got pasted text: ', text);
});
Essa não é a história completa. Antes da API Async Clipboard, havia uma mistura de
diferentes implementações de copiar e colar nos navegadores da Web. Na maioria dos navegadores,
o recurso de copiar e colar pode ser acionado usando
document.execCommand('copy')
e document.execCommand('paste')
. Se o texto a ser copiado não estiver presente no DOM, ele precisará ser injetado no DOM e selecionado:
button.addEventListener('click', (e) => {
const input = document.createElement('input');
input.style.display = 'none';
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.');
}
input.remove();
});
Demonstrações
Você pode testar a API Async Clipboard nas demonstrações abaixo. No Glitch, é possível remixar a demonstração de texto ou a demonstração de imagem para fazer testes.
O primeiro exemplo demonstra como mover o texto para dentro e para fora da área de transferência.
Para testar a API com imagens, use esta demonstração. Lembre-se de que apenas PNGs são aceitos e em alguns navegadores.
Links relacionados
- MDN (link em inglês)
- Formatos personalizados da Web
Agradecimentos
Essa API foi implementada por Darwin Huang e Gary Kačmarčík (links em inglês). Darwin também fez a demonstração. Agradecemos a Kyarik e, novamente, Gary Kačmarčík pela revisão de partes deste artigo.
Imagem principal de Markus Winkler no Unsplash (links em inglês).