Clipboard API: copiare e incollare in React

navigator.clipboard.writeText(text) scrive una stringa negli appunti di sistema e restituisce una Promise. È il sostituto moderno dell'approccio legacy con execCommand. Utilizzate sempre await sulla Promise e gestite un eventuale rifiuto, ad esempio quando l'utente nega l'accesso agli appunti.

navigator.clipboard.readText() legge il contenuto corrente degli appunti come stringa e restituisce anch'esso una Promise. La lettura richiede l'autorizzazione clipboard-read, che il browser chiede all'utente di concedere. Nelle applicazioni React tipiche, la lettura degli appunti viene usata meno spesso della scrittura.

I browser impongono che clipboard.writeText venga chiamato solo all'interno di un gestore di un gesto dell'utente, ad esempio un evento click o keydown. Chiamarlo dentro un useEffect o in modo asincrono dopo il gesto genererà un errore di sicurezza. Attivate sempre la scrittura direttamente da un gestore onClick.

Lo schema standard è il seguente: l'utente fa clic su un pulsante di copia, il gestore chiama navigator.clipboard.writeText(value), in caso di successo impostate lo stato copied su true e il pulsante mostra temporaneamente un segno di spunta o l'etichetta "Copiato!". Dopo un breve intervallo, il pulsante torna allo stato normale.

Incapsulate la logica in un hook useCopyToClipboard che restituisca una tupla: [copied, copyFn]. Il booleano copied controlla il feedback dell'interfaccia, mentre copyFn accetta il testo da copiare. L'hook gestisce internamente la scrittura asincrona e gli eventuali errori, mantenendo semplici i componenti.

All'interno dell'hook, dopo una copia riuscita impostate setCopied(true) e programmate il ripristino con setTimeout(() => setCopied(false), 2000). Memorizzate l'ID del timeout e cancellatelo nella funzione di cleanup di un useEffect per evitare aggiornamenti dello stato dopo lo smontaggio. In questo modo eviterete l'avviso "impossibile aggiornare lo stato su un componente non montato".

I browser meno recenti e le pagine non HTTPS non supportano la Clipboard API. Il fallback legacy crea un textarea temporaneo, ne imposta il valore, lo aggiunge al body, chiama document.execCommand('copy') e rimuove l'elemento. Questo approccio è sincrono e funziona ovunque, anche se è deprecato.

Prima di utilizzare la Clipboard API, controllate: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Se non è disponibile, usate l'approccio legacy con execCommand. Questo controllo difensivo previene gli errori di runtime negli ambienti in cui l'API non è supportata.

La lettura degli appunti richiede l'autorizzazione tramite la Permissions API. Potete interrogare lo stato corrente: navigator.permissions.query({ name: 'clipboard-read' }) restituisce un PermissionStatus con uno state tra granted, denied o prompt. Il browser mostrerà automaticamente la richiesta quando chiamerete readText().

La Clipboard API è disponibile solo nei contesti sicuri, ovvero HTTPS o localhost. Nelle pagine HTTP, navigator.clipboard è undefined. Si tratta di una limitazione di sicurezza, perché il contenuto degli appunti può essere sensibile. Controllate sempre la disponibilità dell'API prima di accedere ai suoi metodi, per evitare errori di riferimento nullo.

jsdom (utilizzato da Jest) non implementa la Clipboard API. Esegua il mock nella configurazione dei test: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). In questo modo può verificare che il componente chiami writeText con l'argomento corretto senza un ambiente browser reale.

Quando è possibile chiamare in sicurezza navigator.clipboard.writeText() nel browser?

Utilizzi navigator.clipboard.writeText() all'interno di un gestore di clic per copiare il testo. Crei un hook useCopyToClipboard che restituisca [copied, copyFn] con un ripristino temporizzato. Verifichi sempre la disponibilità dell'API, fornisca un fallback con execCommand per i browser meno recenti e crei un mock di navigator.clipboard nei test Jest.