USBDevice.forget() — Methode · JavaScript-Referenz

Signatur

USBDevice.prototype.forget()

Beschreibung

Die Methode forget() der Schnittstelle USBDevice widerruft die Berechtigung, die der Nutzer der Webseite zuvor über navigator.usb.requestDevice() erteilt hat. Das zurückgegebene Promise wird erfüllt, sobald alle ausstehenden Übertragungen abgebrochen, alle beanspruchten Schnittstellen freigegeben, die Gerätesitzung geschlossen und die Berechtigung entfernt wurde.

Danach taucht das Gerät nicht mehr in navigator.usb.getDevices() auf. Will die Seite es wieder nutzen, muss der Nutzer es erneut über den Auswahldialog freigeben. Das eignet sich vor allem für einen Button wie „Gerät entfernen“ oder „Verbindung vergessen“ in den Einstellungen einer Web-App. So hat der Nutzer die Kontrolle über seine Freigaben, ohne die Browsereinstellungen öffnen zu müssen.

Ein bloßes close() beendet dagegen nur die aktuelle Sitzung und behält die Berechtigung. Mit forget() ist die Freigabe dauerhaft weg. Zuerst close() aufzurufen ist nicht nötig, denn forget() schließt das Gerät selbst.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Sitzung geschlossen und die Berechtigung widerrufen wurde.

Beispiele

Berechtigung für alle freigegebenen Geräte widerrufen

// z. B. bei „Alle Geräte trennen“ in den Einstellungen
const forgetAllDevices = async () => {
  const devices = await navigator.usb.getDevices();
  for (const device of devices) {
    console.log(`Vergesse: ${device.productName}`);
    await device.forget();
  }
  const remaining = await navigator.usb.getDevices();
  console.log(`Verbleibende Geräte: ${remaining.length}`);
};

forgetAllDevices();

Vergesse: Arduino Uno Verbleibende Geräte: 0

Button „Gerät entfernen“ mit Funktionsprüfung

const removeButton = document.querySelector('#remove-device');
let currentDevice = null;

document.querySelector('#connect').addEventListener('click', async () => {
  currentDevice = await navigator.usb.requestDevice({
    filters: [{ vendorId: 0x2341 }]
  });
  await currentDevice.open();
  console.log('Verbunden mit', currentDevice.productName);
});

removeButton.addEventListener('click', async () => {
  if (!currentDevice) return;
  if (typeof currentDevice.forget !== 'function') {
    console.warn('forget() wird nicht unterstützt – nur close() möglich.');
    await currentDevice.close();
    return;
  }
  try {
    await currentDevice.forget();
    console.log('Berechtigung widerrufen.');
    currentDevice = null;
  } catch (err) {
    console.error('Fehler beim Vergessen:', err);
  }
});

Verbunden mit Arduino Uno Berechtigung widerrufen.

Ein bestimmtes Gerät anhand der Seriennummer vergessen

const forgetBySerial = async (serial) => {
  const devices = await navigator.usb.getDevices();
  const device = devices.find((d) => d.serialNumber === serial);
  if (!device) {
    console.log('Gerät nicht gefunden.');
    return false;
  }
  await device.forget();
  console.log(`Gerät ${serial} vergessen.`);
  return true;
};

forgetBySerial('85736323838351F0B0A1');

Gerät 85736323838351F0B0A1 vergessen.

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). forget() ist erst ab Version 101 verfügbar. Firefox und Safari unterstützen WebUSB nicht. Prüfe die Unterstützung vorab, z. B. mit 'usb' in navigator und typeof device.forget === 'function'.
Sicherer Kontext: Die API funktioniert nur über HTTPS oder localhost. Außerdem kann eine Permissions-Policy (usb) sie sperren, etwa in iframes.
Laufende Übertragungen wie transferIn() oder transferOut() werden abgebrochen, ihre Promises werden abgelehnt. Fange diese Fehler ab.
Nach forget() ist das USBDevice-Objekt nicht mehr nutzbar. Ein neuer Zugriff geht nur über einen neuen Aufruf von navigator.usb.requestDevice(), und der braucht eine Nutzergeste.
Die Methode gibt es auch in Web Workern (sofern WebUSB dort unterstützt wird).

Siehe auch

USBDevice USBDevice.close() USBDevice.open() USB.requestDevice() USB.getDevices() SerialPort.forget() HIDDevice.forget()