Gamepad.hand — Eigenschaft · JavaScript-Referenz

Signatur

Gamepad.hand

Beschreibung

Die Eigenschaft hand des Gamepad-Interfaces gibt einen Wert des Enums GamepadHand zurück. Er zeigt an, in welcher Hand ein Controller gerade gehalten wird oder für welche Hand er gebaut ist. Mögliche Werte sind "left" (linke Hand), "right" (rechte Hand) und "" (leere Zeichenkette). Die leere Zeichenkette steht für „unbekannt“ oder „keiner bestimmten Hand zugeordnet“.

Sinnvoll ist die Eigenschaft vor allem bei VR- und AR-Controllern, die paarweise auftreten, zum Beispiel Bewegungscontroller mit Positionsverfolgung. Damit lässt sich ein virtuelles Hand-Modell auf der richtigen Seite anzeigen oder eine Taste pro Hand unterschiedlich belegen (etwa „links = Teleport, rechts = Greifen“). Bei klassischen Gamepads wie Xbox- oder PlayStation-Controllern ist der Wert in der Regel "".

hand gehört zur Spezifikation Gamepad Extensions, nicht zur Kern-Gamepad-API. Die Eigenschaft ist experimentell und wird kaum unterstützt. Prüfe deshalb immer zuerst, ob sie vorhanden ist ('hand' in gamepad), und sieh eine Ausweichlösung vor. Für moderne XR-Anwendungen gibt es die gleiche Information standardisiert über XRInputSource.handedness aus der WebXR Device API.

Rückgabewert

Typ

"left" | "right" | "" (GamepadHand)

Beschreibung

"left" oder "right", wenn die Hand bekannt ist, sonst "". In Browsern ohne Unterstützung liefert die Eigenschaft undefined.

Beispiele

Hand beim Verbinden eines Controllers ausgeben

window.addEventListener('gamepadconnected', (event) => {
  const pad = event.gamepad;
  if (!('hand' in pad)) {
    console.log(`${pad.id}: Gamepad.hand wird nicht unterstützt`);
    return;
  }
  const label = pad.hand === '' ? 'keine/unbekannt' : pad.hand;
  console.log(`${pad.id} (Index ${pad.index}) – Hand: ${label}`);
});

OpenVR Controller (Index 0) – Hand: left

Controller nach Hand zuordnen (VR-Steuerung)

const getControllersByHand = () => {
  const result = { left: null, right: null, other: [] };
  for (const pad of navigator.getGamepads()) {
    if (!pad) continue;
    if (pad.hand === 'left' || pad.hand === 'right') {
      result[pad.hand] = pad;
    } else {
      result.other.push(pad);
    }
  }
  return result;
};

const loop = () => {
  const { left, right } = getControllersByHand();
  if (left?.buttons[0]?.pressed) console.log('Teleport (linke Hand)');
  if (right?.buttons[0]?.pressed) console.log('Greifen (rechte Hand)');
  requestAnimationFrame(loop);
};
requestAnimationFrame(loop);

Greifen (rechte Hand)

Ausweichlösung: Hand aus der Reihenfolge ableiten

const resolveHand = (pad, fallbackOrder = ['left', 'right']) => {
  if (pad.hand === 'left' || pad.hand === 'right') return pad.hand;
  // Keine Angabe verfügbar: nach Index raten
  return fallbackOrder[pad.index] ?? 'unbekannt';
};

const pads = navigator.getGamepads().filter(Boolean);
pads.forEach((pad) => console.log(pad.id, '→', resolveHand(pad)));

Xbox Wireless Controller → left

// Wichtig · Fallstricke

Kompatibilität: Experimentell und nicht Teil der Baseline. Firefox unterstützt die Eigenschaft nur hinter dem Flag dom.gamepad.extensions.enabled. Chrome, Edge und Safari bieten sie nicht an, dort ist der Wert undefined. Vor der Nutzung immer die Unterstützung prüfen.
Leere Zeichenkette ist kein Fehler: "" heißt nur, dass keine Hand bekannt oder zugeordnet ist. Prüfe deshalb ausdrücklich auf "left" oder "right" und nicht bloß, ob der Wert „wahr“ ist.
Momentaufnahme: In Chromium-basierten Browsern liefert navigator.getGamepads() Momentaufnahmen. Hole das Gamepad-Objekt deshalb in jedem Frame neu ab, weil sich die Zuordnung ändern kann, wenn Controller die Hand wechseln.
Empfehlung für XR: Für WebXR-Anwendungen nimm XRInputSource.handedness. Das ist standardisiert und breiter unterstützt.
Die Gamepad-API ist nur in einem sicheren Kontext (HTTPS) verfügbar und kann durch die Permissions-Policy gamepad gesperrt sein.

Siehe auch

Gamepad Navigator.getGamepads() Gamepad.pose Gamepad.hapticActuators XRInputSource.handedness GainNode.gain