UIEvent.sourceCapabilities — Eigenschaft · JavaScript-Referenz

Signatur

UIEvent.sourceCapabilities

Beschreibung

Die schreibgeschützte Eigenschaft sourceCapabilities eines UIEvent (und damit auch von MouseEvent, PointerEvent, TouchEvent, KeyboardEvent, FocusEvent usw.) gibt ein InputDeviceCapabilities-Objekt zurück. Es beschreibt das physische Eingabegerät, von dem das Ereignis stammt.

Das Hauptproblem, das sie löst: Nach einer Touch-Geste erzeugen Browser aus Kompatibilitätsgründen zusätzliche simulierte Mausereignisse (mousedown, mouseup, click). Mit event.sourceCapabilities.firesTouchEvents lässt sich erkennen, ob ein Mausereignis tatsächlich von einem Touch-Gerät kam. So verhindert man, dass eine Aktion doppelt ausgeführt wird, wenn man sowohl Touch- als auch Maus-Handler registriert hat.

Ist das Ereignis synthetisch (z. B. per new MouseEvent() oder element.click() erzeugt), oder kann der Browser das Quellgerät nicht bestimmen, ist der Wert null. Beim Konstruieren eines Ereignisses kann man die Eigenschaft über das Dictionary-Feld sourceCapabilities selbst setzen.

Rückgabewert

Typ

InputDeviceCapabilities | null

Beschreibung

Ein InputDeviceCapabilities-Objekt mit der Eigenschaft firesTouchEvents (boolean), in neueren Chromium-Versionen zusätzlich pointerMovementScrolls. null, wenn das Quellgerät unbekannt oder das Ereignis synthetisch ist.

Beispiele

Simulierte Mausereignisse nach Touch ignorieren

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

const speichern = () => console.log('Gespeichert');

button.addEventListener('touchstart', (event) => {
  event.preventDefault();
  speichern();
}, { passive: false });

button.addEventListener('mousedown', (event) => {
  // Von Touch abgeleitetes Mausereignis? Dann überspringen.
  if (event.sourceCapabilities?.firesTouchEvents) return;
  speichern();
});

Gespeichert // genau einmal pro Tipp bzw. Klick

Quellgerät eines Klicks protokollieren

document.addEventListener('click', (event) => {
  const caps = event.sourceCapabilities;
  if (caps === undefined) {
    console.log('sourceCapabilities wird nicht unterstützt');
  } else if (caps === null) {
    console.log('Quelle unbekannt (z. B. synthetisches Ereignis)');
  } else {
    console.log(caps.firesTouchEvents ? 'Touch-Eingabe' : 'Maus/Trackpad');
  }
});

Maus/Trackpad

Synthetisches Ereignis mit und ohne Gerätekontext

const ohne = new MouseEvent('click');
console.log(ohne.sourceCapabilities);

if ('InputDeviceCapabilities' in window) {
  const mit = new MouseEvent('click', {
    sourceCapabilities: new InputDeviceCapabilities({ firesTouchEvents: true })
  });
  console.log(mit.sourceCapabilities.firesTouchEvents);
}

null true

// Wichtig · Fallstricke

Browser-Kompatibilität: Experimentell und nicht standardisiert (WICG-Entwurf). Nur Chromium-basierte Browser unterstützen die Eigenschaft. In Firefox und Safari ist sie undefined. Deshalb immer mit optionaler Verkettung (?.) oder einer Feature-Erkennung wie 'sourceCapabilities' in UIEvent.prototype arbeiten.
Drei Zustände unterscheiden: undefined (nicht unterstützt), null (Quelle unbekannt oder synthetisch) und ein Objekt. Bei einer einfachen Wahrheitsprüfung fallen die ersten beiden zusammen.
Moderne Alternative: Für neuen Code sind PointerEvents mit event.pointerType ("mouse", "pen", "touch") meist die bessere, browserübergreifende Wahl. Sie verhindern das Problem doppelter Ereignisse von vornherein.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert, im Strict Mode lösen sie einen TypeError aus.

Siehe auch

UIEvent InputDeviceCapabilities InputDeviceCapabilities.firesTouchEvents PointerEvent.pointerType MouseEvent TouchEvent Request.isReloadNavigation