SerialPort: connect — Ereignis · JavaScript-Referenz

Signatur

serialPort.addEventListener("connect", handler)

Beschreibung

Das connect-Ereignis gehört zur Web Serial API. Es wird an einem SerialPort-Objekt ausgelöst, wenn das Gerät hinter diesem Port physisch bzw. logisch verfügbar wird – typischerweise wenn ein USB-Gerät eingesteckt wird oder ein Bluetooth-RFCOMM-Dienst erreichbar wird. Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften; über event.target erhält man den betroffenen SerialPort.

Das Ereignis steigt auf (bubbles) bis zu navigator.serial. Deshalb kann man es entweder direkt am Port abonnieren oder zentral an navigator.serial lauschen und so auf alle Ports reagieren, für die die Seite bereits eine Berechtigung besitzt. Alternativ steht die Handler-Eigenschaft onconnect zur Verfügung – sowohl am SerialPort als auch an Serial.

Wichtig: Das Ereignis wird nur für Ports gemeldet, für die der Nutzer der Seite schon einmal Zugriff gewährt hat (über navigator.serial.requestPort(); abrufbar mit navigator.serial.getPorts()). Ein fremdes, nie freigegebenes Gerät löst kein connect aus. Typischer Einsatz: automatisches Wiederverbinden nach dem Aus- und Einstecken eines Mikrocontrollers, Aktualisieren einer Geräteliste oder Statusanzeige in der Oberfläche.

Das Ereignis bedeutet nur, dass das Gerät verfügbar ist – der Port ist damit nicht geöffnet. Um Daten auszutauschen, muss weiterhin port.open({ baudRate }) aufgerufen werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"connect"`.
$handler Pflicht	(event: Event) => void		Callback, der ein einfaches `Event` erhält. `event.target` ist der verbundene `SerialPort`.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once`, `signal` oder `capture`.

Beispiele

Direkt am Port lauschen und automatisch öffnen

// Port wurde zuvor per Nutzergeste freigegeben
const [port] = await navigator.serial.getPorts();

if (port) {
  port.addEventListener('connect', async () => {
    console.log('Gerät wieder verbunden – öffne Port …');
    await port.open({ baudRate: 115200 });
    console.log('Port geöffnet');
  });
}

Gerät wieder verbunden – öffne Port … Port geöffnet

Zentral an navigator.serial lauschen (Bubbling)

const statusEl = document.querySelector('#status');

navigator.serial.addEventListener('connect', (event) => {
  const port = event.target; // der betroffene SerialPort
  const { usbVendorId, usbProductId } = port.getInfo();
  statusEl.textContent = `Verbunden: VID ${usbVendorId?.toString(16)} / PID ${usbProductId?.toString(16)}`;
});

navigator.serial.addEventListener('disconnect', () => {
  statusEl.textContent = 'Kein Gerät verbunden';
});

Verbunden: VID 2341 / PID 43

onconnect-Eigenschaft und Listener wieder entfernen

const [port] = await navigator.serial.getPorts();

// Variante 1: Handler-Eigenschaft (überschreibt vorherige Zuweisung)
port.onconnect = () => console.log('connect via onconnect');

// Variante 2: benannter Listener, später entfernbar
const onConnect = () => console.log('connect via Listener');
port.addEventListener('connect', onConnect);

// Aufräumen, z. B. beim Verlassen der Ansicht
const cleanup = () => {
  port.removeEventListener('connect', onConnect);
  port.onconnect = null;
};
cleanup();

Listener per AbortController entfernen

const controller = new AbortController();

navigator.serial.addEventListener('connect', (e) => {
  console.log('Neues Gerät bereit:', e.target.getInfo());
}, { signal: controller.signal });

// Später alle so registrierten Listener auf einmal abmelden
controller.abort();

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Desktop-Browser (Chrome/Edge/Opera ab 89); Firefox und Safari unterstützen die Web Serial API nicht. Vorher mit 'serial' in navigator prüfen.
Sicherer Kontext: Nur über HTTPS bzw. localhost verfügbar. In iframes muss die Permissions-Policy serial erlaubt sein.
Nur freigegebene Ports: connect feuert nur für Geräte, denen der Nutzer bereits Zugriff gewährt hat. Neue Geräte müssen zuerst über requestPort() (erfordert Nutzergeste) freigegeben werden.
Nicht geöffnet: Das Ereignis öffnet den Port nicht; open() muss separat aufgerufen werden. Ein erneuter open()-Aufruf auf einem bereits offenen Port wirft eine InvalidStateError-Ausnahme.
Beim Laden keine Meldung: Bereits beim Seitenaufruf angeschlossene Geräte lösen kein connect aus – diese über getPorts() abfragen.
Bubbling: Wer am Port und an navigator.serial lauscht, erhält das Ereignis doppelt; ggf. nur eine Stelle verwenden.

Siehe auch

SerialPort Serial Serial.requestPort() Serial.getPorts() SerialPort.open() EventTarget.addEventListener() SerialPort: disconnect