PointerEvent.width — Eigenschaft · JavaScript-Referenz

Signatur

PointerEvent.width

Beschreibung

Die schreibgeschützte Eigenschaft width eines PointerEvent gibt die Breite der Kontaktgeometrie des Zeigers entlang der x-Achse in CSS-Pixeln an. Zusammen mit height beschreibt sie ein Rechteck um den Kontaktpunkt (clientX/clientY liegt in dessen Mitte).

Wirklich aussagekräftig ist der Wert vor allem bei Touch-Eingaben: Ein Finger hat eine messbare Auflagefläche, die je nach Druck und Winkel wächst oder schrumpft. So lassen sich etwa Zeichen-Apps mit variabler Pinselbreite bauen, großflächige Berührungen (z. B. Handballen beim Stifteinsatz) herausfiltern oder Trefferflächen großzügiger auswerten.

Bei Geräten ohne Kontaktgeometrie – typischerweise Maus und oft auch Stift – liefert der Browser laut Spezifikation den Wert 1. Frühere Spezifikationsstände und ältere Browser gaben teilweise 0 zurück; robuster Code sollte daher beide Fälle als „keine Geometrie verfügbar“ behandeln.

Rückgabewert

Typ

number

Beschreibung

Breite der Kontaktfläche in CSS-Pixeln als Gleitkommazahl. Bei Zeigern ohne Kontaktgeometrie (z. B. Maus) ist der Wert 1.

Beispiele

Kontaktgröße beim Antippen ausgeben

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

flaeche.addEventListener('pointerdown', (event) => {
  console.log(`${event.pointerType}: ${event.width.toFixed(1)} × ${event.height.toFixed(1)} px`);
});

touch: 23.0 × 25.5 px mouse: 1.0 × 1.0 px

Pinselbreite in einer Zeichen-App aus der Kontaktfläche ableiten

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
canvas.style.touchAction = 'none'; // Scrollen/Zoomen unterdrücken

let letzter = null;

canvas.addEventListener('pointerdown', (e) => {
  letzter = { x: e.offsetX, y: e.offsetY };
  canvas.setPointerCapture(e.pointerId);
});

canvas.addEventListener('pointermove', (e) => {
  if (!letzter) return;
  // Ohne Geometrie (Maus/Stift) Standardbreite verwenden
  const hatGeometrie = e.width > 1;
  const breite = hatGeometrie ? Math.max(e.width, e.height) / 2 : 2 + e.pressure * 6;

  ctx.lineWidth = breite;
  ctx.lineCap = 'round';
  ctx.beginPath();
  ctx.moveTo(letzter.x, letzter.y);
  ctx.lineTo(e.offsetX, e.offsetY);
  ctx.stroke();
  letzter = { x: e.offsetX, y: e.offsetY };
});

canvas.addEventListener('pointerup', () => { letzter = null; });

Handballen-Berührungen ignorieren (Palm Rejection)

const MAX_FINGERBREITE = 40; // CSS-Pixel, empirischer Wert

document.addEventListener('pointerdown', (e) => {
  if (e.pointerType === 'touch' && e.width > MAX_FINGERBREITE) {
    console.log('Große Kontaktfläche erkannt – vermutlich Handballen, ignoriert.');
    e.preventDefault();
    return;
  }
  console.log('Gültige Eingabe bei', e.clientX, e.clientY);
});

Große Kontaktfläche erkannt – vermutlich Handballen, ignoriert.

// Wichtig · Fallstricke

Maus und Stift: Hier liefert width meist 1 (ältere Implementierungen: 0). Prüfe also pointerType oder width > 1, bevor du den Wert als echte Kontaktgröße verwendest.
Hardwareabhängig: Viele Touchscreens melden nur grobe, gerundete oder konstante Werte. Einige Desktop-Touchpads liefern gar keine Geometrie. Verlasse dich nicht auf exakte Pixelwerte, sondern arbeite mit Schwellwerten.
Einheit: Der Wert ist in CSS-Pixeln angegeben und hängt damit vom Zoom bzw. von devicePixelRatio ab. Für Canvas-Zeichnungen in physischen Pixeln entsprechend umrechnen.
Die Eigenschaft ist schreibgeschützt. Bei synthetischen Events lässt sie sich über das Init-Wörterbuch setzen: new PointerEvent('pointerdown', { width: 20 }).
Kompatibilität: In allen aktuellen Browsern (Chrome, Edge, Firefox, Safari 13+) verfügbar. Damit Touch-Pointer-Events zuverlässig ankommen, oft touch-action: none auf dem Element setzen.

Siehe auch

HTMLTableElement.width PointerEvent.tiltX PointerEvent.tiltY PointerEvent.twist PointerEvent.height