HIDInputReportEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface HIDInputReportEvent extends Event

Beschreibung

Das Interface HIDInputReportEvent gehört zur WebHID API. Ein Objekt dieses Typs wird an Listener des inputreport-Ereignisses eines geöffneten HIDDevice übergeben, sobald das Gerät einen Eingabereport sendet. Das passiert etwa bei einem Tastendruck am Gamepad, einer Drehung am Stream-Deck-Regler oder bei neuen Sensordaten.

Das Ereignis erbt von Event und hat drei eigene, schreibgeschützte Eigenschaften:

data: eine DataView mit den Rohdaten des Reports, ohne das Report-ID-Byte.
device: das HIDDevice, von dem der Report stammt.
reportId: die Report-ID als Zahl, oder 0, wenn das Gerät keine Report-IDs verwendet.

Wie die Bytes aufgebaut sind, legt der Report-Deskriptor des Geräts fest. Eine Übersicht über diesen Aufbau liefert device.collections. Häufig braucht man zusätzlich die Datenblätter des Herstellers, um die Werte richtig mit getUint8(), getInt16() usw. auszulesen. Vorher muss das Gerät über navigator.hid.requestDevice() ausgewählt und mit device.open() geöffnet werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Ereignisses, üblicherweise `"inputreport"`.
$eventInitDict Pflicht	{ data: DataView, device: HIDDevice, reportId: number } & EventInit		Konstruktor-Parameter: Initialisierungsobjekt mit `data`, `device` und `reportId`. In der Praxis erzeugt der Browser das Ereignis selbst.

Rückgabewert

Typ

HIDInputReportEvent

Beschreibung

Ereignisobjekt mit den Eigenschaften data (DataView), device (HIDDevice) und reportId (number).

Beispiele

Gerät öffnen und Eingabereports per addEventListener empfangen

const connectButton = document.querySelector('#connect');

connectButton.addEventListener('click', async () => {
  // Muss durch eine Nutzeraktion ausgelöst werden
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: 0x057e }] // z. B. Nintendo
  });
  if (!device) return;

  await device.open();

  device.addEventListener('inputreport', (event) => {
    const { data, device, reportId } = event;
    const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
    console.log(`${device.productName} – Report ${reportId}:`, bytes);
  });
});

Joy-Con (L) – Report 63: Uint8Array(11) [ ... ]

Tastenzustand aus einem Report auslesen (oninputreport)

const handleReport = ({ data, reportId }) => {
  if (reportId !== 0x01) return; // nur Report-ID 1 auswerten

  const buttons = data.getUint8(0);   // Byte 0: Bitmaske der Tasten
  const axisX = data.getInt16(1, true); // Bytes 1–2: X-Achse, Little Endian

  const pressed = [0, 1, 2, 3].filter((bit) => buttons & (1 << bit));
  console.log('Gedrückte Tasten:', pressed, 'X-Achse:', axisX);
};

const [device] = await navigator.hid.getDevices();
if (device) {
  if (!device.opened) await device.open();
  device.oninputreport = handleReport;
}

Gedrückte Tasten: [0, 2] X-Achse: -1204

Listener entfernen und Gerät schließen

const onReport = (event) => {
  console.log('Report-Länge:', event.data.byteLength);
};

const [device] = await navigator.hid.getDevices();
await device.open();
device.addEventListener('inputreport', onReport);

// Nach 10 Sekunden aufräumen
setTimeout(async () => {
  device.removeEventListener('inputreport', onReport);
  await device.close();
  console.log('Gerät geschlossen');
}, 10_000);

Report-Länge: 8 ... Gerät geschlossen

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und steht nur in Chromium-basierten Desktop-Browsern bereit (Chrome/Edge ab 89). Firefox und Safari unterstützen sie nicht. Prüfen Sie vor der Nutzung mit 'hid' in navigator, ob sie vorhanden ist.
Sicherer Kontext: Die API funktioniert nur über HTTPS bzw. localhost. requestDevice() erfordert eine Nutzeraktion. In iframes muss die Permissions-Policy hid erlaubt sein.
Report-ID: data enthält die Report-ID nicht. Die Byte-Offsets beginnen also direkt bei den Nutzdaten.
DataView korrekt lesen: Achten Sie bei getInt16() und ähnlichen Methoden auf die Byte-Reihenfolge (Endianness). Viele HID-Geräte senden Little Endian, deshalb ist das zweite Argument oft true. Wenn Sie ein Uint8Array erzeugen, berücksichtigen Sie byteOffset und byteLength.
Performance: Manche Geräte senden Hunderte Reports pro Sekunde. Halten Sie die Listener schlank und bündeln Sie DOM-Updates, zum Beispiel mit requestAnimationFrame.
Gesperrte Geräte: Tastaturen, Mäuse und FIDO-Sicherheitsschlüssel sind aus Sicherheitsgründen ganz oder teilweise gesperrt. Von ihnen kommen daher keine Reports.
Reports werden erst nach device.open() zugestellt. Nach close() oder beim Trennen des Geräts (disconnect-Ereignis) hört die Zustellung auf.

Siehe auch

HIDDevice HID HIDConnectionEvent HID.requestDevice() HIDDevice.sendReport() DataView Event