Element: webkitmouseforcewillbegin — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("webkitmouseforcewillbegin", handler)

Beschreibung

Das Ereignis webkitmouseforcewillbegin gehört zu Apples proprietären Force-Touch-Ereignissen in Safari für macOS. Safari löst es an einem Element aus, bevor das erste mousedown kommt. Die Seite erfährt so frühzeitig, dass der Nutzer gleich fester auf das Trackpad drücken könnte.

Hauptzweck ist, das Standardverhalten des Systems bei einem kräftigen Klick zu verhindern. Standardmäßig öffnet ein Force Click etwa die Nachschlagen-Funktion oder eine Link-Vorschau. Rufen Sie in diesem Ereignis event.preventDefault() auf, unterdrückt Safari diese Aktion. Die Seite kann den Druck dann über webkitmouseforcechanged, webkitmouseforcedown und webkitmouseforceup selbst auswerten.

Das Ereignis ist ein MouseEvent mit der zusätzlichen Eigenschaft webkitForce, die die aktuelle Druckstärke enthält. Sie können den Handler mit addEventListener() registrieren oder über die Eigenschaft onwebkitmouseforcewillbegin. Diese Eigenschaft gibt es aber nicht zuverlässig in jeder Safari-Version, deshalb ist addEventListener() vorzuziehen.

Da es sich um eine reine WebKit-Erweiterung handelt, sollte sie höchstens als progressive Verbesserung eingesetzt werden. Für browserübergreifende Druckerkennung ist die standardisierte Eigenschaft PointerEvent.pressure die richtige Wahl.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"webkitmouseforcewillbegin"`.
$handler Pflicht	(event: MouseEvent) => void		Callback, der ein `MouseEvent` mit der zusätzlichen Eigenschaft `webkitForce` (number) erhält.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `capture`, `once` und `signal`. Setzen Sie nicht `passive: true`, wenn Sie `preventDefault()` aufrufen wollen.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück.

Beispiele

Standard-Force-Click (Nachschlagen) unterdrücken

const canvas = document.querySelector('#zeichenflaeche');

canvas.addEventListener('webkitmouseforcewillbegin', (event) => {
  // Verhindert Nachschlagen/Vorschau, damit wir den Druck selbst auswerten
  event.preventDefault();
  console.log('Force Touch vorbereitet, Startdruck:', event.webkitForce);
});

Force Touch vorbereitet, Startdruck: 0

Zusammenspiel mit webkitmouseforcechanged

const button = document.querySelector('#druck-button');

button.addEventListener('webkitmouseforcewillbegin', (e) => e.preventDefault());

button.addEventListener('webkitmouseforcechanged', (e) => {
  // Druck ab MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN (ca. 2) gilt als Force Click
  const stufe = Math.min(e.webkitForce / 3, 1);
  button.style.setProperty('--druck', stufe.toFixed(2));
});

Registrieren per on-Property und wieder entfernen

const link = document.querySelector('a.vorschau');

const beiForceStart = (event) => {
  event.preventDefault();
  console.log('Link-Vorschau unterdrückt');
};

if ('onwebkitmouseforcewillbegin' in link) {
  link.onwebkitmouseforcewillbegin = beiForceStart;
} else {
  link.addEventListener('webkitmouseforcewillbegin', beiForceStart);
}

// Später wieder entfernen
const entfernen = () => {
  link.onwebkitmouseforcewillbegin = null;
  link.removeEventListener('webkitmouseforcewillbegin', beiForceStart);
};

Link-Vorschau unterdrückt

Feature-Erkennung mit Rückfall auf Pointer Events

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

if ('WEBKIT_FORCE_AT_MOUSE_DOWN' in MouseEvent) {
  flaeche.addEventListener('webkitmouseforcewillbegin', (e) => e.preventDefault());
  flaeche.addEventListener('webkitmouseforcechanged', (e) => console.log('WebKit-Druck:', e.webkitForce));
} else {
  flaeche.addEventListener('pointermove', (e) => {
    if (e.buttons) console.log('Pointer-Druck:', e.pressure);
  });
}

Pointer-Druck: 0.5

// Wichtig · Fallstricke

Nicht standardisiert: Das Ereignis gibt es nur in Safari unter macOS und nur mit Force-Touch-Hardware. Chrome, Firefox, Edge und Safari unter iOS lösen es nicht aus. Verwenden Sie es nicht in Produktionscode, ohne einen Rückfall vorzusehen.
Um das Standardverhalten zu unterdrücken, muss preventDefault() in diesem Ereignis aufgerufen werden. Ein späterer Aufruf in mousedown oder webkitmouseforcedown ist zu spät.
Die Konstanten MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN (1) und MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN (2) eignen sich zur Feature-Erkennung und als Schwellenwerte.
Wer das System-Nachschlagen unterdrückt, schränkt die Barrierefreiheit und die gewohnte Bedienung ein. Tun Sie das nur, wenn die Seite den Force Click sinnvoll selbst nutzt.
Standardisierte Alternative: PointerEvent.pressure zusammen mit pointerdown und pointermove.

Siehe auch

MouseEvent.webkitForce PointerEvent.pressure Element: DOMMouseScroll Element: webkitmouseforcechanged Element: webkitmouseforcedown