GamepadButton.touched — Eigenschaft · JavaScript-Referenz

Signatur

GamepadButton.touched

Beschreibung

Die Eigenschaft touched eines GamepadButton-Objekts liefert true, wenn die Taste gerade berührt wird, sonst false. Manche Controller haben Tasten mit kapazitiven Sensoren, etwa VR-Controller wie Oculus Touch oder Valve Index. Diese Tasten erkennen einen aufliegenden Finger auch dann, wenn die Taste nicht gedrückt ist.

Laut Spezifikation gilt: Eine gedrückte Taste (pressed === true) ist immer auch berührt. Hat eine Taste keinen Berührungssensor, liefert touched denselben Wert wie pressed. Du kannst touched also abfragen, ohne vorher zu prüfen, was die Hardware kann.

Typische Einsatzfälle:

Fingerhaltung in VR-Anwendungen darstellen, z. B. ein Handmodell, dessen Daumen auf der Taste liegt.
Hinweise zur Tastenbelegung einblenden, sobald der Nutzer eine Taste nur berührt.
Eine Vorschau zeigen, bevor die Aktion tatsächlich ausgelöst wird.

Wie alle Gamepad-Zustände wird touched nicht über Events gemeldet. Du musst den Wert selbst abfragen, meist in einer requestAnimationFrame-Schleife über navigator.getGamepads().

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Taste berührt oder gedrückt wird, sonst false. Ohne Berührungssensor ist der Wert identisch mit pressed.

Beispiele

Berührungszustand aller Tasten einmalig auslesen

window.addEventListener('gamepadconnected', (event) => {
  const pad = navigator.getGamepads()[event.gamepad.index];
  pad.buttons.forEach((button, i) => {
    console.log(`Taste ${i}: touched=${button.touched}, pressed=${button.pressed}`);
  });
});

Taste 0: touched=false, pressed=false Taste 1: touched=false, pressed=false ...

Tastenhinweis beim Berühren einblenden (Polling-Schleife)

const hint = document.querySelector('#hint');
const labels = ['Springen', 'Ducken', 'Nachladen', 'Menü'];

const poll = () => {
  const pad = navigator.getGamepads().find((p) => p !== null);
  if (pad) {
    const idx = pad.buttons.findIndex((b, i) => i < labels.length && b.touched && !b.pressed);
    hint.textContent = idx >= 0 ? `Taste ${idx}: ${labels[idx]}` : '';
  }
  requestAnimationFrame(poll);
};

requestAnimationFrame(poll);

Übergänge erkennen: Berührung beginnt / endet

let previous = [];

const loop = () => {
  const pad = navigator.getGamepads()[0];
  if (pad) {
    pad.buttons.forEach((button, i) => {
      const was = previous[i] ?? false;
      if (button.touched && !was) console.log(`Finger auf Taste ${i}`);
      if (!button.touched && was) console.log(`Finger von Taste ${i} genommen`);
    });
    previous = pad.buttons.map((b) => b.touched);
  }
  requestAnimationFrame(loop);
};

requestAnimationFrame(loop);

Finger auf Taste 0 Finger von Taste 0 genommen

// Wichtig · Fallstricke

Kein Event: Änderungen an touched lösen kein Event aus. Frage den Wert regelmäßig ab und vergleiche ihn mit dem vorherigen Zustand, um Übergänge zu erkennen.
Momentaufnahmen: In Chrome sind die von navigator.getGamepads() gelieferten Objekte Momentaufnahmen. Rufe getGamepads() deshalb in jedem Frame neu auf, statt ein altes Gamepad-Objekt aufzubewahren.
Hardwareabhängig: Klassische Controller (Xbox, PlayStation) haben meist keine Berührungssensoren. Dann ist touched gleich pressed. Du kannst auf diesem Weg also nicht feststellen, ob eine Taste einen Berührungssensor hat.
Kompatibilität: Firefox und ältere Browser unterstützen touched teils nicht, dann ist der Wert undefined. Als Rückfall eignet sich button.touched ?? button.pressed. Die Gamepad API ist nur in sicheren Kontexten (HTTPS) verfügbar und kann per Permissions-Policy: gamepad gesperrt sein.
Für VR-Controller liefert WebXR die Tastenzustände über XRInputSource.gamepad, dort mit denselben GamepadButton-Objekten.

Siehe auch

GamepadButton GamepadButton.pressed GamepadButton.value Gamepad.buttons Navigator.getGamepads() requestAnimationFrame()