EyeDropper.open() — Methode · JavaScript-Referenz

Signatur

EyeDropper.prototype.open(options)

Beschreibung

Die Methode open() einer EyeDropper-Instanz schaltet den Browser in den Pipettenmodus. Der Mauszeiger wird dann zu einer Lupe, mit der der Benutzer jeden Pixel auf dem Bildschirm anklicken kann, auch außerhalb des Browserfensters. Nach dem Klick wird das zurückgegebene Promise mit einem Objekt erfüllt, dessen Eigenschaft sRGBHex die gewählte Farbe enthält, z. B. "#1a73e8".

Typische Einsatzfälle sind Farbwähler in Grafik- und Design-Werkzeugen, Theme-Editoren, CSS-Generatoren oder Barrierefreiheits-Prüfer, mit denen man Kontraste auf beliebigen Bildschirminhalten misst.

Wichtig: open() darf nur als Reaktion auf eine Benutzeraktion aufgerufen werden, zum Beispiel in einem click-Handler (transiente Benutzeraktivierung). Bricht der Benutzer mit Esc ab oder wird über ein AbortSignal abgebrochen, wird das Promise mit einer AbortError-DOMException abgelehnt. Das Ergebnis wird immer im sRGB-Format als Hex-String geliefert, auch auf Bildschirmen mit größerem Farbraum.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt.
$options.signal	AbortSignal		Ein `AbortSignal` (z. B. von einem `AbortController`), mit dem der Pipettenmodus per Code beendet werden kann. Danach wird das Promise mit `AbortError` abgelehnt.

Rückgabewert

Typ

Promise<{ sRGBHex: string }>

Beschreibung

Ein Promise, das mit einem Objekt erfüllt wird, dessen Eigenschaft sRGBHex die gewählte Farbe als Hex-String enthält (z. B. "#ff8800"). Abgelehnt wird es mit AbortError bei Abbruch, mit NotAllowedError ohne Benutzeraktivierung und mit InvalidStateError, wenn bereits eine Pipette geöffnet ist.

Beispiele

Farbe per Button-Klick auswählen

const button = document.querySelector('#pick-color');
const preview = document.querySelector('#preview');

button.addEventListener('click', async () => {
  if (!('EyeDropper' in window)) {
    alert('Ihr Browser unterstützt die EyeDropper-API nicht.');
    return;
  }

  const eyeDropper = new EyeDropper();
  try {
    const { sRGBHex } = await eyeDropper.open();
    preview.style.backgroundColor = sRGBHex;
    console.log('Gewählte Farbe:', sRGBHex);
  } catch (err) {
    // Esc gedrückt oder abgebrochen
    console.log('Auswahl abgebrochen:', err.name);
  }
});

Gewählte Farbe: #1a73e8

Pipette nach Zeitlimit per AbortSignal abbrechen

document.querySelector('#pick-color').addEventListener('click', async () => {
  const controller = new AbortController();
  // Nach 5 Sekunden automatisch beenden
  const timer = setTimeout(() => controller.abort(), 5000);

  try {
    const result = await new EyeDropper().open({ signal: controller.signal });
    console.log(result.sRGBHex);
  } catch (err) {
    if (err.name === 'AbortError') {
      console.log('Pipette beendet (Timeout oder Esc).');
    } else {
      throw err;
    }
  } finally {
    clearTimeout(timer);
  }
});

Pipette beendet (Timeout oder Esc).

Gewählte Farbe in ein Farbfeld übernehmen und kopieren

const input = document.querySelector('input[type="color"]');

document.querySelector('#pipette').addEventListener('click', async () => {
  try {
    const { sRGBHex } = await new EyeDropper().open();
    input.value = sRGBHex; // <input type="color"> erwartet #rrggbb
    await navigator.clipboard.writeText(sRGBHex);
    console.log(`${sRGBHex} in die Zwischenablage kopiert`);
  } catch {
    // Abbruch ignorieren
  }
});

#ff8800 in die Zwischenablage kopiert

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Desktop-Browser (Chrome/Edge/Opera ab Version 95). Firefox, Safari und mobile Browser unterstützen die API nicht. Deshalb immer vorher mit 'EyeDropper' in window prüfen und eine Alternative anbieten, z. B. <input type="color">.
Benutzeraktivierung nötig: Ein Aufruf ohne vorherige Benutzeraktion, etwa beim Laden der Seite oder nach einem langen await, führt zu NotAllowedError.
Nur eine Pipette gleichzeitig: Ein zweiter Aufruf von open(), während noch eine Pipette offen ist, wird mit InvalidStateError abgelehnt.
Sicherer Kontext: Die API ist nur über HTTPS oder localhost verfügbar und in Cross-Origin-iframes eingeschränkt.
Datenschutz: Die Seite erfährt nur die Farbe des einen Pixels, den der Benutzer bewusst angeklickt hat, und keine sonstigen Bildschirminhalte.
Das Ergebnis ist immer ein sRGB-Hex-String. Werte aus Farbräumen wie Display-P3 werden dabei in sRGB umgerechnet und können dadurch ungenau werden.
Abbrechen mit Esc ist ein normaler Fall. Es löst eine Ablehnung aus, die mit try/catch behandelt werden sollte.

Siehe auch

EyeDropper new EyeDropper() AbortSignal Clipboard.writeText() new HIDConnectionEvent() new MediaRecorderErrorEvent()