API Clipboard : copier et coller dans React

navigator.clipboard.writeText(text) écrit une chaîne dans le presse-papiers du système et renvoie une promesse. Il s'agit du remplacement moderne de l'ancienne approche execCommand. Attendez toujours la promesse avec await et gérez son éventuel rejet, par exemple lorsque l'utilisateur refuse l'accès au presse-papiers.

navigator.clipboard.readText() lit le contenu actuel du presse-papiers sous forme de chaîne et renvoie également une promesse. La lecture nécessite l'autorisation clipboard-read, que le navigateur demande à l'utilisateur d'accorder. En pratique, la lecture du presse-papiers est moins fréquente que l'écriture dans les applications React courantes.

Les navigateurs imposent que clipboard.writeText ne puisse être appelé que dans le gestionnaire d'une action de l'utilisateur, par exemple un événement de clic ou d'appui sur une touche. L'appeler dans un useEffect ou de manière asynchrone après l'action déclenchera une erreur de sécurité. Déclenchez toujours l'écriture directement depuis un gestionnaire onClick.

Le modèle standard est le suivant : l'utilisateur clique sur un bouton de copie, votre gestionnaire appelle navigator.clipboard.writeText(value), puis, en cas de succès, vous définissez l'état copied sur true ; le bouton affiche temporairement une coche ou le libellé « Copié ! ». Après un court délai, le bouton revient à son état normal.

Encapsulez la logique dans une fonction useCopyToClipboard qui renvoie un tuple : [copied, copyFn]. Le booléen copied pilote le retour visuel de l'interface utilisateur, et copyFn accepte le texte à copier. La fonction gère en interne l'écriture asynchrone et les éventuelles erreurs afin que les composants restent simples.

Dans la fonction, après une copie réussie, appelez setCopied(true) et programmez une réinitialisation avec setTimeout(() => setCopied(false), 2000). Stockez l'ID du délai d'attente et effacez-le dans le nettoyage d'un useEffect afin d'empêcher les mises à jour d'état après le démontage. Cela évite l'avertissement « impossible de mettre à jour l'état d'un composant démonté ».

Les anciens navigateurs et les pages qui n'utilisent pas HTTPS ne prennent pas en charge l'API du presse-papiers. L'ancienne solution de repli crée un textarea temporaire, définit sa valeur, l'ajoute au corps du document, appelle document.execCommand('copy'), puis supprime l'élément. Cette approche est synchrone et fonctionne partout, bien qu'elle soit obsolète.

Avant d'utiliser l'API du presse-papiers, vérifiez : navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Si elle n'est pas disponible, utilisez l'ancienne approche de repli execCommand. Cette vérification préventive évite les erreurs à l'exécution dans les environnements qui ne prennent pas l'API en charge.

La lecture du presse-papiers nécessite l'autorisation de l'utilisateur via l'API des permissions. Vous pouvez interroger l'état actuel : navigator.permissions.query({ name: 'clipboard-read' }) renvoie un PermissionStatus dont l'état est granted, denied ou prompt. Le navigateur demandera automatiquement l'autorisation lorsque vous appellerez readText().

L'API du presse-papiers est disponible uniquement dans des contextes sécurisés (HTTPS ou localhost). Sur les pages HTTP, navigator.clipboard vaut undefined. Il s'agit d'une restriction de sécurité, car le contenu du presse-papiers peut être sensible. Vérifiez toujours la disponibilité de l'API avant de référencer ses méthodes afin d'éviter les erreurs de référence nulle.

jsdom (utilisé par Jest) n’implémente pas l’API du presse-papiers. Simulez-la dans la configuration de vos essais : Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). Cela vous permet de vérifier que votre composant appelle writeText avec l’argument correct, sans environnement de navigateur réel.

Quand peut-on appeler navigator.clipboard.writeText() en toute sécurité dans le navigateur ?

Utilisez navigator.clipboard.writeText() dans un gestionnaire de clic pour copier du texte. Créez un crochet useCopyToClipboard qui renvoie [copied, copyFn] avec une réinitialisation temporisée. Vérifiez toujours la disponibilité de l’API, fournissez une solution de secours utilisant execCommand pour les anciens navigateurs et simulez navigator.clipboard dans les essais Jest.