Element: copy — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("copy", handler)

Beschreibung

Das copy-Ereignis gehört zur Clipboard API und wird ausgelöst, sobald der Benutzer über die Browser-Oberfläche kopiert – per Tastenkürzel (Strg+C / Cmd+C), über das Kontextmenü oder das Bearbeiten-Menü. Das Ereignis ist ein ClipboardEvent. Es wird an dem Element ausgelöst, das den Fokus hat, bzw. am Element, in dem die aktuelle Auswahl beginnt. Ist nichts fokussiert, geht es an document.body. Das Ereignis steigt im DOM auf (Bubbling) und lässt sich abbrechen.

Registrieren kannst du den Handler mit element.addEventListener("copy", handler) oder über die Eigenschaft element.oncopy = handler. Oft hängt man ihn an document, um alle Kopiervorgänge der Seite zu erfassen.

Typische Anwendungsfälle:

Den kopierten Text anpassen, etwa eine Quellenangabe anhängen oder Formatierungen bereinigen.
Mehrere Formate bereitstellen (text/plain und text/html).
Kopieren protokollieren, z. B. für Analysen im Code-Editor.
Kopieren sensibler Inhalte verhindern.

Wichtig: Soll der Handler die Daten der Zwischenablage selbst festlegen, muss er event.clipboardData.setData() aufrufen und event.preventDefault(). Ohne preventDefault() kopiert der Browser weiterhin die normale Auswahl und verwirft deine Daten.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"copy"`.
$handler Pflicht	(event: ClipboardEvent) => void		Callback-Funktion, die ein `ClipboardEvent` erhält. Über `event.clipboardData` (ein `DataTransfer`) lassen sich die Daten mit `setData(format, data)` festlegen.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `capture`, `once`, `passive` oder `signal`. Achtung: Mit `passive: true` wirkt `preventDefault()` nicht.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein ClipboardEvent mit der Eigenschaft clipboardData.

Beispiele

Quellenangabe an kopierten Text anhängen

document.addEventListener("copy", (event) => {
  const selection = document.getSelection().toString();
  if (!selection) return;

  const quelle = `\n\nQuelle: ${location.href}`;
  event.clipboardData.setData("text/plain", selection + quelle);
  event.clipboardData.setData(
    "text/html",
    `${selection}<br><br>Quelle: <a href="${location.href}">${location.href}</a>`
  );
  // Ohne preventDefault würde der Browser die normale Auswahl kopieren
  event.preventDefault();
});

Zwischenablage: "Markierter Text\n\nQuelle: https://example.com/artikel"

Kopieren in einem Bereich verhindern (oncopy-Eigenschaft)

const geheim = document.querySelector("#api-schluessel");

geheim.oncopy = (event) => {
  event.preventDefault();
  console.log("Kopieren ist hier nicht erlaubt.");
};

// Wieder entfernen:
// geheim.oncopy = null;

Kopieren ist hier nicht erlaubt.

Auswahl in Großbuchstaben kopieren und Listener wieder entfernen

const editor = document.querySelector("#editor");

const onCopy = (event) => {
  const text = document.getSelection().toString();
  event.clipboardData.setData("text/plain", text.toUpperCase());
  event.preventDefault();
  console.log(`Kopiert: ${text.length} Zeichen`);
};

editor.addEventListener("copy", onCopy);

// Später, z. B. beim Abbau der Komponente:
const stopButton = document.querySelector("#stop");
stopButton.addEventListener("click", () => {
  editor.removeEventListener("copy", onCopy);
});

Kopiert: 12 Zeichen

Kopiervorgang auslesen: Auswahl in einem Textfeld

const input = document.querySelector("textarea");

input.addEventListener("copy", () => {
  // In <input>/<textarea> liefert getSelection() oft nichts – selectionStart/End nutzen
  const text = input.value.slice(input.selectionStart, input.selectionEnd);
  console.log("Benutzer kopiert:", text);
});

Benutzer kopiert: Hallo Welt

// Wichtig · Fallstricke

preventDefault ist Pflicht: Daten, die mit clipboardData.setData() gesetzt werden, landen nur dann in der Zwischenablage, wenn du auch event.preventDefault() aufrufst.
Nur lesen geht nicht: Im copy-Handler liefert clipboardData.getData() keine Daten. Den kopierten Inhalt bekommst du über document.getSelection(), in Formularfeldern über selectionStart/selectionEnd.
Synthetische Ereignisse: Ein selbst erzeugtes new ClipboardEvent(\"copy\") per dispatchEvent() verändert die echte Zwischenablage nicht. Zum programmatischen Kopieren nutzt du navigator.clipboard.writeText(). Das veraltete document.execCommand(\"copy\") solltest du nicht mehr verwenden.
Kopierschutz ist kein Schutz: Kopieren zu blockieren lässt sich leicht umgehen, etwa über die Entwicklertools, den Quelltext oder Screenshots. Es schadet außerdem der Barrierefreiheit und der Bedienbarkeit. Setze es nur sparsam ein.
Sicherheit: Werte, die du in text/html schreibst, werden woanders als HTML eingefügt. Escape deshalb Werte aus Benutzereingaben, damit beim Einfügen in andere Editoren kein fremdes Markup entsteht.
Kompatibilität: Das Ereignis wird in allen modernen Browsern unterstützt. Welche MIME-Typen neben text/plain und text/html möglich sind, unterscheidet sich je nach Browser.

Siehe auch

ClipboardEvent ClipboardEvent.clipboardData DataTransfer.setData() Clipboard.writeText() Document.getSelection()