USB: disconnect — Ereignis · JavaScript-Referenz

Signatur

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

Beschreibung

Das disconnect-Ereignis gehört zur WebUSB-API. Der Browser löst es am Objekt navigator.usb aus, sobald ein USB-Gerät vom System getrennt wird. Das kann durch Abziehen des Kabels, Ausschalten des Geräts oder einen Neustart der Firmware passieren. Der Handler bekommt ein USBConnectionEvent. Dessen Eigenschaft device verweist auf das betroffene USBDevice.

Das Ereignis kommt nur für Geräte an, für die die Seite bereits eine Berechtigung hat. Diese Berechtigung entsteht über navigator.usb.requestDevice() oder durch eine früher erteilte Freigabe, die navigator.usb.getDevices() liefert. Andere Geräte am System lösen kein Ereignis aus. So kann eine Seite nicht ausspähen, welche USB-Hardware angeschlossen ist.

Typische Einsätze:

Die Oberfläche aktualisieren, z. B. den Status auf „Gerät getrennt“ setzen.
Laufende Übertragungen abbrechen und Ressourcen freigeben.
Geräte aus einer internen Liste entfernen.

Das Gegenstück ist das Ereignis connect. Mit ihm kann eine Anwendung ein bekanntes Gerät automatisch wieder einbinden, wenn es erneut eingesteckt wird.

Einen Handler kann man auf zwei Arten registrieren: mit navigator.usb.addEventListener("disconnect", handler) oder über die Eigenschaft navigator.usb.ondisconnect = handler. Das Ereignis steigt nicht auf (kein Bubbling) und lässt sich nicht abbrechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier `"disconnect"`.
$handler Pflicht	(event: USBConnectionEvent) => void		Callback, das beim Trennen aufgerufen wird. `event.device` enthält das getrennte `USBDevice`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` zum späteren Entfernen über einen `AbortController`.

Rückgabewert

Typ

void

Beschreibung

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

Beispiele

Trennen eines Geräts protokollieren

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

Getrennt: Arduino Uno (VID 0x2341, PID 0x43)

Aktives Gerät verwalten und UI aktualisieren

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

document.querySelector('#connect').addEventListener('click', async () => {
  try {
    activeDevice = await navigator.usb.requestDevice({ filters: [{ vendorId: 0x2341 }] });
    await activeDevice.open();
    if (activeDevice.configuration === null) await activeDevice.selectConfiguration(1);
    await activeDevice.claimInterface(0);
    status.textContent = `Verbunden: ${activeDevice.productName}`;
  } catch (err) {
    console.error('Verbindung fehlgeschlagen:', err);
  }
});

navigator.usb.ondisconnect = ({ device }) => {
  // Objektidentität: dieselbe USBDevice-Instanz wie bei requestDevice()
  if (device === activeDevice) {
    activeDevice = null;
    status.textContent = 'Gerät getrennt – bitte erneut verbinden.';
  }
};

Listener mit AbortController wieder entfernen

const controller = new AbortController();

const onDisconnect = ({ device }) => {
  console.log('Getrennt:', device.serialNumber);
};

navigator.usb.addEventListener('disconnect', onDisconnect, { signal: controller.signal });

// Später, z. B. beim Verlassen der Ansicht:
controller.abort();
// Alternativ klassisch:
// navigator.usb.removeEventListener('disconnect', onDisconnect);

connect und disconnect für eine Geräteliste kombinieren

const devices = new Set(await navigator.usb.getDevices());
const render = () => console.log('Geräte:', [...devices].map(d => d.productName));

navigator.usb.addEventListener('connect', ({ device }) => {
  devices.add(device);
  render();
});

navigator.usb.addEventListener('disconnect', ({ device }) => {
  devices.delete(device);
  render();
});

render();

Geräte: [ 'Arduino Uno' ] Geräte: []

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern auf dem Desktop und unter Android, also Chrome, Edge und Opera. Firefox und Safari unterstützen die API nicht. Prüfe deshalb vorher mit 'usb' in navigator, ob sie vorhanden ist.
Nur sichere Kontexte: Die API funktioniert nur über HTTPS oder localhost. In Frames muss die Permissions-Policy usb sie erlauben.
Nur berechtigte Geräte: Das Ereignis kommt nur für Geräte, die der Nutzer freigegeben hat. Wer alle Geräte erkennen will, bekommt dafür kein Ereignis. Das ist so gewollt und schützt die Privatsphäre.
Offene Übertragungen: Beim Trennen werden laufende transferIn()/transferOut()-Promises mit einem NotFoundError oder NetworkError abgelehnt. Fange diese Fehler ab, statt dich allein auf das Ereignis zu verlassen.
Geräte vergleichen: Innerhalb einer Seite liefert der Browser für dasselbe physische Gerät dieselbe USBDevice-Instanz. Ein Vergleich mit === ist daher zuverlässig. Nach dem erneuten Einstecken kann aber ein neues Objekt entstehen. Zum Wiedererkennen eignen sich vendorId, productId und serialNumber.
Kein Worker-Support überall: In Dedicated Workern steht navigator.usb ab Chrome 96 zur Verfügung. In Service Workern gibt es die API nur eingeschränkt, nämlich in Erweiterungen.
Das Ereignis kommt nicht, wenn nur device.close() aufgerufen wird. Es signalisiert ausschließlich das physische bzw. logische Trennen des Geräts vom System.

Siehe auch

USB USB: connect USBConnectionEvent USBDevice USB.requestDevice() USB.getDevices() EventTarget.addEventListener()