Clipboard API: kopiowanie i wklejanie w React

navigator.clipboard.writeText(text) zapisuje ciąg znaków w schowku systemowym i zwraca obiekt Promise. Jest nowoczesnym zamiennikiem starszego podejścia opartego na execCommand. Zawsze należy używać await dla obiektu Promise i obsługiwać ewentualne odrzucenie, na przykład gdy użytkownik odmówi dostępu do schowka.

navigator.clipboard.readText() odczytuje bieżącą zawartość schowka jako ciąg znaków i również zwraca obiekt Promise. Odczyt wymaga uprawnienia clipboard-read, o którego udzielenie przeglądarka prosi użytkownika. W praktyce w typowych aplikacjach React odczyt ze schowka jest używany rzadziej niż zapis.

Przeglądarki wymagają, aby clipboard.writeText było wywoływane wyłącznie w ramach procedury obsługi gestu użytkownika, takiego jak zdarzenie kliknięcia lub keydown. Wywołanie go wewnątrz useEffect albo asynchronicznie po wykonaniu gestu spowoduje błąd bezpieczeństwa. Zapis należy zawsze uruchamiać bezpośrednio z procedury obsługi onClick.

Standardowy wzorzec wygląda następująco: użytkownik klika przycisk kopiowania, procedura obsługi wywołuje navigator.clipboard.writeText(value), po pomyślnym wykonaniu ustawia stan copied na true, a przycisk tymczasowo wyświetla znacznik wyboru lub etykietę "Skopiowano!". Po krótkim opóźnieniu przycisk powraca do zwykłego stanu.

Należy zamknąć tę logikę w hooku useCopyToClipboard, który zwraca krotkę: [copied, copyFn]. Wartość logiczna copied steruje informacją zwrotną interfejsu, a copyFn przyjmuje tekst do skopiowania. Hook wewnętrznie obsługuje asynchroniczny zapis i wszelkie błędy, dzięki czemu komponenty pozostają proste.

W hooku po pomyślnym skopiowaniu należy wywołać setCopied(true) i zaplanować reset za pomocą setTimeout(() => setCopied(false), 2000). Identyfikator limitu czasu należy przechowywać i usuwać w funkcji czyszczącej useEffect, aby zapobiec aktualizowaniu stanu po odmontowaniu komponentu. Pozwala to uniknąć ostrzeżenia "cannot update state on an unmounted component".

Starsze przeglądarki i strony niekorzystające z HTTPS nie obsługują Clipboard API. Starsze rozwiązanie zastępcze tworzy tymczasowy element textarea, ustawia jego wartość, dołącza go do body, wywołuje document.execCommand('copy'), a następnie usuwa element. To podejście działa synchronicznie i jest obsługiwane wszędzie, choć zostało wycofane.

Przed użyciem Clipboard API należy sprawdzić: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Jeśli API jest niedostępne, należy użyć starszego rozwiązania opartego na execCommand. To sprawdzenie zabezpieczające zapobiega błędom w czasie działania w środowiskach, które nie obsługują tego API.

Odczyt schowka wymaga uprawnienia użytkownika za pośrednictwem Permissions API. Bieżący stan można sprawdzić za pomocą: navigator.permissions.query({ name: 'clipboard-read' }), które zwraca obiekt PermissionStatus ze stanem granted, denied lub prompt. Przeglądarka automatycznie poprosi o uprawnienie po wywołaniu readText().

Clipboard API jest dostępne wyłącznie w bezpiecznych kontekstach (HTTPS lub localhost). Na stronach HTTP navigator.clipboard ma wartość undefined. Jest to ograniczenie bezpieczeństwa, ponieważ zawartość schowka może zawierać poufne dane. Zawsze należy sprawdzać dostępność API przed odwołaniem się do jego metod, aby uniknąć błędów odwołań do wartości null.

jsdom (używany przez Jest) nie implementuje Clipboard API. Należy je zamockować w konfiguracji testów: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). Dzięki temu można sprawdzić, czy komponent wywołuje writeText z poprawnym argumentem, bez korzystania z rzeczywistego środowiska przeglądarki.

Kiedy można bezpiecznie wywołać navigator.clipboard.writeText() w przeglądarce?

Należy używać navigator.clipboard.writeText() wewnątrz procedury obsługi kliknięcia, aby kopiować tekst. Należy utworzyć hook useCopyToClipboard zwracający [copied, copyFn] z resetowaniem po określonym czasie. Zawsze należy sprawdzać dostępność API, zapewnić alternatywę opartą na execCommand dla starszych przeglądarek oraz zamockować navigator.clipboard w testach Jest.