Navigator.hid — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.hid

Beschreibung

navigator.hid ist der Einstieg in die WebHID-API. Das zurückgegebene HID-Objekt (ein EventTarget) enthält die Methoden requestDevice() und getDevices() sowie die Ereignisse connect und disconnect. Damit kann eine Webanwendung direkt mit Human Interface Devices kommunizieren, also etwa mit Spezial-Gamepads, Makro-Tastaturen, Stream-Decks, Barcode-Scannern oder Messgeräten, für die es keinen passenden Standardtreiber im Browser gibt.

Typischer Ablauf: Zuerst prüft man per Feature-Erkennung ('hid' in navigator), ob die API vorhanden ist. Danach fordert man mit navigator.hid.requestDevice() nach einer Nutzergeste (z. B. Klick) die Freigabe eines Geräts an. Bereits erlaubte Geräte ruft man bei späteren Besuchen mit getDevices() ab, ohne erneut nachzufragen. Das Gerät wird mit HIDDevice.open() geöffnet; Daten liest man über das Ereignis inputreport und sendet sie mit sendReport().

Die Eigenschaft ist nur in einem sicheren Kontext (HTTPS oder localhost) vorhanden und kann per Permissions-Policy (hid) für eingebettete Frames gesperrt werden. Sie steht außerdem in dedizierten Workern und Service-Workern von Erweiterungen zur Verfügung (WorkerNavigator.hid, eingeschränkt).

Rückgabewert

Typ

HID

Beschreibung

Das HID-Objekt des aktuellen Browsing-Kontexts. In nicht unterstützenden Browsern ist die Eigenschaft nicht vorhanden (undefined).

Beispiele

Feature-Erkennung

if ('hid' in navigator) {
  console.log('WebHID wird unterstützt:', navigator.hid);
} else {
  console.log('WebHID ist in diesem Browser nicht verfügbar.');
}

WebHID wird unterstützt: HID {onconnect: null, ondisconnect: null}

Gerät per Klick anfordern und Eingaben lesen

const button = document.querySelector('#verbinden');

button.addEventListener('click', async () => {
  // Filter: nur Geräte eines bestimmten Herstellers (Beispiel: Nintendo)
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: 0x057e }]
  });
  if (!device) return console.log('Kein Gerät ausgewählt.');

  await device.open();
  console.log(`Verbunden mit: ${device.productName}`);

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

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

Bereits freigegebene Geräte abrufen und Verbindungen überwachen

const init = async () => {
  const devices = await navigator.hid.getDevices();
  devices.forEach((d) => console.log('Bekannt:', d.productName));

  navigator.hid.addEventListener('connect', ({ device }) => {
    console.log('Angeschlossen:', device.productName);
  });
  navigator.hid.addEventListener('disconnect', ({ device }) => {
    console.log('Getrennt:', device.productName);
  });
};

init();

Bekannt: Stream Deck Getrennt: Stream Deck

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-basierte Desktop-Browser (Chrome, Edge, Opera ab Version 89). Firefox und Safari unterstützen WebHID nicht; auf Android ist die API nicht verfügbar. Immer per 'hid' in navigator prüfen.
Sicherer Kontext & Nutzergeste: Nur unter HTTPS/localhost vorhanden. requestDevice() wirft einen SecurityError, wenn es nicht durch eine Nutzeraktion ausgelöst wird.
Permissions-Policy: In iframes muss allow="hid" gesetzt sein, sonst schlägt der Zugriff fehl.
Blockierte Geräte: Aus Sicherheitsgründen sind bestimmte Geräteklassen (z. B. Standard-Tastaturen und -Mäuse für Eingaben, FIDO-Sicherheitsschlüssel) gesperrt, um Keylogging und Umgehung von Authentifizierung zu verhindern.
Exklusiver Zugriff: Unter manchen Betriebssystemen kann ein Gerät nicht geöffnet werden, wenn bereits ein anderes Programm es beansprucht. Unter Linux sind ggf. udev-Regeln nötig.

Siehe auch

HID Navigator.usb Navigator.serial MediaStream.id Navigator.gpu