Signatur
Beschreibung
Der Konstruktor USBConnectionEvent() erzeugt ein Ereignisobjekt der WebUSB API. Solche Ereignisse löst der Browser normalerweise selbst auf navigator.usb aus: connect, wenn ein freigegebenes USB-Gerät angeschlossen wird, und disconnect, wenn es getrennt wird. Die Eigenschaft event.device enthält das betroffene USBDevice.
Selbst aufrufen muss man den Konstruktor nur selten. Praktisch ist er vor allem für Tests (Verbindungsereignisse simulieren, ohne Hardware anzuschließen) und für eigene Ereignis-Busse, die Verbindungsänderungen im Format der WebUSB API weitergeben sollen.
Das Wörterbuch options muss die Eigenschaft device mit einem echten USBDevice enthalten. Ein solches Objekt erhältst du nur über navigator.usb.requestDevice() oder navigator.usb.getDevices(). Wenn du ein eigenes Ereignis mit dispatchEvent() auslöst, vertrauenswürdig ist es trotzdem nicht: event.isTrusted ist false.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, üblich sind "connect" oder "disconnect". Groß- und Kleinschreibung wird beachtet. |
|
| $options Pflicht | USBConnectionEventInit | Wörterbuch mit der Pflicht-Eigenschaft device (ein USBDevice). Dazu kommen die üblichen EventInit-Felder bubbles, cancelable und composed (jeweils Standard false). |
Rückgabewert
USBConnectionEvent-Objekt. Seine schreibgeschützte Eigenschaft device verweist auf das übergebene USBDevice.Beispiele
Echte Verbindungsereignisse auf navigator.usb abhören
// Der Browser erzeugt USBConnectionEvent-Objekte selbst
navigator.usb.addEventListener('connect', (event) => {
const { productName, vendorId } = event.device;
console.log(`Angeschlossen: ${productName} (0x${vendorId.toString(16)})`);
});
navigator.usb.addEventListener('disconnect', (event) => {
console.log(`Getrennt: ${event.device.productName}`);
});Ereignis mit dem Konstruktor erzeugen und auslösen
const btn = document.querySelector('#verbinden');
btn.addEventListener('click', async () => {
// Braucht eine Benutzeraktion und einen sicheren Kontext (HTTPS)
const device = await navigator.usb.requestDevice({ filters: [] });
const event = new USBConnectionEvent('connect', { device });
console.log(event.type, event.device === device, event.isTrusted);
// Eigene Listener auf navigator.usb auslösen
navigator.usb.dispatchEvent(event);
});Geräteliste in einem Test ohne Hardware aktualisieren
const bus = new EventTarget();
const geraete = new Set();
bus.addEventListener('connect', (e) => geraete.add(e.device));
bus.addEventListener('disconnect', (e) => geraete.delete(e.device));
// Ein bereits freigegebenes Gerät für die Simulation verwenden
const [device] = await navigator.usb.getDevices();
if (device) {
bus.dispatchEvent(new USBConnectionEvent('connect', { device }));
console.log('Nach connect:', geraete.size);
bus.dispatchEvent(new USBConnectionEvent('disconnect', { device }));
console.log('Nach disconnect:', geraete.size);
}// Wichtig · Fallstricke
- Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen es nicht. Vorher prüfen, z. B. mit
if ('usb' in navigator)odertypeof USBConnectionEvent !== 'undefined'. - Die API steht nur in sicheren Kontexten (HTTPS oder
localhost) zur Verfügung. Sie kann außerdem per Permissions-Policy (usb) gesperrt sein, etwa in iframes. - Fehlt
optionsoderoptions.device, oder istdevicekeinUSBDevice, wirft der Konstruktor einenTypeError. Ein eigenes Objekt als Ersatz für ein Gerät geht nicht. Für Tests ohne Hardware musst du den Konstruktor selbst nachbilden. - Selbst erzeugte Ereignisse haben
isTrusted === false. Außerdem wird dabei kein Gerät wirklich verbunden oder getrennt. - Das
disconnect-Ereignis kommt nur für Geräte, die die Seite bereits freigegeben bekommen hat. Nach dem Trennen ist dasUSBDevicenicht mehr nutzbar. - In Web Workern ist WebUSB nur teilweise verfügbar. In Service Workern gibt es die API nur für Chrome-Erweiterungen.