Signatur
Beschreibung
Die schreibgeschützte Eigenschaft changeId gehört zur Schnittstelle ClipboardChangeEvent. Das zugehörige Ereignis clipboardchange wird auf navigator.clipboard ausgelöst, wenn sich der Inhalt der System-Zwischenablage ändert. Das kann durch die eigene Seite, einen anderen Tab oder eine andere Anwendung passieren. changeId ist eine Ganzzahl, die genau diesen einen Änderungsvorgang kennzeichnet.
Die Kennung ist kein fortlaufender Zähler, auf dessen Werte man sich verlassen kann. Sie ist ein Vergleichswert: Zwei Ereignisse mit derselben changeId beschreiben dieselbe Änderung der Zwischenablage. Laut Spezifikation sehen alle Dokumente desselben Ursprungs, die das Ereignis für dieselbe Änderung bekommen, denselben Wert. Deshalb eignet sich changeId gut, um Ereignisse aus mehreren Tabs oder Fenstern zusammenzuführen. Ein Beispiel dafür ist die Abstimmung über einen BroadcastChannel.
Typische Einsatzfälle:
- Ein Zwischenablage-Verlauf in einer Web-App, der doppelte Einträge vermeiden soll.
- Eine Synchronisierung über mehrere Tabs, bei der nur ein Tab eine Änderung verarbeiten soll.
- Ein Cache, in dem gelesene Inhalte der Zwischenablage unter ihrer
changeIdabgelegt werden. So muss mannavigator.clipboard.read()nicht unnötig oft aufrufen.
Zusammen mit ClipboardChangeEvent.types (Liste der verfügbaren MIME-Typen) kann man also entscheiden, ob sich ein Lesen der Zwischenablage lohnt und ob diese Änderung schon verarbeitet wurde. Dafür muss man die Daten nicht selbst lesen.
Rückgabewert
unsigned long long festgelegt), die den Änderungsvorgang eindeutig kennzeichnet. Die Eigenschaft ist schreibgeschützt.Beispiele
changeId beim Ereignis clipboardchange ausgeben
if ('onclipboardchange' in navigator.clipboard) {
navigator.clipboard.addEventListener('clipboardchange', (event) => {
console.log('Änderungs-ID:', event.changeId);
console.log('Verfügbare Typen:', event.types);
});
} else {
console.warn('clipboardchange wird von diesem Browser nicht unterstützt.');
}Doppelte Verarbeitung im selben Tab vermeiden
const verarbeitet = new Set();
navigator.clipboard.onclipboardchange = async (event) => {
if (verarbeitet.has(event.changeId)) return; // schon bekannt
verarbeitet.add(event.changeId);
if (event.types.includes('text/plain')) {
const text = await navigator.clipboard.readText();
console.log(`Neuer Text (#${event.changeId}):`, text);
}
};Mehrere Tabs abstimmen: nur ein Tab verarbeitet die Änderung
const kanal = new BroadcastChannel('zwischenablage');
const beansprucht = new Set();
// IDs merken, die ein anderer Tab schon übernommen hat
kanal.onmessage = ({ data }) => beansprucht.add(data.changeId);
navigator.clipboard.addEventListener('clipboardchange', async (event) => {
// Nur der Tab mit Fokus verarbeitet die Änderung
if (!document.hasFocus() || beansprucht.has(event.changeId)) return;
beansprucht.add(event.changeId);
kanal.postMessage({ changeId: event.changeId });
const text = await navigator.clipboard.readText();
console.log('Im Verlauf gespeichert:', text);
});// Wichtig · Fallstricke
- Experimentell:
ClipboardChangeEventundchangeIdstehen in einem Entwurf der Clipboard-API-Spezifikation. Bisher gibt es sie nur in Chromium-basierten Browsern, teils nur hinter Flags oder in einem Origin Trial. Firefox und Safari unterstützen sie derzeit nicht. Vor der Nutzung sollte man die Unterstützung prüfen, etwa mit'onclipboardchange' in navigator.clipboard. - Keine Reihenfolge ableiten: Der Wert ist nur eine Kennung. Man sollte weder fortlaufende noch aufsteigende Werte erwarten und keine Differenzen berechnen. Vergleichen Sie Werte nur auf Gleichheit.
- Nicht über Sitzungen hinweg speichern: Nach einem Neustart des Browsers oder Systems können sich die Kennungen wiederholen oder anders berechnet werden.
- Berechtigungen und Fokus: Das Ereignis wird nur ausgelöst, wenn das Dokument den Fokus hat oder die Berechtigung
clipboard-readerteilt wurde. Außerdem ist ein sicherer Kontext (HTTPS) nötig. Die Inhalte der Zwischenablage selbst liefert das Ereignis nicht. Zum Lesen braucht man weiterhinnavigator.clipboard.read()bzw.readText(). - Große Zahlen: Der WebIDL-Typ
unsigned long longwird alsnumberabgebildet. Sehr große Werte könnten deshalb oberhalb vonNumber.MAX_SAFE_INTEGERan Genauigkeit verlieren. Für Vergleiche innerhalb einer Sitzung spielt das in der Praxis kaum eine Rolle.