Element: webkitmouseforcechanged — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("webkitmouseforcechanged", handler)

Beschreibung

Das Ereignis webkitmouseforcechanged ist eine proprietäre Erweiterung von Apple für Safari unter macOS. Es feuert jedes Mal, wenn sich der Druck ändert, mit dem ein Finger auf ein Force-Touch-Trackpad drückt, während sich der Mauszeiger über dem Element befindet. Das übergebene Objekt ist ein MouseEvent mit der zusätzlichen Eigenschaft webkitForce, die den aktuellen Druck als Zahl enthält.

Zusammen mit webkitmouseforcewillbegin, webkitmouseforcedown und webkitmouseforceup lassen sich damit druckabhängige Oberflächen bauen, z. B. Zeichenwerkzeuge mit variabler Strichstärke oder Vorschauen, die bei stärkerem Druck aufgehen. Die Schwellwerte liefern die Konstanten MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN (normaler Klick, etwa 1) und MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN (Force-Klick, etwa 2).

Du registrierst das Ereignis entweder mit addEventListener("webkitmouseforcechanged", handler) oder über die Eigenschaft element.onwebkitmouseforcechanged. Für plattformübergreifenden Code nimmst du besser die standardisierte Eigenschaft PointerEvent.pressure zusammen mit dem Ereignis pointermove und das Safari-Ereignis höchstens als zusätzliche Verbesserung.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"webkitmouseforcechanged"`.
$handler Pflicht	(event: MouseEvent) => void		Callback, der ein `MouseEvent` mit der zusätzlichen Eigenschaft `webkitForce` (number) erhält.
$options	boolean\|AddEventListenerOptions	false	Optionen wie `capture`, `once`, `passive` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein MouseEvent, dessen Eigenschaft event.webkitForce den aktuellen Druck angibt.

Beispiele

Druck live anzeigen mit addEventListener

const pad = document.querySelector('#pad');
const anzeige = document.querySelector('#druck');

const onForce = (event) => {
  // webkitForce: 0 bis ca. 3
  anzeige.textContent = `Druck: ${event.webkitForce.toFixed(2)}`;
};

pad.addEventListener('webkitmouseforcechanged', onForce);

Druck: 1.37 (Wert ändert sich laufend beim Drücken)

Force-Klick erkennen und den Listener wieder entfernen

const karte = document.querySelector('.karte');
const FORCE_KLICK = MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN ?? 2;

const pruefeForce = (event) => {
  if (event.webkitForce >= FORCE_KLICK) {
    karte.classList.add('vorschau-offen');
    // Nach dem ersten Force-Klick nicht mehr reagieren
    karte.removeEventListener('webkitmouseforcechanged', pruefeForce);
  }
};

karte.addEventListener('webkitmouseforcechanged', pruefeForce);

on-Property mit Feature-Erkennung und Rückfall auf Pointer Events

const flaeche = document.querySelector('#zeichnen');
const setzeStaerke = (wert) => {
  flaeche.style.setProperty('--strich', `${1 + wert * 4}px`);
};

if ('onwebkitmouseforcechanged' in flaeche) {
  // Safari: webkitForce auf 0–1 normieren (max. ca. 3)
  flaeche.onwebkitmouseforcechanged = (e) => setzeStaerke(Math.min(e.webkitForce / 3, 1));
} else {
  // Standard: pressure liegt bereits zwischen 0 und 1
  flaeche.addEventListener('pointermove', (e) => setzeStaerke(e.pressure));
}

// Wichtig · Fallstricke

Nicht standardisiert: Das Ereignis gibt es nur in Safari unter macOS mit Force-Touch-Trackpad. Chrome, Firefox, Edge und Safari unter iOS unterstützen es nicht. Nutze es nicht in Produktivcode, ohne vorher zu prüfen, ob es verfügbar ist.
Prüfe die Unterstützung mit 'onwebkitmouseforcechanged' in element. Ein fehlendes Ereignis erzeugt keinen Fehler, der Handler wird dann einfach nie aufgerufen.
Das Ereignis kann sehr oft feuern. Aufwendige DOM-Änderungen solltest du drosseln oder mit requestAnimationFrame bündeln.
Um das Standardverhalten des Systems beim Force-Klick (z. B. Nachschlagen) zu unterdrücken, rufst du in webkitmouseforcewillbegin die Methode event.preventDefault() auf.
Die standardisierte Alternative ist PointerEvent.pressure (Wertebereich 0–1). Beachte, dass webkitForce einen anderen Wertebereich hat (etwa 0–3).

Siehe auch

MouseEvent.webkitForce PointerEvent.pressure Element: contentvisibilityautostatechange Element: webkitmouseforcedown Element: webkitmouseforceup