Publicado em: 23 de setembro de 2025
O evento clipboardchange é um novo recurso adicionado ao Chrome pela equipe do Microsoft Edge. Ele permite monitorar com eficiência as mudanças na área de transferência sem a sobrecarga de desempenho da sondagem.
Agora é possível testar o evento clipboardchange com um teste de origem no Chrome e no Edge, começando pela versão 140.
Queremos receber seu feedback durante o teste desse novo recurso, já que esperamos padronizá-lo.
Os desafios de pesquisar a área de transferência para detectar mudanças
Para saber qual conteúdo está disponível na área de transferência do sistema, é preciso usar métodos de polling ineficientes. Por exemplo, apps da Web de edição de texto podem querer ativar diferentes botões "Colar" com base em se a área de transferência contém texto, uma imagem ou conteúdo HTML.
A abordagem atual para fazer isso exige que você chame repetidamente o método
navigator.clipboard.read() para verificar o conteúdo da área de transferência, conforme mostrado no
snippet de código a seguir:
// Inefficient polling approach
setInterval(async () => {
try {
const clipboardItems = await navigator.clipboard.read();
updatePasteButtons(clipboardItems);
} catch (err) {
console.error('Failed to read clipboard:', err);
}
}, 1000); // Poll every second
Embora isso funcione, também tem desvantagens significativas.
Impacto no desempenho
A pesquisa constante da área de transferência cria um overhead desnecessário. Cada chamada para
navigator.clipboard.read() exige acesso à área de transferência no nível do sistema, o que pode
afetar negativamente o desempenho do aplicativo, especialmente em
dispositivos com poucos recursos. A frequência de polling se torna um equilíbrio entre capacidade de resposta e desempenho.
Consumo elevado da bateria
Em dispositivos móveis, a sondagem frequente da área de transferência pode contribuir para o consumo da bateria, já que o aplicativo acessa continuamente os recursos do sistema, mesmo quando o usuário não está copiando ou colando conteúdo ativamente.
Inconsistências na experiência do usuário
O intervalo de polling cria atrasos entre o momento em que o conteúdo é copiado e quando a interface é atualizada para refletir o novo estado da área de transferência. Os usuários podem ver estados desatualizados do botão colar ou passar por breves períodos em que as opções corretas não estão disponíveis.
Problemas de privacidade com o excesso de consultas
O acesso frequente à área de transferência pode levantar problemas de privacidade, já que os aplicativos leem continuamente os dados da área de transferência, mesmo quando eles não mudaram. Isso pode ser invasivo para usuários que se preocupam com a privacidade do conteúdo da área de transferência.
O evento clipboardchange
Para resolver esses desafios, implementamos um novo evento chamado
clipboardchange e estamos lançando um teste de origem no Edge e no Chrome para que
você possa testá-lo nos seus apps.
Esse evento permite que os aplicativos da Web respondam de forma reativa às mudanças da área de transferência, em vez de fazer pesquisas proativas. Ele é acionado automaticamente quando o conteúdo é copiado ou recortado para a área de transferência de qualquer aplicativo, quando a área de transferência é limpa ou quando o conteúdo é colado (o que pode limpar a área de transferência em alguns casos). O evento só é disparado quando o documento está em foco.
Para detectar o evento clipboardchange, adicione um listener à interface
navigator.clipboard, conforme mostrado aqui:
navigator.clipboard.addEventListener('clipboardchange', event => {
console.log('Clipboard content changed!');
console.log('Available MIME types:', event.types);
// Update UI based on available formats
updatePasteButtons(event.types);
});
Veja as principais vantagens
O evento clipboardchange oferece vários benefícios em relação à pesquisa:
- Eficiente: os eventos só são acionados quando ocorrem mudanças.
- Preservação da privacidade: o evento expõe apenas tipos MIME nativos, não o conteúdo real.
- Sem solicitações de permissão: como nenhum dado sensível é exposto, não é necessária a permissão do usuário.
- Capacidade de resposta em tempo real: a interface é atualizada imediatamente quando o conteúdo da área de transferência muda.
- Com reconhecimento de foco: os eventos só são disparados quando o documento está em foco.
A propriedade types
O objeto de evento clipboardchange inclui uma propriedade types, que contém
uma matriz de tipos MIME disponíveis na área de transferência:
navigator.clipboard.addEventListener('clipboardchange', event => {
// Example types array: ['text/plain', 'text/html', 'image/png']
const hasText = event.types.includes('text/plain');
const hasImage = event.types.includes('image/png');
const hasHtml = event.types.includes('text/html');
// Enable/disable paste buttons accordingly
document.getElementById('paste-text').disabled = !hasText;
document.getElementById('paste-image').disabled = !hasImage;
document.getElementById('paste-html').disabled = !hasHtml;
});
Comportamento de foco
Se ocorrerem mudanças na área de transferência enquanto o documento não estiver em foco, um único evento
clipboardchange será acionado quando o documento recuperar o foco do sistema.
As informações históricas de mudanças na área de transferência não estarão disponíveis. Somente os tipos disponíveis quando a página ganhou foco serão incluídos no membro types.
Teste o evento clipboardchange hoje
Teste o novo evento clipboardchange hoje mesmo:
- Localmente, ativando o recurso apenas no seu navegador.
- Ou no seu aplicativo Web de produção, registrando-se no teste de origem.
Detectar o evento clipboardchange para melhorar a compatibilidade
Primeiro, como esse é um recurso novo, você precisa detectar o suporte dele antes de
usá-lo. Para isso, teste a existência da propriedade
onclipboardchange em navigator.clipboard, conforme mostrado aqui:
if ('onclipboardchange' in navigator.clipboard) {
// The clipboardchange event is supported
navigator.clipboard.addEventListener('clipboardchange', handleClipboardChange);
} else {
// Fallback to polling or other methods
console.log('clipboardchange event not supported, using fallback');
setInterval(checkClipboard, 2000);
}
Testar localmente
Para testar o evento clipboardchange apenas no navegador:
- Abra a página
about://flags. - Pesquise
ClipboardChangeEventna caixa Pesquisar flags. - Use o menu suspenso e mude o valor de Padrão para Ativado.
- Reinicie o navegador.
Inscrever-se no teste de origem
Para testar o evento clipboardchange no seu site com usuários reais, inscreva-se no
teste de origem no
Chrome
ou
Edge.
O teste de origem será executado no Chrome e no Edge entre as versões 140 e 142 (entre 2 de setembro e 2 de dezembro de 2025).
Leia Começar a usar testes de origem para saber mais sobre eles e como começar.
Demonstração
Para ver o evento em ação, confira nossa demonstração e o código-fonte no GitHub.
Esta demonstração mostra como o evento clipboardchange pode ser usado para criar uma
interface de colagem responsiva que é atualizada automaticamente com base no conteúdo
da área de transferência.
Copie diferentes tipos de conteúdo (texto, imagens, HTML) e veja como os botões de colar são ativados e desativados em tempo real sem nenhuma pesquisa.
Feedback
Gostaríamos de saber como o evento clipboardchange funciona para seus casos de uso. Envie feedback criando um problema no repositório
W3C/clipboard-apis.
Os indicadores públicos sobre seu interesse vão ajudar o Google e outros navegadores a entender
a importância desse recurso para você, o que pode influenciar o processo de
padronização.
Mesmo que esse evento possa ser usado como um aprimoramento progressivo, queremos padronizá-lo como parte da especificação da API Clipboard e, eventualmente, vê-lo adotado por todos os navegadores. Por enquanto, você pode usar a pesquisa ou outras técnicas de monitoramento da área de transferência.