SerialPort.forget() — Methode · JavaScript-Referenz

Signatur

SerialPort.prototype.forget()

Beschreibung

Mit forget() gibt eine Webanwendung eine Berechtigung für einen seriellen Port wieder ab, die der Nutzer ihr vorher über navigator.serial.requestPort() erteilt hat. Danach taucht der Port nicht mehr in navigator.serial.getPorts() auf. Will die Seite ihn wieder nutzen, muss der Nutzer ihn erneut im Auswahldialog freigeben.

Sinnvoll ist die Methode überall, wo man Nutzern eine „Gerät entfernen“- oder „Verbindung trennen und vergessen“-Funktion anbietet, etwa in Konfigurationstools für Mikrocontroller, 3D-Drucker oder Messgeräte. Auch aus Datenschutzsicht lohnt es sich, nicht mehr gebrauchte Berechtigungen aktiv zurückzugeben, statt sie dauerhaft gespeichert zu lassen.

Ist der Port zum Zeitpunkt des Aufrufs noch geöffnet, schließt der Browser ihn im Rahmen des Widerrufs. Trotzdem ist es sauberer, laufende Reader und Writer vorher selbst freizugeben und port.close() aufzurufen, damit keine Daten verloren gehen und keine Streams in einem undefinierten Zustand hängen bleiben.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Berechtigung für den Port widerrufen ist.

Beispiele

Freigegebenen Port wieder vergessen

// Muss innerhalb einer Nutzeraktion (z. B. Klick) aufgerufen werden
const connectBtn = document.querySelector('#connect');
const forgetBtn = document.querySelector('#forget');
let port;

connectBtn.addEventListener('click', async () => {
  port = await navigator.serial.requestPort();
  console.log('Port freigegeben:', port.getInfo());
});

forgetBtn.addEventListener('click', async () => {
  if (!port) return;
  await port.forget();
  console.log('Berechtigung widerrufen');
  port = undefined;
});

Port freigegeben: { usbVendorId: 9025, usbProductId: 67 } Berechtigung widerrufen

Verbindung sauber schließen und danach vergessen

const disconnectAndForget = async (port, reader) => {
  try {
    if (reader) {
      await reader.cancel();      // laufendes Lesen beenden
      reader.releaseLock();
    }
    if (port.readable || port.writable) {
      await port.close();         // Port ordentlich schließen
    }
  } finally {
    await port.forget();          // Berechtigung zurückgeben
  }
  const remaining = await navigator.serial.getPorts();
  console.log(`Noch freigegebene Ports: ${remaining.length}`);
};

Noch freigegebene Ports: 0

Alle gespeicherten Berechtigungen zurücksetzen (mit Feature-Erkennung)

const forgetAllPorts = async () => {
  if (!('serial' in navigator)) {
    console.warn('Web Serial API wird nicht unterstützt');
    return;
  }
  const ports = await navigator.serial.getPorts();
  const forgettable = ports.filter((p) => typeof p.forget === 'function');
  await Promise.all(forgettable.map((p) => p.forget()));
  console.log(`${forgettable.length} Port(s) vergessen`);
};

forgetAllPorts();

2 Port(s) vergessen

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Web Serial API gibt es nur in Chromium-basierten Desktop-Browsern (Chrome, Edge, Opera). forget() gibt es erst ab Chrome 103. Firefox und Safari unterstützen die API nicht. Prüfe deshalb vorher mit 'serial' in navigator und typeof port.forget === 'function'.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung. In iframes muss die Permissions Policy serial sie erlauben.
Nach forget() ist das SerialPort-Objekt nicht mehr brauchbar. Verwirf alle Referenzen darauf und hole für eine neue Verbindung mit requestPort() einen neuen Port.
Gesperrte Streams (aktive Reader oder Writer) solltest du vorher freigeben. Sonst kann das anschließende Schließen fehlschlagen oder noch gepufferte Daten gehen verloren.
Das Promise wird zurückgewiesen, wenn der Widerruf nicht möglich ist, etwa weil der Kontext zerstört wurde. Setze deshalb try/catch ein.

Siehe auch

SerialPort Serial.requestPort() Serial.getPorts() SerialPort.close() SerialPort.open() USBDevice.forget() KeyboardLayoutMap.get()