MouseEvent.webkitForce — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.webkitForce

Beschreibung

MouseEvent.webkitForce ist eine nicht standardisierte, schreibgeschützte Eigenschaft, die nur Apple mit WebKit/Safari eingeführt hat. Sie enthält eine Gleitkommazahl mit dem aktuellen Druck, den der Finger auf ein Force-Touch-Trackpad (z. B. MacBook, Magic Trackpad 2) ausübt. Der Wert ist in allen Maus-Ereignissen vorhanden, richtig aussagekräftig ist er aber vor allem bei den WebKit-spezifischen Force-Ereignissen.

Zur Einordnung gibt es zwei Konstanten: MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN (Wert 1) ist der Mindestdruck für einen normalen Klick, und MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN (Wert 2) ist der Mindestdruck für einen „Force Click“ (festes Drücken). Werte zwischen 0 und 1 bedeuten leichtes Aufliegen, Werte über 2 sehr festes Drücken. Der Höchstwert liegt ungefähr bei 3.

Passende Ereignisse sind webkitmouseforcewillbegin (hier lässt sich mit preventDefault() die Systemaktion unterdrücken, z. B. das Nachschlagen im Wörterbuch), webkitmouseforcedown, webkitmouseforcechanged und webkitmouseforceup. Damit lassen sich druckabhängige Bedienelemente bauen, etwa Vorschauen beim festen Drücken oder Zeichenwerkzeuge mit unterschiedlicher Strichstärke.

Für neue Projekte empfiehlt sich die standardisierte Eigenschaft PointerEvent.pressure (Wertebereich 0–1). Sie funktioniert in allen Browsern mit Stift, Touch und Maus. webkitForce sollte man höchstens als zusätzliche Verbesserung in Safari einsetzen.

Rückgabewert

Typ

number | undefined

Beschreibung

Gleitkommazahl mit dem aktuellen Druck (etwa 0 bis 3). In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Force Click erkennen und Systemaktion unterdrücken

const karte = document.querySelector('#produkt-karte');

// Standardaktion (z. B. Wörterbuch-Vorschau) verhindern
karte.addEventListener('webkitmouseforcewillbegin', (event) => {
  event.preventDefault();
});

karte.addEventListener('webkitmouseforcedown', (event) => {
  console.log('Force Click mit Druck:', event.webkitForce.toFixed(2));
  karte.classList.add('vorschau-offen');
});

karte.addEventListener('webkitmouseforceup', () => {
  karte.classList.remove('vorschau-offen');
});

Force Click mit Druck: 2.03

Druck laufend auswerten und visualisieren

const knopf = document.querySelector('#druck-knopf');
const { WEBKIT_FORCE_AT_MOUSE_DOWN: KLICK, WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN: FORCE } = MouseEvent;

knopf.addEventListener('webkitmouseforcechanged', (event) => {
  const kraft = event.webkitForce;
  // Skaliert zwischen normalem Klick (1) und Force Click (2) auf 1.0–1.2
  const anteil = Math.min(Math.max((kraft - KLICK) / (FORCE - KLICK), 0), 1);
  knopf.style.transform = `scale(${1 + anteil * 0.2})`;
  console.log(`Kraft: ${kraft.toFixed(2)}, Anteil: ${Math.round(anteil * 100)} %`);
});

Kraft: 1.50, Anteil: 50 %

Feature-Erkennung mit standardkonformem Ersatz

const leinwand = document.querySelector('canvas');
const ctx = leinwand.getContext('2d');

// Liefert einen normierten Druck von 0 bis 1
const druckAus = (event) => {
  if (typeof event.webkitForce === 'number') {
    return Math.min(event.webkitForce / 3, 1); // Safari/Force Touch
  }
  return event.pressure ?? 0.5; // PointerEvent-Standard
};

leinwand.addEventListener('pointermove', (event) => {
  if (event.buttons !== 1) return;
  const radius = 1 + druckAus(event) * 8;
  ctx.beginPath();
  ctx.arc(event.offsetX, event.offsetY, radius, 0, Math.PI * 2);
  ctx.fill();
});

// Wichtig · Fallstricke

Nicht standardisiert: Die Eigenschaft steht in keiner Spezifikation und wird nur von Safari unter macOS mit Force-Touch-Hardware unterstützt. Chrome, Firefox und Edge kennen sie nicht, dort ist sie undefined. Vor der Nutzung immer mit typeof event.webkitForce === 'number' prüfen.
Ohne Force-Touch-Trackpad (z. B. mit einer normalen Maus) liefert Safari feste Werte oder 0. Ein gültiger Zahlenwert heißt also noch nicht, dass echte Druckdaten vorliegen.
Unter iOS gibt es webkitForce nicht an MouseEvent. Dort gab es früher Touch.force für 3D Touch, und diese Hardware wird inzwischen nicht mehr gebaut.
Die Systemaktion bei festem Drücken lässt sich nur im Ereignis webkitmouseforcewillbegin mit preventDefault() unterdrücken, später nicht mehr.
Wichtige Funktionen dürfen nie nur über festes Drücken erreichbar sein. Aus Gründen der Barrierefreiheit und der Kompatibilität braucht es immer einen anderen Weg, etwa per Klick oder Tastatur.
Die empfohlene, browserübergreifende Alternative ist PointerEvent.pressure.

Siehe auch

MouseEvent PointerEvent.pressure Touch.force PointerEvent Event.preventDefault() EventTarget.addEventListener() MouseEvent.mozInputSource