USBConnectionEvent.device — Eigenschaft · JavaScript-Referenz

Signatur

USBConnectionEvent.device

Beschreibung

Die Eigenschaft device des Interfaces USBConnectionEvent enthält das USBDevice-Objekt, auf das sich ein connect- oder disconnect-Ereignis bezieht. Beide Ereignisse werden auf navigator.usb ausgelöst. Allerdings nur für Geräte, für die die Seite bereits eine Berechtigung hat, etwa über navigator.usb.requestDevice().

Die Eigenschaft wird vor allem gebraucht, um auf das Ein- und Ausstecken von Hardware zu reagieren. Beim connect-Ereignis kann man das Gerät sofort öffnen (device.open()) und konfigurieren. Beim disconnect-Ereignis kann man den eigenen Zustand aufräumen, zum Beispiel das Gerät aus einer Liste entfernen oder die Oberfläche aktualisieren.

Bei einem erneuten Anschluss derselben Hardware liefert der Browser eine neue USBDevice-Instanz. Getrennte Geräte vergleicht man deshalb am besten über die Objektidentität (für die aktuelle Sitzung) oder über Merkmale wie vendorId, productId und serialNumber.

Rückgabewert

Typ

USBDevice

Beschreibung

Das USBDevice-Objekt des angeschlossenen bzw. getrennten Geräts. Die Eigenschaft ist schreibgeschützt.

Beispiele

Angeschlossenes Gerät automatisch öffnen

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

  try {
    await device.open();
    if (device.configuration === null) {
      await device.selectConfiguration(1);
    }
    await device.claimInterface(0);
    console.log('Gerät bereit');
  } catch (err) {
    console.error('Öffnen fehlgeschlagen:', err);
  }
});

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

Getrenntes Gerät aus der Geräteliste entfernen

const devices = new Set(await navigator.usb.getDevices());

const onDisconnect = (event) => {
  if (devices.delete(event.device)) {
    console.log(`Getrennt: ${event.device.productName}`);
    console.log(`Noch verbunden: ${devices.size}`);
  }
};

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

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

Getrennt: Arduino Leonardo Noch verbunden: 0

Über die on-Eigenschaften und Gerätemerkmale filtern

const TARGET = { vendorId: 0x2341, productId: 0x8036 };

const matches = (device) =>
  device.vendorId === TARGET.vendorId && device.productId === TARGET.productId;

navigator.usb.onconnect = ({ device }) => {
  if (matches(device)) console.log('Zielgerät angeschlossen, Seriennummer:', device.serialNumber);
};

navigator.usb.ondisconnect = ({ device }) => {
  if (matches(device)) console.log('Zielgerät getrennt');
};

Zielgerät angeschlossen, Seriennummer: 8573530303135170C1B1

// Wichtig · Fallstricke

Nur Geräte mit Berechtigung: connect/disconnect werden nur für Geräte ausgelöst, die der Nutzer der Seite schon freigegeben hat. Unbekannte Geräte lösen keine Ereignisse aus.
Browser-Unterstützung: WebUSB gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen es nicht. Vorher prüfen: 'usb' in navigator.
Sicherer Kontext: Die API funktioniert nur über HTTPS (oder localhost) und kann per Permissions-Policy (usb) gesperrt sein, etwa in iframes.
Getrennte Geräte: Nach disconnect schlagen Aufrufe wie transferIn() auf event.device fehl. Laufende Übertragungen werden mit einem Fehler abgebrochen.
Neue Instanz beim erneuten Anschließen: Wird das Gerät erneut angeschlossen, liefert device ein neues Objekt. Alte Referenzen sollte man daher nicht weiterverwenden.
In Web Workern ist die API über WorkerNavigator.usb nur eingeschränkt verfügbar (Chrome, dedizierte Worker).

Siehe auch

USB HIDConnectionEvent.device MIDIConnectionEvent.port CompositionEvent.data CompositionEvent.locale