HIDInputReportEvent.data — Eigenschaft · JavaScript-Referenz

Signatur

HIDInputReportEvent.data

Beschreibung

Die Eigenschaft data eines HIDInputReportEvent enthält die Rohdaten, die ein HID-Gerät (z. B. Gamepad, Barcode-Scanner, Makro-Tastatur oder Sensor) in einem Eingabebericht gesendet hat. Das Ereignis wird als inputreport auf dem zugehörigen HIDDevice ausgelöst.

Die Daten liegen als DataView vor, sodass du einzelne Bytes und mehrbytige Werte gezielt mit getUint8(), getInt16(), getUint32() usw. auslesen kannst. Verwendet das Gerät Berichts-IDs, wird das erste Byte (die ID) entfernt und separat in event.reportId bereitgestellt – Offset 0 in data ist also bereits das erste Nutzdatenbyte.

Wie die Bytes zu interpretieren sind (Bitfelder für Tasten, Achsenwerte, Byte-Reihenfolge), legt der Report-Deskriptor des Geräts fest. Die Struktur kannst du über device.collections ermitteln oder dem Datenblatt des Herstellers entnehmen. HID-Geräte übertragen mehrbytige Werte üblicherweise im Little-Endian-Format.

Beispiele

Eingabeberichte eines Geräts empfangen

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

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

  await device.open();

  device.addEventListener('inputreport', (event) => {
    const { data, reportId } = event;
    const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
    console.log(`Report ${reportId}:`, [...bytes].map(b => b.toString(16).padStart(2, '0')).join(' '));
  });
});

Report 1: 7f 80 7f 7f 08 00 00 ...

Achsen und Tasten auswerten

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

  // Annahme laut Deskriptor: Byte 0/1 = X/Y-Achse, Byte 4 = Tasten-Bitfeld
  const x = data.getUint8(0);
  const y = data.getUint8(1);
  const buttons = data.getUint8(4);
  const aPressed = (buttons & 0b0000_0001) !== 0;

  console.log({ x, y, aPressed });
};

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

{ x: 127, y: 128, aPressed: true }

16-Bit-Sensorwert (Little Endian) lesen

const [sensor] = await navigator.hid.getDevices();
await sensor.open();

sensor.oninputreport = ({ data }) => {
  if (data.byteLength < 2) return;
  // true = Little Endian, bei HID üblich
  const raw = data.getInt16(0, true);
  const celsius = raw / 100;
  console.log(`Temperatur: ${celsius.toFixed(2)} °C`);
};

Temperatur: 23.47 °C

// Wichtig · Fallstricke

Kompatibilität: WebHID gibt es nur in Chromium-Browsern (Chrome, Edge, Opera) ab Version 89, auf dem Desktop. Firefox und Safari unterstützen die API nicht. Prüfe das vorher mit 'hid' in navigator.
Sicherer Kontext: Die API funktioniert nur über HTTPS (oder localhost). requestDevice() braucht eine Nutzeraktion, und in iframes muss die Permissions Policy hid erlaubt sein.
Kein reportId-Byte: Der Offset 0 ist bereits das erste Nutzdatenbyte. Wer Code von nativen HID-Bibliotheken übernimmt, die die ID mitliefern, muss alle Offsets um 1 verschieben.
DataView-Offsets: Wenn du ein Uint8Array erzeugst, gib immer data.byteOffset und data.byteLength mit. Nur data.buffer allein kann mehr Bytes enthalten als der Bericht.
Endianness: DataView liest standardmäßig Big Endian. Für HID-Werte fast immer true als zweites Argument übergeben.
Performance: Geräte können sehr viele Berichte pro Sekunde senden. Halte den Handler schlank und aktualisiere die Oberfläche z. B. gebündelt über requestAnimationFrame.
Manche Geräte (z. B. Tastaturen und Mäuse) sind vom Browser gesperrt und liefern keine Berichte.

Siehe auch

HIDInputReportEvent HIDInputReportEvent.reportId HIDInputReportEvent.device HID.requestDevice() DataView MediaQueryListEvent.matches