HID: disconnect — Ereignis · JavaScript-Referenz

Signatur

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

Beschreibung

Das disconnect-Ereignis der WebHID-API wird am globalen HID-Objekt (navigator.hid) ausgelöst, wenn ein HID-Gerät (Human Interface Device, z. B. Gamepad, Makro-Tastatur, Barcode-Scanner, USV) getrennt wird. Das kann ein abgezogenes USB-Kabel sein, ein Bluetooth-Gerät außer Reichweite oder ein Gerät, das sich selbst abmeldet. Das Ereignis ist vom Typ HIDConnectionEvent. Seine Eigenschaft device enthält das betroffene HIDDevice.

Gemeldet werden nur Geräte, für die die Seite bereits eine Berechtigung hat, also Geräte, die über navigator.hid.requestDevice() freigegeben wurden oder in navigator.hid.getDevices() auftauchen. Über andere angeschlossene Geräte erfährt die Seite aus Datenschutzgründen nichts.

In der Praxis nutzt man das Ereignis, um die Oberfläche anzupassen (z. B. „Gerät getrennt“ anzeigen), Verweise auf das HIDDevice zu löschen, laufende Abfragen oder inputreport-Listener zu beenden und sich auf ein späteres Wiederverbinden vorzubereiten. Das Gegenstück ist das Ereignis connect.

Den Listener registriert man entweder mit navigator.hid.addEventListener("disconnect", handler) oder über die Eigenschaft navigator.hid.ondisconnect = handler.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"disconnect"`.
$handler Pflicht	(event: HIDConnectionEvent) => void		Callback, der ein `HIDConnectionEvent` erhält. Über `event.device` erreicht man das getrennte `HIDDevice` (u. a. `vendorId`, `productId`, `productName`).
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }` zum Abmelden per `AbortController`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein HIDConnectionEvent mit der schreibgeschützten Eigenschaft device (HIDDevice).

Beispiele

Trennung mit addEventListener erkennen

if ('hid' in navigator) {
  navigator.hid.addEventListener('disconnect', (event) => {
    const { device } = event;
    console.log(`Getrennt: ${device.productName} (VID 0x${device.vendorId.toString(16)}, PID 0x${device.productId.toString(16)})`);
  });
} else {
  console.warn('WebHID wird in diesem Browser nicht unterstützt.');
}

Getrennt: USB Gamepad (VID 0x54c, PID 0x5c4)

Aktives Gerät aufräumen und Oberfläche aktualisieren

let activeDevice = null;
const status = document.querySelector('#status');

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

document.querySelector('#connect').addEventListener('click', async () => {
  const [device] = await navigator.hid.requestDevice({ filters: [{ vendorId: 0x054c }] });
  if (!device) return;
  await device.open();
  device.addEventListener('inputreport', onInputReport);
  activeDevice = device;
  status.textContent = `Verbunden: ${device.productName}`;
});

navigator.hid.addEventListener('disconnect', ({ device }) => {
  if (device !== activeDevice) return;
  device.removeEventListener('inputreport', onInputReport);
  activeDevice = null;
  status.textContent = 'Gerät getrennt – bitte erneut anschließen.';
});

on-Property nutzen und Listener per AbortController entfernen

// Variante 1: Event-Handler-Eigenschaft
navigator.hid.ondisconnect = (event) => {
  console.log('ondisconnect:', event.device.productName);
};

// Variante 2: Listener mit AbortSignal, später sauber abmelden
const controller = new AbortController();
navigator.hid.addEventListener('disconnect', (event) => {
  console.log('Listener:', event.device.productName);
}, { signal: controller.signal });

// z. B. beim Verlassen der Ansicht:
const teardown = () => {
  controller.abort();              // entfernt den addEventListener-Listener
  navigator.hid.ondisconnect = null; // entfernt den Property-Handler
};

ondisconnect: Macro Keypad Listener: Macro Keypad

Zusammen mit connect automatisch neu verbinden

const KNOWN = { vendorId: 0x046d, productId: 0xc52b };
const matches = (d) => d.vendorId === KNOWN.vendorId && d.productId === KNOWN.productId;

navigator.hid.addEventListener('disconnect', ({ device }) => {
  if (matches(device)) console.log('Empfänger entfernt, warte auf Wiederverbindung …');
});

navigator.hid.addEventListener('connect', async ({ device }) => {
  if (!matches(device)) return;
  if (!device.opened) await device.open();
  console.log('Wieder verbunden:', device.productName);
});

Empfänger entfernt, warte auf Wiederverbindung … Wieder verbunden: USB Receiver

// Wichtig · Fallstricke

Browser-Unterstützung: WebHID gibt es nur in Chromium-Browsern auf dem Desktop (Chrome, Edge, Opera ab 89). Firefox und Safari unterstützen die API nicht. Vorher mit 'hid' in navigator prüfen.
Sicherer Kontext: Die API steht nur unter HTTPS (oder localhost) zur Verfügung. Sie kann per Permissions-Policy hid gesperrt sein, z. B. in iframes ohne allow="hid".
Nur freigegebene Geräte: Das Ereignis kommt nur für Geräte, für die die Seite eine Berechtigung hat. Für beliebige angeschlossene Geräte wird es nicht ausgelöst.
Objekt-Identität: Nach einer Trennung ist das HIDDevice geschlossen (opened === false). Beim erneuten Anschließen kann ein neues HIDDevice-Objekt entstehen. Deshalb Geräte besser über vendorId/productId wiedererkennen als über die Objektreferenz.
Kein Ereignis am Gerät: disconnect wird an navigator.hid ausgelöst, nicht am HIDDevice selbst. Listener deshalb dort registrieren.
Auch HIDDevice.forget() kann zur Trennung führen. Ausstehende sendReport()-Promises werden bei der Trennung abgelehnt, sie sollten also mit try/catch abgesichert sein.
In Service Workern von Browser-Erweiterungen (Chrome 117+) steht navigator.hid ebenfalls zur Verfügung, in normalen Web-Workern dagegen nicht zuverlässig.

Siehe auch

HID HIDConnectionEvent HIDDevice HID.requestDevice() HID.getDevices() EventTarget.addEventListener() SerialPort: disconnect