USBConnectionEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface USBConnectionEvent extends Event

Beschreibung

Die Schnittstelle USBConnectionEvent gehört zur WebUSB API. Ein solches Objekt wird ausgelöst, wenn der Browser erkennt, dass ein USB-Gerät angeschlossen (connect) oder getrennt (disconnect) wurde. Die Ereignisse treten am Objekt navigator.usb (Typ USB) auf. Die wichtigste Eigenschaft ist device, die schreibgeschützt das betroffene USBDevice liefert.

Gemeldet werden nur Geräte, für die die Seite bereits eine Berechtigung hat, also Geräte, die der Nutzer vorher über navigator.usb.requestDevice() freigegeben hat. Andere Geräte, die angeschlossen werden, lösen kein Ereignis aus. Deshalb eignet sich das Ereignis gut dafür, eine bestehende Verbindung wiederherzustellen, wenn ein bekanntes Gerät erneut eingesteckt wird, oder die Oberfläche anzupassen, wenn es entfernt wurde.

Man registriert die Handler entweder mit navigator.usb.addEventListener('connect', …) bzw. 'disconnect' oder über die Eigenschaften navigator.usb.onconnect und navigator.usb.ondisconnect. Einen eigenen Konstruktor new USBConnectionEvent(type, init) gibt es ebenfalls. Er ist aber vor allem für Tests oder zum Simulieren von Ereignissen nützlich.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Nur beim Konstruktor: Name des Ereignisses, üblicherweise `"connect"` oder `"disconnect"`.
$options Pflicht	USBConnectionEventInit	Nur beim Konstruktor: Objekt, das zusätzlich zu den `EventInit`-Feldern (`bubbles`, `cancelable`, `composed`) das Pflichtfeld `device` (`USBDevice`) enthält.
$device	USBDevice	Schreibgeschützte Eigenschaft der Instanz: das USB-Gerät, das angeschlossen oder getrennt wurde.

Rückgabewert

Typ

USBConnectionEvent

Beschreibung

Der Konstruktor gibt ein neues USBConnectionEvent zurück. Im Handler bekommt man die Instanz als Parameter und liest das Gerät über event.device aus.

Beispiele

Anschließen und Trennen mit addEventListener überwachen

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

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

Verbunden: Arduino Uno (VID 0x2341) Getrennt: Arduino Uno

Bekanntes Gerät nach erneutem Einstecken automatisch öffnen (on-Property)

const VENDOR_ID = 0x2341;
let activeDevice = null;

navigator.usb.onconnect = async ({ device }) => {
  if (device.vendorId !== VENDOR_ID) return;
  try {
    await device.open();
    if (device.configuration === null) {
      await device.selectConfiguration(1);
    }
    await device.claimInterface(0);
    activeDevice = device;
    console.log('Gerät bereit:', device.serialNumber);
  } catch (err) {
    console.error('Öffnen fehlgeschlagen:', err);
  }
};

navigator.usb.ondisconnect = ({ device }) => {
  if (device === activeDevice) {
    activeDevice = null;
    console.log('Aktives Gerät wurde entfernt.');
  }
};

Gerät bereit: 85736323838351F0E1B1 Aktives Gerät wurde entfernt.

Listener wieder entfernen

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

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

// Später, z. B. beim Verlassen der Ansicht:
navigator.usb.removeEventListener('disconnect', onDisconnect);
// bzw. bei Nutzung der Property:
navigator.usb.ondisconnect = null;

Ereignis zu Testzwecken selbst erzeugen

const [device] = await navigator.usb.getDevices();
if (device) {
  const evt = new USBConnectionEvent('connect', { device });
  console.log(evt.type, evt.device === device);
}

connect true

// Wichtig · Fallstricke

Browser-Kompatibilität: WebUSB gibt es nur in Chromium-Browsern (Chrome und Edge ab Version 61, Opera, Chrome für Android). Firefox und Safari unterstützen die API nicht. Prüfe deshalb vorher mit 'usb' in navigator, ob sie verfügbar ist.
Sicherer Kontext: Die API funktioniert nur über HTTPS oder localhost. Außerdem kann eine Permissions-Policy (usb) sie blockieren, zum Beispiel in iframes ohne allow="usb".
Nur freigegebene Geräte: connect und disconnect werden nur für Geräte ausgelöst, die der Nutzer der Herkunft (Origin) vorher über requestDevice() freigegeben hat. Um ein Gerät zum ersten Mal zu koppeln, ist immer eine Nutzeraktion nötig, etwa ein Klick.
Nach einem disconnect ist das USBDevice nicht mehr nutzbar. Laufende Übertragungen schlagen dann fehl, meist mit NetworkError. Wird das Gerät erneut angeschlossen, entsteht in der Regel ein neues USBDevice-Objekt. Vergleiche Geräte deshalb besser über vendorId, productId und serialNumber als über die Objektidentität.
Die API ist auch in Dedicated Workern verfügbar, dort allerdings ohne requestDevice().
In Chrome können Seiten mit device.forget() eine Berechtigung selbst wieder zurückgeben. Danach kommen für dieses Gerät keine Ereignisse mehr.

Siehe auch

USB USBDevice Event HIDConnectionEvent MIDIConnectionEvent