HIDConnectionEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface HIDConnectionEvent extends Event

Beschreibung

HIDConnectionEvent ist der Ereignistyp, den die WebHID API an die Handler für connect und disconnect übergibt. Die Ereignisse werden am Objekt navigator.hid ausgelöst, wenn ein HID-Gerät (z. B. Gamepad, Makro-Tastatur, Barcode-Scanner oder Streamdeck) angeschlossen oder getrennt wird. Das gilt nur für Geräte, für die die Seite bereits eine Berechtigung hat.

Die wichtigste Eigenschaft ist device (schreibgeschützt). Sie verweist auf das betroffene HIDDevice-Objekt. Damit kannst du ein wieder angeschlossenes Gerät automatisch öffnen, deine Oberfläche aktualisieren oder beim Trennen Ressourcen freigeben. Außerdem erbt die Schnittstelle alle Eigenschaften und Methoden von Event, zum Beispiel type, timeStamp und target.

Einen Handler registrierst du wahlweise mit navigator.hid.addEventListener("connect", handler) oder über die Eigenschaften navigator.hid.onconnect bzw. navigator.hid.ondisconnect. Mit dem Konstruktor new HIDConnectionEvent(type, options) erzeugst du ein Ereignis selbst. Das ist hauptsächlich für Tests sinnvoll, denn options.device muss ein echtes HIDDevice sein.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Name des Ereignisses (nur für den Konstruktor): `"connect"` oder `"disconnect"`.
$options Pflicht	object	Wörterbuch für die Initialisierung. Es enthält neben den üblichen `Event`-Optionen (`bubbles`, `cancelable`, `composed`) das Pflichtfeld `device`.
$options.device Pflicht	HIDDevice	Das Gerät, auf das sich das Ereignis bezieht. Später ist es über `event.device` abrufbar.

Rückgabewert

Typ

HIDConnectionEvent

Beschreibung

Der Konstruktor gibt ein neues HIDConnectionEvent zurück. Die Eigenschaft device (HIDDevice, schreibgeschützt) enthält das betroffene Gerät.

Beispiele

Anschließen und Trennen mit addEventListener überwachen

if ('hid' in navigator) {
  navigator.hid.addEventListener('connect', (event) => {
    const { productName, vendorId, productId } = event.device;
    console.log(`Verbunden: ${productName} (${vendorId.toString(16)}:${productId.toString(16)})`);
  });

  navigator.hid.addEventListener('disconnect', (event) => {
    console.log(`Getrennt: ${event.device.productName}`);
  });
} else {
  console.warn('WebHID wird von diesem Browser nicht unterstützt.');
}

Verbunden: Stream Deck Mini (fd9:63) Getrennt: Stream Deck Mini

Gerät nach erneutem Anschließen automatisch öffnen (on-Property)

const TARGET_VENDOR = 0x0fd9;

const handleReport = (e) => {
  console.log('Report', e.reportId, new Uint8Array(e.data.buffer));
};

navigator.hid.onconnect = async ({ device }) => {
  if (device.vendorId !== TARGET_VENDOR) return;
  if (!device.opened) await device.open();
  device.addEventListener('inputreport', handleReport);
  console.log(`${device.productName} ist bereit.`);
};

navigator.hid.ondisconnect = ({ device }) => {
  device.removeEventListener('inputreport', handleReport);
  console.log(`${device.productName} entfernt – Oberfläche wird zurückgesetzt.`);
};

Stream Deck Mini ist bereit.

Handler wieder entfernen

const onDisconnect = (event) => {
  console.log('Gerät weg:', event.device.productName);
};

navigator.hid.addEventListener('disconnect', onDisconnect);

// Später, z. B. beim Verlassen der Ansicht:
navigator.hid.removeEventListener('disconnect', onDisconnect);
// bzw. bei on-Properties:
navigator.hid.ondisconnect = null;

Ereignis in einem Test selbst erzeugen

const [device] = await navigator.hid.getDevices();
if (device) {
  const fakeEvent = new HIDConnectionEvent('connect', { device });
  navigator.hid.dispatchEvent(fakeEvent);
  console.log(fakeEvent.type, fakeEvent.device === device);
}

connect true

// Wichtig · Fallstricke

Browserunterstützung: Die API funktioniert nur in Chromium-Browsern auf dem Desktop (ab Chrome/Edge 89). Firefox und Safari unterstützen sie nicht, Android ebenfalls nicht. Prüfe deshalb vorher mit 'hid' in navigator.
Nur freigegebene Geräte: connect und disconnect werden nur für Geräte ausgelöst, für die die Seite schon eine Berechtigung hat. Diese erteilt der Nutzer über navigator.hid.requestDevice(). Unbekannte Geräte lösen kein Ereignis aus.
Sicherer Kontext: Die API ist nur über HTTPS (oder localhost) verfügbar. Eine Permissions Policy (hid) kann sie sperren, besonders in iframes. Ab Chrome 117 ist die API auch in Dedicated Workern nutzbar, wenn es die Freigaben schon gibt.
Nach einem disconnect ist das HIDDevice-Objekt geschlossen. Nach dem erneuten Anschließen musst du open() noch einmal aufrufen.
Ein Gerät mit mehreren HID-Schnittstellen kann mehrere HIDDevice-Objekte liefern und dadurch mehrere Ereignisse gleichzeitig auslösen.

Siehe auch

HID HIDDevice HIDInputReportEvent Event MIDIConnectionEvent