PointerEvent.persistentDeviceId — Eigenschaft · JavaScript-Referenz

Signatur

PointerEvent.persistentDeviceId

Beschreibung

Die schreibgeschützte Eigenschaft persistentDeviceId der Schnittstelle PointerEvent liefert eine Kennung für das physische Gerät, das das Ereignis ausgelöst hat. Das Gegenstück pointerId kennzeichnet nur einen einzelnen aktiven Zeiger und kann für jeden neuen Strich einen anderen Wert haben. persistentDeviceId bleibt dagegen für dasselbe Gerät gleich, solange das Dokument geladen ist.

Das ist vor allem bei Zeichen- und Whiteboard-Anwendungen mit mehreren Stiften nützlich. Wenn zwei Personen mit zwei verschiedenen Stiften auf demselben Touch-Display zeichnen, kann die Anwendung jedem Stift dauerhaft eine eigene Farbe, Strichstärke oder ein eigenes Werkzeug zuordnen, statt die Zuordnung bei jedem pointerdown neu raten zu müssen.

Wenn der Browser das Gerät nicht eindeutig erkennen kann, ist der Wert 0. Das gilt auch, wenn die Hardware keine Kennung liefert. Die Kennung wird aus Datenschutzgründen nicht über Dokumente oder Seitenaufrufe hinweg beibehalten. Sie eignet sich also nicht, um Geräte dauerhaft wiederzuerkennen, sondern nur für die Zuordnung innerhalb einer Sitzung.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl, die das Zeigegerät kennzeichnet. Kann das Gerät nicht erkannt werden, ist der Wert 0.

Beispiele

Geräte-ID beim Aufsetzen des Stifts ausgeben

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

canvas.addEventListener('pointerdown', (event) => {
  console.log(`Typ: ${event.pointerType}`);
  console.log(`pointerId: ${event.pointerId}`);
  console.log(`persistentDeviceId: ${event.persistentDeviceId}`);
});

Typ: pen pointerId: 3 persistentDeviceId: 17

Jedem Stift dauerhaft eine eigene Farbe zuordnen

const canvas = document.querySelector('#zeichenflaeche');
const ctx = canvas.getContext('2d');
const farben = ['#e63946', '#1d3557', '#2a9d8f', '#f4a261'];
const farbeProGeraet = new Map();

const farbeFuer = (event) => {
  const id = event.persistentDeviceId;
  // 0 = Gerät nicht erkennbar -> Standardfarbe
  if (!id) return '#000000';
  if (!farbeProGeraet.has(id)) {
    farbeProGeraet.set(id, farben[farbeProGeraet.size % farben.length]);
  }
  return farbeProGeraet.get(id);
};

canvas.addEventListener('pointerdown', (event) => {
  ctx.strokeStyle = farbeFuer(event);
  ctx.lineWidth = 3;
  ctx.beginPath();
  ctx.moveTo(event.offsetX, event.offsetY);
  canvas.setPointerCapture(event.pointerId);
});

canvas.addEventListener('pointermove', (event) => {
  if (!canvas.hasPointerCapture(event.pointerId)) return;
  ctx.lineTo(event.offsetX, event.offsetY);
  ctx.stroke();
});

Feature-Erkennung mit Rückfall auf pointerId

const unterstuetzt = 'persistentDeviceId' in PointerEvent.prototype;

const geraeteSchluessel = (event) =>
  unterstuetzt && event.persistentDeviceId !== 0
    ? `geraet-${event.persistentDeviceId}`
    : `zeiger-${event.pointerId}`;

document.addEventListener('pointerdown', (event) => {
  console.log(geraeteSchluessel(event));
});

geraet-17 // Chromium mit erkanntem Stift zeiger-1 // Firefox/Safari oder unbekanntes Gerät

// Wichtig · Fallstricke

Browser-Unterstützung: Nur in Chromium-Browsern (Chrome/Edge ab Version 128). Firefox und Safari unterstützen die Eigenschaft nicht, dort ist sie undefined. Prüfe die Unterstützung vorher, z. B. mit 'persistentDeviceId' in PointerEvent.prototype.
Wert 0: Bedeutet, dass das Gerät nicht erkannt wurde. Das kommt bei Maus- oder Touch-Eingabe häufig vor, ebenso bei Stiften ohne Hardware-Kennung. Bei manchen Stiften ist die Kennung erst nach dem Aufsetzen verfügbar, sodass frühe pointerover- oder Hover-Ereignisse noch 0 liefern können. Ordne das Gerät daher am besten bei pointerdown zu.
Nicht dauerhaft gespeichert: Trotz des Namens bleibt die Kennung nur erhalten, solange das Dokument geladen ist. Nach einem Neuladen oder Seitenwechsel kann sie anders sein. Speichere sie also nicht in localStorage, um Einstellungen über Sitzungen hinweg zu merken.
Datenschutz: Der Wert ist absichtlich nur innerhalb eines Dokuments gültig, damit er nicht zum Fingerprinting taugt. Er enthält keine Seriennummer der Hardware.
Nicht mit pointerId verwechseln: Für setPointerCapture() und releasePointerCapture() brauchst du weiterhin pointerId.
Bei selbst erzeugten Ereignissen setzt du den Wert über das Feld persistentDeviceId in PointerEventInit von new PointerEvent(). Ohne Angabe ist er 0.

Siehe auch

MediaTrackSupportedConstraints.deviceId PointerEvent.pointerId PointerEvent.pointerType PointerEvent.altitudeAngle PointerEvent.pressure