Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Clipboard.write — escrita assíncrona na área de transferência

Clipboard.write escreve objetos ClipboardItem na área de transferência do sistema. Aceita representações MIME alternativas, mas requer um contexto seguro e autorização do navegador.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

await navigator.clipboard.write([new ClipboardItem({ "text/plain": new Blob([text], { type: "text/plain" }) })]);

Clipboard.write, chamada como navigator.clipboard.write(items), aceita objetos ClipboardItem. Um elemento pode conter várias representações MIME do mesmo conteúdo. writeText(text) é mais simples quando se trata apenas de texto. A promessa devolvida é cumprida com undefined após a escrita; o acesso recusado pode causar NotAllowedError.

Esta é uma API Web, não faz parte de ECMAScript; o Node 24 não comprova o suporte nos navegadores. Verifique se a API está disponível e teste os navegadores pretendidos. Utilize um contexto seguro: HTTPS ou uma origem local fidedigna, como localhost. O HTTPS, por si só, não garante um contexto seguro quando a página está incorporada sob um antecessor não seguro; verifique window.isSecureContext.

Faça a escrita diretamente após um clique, com o documento focado, e trate os erros; as políticas de autorização variam consoante o navegador. Não confunda várias representações com vários elementos: a plataforma pode conservar apenas o primeiro elemento. O exemplo substitui o conteúdo da área de transferência após um clique intencional do utilizador.

Exemplos

<!doctype html>
<meta charset="utf-8">
<title>Clipboard.write</title>
<button id="copy" type="button">Copy: Hello, clipboard!</button>
<output id="status" aria-live="polite"></output>
<script>
const button = document.querySelector('#copy');
const status = document.querySelector('#status');

button.addEventListener('click', async () => {
  if (!window.isSecureContext ||
      typeof navigator.clipboard?.write !== 'function' ||
      typeof ClipboardItem !== 'function') {
    status.textContent = 'Unavailable';
    return;
  }

  try {
    const blob = new Blob(['Hello, clipboard!'], { type: 'text/plain' });
    const item = new ClipboardItem({ 'text/plain': blob });
    await navigator.clipboard.write([item]);
    status.textContent = 'Copied';
  } catch (error) {
    status.textContent = `Failed: ${error.name}`;
  }
});
</script>

Resultado

The status is initially empty. After the user clicks the button, it displays `Copied` only if the clipboard write succeeds. If the context is insecure or the required API is unavailable, it displays `Unavailable`. If an error occurs while preparing or writing the clipboard item, it displays `Failed: ` followed by the error name.

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes