Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

Clipboard.write — asynchroniczny zapis do schowka

Clipboard.write zapisuje elementy ClipboardItem do schowka systemowego. Pozwala przekazać różne reprezentacje MIME, ale wymaga bezpiecznego kontekstu i zgody przeglądarki.

Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Składnia

await navigator.clipboard.write([new ClipboardItem({ "text/plain": new Blob([text], { type: "text/plain" }) })]);

Clipboard.write, wywoływane jako navigator.clipboard.write(items), przyjmuje elementy ClipboardItem. Jeden element może zawierać kilka reprezentacji MIME tej samej treści. writeText(text) to prostsza metoda dla samego tekstu. Zwracana obietnica spełnia się wartością undefined po zapisie; odmowa dostępu może spowodować NotAllowedError.

To Web API, nie część ECMAScript; Node 24 nie dowodzi obsługi w przeglądarce. Sprawdź dostępność API i przetestuj docelowe przeglądarki. Użyj bezpiecznego kontekstu: HTTPS lub zaufanego lokalnego pochodzenia, np. localhost. Samo HTTPS nie gwarantuje bezpiecznego kontekstu, gdy strona jest osadzona w niezabezpieczonym przodku; sprawdź window.isSecureContext.

Wywołuj zapis bezpośrednio po kliknięciu w dokumencie, który ma fokus, i obsługuj błędy; polityka uprawnień zależy od przeglądarki. Nie traktuj wielu reprezentacji jako wielu elementów: platforma może zachować tylko pierwszy element. Przykład nadpisuje schowek po świadomym kliknięciu użytkownika.

Przykłady

<!doctype html>
<meta charset="utf-8">
<title>Clipboard.write</title>
<button id="copy" type="button">Copy: Hello, clipboard!</button>
<output id="status" aria-live="polite"></output>
<script>
const button = document.querySelector('#copy');
const status = document.querySelector('#status');

button.addEventListener('click', async () => {
  if (!window.isSecureContext ||
      typeof navigator.clipboard?.write !== 'function' ||
      typeof ClipboardItem !== 'function') {
    status.textContent = 'Unavailable';
    return;
  }

  try {
    const blob = new Blob(['Hello, clipboard!'], { type: 'text/plain' });
    const item = new ClipboardItem({ 'text/plain': blob });
    await navigator.clipboard.write([item]);
    status.textContent = 'Copied';
  } catch (error) {
    status.textContent = `Failed: ${error.name}`;
  }
});
</script>

Wynik

The status is initially empty. After the user clicks the button, it displays `Copied` only if the clipboard write succeeds. If the context is insecure or the required API is unavailable, it displays `Unavailable`. If an error occurs while preparing or writing the clipboard item, it displays `Failed: ` followed by the error name.

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła