UIEvent.detail — Eigenschaft · JavaScript-Referenz

Signatur

UIEvent.detail

Beschreibung

UIEvent.detail ist eine nur lesbare Ganzzahl, deren Bedeutung vom Ereignistyp abhängt. Bei click, mousedown und mouseup gibt sie an, wie oft kurz hintereinander an derselben Stelle geklickt wurde. Bei dblclick ist der Wert immer 2. Bei mousedown ist es die Klickanzahl einschließlich des gerade beginnenden Klicks, also die „nächste“ Zählung.

Damit lassen sich Einfach-, Doppel- und Dreifachklicks in einem einzigen click-Handler unterscheiden. So kann man zum Beispiel bei einem Dreifachklick einen ganzen Absatz markieren oder eigene Mehrfachklick-Gesten bauen, ohne selbst Zeitmessung zu programmieren. Wie groß der Zeitabstand zwischen den Klicks sein darf, legen Betriebssystem und Browser fest.

Bei den meisten anderen Ereignissen (z. B. focus, blur, Tastatur-Ereignisse) ist detail 0. Bei Klicks, die per Tastatur (Enter/Leertaste auf einem Button) oder per element.click() ausgelöst werden, ist der Wert ebenfalls 0. Daran lässt sich erkennen, ob ein click wirklich von einem Zeigegerät kam.

Rückgabewert

Typ

number

Beschreibung

Ganzzahl (long). Bei Maus-Ereignissen die Klickanzahl (≥ 1), sonst meist 0. Bei eigenen UIEvents der Wert, der im Konstruktor unter detail übergeben wurde (Standard 0).

Beispiele

Einfach-, Doppel- und Dreifachklick unterscheiden

const box = document.querySelector('#box');

box.addEventListener('click', (event) => {
  switch (event.detail) {
    case 1:
      console.log('Einfachklick');
      break;
    case 2:
      console.log('Doppelklick');
      break;
    case 3:
      console.log('Dreifachklick – ganzen Block markieren');
      break;
    default:
      console.log(`Klickanzahl: ${event.detail}`);
  }
});

Einfachklick Doppelklick Dreifachklick – ganzen Block markieren

Tastatur- bzw. programmatische Klicks erkennen

const button = document.querySelector('button');

button.addEventListener('click', (event) => {
  if (event.detail === 0) {
    console.log('Ausgelöst per Tastatur oder element.click()');
  } else {
    console.log(`Mausklick (detail = ${event.detail})`);
  }
});

button.click(); // programmatisch auslösen

Ausgelöst per Tastatur oder element.click()

Textauswahl bei Doppelklick verhindern

const label = document.querySelector('.no-select');

// mousedown liefert bereits die Zählung des beginnenden Klicks
label.addEventListener('mousedown', (event) => {
  if (event.detail > 1) {
    event.preventDefault(); // verhindert Wort-/Zeilenauswahl
  }
});

Eigenes UIEvent mit detail erzeugen

const evt = new UIEvent('custom-ui', { detail: 5, bubbles: true });

document.addEventListener('custom-ui', (e) => {
  console.log(e.detail);
});

document.dispatchEvent(evt);

5

// Wichtig · Fallstricke

Nicht verwechseln mit CustomEvent.detail. Dort kann detail beliebige Daten enthalten, bei UIEvent ist es immer eine Zahl. Bei einem Nicht-Zahlenwert im Konstruktor wird der Wert in eine Zahl umgewandelt.
Ein Doppelklick löst zwei click-Ereignisse aus (detail 1 und 2) und danach ein dblclick. Wer Einfach- und Doppelklick streng trennen will, muss den ersten Klick verzögert verarbeiten, zum Beispiel mit setTimeout.
Das Zeitfenster für Mehrfachklicks hängt von Betriebssystem und Browser ab und lässt sich nicht aus JavaScript auslesen.
Bei pointerdown/pointerup ist detail laut Spezifikation 0. Ältere Browser setzten hier teilweise die Klickanzahl. Für die Klickanzahl sollte man sich deshalb auf click/mousedown stützen.
Bei Touch-Eingaben zählen einige mobile Browser Mehrfach-Tipps nicht zuverlässig hoch.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch von sehr alten Versionen.

Siehe auch

UIEvent MouseEvent CustomEvent.detail UIEvent.view UIEvent.which