HID: connect — Ereignis · JavaScript-Referenz

Signatur

navigator.hid.addEventListener("connect", handler)

Beschreibung

Das connect-Ereignis der HID-Schnittstelle (erreichbar über navigator.hid) meldet, dass ein HID-Gerät (Human Interface Device, z. B. Gamepad, Tastatur mit Sonderfunktionen, Barcode-Scanner, Stream Deck) an das System angeschlossen wurde. Ausgelöst wird es aber nur für Geräte, für die die Seite bereits eine Berechtigung hat – also Geräte, die der Benutzer vorher über navigator.hid.requestDevice() freigegeben hat.

Der Handler bekommt ein HIDConnectionEvent. Dessen Eigenschaft device enthält das betreffende HIDDevice. Das Gerät ist zu diesem Zeitpunkt noch nicht geöffnet: Bevor du Reports senden oder empfangen kannst, musst du device.open() aufrufen.

Typischerweise nutzt man das Ereignis zusammen mit disconnect, damit eine Anwendung ein Gerät nach dem Ab- und Wiederanstecken automatisch neu verbindet, ohne dass der Benutzer erneut die Geräteauswahl öffnen muss. Den Handler kannst du per addEventListener("connect", …) oder über die Eigenschaft navigator.hid.onconnect registrieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"connect"`.
$handler Pflicht	(event: HIDConnectionEvent) => void		Callback, das ein `HIDConnectionEvent` erhält; `event.device` ist das angeschlossene `HIDDevice`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignisobjekt ist ein HIDConnectionEvent mit der schreibgeschützten Eigenschaft device (HIDDevice).

Beispiele

Angeschlossene Geräte protokollieren und öffnen

const onConnect = async (event) => {
  const { device } = event;
  console.log(`Verbunden: ${device.productName} (VID 0x${device.vendorId.toString(16)}, PID 0x${device.productId.toString(16)})`);

  if (!device.opened) {
    await device.open();
  }
  device.addEventListener('inputreport', (e) => {
    console.log('Report', e.reportId, new Uint8Array(e.data.buffer));
  });
};

if ('hid' in navigator) {
  navigator.hid.addEventListener('connect', onConnect);
} else {
  console.warn('WebHID wird in diesem Browser nicht unterstützt.');
}

Verbunden: Stream Deck (VID 0xfd9, PID 0x60)

Variante mit onconnect-Eigenschaft und disconnect

navigator.hid.onconnect = ({ device }) => {
  console.log(`${device.productName} wieder angesteckt`);
};

navigator.hid.ondisconnect = ({ device }) => {
  console.log(`${device.productName} getrennt`);
};

// Handler wieder entfernen
const stopWatching = () => {
  navigator.hid.onconnect = null;
  navigator.hid.ondisconnect = null;
};

Stream Deck getrennt Stream Deck wieder angesteckt

Erst Berechtigung einholen, dann automatisch neu verbinden

const VENDOR_ID = 0x057e; // Beispiel: Nintendo
const controller = new AbortController();

// Muss aus einer Benutzeraktion heraus aufgerufen werden
document.querySelector('#pair').addEventListener('click', async () => {
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: VENDOR_ID }]
  });
  if (device) await device.open();
});

// Nur Geräte des gewünschten Herstellers behandeln
navigator.hid.addEventListener('connect', async ({ device }) => {
  if (device.vendorId !== VENDOR_ID) return;
  await device.open();
  console.log('Controller automatisch neu verbunden');
}, { signal: controller.signal });

// Später: Listener entfernen
// controller.abort();

Controller automatisch neu verbunden

// Wichtig · Fallstricke

Nur freigegebene Geräte: Für Geräte ohne Berechtigung wird kein connect ausgelöst. Beim ersten Mal musst du navigator.hid.requestDevice() aus einer Benutzeraktion (z. B. einem Klick) heraus aufrufen.
Gerät ist nicht geöffnet: event.device.opened ist zunächst false; vor sendReport() oder dem Empfang von inputreport ist open() nötig.
Bereits angeschlossene Geräte: Geräte, die beim Laden der Seite schon angesteckt sind, lösen kein connect aus – frage sie mit navigator.hid.getDevices() ab.
Kompatibilität: WebHID gibt es nur in Chromium-basierten Desktop-Browsern (Chrome/Edge/Opera ab 89). Firefox und Safari unterstützen es nicht. Prüfe also vorher mit 'hid' in navigator.
Sicherer Kontext: Die API funktioniert nur über HTTPS (oder localhost). In Cross-Origin-iframes kann sie über die Permissions Policy hid gesperrt sein. Ab Chrome 117 ist sie teilweise auch in Service Workern von Erweiterungen verfügbar.
Sperrliste: Manche sicherheitsrelevanten Geräte, z. B. FIDO-Sicherheitsschlüssel, blockiert der Browser. Auch Standardtastaturen und -mäuse bleiben gesperrt.

Siehe auch

HID: disconnect Element: mouseup USB: connect USB: disconnect SerialPort: connect