HID — Schnittstelle · JavaScript-Referenz

Signatur

interface HID extends EventTarget

Beschreibung

Die Schnittstelle HID ist der Einstiegspunkt der WebHID-API. Sie ist nicht direkt instanziierbar, sondern wird über navigator.hid (im Fenster) bzw. self.navigator.hid (in Dedicated Workers und Service Workers von Erweiterungen) bereitgestellt. Mit ihr können Webanwendungen direkt mit Human Interface Devices sprechen, also etwa mit Gamepads, Stream-Decks, Barcode-Scannern, Headsets, LED-Controllern oder anderer Spezialhardware, für die es keine eigene Web-API gibt.

Wichtige Mitglieder:

requestDevice(options) – öffnet einen Browser-Dialog zur Geräteauswahl und gibt ein Promise<HIDDevice[]> zurück. Muss durch eine Nutzeraktion (z. B. einen Klick) ausgelöst werden.
getDevices() – liefert ein Promise<HIDDevice[]> mit allen Geräten, für die die Seite bereits eine Berechtigung hat und die aktuell angeschlossen sind.
connect-Event bzw. onconnect – wird ausgelöst, wenn ein freigegebenes Gerät angeschlossen wird.
disconnect-Event bzw. ondisconnect – wird ausgelöst, wenn ein freigegebenes Gerät getrennt wird.

Typischer Ablauf: Beim Laden der Seite mit getDevices() nach bekannten Geräten suchen; falls keines vorhanden ist, einen Button anbieten, der requestDevice() mit passenden Filtern (vendorId, productId, usagePage, usage) aufruft. Das erhaltene HIDDevice wird mit open() geöffnet; anschließend kommuniziert man über sendReport(), sendFeatureReport() und das inputreport-Event.

Parameter

Name	Typ	Default	Beschreibung
$options.filters Pflicht	Array<{vendorId?: number, productId?: number, usagePage?: number, usage?: number}>		Für `requestDevice()`: Liste von Filtern; ein Gerät wird angezeigt, wenn es mindestens einen Filter erfüllt. Ein leeres Array zeigt alle Geräte an.
$options.exclusionFilters	Array<{vendorId?: number, productId?: number, usagePage?: number, usage?: number}>	[]	Für `requestDevice()`: Geräte, die einen dieser Filter erfüllen, werden aus der Auswahl ausgeschlossen (Chrome 114+).

Rückgabewert

Typ

HID

Beschreibung

Das Objekt navigator.hid. requestDevice() und getDevices() liefern jeweils Promise<HIDDevice[]>.

Beispiele

Gerät per Klick anfordern und öffnen

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

button.addEventListener('click', async () => {
  if (!('hid' in navigator)) {
    console.warn('WebHID wird nicht unterstützt');
    return;
  }
  // Beispiel: Filter auf Hersteller-ID (hier Logitech 0x046d)
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: 0x046d }]
  });
  if (!device) {
    console.log('Kein Gerät ausgewählt');
    return;
  }
  await device.open();
  console.log(`Verbunden: ${device.productName}`);

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

Verbunden: USB Receiver Report 1: Uint8Array(8) [...]

Bereits freigegebene Geräte beim Start laden

const init = async () => {
  const devices = await navigator.hid.getDevices();
  if (devices.length === 0) {
    console.log('Noch keine Berechtigung – bitte Gerät auswählen');
    return;
  }
  for (const device of devices) {
    console.log(device.productName, device.vendorId.toString(16), device.productId.toString(16));
  }
};

init();

Stream Deck 0fd9 60

Verbindungsereignisse überwachen

const onConnect = ({ device }) => {
  console.log(`Angeschlossen: ${device.productName}`);
};

navigator.hid.addEventListener('connect', onConnect);

// Alternative über die on-Property
navigator.hid.ondisconnect = ({ device }) => {
  console.log(`Getrennt: ${device.productName}`);
};

// Später wieder abmelden
const stop = () => {
  navigator.hid.removeEventListener('connect', onConnect);
  navigator.hid.ondisconnect = null;
};

Angeschlossen: Stream Deck Getrennt: Stream Deck

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Desktop-Browser (Chrome/Edge/Opera ab 89). Firefox und Safari unterstützen WebHID nicht; auch mobil (Android) nicht verfügbar. Immer per 'hid' in navigator prüfen.
Sicherer Kontext: Nur über HTTPS (oder localhost) verfügbar. In iframes ist die Permissions-Policy hid erforderlich (allow="hid").
Nutzeraktion erforderlich: requestDevice() wirft einen SecurityError, wenn es nicht in einem Klick- o. ä. Handler aufgerufen wird.
Gesperrte Geräte: Tastaturen, Mäuse und sicherheitsrelevante Geräte (z. B. FIDO-Sicherheitsschlüssel) sind per Blockliste ausgeschlossen bzw. ihre Top-Level-Collections werden verborgen.
connect/disconnect feuern nur für Geräte, für die die Seite bereits eine Berechtigung hat. Berechtigungen lassen sich mit HIDDevice.forget() wieder entziehen.
Ein Gerät kann nur von einem Prozess gleichzeitig geöffnet sein; wenn native Treiber/Programme es exklusiv beanspruchen, schlägt open() fehl.

Siehe auch

USB Serial CSS File GPU