Signatur
Beschreibung
Die Methode open() des Interfaces HIDDevice öffnet eine Verbindung zu einem HID-Gerät (Human Interface Device), z. B. einem Gamepad, einer programmierbaren Tastatur, einem Barcode-Scanner oder einem LED-Controller. Erst nach erfolgreichem Öffnen kann die Seite mit sendReport(), sendFeatureReport() und receiveFeatureReport() mit dem Gerät kommunizieren. Eingehende Input-Reports kommen über das Event inputreport an.
Ein HIDDevice-Objekt erhält man über navigator.hid.requestDevice(). Dafür ist eine Nutzeraktion nötig, etwa ein Klick. Bereits freigegebene Geräte liefert navigator.hid.getDevices(). Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald das Gerät offen ist, und abgelehnt, wenn das Betriebssystem den Zugriff verweigert oder das Gerät nicht mehr verfügbar ist.
Ob ein Gerät schon geöffnet ist, zeigt die Eigenschaft opened. Nach der Nutzung sollte man die Verbindung mit close() wieder schließen, damit andere Anwendungen oder Tabs darauf zugreifen können.
Rückgabewert
Promise, das mit undefined erfüllt wird, sobald die Verbindung offen ist. Schlägt das Öffnen fehl, wird es mit einer DOMException abgelehnt (z. B. InvalidStateError oder NotAllowedError).Beispiele
Gerät auswählen und öffnen
const button = document.querySelector('#connect');
button.addEventListener('click', async () => {
// Nutzer wählt ein Gerät aus (Vendor-ID als Filter)
const [device] = await navigator.hid.requestDevice({
filters: [{ vendorId: 0x046d }]
});
if (!device) return; // Dialog abgebrochen
await device.open();
console.log(`Geöffnet: ${device.productName}, opened=${device.opened}`);
});Input-Reports empfangen nach dem Öffnen
const connect = async (device) => {
if (!device.opened) {
await device.open();
}
device.addEventListener('inputreport', (event) => {
const { reportId, data } = event;
const bytes = new Uint8Array(data.buffer);
console.log(`Report ${reportId}:`, bytes);
});
};
// Bereits freigegebene Geräte ohne erneuten Dialog öffnen
const devices = await navigator.hid.getDevices();
if (devices.length > 0) await connect(devices[0]);Fehlerbehandlung und sauberes Schließen
const withDevice = async (device, task) => {
try {
await device.open();
} catch (err) {
console.error(`Öffnen fehlgeschlagen: ${err.name} – ${err.message}`);
return;
}
try {
await task(device);
} finally {
await device.close();
}
};
const [device] = await navigator.hid.getDevices();
if (device) {
await withDevice(device, async (d) => {
// Report-ID 0x01 mit zwei Datenbytes senden (z. B. LED an)
await d.sendReport(0x01, new Uint8Array([0xff, 0x00]));
console.log('Report gesendet');
});
}// Wichtig · Fallstricke
- Browser-Kompatibilität: WebHID gibt es nur in Chromium-basierten Desktop-Browsern (Chrome, Edge, Opera ab Version 89). Firefox und Safari unterstützen die API nicht. Vorher mit
'hid' in navigatorprüfen, ob sie vorhanden ist. - Sicherer Kontext: Die API funktioniert nur über HTTPS oder
localhost. In Cross-Origin-iframes muss die Permissions-Policyhiderlaubt sein. - Bereits geöffnet: Ruft man
open()auf einem schon geöffneten Gerät auf, wird das Promise mitInvalidStateErrorabgelehnt. Vorherdevice.openedprüfen. - Exklusiver Zugriff: Manche Betriebssysteme, vor allem Windows, oder andere Programme blockieren das Gerät. Dann schlägt
open()fehl. - Gesperrte Geräte: Tastaturen, Mäuse und FIDO-Sicherheitsschlüssel sind aus Sicherheitsgründen ganz oder teilweise gesperrt. Ihre geschützten Reports lassen sich nicht lesen.
- Trennen des Geräts: Wird das Gerät abgezogen, löst
navigator.hiddas Eventdisconnectaus, und die Verbindung ist ungültig. Nach dem erneuten Einstecken mussopen()noch einmal aufgerufen werden. - Nicht im Hauptthread von Service Workern verfügbar (Chrome ab Version 117 unterstützt WebHID in Extension-Service-Workern).