Pular para o conteúdo
FrAIFlow

Soluções / Navegador & Dispositivo

O botão Copiar funciona no localhost, mas falha no site

Seu botão Copiar funciona no localhost e falha depois da publicação. Primeiro, descubra se a Clipboard API está indisponível ou se uma gravação na área de transferência está sendo rejeitada. Essas falhas exigem soluções diferentes.

Localize a etapa que está falhando
Explicação criada pelos autores com base no exemplo preservado; não é uma captura de aplicativo.

Copie o texto sem enfraquecer a segurança do navegador

Se você só precisa copiar um resultado, clique no texto visível, selecione-o e use o comando Copiar do sistema operacional. No celular, toque no texto e mantenha o toque para exibir os controles de seleção. Se a página esconde o resultado atrás de um botão Copiar quebrado, há um problema de usabilidade que o responsável pelo site deve corrigir. Não instale extensões nem desative restrições de segurança apenas para copiar um pequeno trecho de texto.

Para quem administra o site, reproduza o problema na página publicada. Confira se o endereço começa com HTTPS, se a página está em foco e se está incorporada a outro site. Um botão funcionando no localhost ajuda durante o desenvolvimento, mas não comprova que a origem publicada tenha as mesmas permissões.

Confira a página publicada, não apenas o localhost

Um relato público de 2018 confirmou que o HTTPS restaurou um objeto clipboard indisponível. O localhost pode ocultar esse problema porque o HTTP de loopback pode ser considerado confiável. Essa exceção não torna seguro um site HTTP comum.

console.table({
  secure: window.isSecureContext,
  exposed: Boolean(navigator.clipboard),
  active: navigator.userActivation?.isActive
});

O teste isolado preservado com Chromium comparou HTTP de loopback com um nome de host de teste apontado para loopback. Ele mediu somente a disponibilidade da API. Nenhum conteúdo da área de transferência foi lido ou escrito, e nenhuma permissão foi concedida. Se a página publicada é insegura, corrija a entrega via HTTPS em vez de pedir aos visitantes que desativem controles de segurança.

Mantenha a ação junto ao clique
Explicação criada pelos autores com base no exemplo preservado; não é uma captura de aplicativo.

Mantenha a gravação na área de transferência dentro do clique

HTTPS, por si só, não garante permissão. Um relato do WebKit mostrou uma gravação no Safari falhando depois que o manipulador de clique aguardava um fetch. O exemplo corrigido iniciava a gravação durante o clique e fornecia os dados de ClipboardItem por uma promise. Isso não prova que toda operação assíncrona falhe em todos os navegadores.

Este exemplo mínimo mantém o texto visível, inicia a gravação na área de transferência diretamente a partir de um clique real e mostra uma instrução de cópia manual quando o pedido falha. Salve-o em uma página de teste servida por uma origem segura permitida. Ele não solicita leitura da área de transferência nem envia o texto a lugar algum. Substitua o valor de exemplo do textarea pelo resultado já preparado no seu aplicativo.

<textarea id="copy-source" readonly aria-label="Text to copy">Your finished result</textarea>
<button id="copy-button" type="button">Copy result</button>
<p id="copy-status" role="status"></p>
<script>
const source = document.getElementById("copy-source");
const status = document.getElementById("copy-status");
document.getElementById("copy-button").addEventListener("click", async () => {
  try {
    if (!window.isSecureContext || !navigator.clipboard) {
      throw new Error("Clipboard unavailable");
    }
    await navigator.clipboard.writeText(source.value);
    status.textContent = "Copied. Paste it where you need it.";
  } catch {
    source.focus();
    source.select();
    status.textContent = "Automatic copy failed. Use your device's Copy command on the selected text.";
  }
});
</script>

Esta é uma orientação de implementação, não uma afirmação de que um novo teste entre navegadores foi realizado. Se o resultado exige uma requisição de rede, conclua-a antes de habilitar Copiar. Evite informar sucesso apenas porque o manipulador de clique foi executado. Neste exemplo, o sucesso só é anunciado quando a promise de gravação é resolvida.

Confirme a cópia e mantenha uma alternativa manual

Use uma amostra curta e não sensível, com uma quebra de linha e um caractere acentuado. Clique em Copiar, cole em um editor de texto simples e compare o valor inteiro. Teste também a alternativa manual. Se a cópia automática falhar somente em um frame incorporado, compare a página de nível superior com a versão incorporada e confira a política de incorporação com o responsável pelo site. Não presuma que uma janela de permissão ou configuração do navegador se comporte igual em todos os mecanismos.

Interprete corretamente o teste de origem registrado abaixo: ele determinou se a API estava disponível, não se este botão pode gravar em todos os navegadores. O objetivo prático é oferecer dois caminhos utilizáveis: a cópia bem-sucedida quando permitida e uma saída visível e selecionável quando não for.

Mantenha o texto visível e selecionável. Uma página incorporada pode ser restringida pela Permissions Policy da página que a contém; o foco do documento, as configurações do navegador e as regras da plataforma também importam. Os nomes e o comportamento das permissões de área de transferência variam entre navegadores. Consulte a documentação correspondente em vez de tratar um resultado no Chromium como garantia para Safari ou Firefox.

No teste, o HTTP de loopback disponibiliza a Clipboard API; o nome de host HTTP comum de teste não.
Explicação original preservada.
Saída registrada do teste sintético de O botão Copiar funciona no localhost, mas falha no site
Verificações isoladas registradas no Chromium sobre origem e disponibilidade da API. Nenhum conteúdo da área de transferência foi lido ou escrito. Esta é uma captura da saída de teste registrada, não do aplicativo do autor do relato. Abrir a imagem de evidência em tamanho original.

Fontes e leituras relacionadas