USB: connect — Ereignis · JavaScript-Referenz

Signatur

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

Beschreibung

Das connect-Ereignis des USB-Interfaces (erreichbar über navigator.usb) wird ausgelöst, sobald ein USB-Gerät angeschlossen wird, das der Nutzer der Website zuvor über navigator.usb.requestDevice() freigegeben hat. Geräte ohne erteilte Berechtigung lösen kein Ereignis aus. So bleibt die Privatsphäre gewahrt: Seiten können nicht beliebige angeschlossene Hardware beobachten.

Der Handler bekommt ein USBConnectionEvent. Dessen Eigenschaft device enthält das betroffene USBDevice-Objekt. Direkt nach dem Ereignis ist das Gerät noch nicht geöffnet. Du musst also zuerst device.open(), danach selectConfiguration() und schließlich claimInterface() aufrufen, bevor du Daten übertragen kannst.

Den Handler kannst du auf zwei Arten registrieren: mit navigator.usb.addEventListener("connect", handler) oder über die Eigenschaft navigator.usb.onconnect = handler. Typischerweise nutzt man das Ereignis zusammen mit disconnect. Damit hält man eine Liste verfügbarer Geräte aktuell oder stellt eine unterbrochene Verbindung automatisch wieder her, etwa bei Mikrocontrollern, Messgeräten oder Hardware-Token.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, hier `"connect"`.
$handler Pflicht	(event: USBConnectionEvent) => void		Callback-Funktion. Sie bekommt ein `USBConnectionEvent`, dessen Eigenschaft `event.device` das angeschlossene `USBDevice` enthält.
$options	boolean\|AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Daten stehen im übergebenen USBConnectionEvent.

Beispiele

Angeschlossenes Gerät erkennen und öffnen

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

    // Gerät für die Kommunikation vorbereiten
    await device.open();
    if (device.configuration === null) {
      await device.selectConfiguration(1);
    }
    await device.claimInterface(0);
    console.log('Gerät bereit');
  });
} else {
  console.warn('WebUSB wird von diesem Browser nicht unterstützt.');
}

Verbunden: Arduino Leonardo (VID 0x2341) Gerät bereit

Geräteliste mit onconnect und ondisconnect aktuell halten

const devices = new Set();

const render = () => {
  console.log('Verfügbare Geräte:', [...devices].map((d) => d.productName));
};

// Bereits freigegebene und angeschlossene Geräte beim Start laden
const init = async () => {
  for (const d of await navigator.usb.getDevices()) devices.add(d);
  render();
};

navigator.usb.onconnect = ({ device }) => {
  devices.add(device);
  render();
};

navigator.usb.ondisconnect = ({ device }) => {
  devices.delete(device);
  render();
};

init();

Verfügbare Geräte: [] Verfügbare Geräte: ['Arduino Leonardo']

Listener per AbortController wieder entfernen

const controller = new AbortController();

const onConnect = (event) => {
  console.log('Neues Gerät:', event.device.serialNumber);
};

navigator.usb.addEventListener('connect', onConnect, { signal: controller.signal });

// Später, z. B. beim Verlassen der Ansicht:
controller.abort();
// alternativ: navigator.usb.removeEventListener('connect', onConnect);

Neues Gerät: 85736323838351F0B0E1

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, ab Chrome 61). Firefox und Safari unterstützen die API nicht. Prüfe daher vorher mit 'usb' in navigator.
Nur für freigegebene Geräte: Das Ereignis kommt nur für Geräte, denen der Nutzer zuvor über requestDevice() den Zugriff erlaubt hat. requestDevice() braucht eine Nutzeraktion, zum Beispiel einen Klick.
Sicherer Kontext: Die API ist nur unter HTTPS oder localhost verfügbar. In iframes muss sie per Permissions Policy (allow=\"usb\") erlaubt sein.
Das Gerät ist beim Ereignis noch geschlossen. Vor transferIn() oder transferOut() musst du open() und claimInterface() aufrufen.
Geräte, die das Betriebssystem bereits belegt (z. B. Tastaturen, Massenspeicher), sind durch eine Blockliste geschützt und über WebUSB nicht nutzbar.
In Workern (z. B. Service Worker in Erweiterungen) ist die Verfügbarkeit eingeschränkt. Das Ereignis wird nur ausgelöst, solange die Seite geöffnet ist.

Siehe auch

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