EyeDropper — Schnittstelle · JavaScript-Referenz

Signatur

interface EyeDropper

Beschreibung

Die Schnittstelle EyeDropper gehört zur EyeDropper API. Mit ihr öffnet eine Webanwendung eine vom Browser bereitgestellte Pipette. Damit kann der Benutzer die Farbe eines beliebigen Pixels auf dem Bildschirm aufnehmen, und zwar auch außerhalb des Browserfensters, etwa in anderen Programmen oder auf dem Desktop. Typische Einsatzgebiete sind Grafik- und Design-Werkzeuge, Theme-Editoren, Farbpaletten-Generatoren und Barrierefreiheits-Prüfer für Kontraste.

Eine Instanz entsteht mit dem Konstruktor new EyeDropper(), der keine Argumente erwartet. Die einzige Methode EyeDropper.prototype.open(options) gibt ein Promise zurück. Es wird mit einem Objekt der Form { sRGBHex: "#rrggbb" } erfüllt, sobald der Benutzer eine Farbe gewählt hat. Bricht der Benutzer mit Esc ab oder wird der Vorgang über ein AbortSignal beendet, wird das Promise mit einer DOMException vom Typ AbortError abgelehnt.

Weil die Pipette Bildschirminhalte außerhalb der Seite erfassen kann, ist sie aus Datenschutzgründen stark eingeschränkt. open() darf nur als Reaktion auf eine Benutzeraktion aufgerufen werden, etwa in einem click-Handler. Außerdem erfährt die Seite nur den Farbwert des einen Pixels, das der Benutzer ausdrücklich gewählt hat, und keinen weiteren Bildschirminhalt.

Parameter

Name	Typ	Default	Beschreibung
$options	{ signal?: AbortSignal }	{}	Optionen für `open()`. Mit `signal` wird ein `AbortSignal` übergeben, über das sich die geöffnete Pipette per Code abbrechen lässt.

Rückgabewert

Typ

EyeDropper (Konstruktor) / Promise<{ sRGBHex: string }> (open())

Beschreibung

new EyeDropper() liefert eine neue Instanz. open() gibt ein Promise zurück, das mit einem Objekt erfüllt wird, dessen Eigenschaft sRGBHex die gewählte Farbe als Hex-String im sRGB-Farbraum enthält, z. B. "#3a7bd5".

Beispiele

Instanz erzeugen und Farbe per Button-Klick aufnehmen

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

button.addEventListener('click', async () => {
  const eyeDropper = new EyeDropper();
  try {
    const { sRGBHex } = await eyeDropper.open();
    swatch.style.backgroundColor = sRGBHex;
    console.log('Gewählte Farbe:', sRGBHex);
  } catch (err) {
    // AbortError: Benutzer hat mit Esc abgebrochen
    console.log('Auswahl abgebrochen:', err.name);
  }
});

Gewählte Farbe: #3a7bd5

Feature-Detection mit Fallback auf <input type="color">

const pickColor = async () => {
  if ('EyeDropper' in window) {
    const result = await new EyeDropper().open();
    return result.sRGBHex;
  }
  // Fallback: nativer Farbwähler
  return new Promise((resolve) => {
    const input = document.createElement('input');
    input.type = 'color';
    input.addEventListener('change', () => resolve(input.value), { once: true });
    input.click();
  });
};

document.querySelector('#pick').addEventListener('click', async () => {
  const color = await pickColor();
  console.log('Farbe:', color);
});

Farbe: #ff6600

Pipette nach Zeitlimit per AbortController abbrechen

document.querySelector('#pick').addEventListener('click', async () => {
  const controller = new AbortController();
  // Nach 10 Sekunden automatisch abbrechen
  const timer = setTimeout(() => controller.abort(), 10_000);

  try {
    const { sRGBHex } = await new EyeDropper().open({ signal: controller.signal });
    console.log('Farbe:', sRGBHex);
  } catch (err) {
    if (err.name === 'AbortError') {
      console.log('Keine Farbe gewählt (Abbruch oder Zeitlimit).');
    } else {
      throw err;
    }
  } finally {
    clearTimeout(timer);
  }
});

Keine Farbe gewählt (Abbruch oder Zeitlimit).

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und wird nur von Chromium-basierten Desktop-Browsern unterstützt (Chrome/Edge ab 95, Opera). Firefox, Safari und mobile Browser unterstützen sie nicht. Prüfe deshalb immer mit 'EyeDropper' in window und biete einen Fallback an, etwa <input type="color">.
Benutzeraktion erforderlich: Ein Aufruf von open() ohne vorausgehende Benutzeraktion, etwa beim Laden der Seite oder in einem setTimeout, wird mit einer NotAllowedError-DOMException abgelehnt.
Nur eine Pipette gleichzeitig: Ist bereits eine Pipette offen, wird ein weiterer open()-Aufruf mit InvalidStateError abgelehnt.
Sicherer Kontext: Die API ist nur über HTTPS bzw. localhost verfügbar.
Abbruch immer abfangen: Drückt der Benutzer Esc, wird das Promise mit AbortError abgelehnt. Ohne try/catch erscheint dann ein unbehandelter Promise-Fehler in der Konsole.
Farbformat: Das Ergebnis ist immer ein sRGB-Hex-Wert in Kleinbuchstaben ohne Alphakanal. Farben aus größeren Farbräumen (z. B. Display P3) können dabei ungenau wiedergegeben werden.

Siehe auch

EyeDropper.prototype.open() AbortController AbortSignal DOMException HTMLInputElement