navigator.
Accès asynchrone au presse-papiers système. La méthode writeText() copie du texte, et readText() le lit depuis le presse-papiers.
- Renvoie
- Une promesse. Pour
writeText()etwrite(), elle se résout avecundefined, pourreadText()avec la chaîne du presse-papiers, et pourread()avec un tableau d’objetsClipboardItem.
Exemple
#const copyButton = document.querySelector('#copy')
const snippet = document.querySelector('#snippet')
copyButton.addEventListener('click', async () => {
try {
await navigator.clipboard.writeText(snippet.textContent)
copyButton.textContent = 'Copié !'
console.log('Copié :', snippet.textContent)
} catch (error) {
console.log('Échec de la copie :', error.name)
}
})Copié : console.log('Bienvenue dans CodeWorlds !')Le navigateur bloque le presse-papiers dans le cadre isolé où s’exécutent les exemples de cette page, donc le code ne s’exécute pas dans l’aperçu. Sur une page normale avec un bloc de code #snippet, un clic sur le bouton copie son contenu, et la console affiche le résultat ci-dessus.
Définition et utilisation
#navigator.clipboard est un objet pour travailler avec le presse-papiers système. Vous utiliserez le plus souvent la méthode writeText(texte), qui copie une chaîne dans le presse-papiers, par exemple après un clic sur un bouton « Copier le code ». La méthode readText() lit le texte du presse-papiers, et write() et read() gèrent aussi d’autres données, par exemple des images, enveloppées dans des objets ClipboardItem.
Toutes les méthodes sont asynchrones et renvoient des promesses, donc utilisez-les avec await ou then(). La promesse est rejetée quand le navigateur n’autorise pas l’opération, donc gérez toujours les erreurs, par exemple avec un bloc try...catch.
Le presse-papiers ne fonctionne que sur les pages ouvertes en HTTPS (ou depuis localhost), et les navigateurs le protègent contre les abus. L’écriture exige que la page soit active, et dans certains navigateurs aussi que le code s’exécute en réaction à une action de l’utilisateur, par exemple un clic. La lecture est protégée plus strictement : le navigateur peut demander une autorisation ou afficher un bouton « Coller ». Dans les cadres iframe, la page parente doit en plus autoriser l’accès.
La méthode writeText() fonctionne dans tous les grands navigateurs depuis des années. readText(), read(), write() et les objets ClipboardItem ne sont disponibles partout que depuis 2024, donc il vaut la peine de vérifier leur existence avant de les utiliser.
Syntaxe
#navigator.clipboard.writeText(text)
navigator.clipboard.readText()
navigator.clipboard.write(items)
navigator.clipboard.read()Paramètres
#text
chaîne
Le texte à copier, danswriteText().items
tableau de ClipboardItem
Les données à enregistrer danswrite(), par exemple une image ou du texte sous plusieurs formats.
Plus d’exemples
#document.querySelector('#paste').addEventListener('click', async () => {
try {
const text = await navigator.clipboard.readText()
document.querySelector('#project-link').value = text.trim()
console.log('Collé :', text.trim())
} catch (error) {
console.log('Pas d’accès au presse-papiers :', error.name)
}
})Collé : https://github.com/lea/calculatrice
Lors de la lecture, le navigateur peut demander une autorisation ou afficher un bouton « Coller ». Si l’utilisateur refuse, la promesse est rejetée avec une erreur NotAllowedError, et le bloc catch s’exécute.
async function copyText(text) {
if (!navigator.clipboard) return 'Presse-papiers indisponible, copiez le texte à la main'
try {
await navigator.clipboard.writeText(text)
return 'Copié dans le presse-papiers'
} catch (error) {
return `Pas d’autorisation d’écriture : ${error.name}`
}
}
document.querySelector('#coupon').addEventListener('click', async () => {
console.log(await copyText('COURS-20'))
})Copié dans le presse-papiers
Le résultat apparaît après un clic sur le bouton, sur une page ouverte en HTTPS. Sur une page ouverte en HTTP classique, l’objet navigator.clipboard n’existe pas, et la fonction renvoie le premier message.
Compatibilité des navigateurs
#Nouveau dans les navigateurs · depuis 2024
Fonctionne dans les versions actuelles de tous les grands navigateurs. Les anciennes versions peuvent ne pas le prendre en charge.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- Appelez
writeText()depuis un gestionnaire de clic. Certains navigateurs bloquent la copie sans action de l’utilisateur. - Gérez toujours une promesse rejetée et indiquez si la copie a réussi, par exemple en changeant le texte du bouton en « Copié ! ».
- Sur les pages sans HTTPS,
navigator.clipboardn’existe pas. Vérifiez-le avant de l’utiliser, par exemple avecnavigator.clipboard?.writeText.
Entrées associées
#- EventTarget.addEventListener()Enregistre une fonction appelée à chaque fois qu’un événement se produit sur un élément, par ex. un clic.
- async functionDéclare une fonction asynchrone, qui renvoie toujours une promesse et peut utiliser le mot-clé await à l’intérieur.
- awaitMet en pause une fonction async jusqu’au règlement d’une promesse, puis renvoie sa valeur ou lève son erreur.
- try...catchCapture les erreurs levées dans un bloc try et les traite dans catch. Un finally optionnel s’exécute toujours.
- PromiseUn objet qui représente le résultat d’une opération disponible plus tard : une valeur en cas de succès, ou une erreur.
Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.