Signatur
Beschreibung
Die schreibgeschützte Eigenschaft reportId der Schnittstelle HIDInputReportEvent enthält das Präfix, mit dem ein HID-Gerät seine Eingabeberichte kennzeichnet. Viele Geräte wie Gamepads, Tastaturen mit Zusatztasten oder Controller mit Sensoren senden mehrere Berichtstypen über dieselbe Schnittstelle. Anhand der Report-ID kannst du erkennen, welches Datenformat ein Bericht hat, und ihn passend auswerten.
Der Wert ist eine ganze Zahl zwischen 0 und 255. Nutzt das Gerät laut seinem Report-Deskriptor keine Report-IDs, ist der Wert immer 0. Wichtig: Die Report-ID ist nicht in event.data enthalten. Der Browser entfernt das Präfix-Byte, sodass data nur die eigentlichen Nutzdaten enthält.
Typischerweise liest du reportId im Handler des Events inputreport eines geöffneten HIDDevice aus, meist in einer switch-Anweisung, die je nach Berichtstyp einen anderen Parser aufruft. Welche IDs es gibt und wie sie aufgebaut sind, siehst du in HIDDevice.collections unter inputReports[].reportId.
Rückgabewert
0–255) mit der Report-ID des Eingabeberichts. Der Wert ist 0, wenn das Gerät keine Report-IDs verwendet.Beispiele
Report-ID beim Empfang ausgeben
// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
const button = document.querySelector('#verbinden');
button.addEventListener('click', async () => {
const [device] = await navigator.hid.requestDevice({ filters: [] });
if (!device) return;
await device.open();
device.addEventListener('inputreport', (event) => {
console.log(`Report-ID: ${event.reportId}, Länge: ${event.data.byteLength} Byte`);
});
});Berichte je nach Report-ID unterschiedlich auswerten
const handleReport = (event) => {
const { reportId, data } = event;
switch (reportId) {
case 0x01: {
// Tastenstatus: 1 Byte Bitmaske
const buttons = data.getUint8(0);
console.log('Taste A gedrückt:', Boolean(buttons & 0x01));
break;
}
case 0x02: {
// Sensorwerte: drei 16-Bit-Werte (Little Endian)
const x = data.getInt16(0, true);
const y = data.getInt16(2, true);
const z = data.getInt16(4, true);
console.log('Beschleunigung:', { x, y, z });
break;
}
case 0:
console.log('Gerät verwendet keine Report-IDs');
break;
default:
console.warn('Unbekannte Report-ID:', reportId);
}
};
const [device] = await navigator.hid.getDevices();
if (device) {
await device.open();
device.addEventListener('inputreport', handleReport);
}Erwartete Report-IDs aus dem Deskriptor prüfen
const [device] = await navigator.hid.getDevices();
if (device) {
// Bekannte Eingabe-Report-IDs aus den Collections sammeln
const known = new Set(
device.collections.flatMap((c) => c.inputReports.map((r) => r.reportId))
);
console.log('Bekannte Input-Report-IDs:', [...known]);
await device.open();
device.oninputreport = (event) => {
if (!known.has(event.reportId)) {
console.warn('Unerwarteter Bericht mit ID', event.reportId);
}
};
}// Wichtig · Fallstricke
- Report-ID nicht in
data: Das Präfix-Byte wird entfernt. Rechne Offsets inevent.datadeshalb ab Byte 0 der Nutzdaten und nicht so, wie sie in der Gerätedokumentation inklusive ID-Byte angegeben sind. 0hat zwei Bedeutungen:0ist keine gültige Report-ID. Der Wert bedeutet nur, dass das Gerät keine IDs verwendet. Beim Senden mitHIDDevice.sendReport()übergibst du in diesem Fall ebenfalls0.- Browser-Kompatibilität: WebHID wird nur von Chromium-Browsern auf dem Desktop unterstützt (Chrome, Edge, Opera). Firefox und Safari unterstützen die API nicht. Prüfe das vorab mit
'hid' in navigator. - Sicherheit: Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung.
requestDevice()braucht eine Nutzeraktion und kann per Permissions-Policy (hid) gesperrt sein, zum Beispiel in iframes. Bestimmte Geräteklassen wie Tastaturen und FIDO-Schlüssel blockiert der Browser. - Die Eigenschaft ist schreibgeschützt. Wenn du ihr einen Wert zuweist, passiert nichts.