navigator.clipboard

Asynchroniczny dostęp do schowka systemowego. Metoda writeText() kopiuje tekst, a readText() odczytuje go ze schowka.

Zwraca: Obietnicę. Dla writeText() i write() spełnia się wartością undefined, dla readText() napisem ze schowka, a dla read() tablicą obiektów ClipboardItem.

Na tej stronie

Przykład
Definicja i zastosowanie
Składnia
Parametry
Więcej przykładów
Obsługa przeglądarek
Dobre praktyki
Powiązane hasła

Przykład

JavaScript

const copyButton = document.querySelector('#copy')
const snippet = document.querySelector('#snippet')

copyButton.addEventListener('click', async () => {
  try {
    await navigator.clipboard.writeText(snippet.textContent)
    copyButton.textContent = 'Skopiowano!'
    console.log('Skopiowano:', snippet.textContent)
  } catch (error) {
    console.log('Nie udało się skopiować:', error.name)
  }
})

Wynik

Skopiowano: console.log('Witaj w CodeWorlds!')

Przeglądarka blokuje schowek w izolowanej ramce, w której działają przykłady na tej stronie, dlatego kod nie uruchamia się w podglądzie. Na zwykłej stronie z blokiem kodu #snippet kliknięcie przycisku kopiuje jego treść, a konsola pokazuje wynik powyżej.

Definicja i zastosowanie

navigator.clipboard to obiekt do pracy ze schowkiem systemowym. Najczęściej używasz metody writeText(tekst), która kopiuje napis do schowka, np. po kliknięciu przycisku „Kopiuj kod”. Metoda readText() odczytuje tekst ze schowka, a write() i read() obsługują też inne dane, np. obrazy, zapakowane w obiekty ClipboardItem.

Wszystkie metody są asynchroniczne i zwracają obietnice, więc używaj ich z await albo then(). Obietnica zostanie odrzucona, gdy przeglądarka nie pozwoli na operację, dlatego zawsze obsługuj błędy, np. blokiem try...catch.

Schowek działa tylko na stronach otwartych przez HTTPS (albo z adresu localhost), a przeglądarki chronią go przed nadużyciami. Zapis wymaga, żeby strona była aktywna, a w części przeglądarek także żeby kod działał w reakcji na działanie użytkownika, np. kliknięcie. Odczyt jest chroniony mocniej: przeglądarka może zapytać o zgodę albo pokazać przycisk „Wklej”. W ramkach iframe na dostęp musi dodatkowo zezwolić strona nadrzędna.

Metoda writeText() działa we wszystkich głównych przeglądarkach od lat. readText(), read(), write() i obiekty ClipboardItem są dostępne wszędzie dopiero od 2024 roku, dlatego przed ich użyciem warto sprawdzić, czy istnieją.

Składnia

navigator.clipboard.writeText(text)
navigator.clipboard.readText()
navigator.clipboard.write(items)
navigator.clipboard.read()

Parametry

text
napis
Tekst do skopiowania w writeText().
items
tablica ClipboardItem
Dane do zapisania w write(), np. obraz albo tekst w kilku formatach.

Parametr	Typ	Opis
text	napis	Tekst do skopiowania w `writeText()`.
items	tablica ClipboardItem	Dane do zapisania w `write()`, np. obraz albo tekst w kilku formatach.

Więcej przykładów

Wklejanie linku ze schowka

JavaScript

document.querySelector('#paste').addEventListener('click', async () => {
  try {
    const text = await navigator.clipboard.readText()
    document.querySelector('#project-link').value = text.trim()
    console.log('Wklejono:', text.trim())
  } catch (error) {
    console.log('Brak dostępu do schowka:', error.name)
  }
})

Wynik

Wklejono: https://github.com/ania/kalkulator

Przy odczycie przeglądarka może zapytać o zgodę albo pokazać przycisk „Wklej”. Gdy użytkownik odmówi, obietnica zostanie odrzucona błędem NotAllowedError i zadziała blok catch.

Sprawdzenie, czy schowek jest dostępny

JavaScript

async function copyText(text) {
  if (!navigator.clipboard) return 'Schowek niedostępny, skopiuj tekst ręcznie'

  try {
    await navigator.clipboard.writeText(text)
    return 'Skopiowano do schowka'
  } catch (error) {
    return `Brak zgody na zapis: ${error.name}`
  }
}

document.querySelector('#coupon').addEventListener('click', async () => {
  console.log(await copyText('KURS-20'))
})

Wynik

Skopiowano do schowka

Wynik pojawia się po kliknięciu przycisku na stronie otwartej przez HTTPS. Na stronie otwartej przez zwykłe HTTP obiekt navigator.clipboard nie istnieje i funkcja zwraca pierwszy komunikat.

Obsługa przeglądarek

Nowość w przeglądarkach · od 2024 roku

Działa w aktualnych wersjach wszystkich głównych przeglądarek. Starsze wersje mogą tego nie obsługiwać.

Chrome
Edge
Firefox
Safari

Dobre praktyki

Wywołuj writeText() w obsłudze kliknięcia. Kopiowanie bez działania użytkownika część przeglądarek zablokuje.
Zawsze obsłuż odrzuconą obietnicę i daj znać, czy kopiowanie się udało, np. zmieniając napis na przycisku na „Skopiowano!”.
Na stronach bez HTTPS navigator.clipboard nie istnieje. Sprawdź go przed użyciem, np. przez navigator.clipboard?.writeText.

Powiązane hasła

Widzisz błąd albo brakuje przykładu? Napisz do nas.

Darmowy kursPrzećwicz JavaScript w kursie JavaScript i ReactZadania z podpowiedziami, edytor kodu i postępy zapisywane na bieżąco.Zobacz kurs