USBDevice.close() — Methode · JavaScript-Referenz

Signatur

USBDevice.prototype.close()

Beschreibung

close() ist das Gegenstück zu USBDevice.open(). Die Methode beendet die Sitzung, die Ihre Seite mit einem über WebUSB angebundenen Gerät geöffnet hat. Dabei gibt der Browser zuerst alle Schnittstellen frei, die mit claimInterface() beansprucht wurden, und schließt danach den Gerätezugriff. Andere Anwendungen oder Treiber des Betriebssystems können das Gerät dann wieder nutzen.

Rufen Sie close() auf, sobald Ihre Anwendung das Gerät nicht mehr braucht, zum Beispiel wenn der Nutzer auf „Trennen“ klickt, eine Übertragung fertig ist oder die Seite verlassen wird. Nach dem Schließen hat device.opened den Wert false. Übertragungen wie transferIn() oder controlTransferOut() sind erst nach einem erneuten open() wieder möglich.

Die Berechtigung für das Gerät bleibt nach close() bestehen. Das USBDevice-Objekt können Sie also später ohne neuen Auswahldialog wieder öffnen. Wenn Sie die Berechtigung vollständig entziehen wollen, verwenden Sie USBDevice.forget().

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald alle Schnittstellen freigegeben sind und die Sitzung beendet ist. Wenn das Schließen fehlschlägt (z. B. weil das Gerät getrennt wurde), wird es mit einer DOMException abgelehnt, etwa NotFoundError oder InvalidStateError.

Beispiele

Gerät öffnen, Daten senden und sauber schließen

const connectAndSend = async () => {
  // Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
  const device = await navigator.usb.requestDevice({
    filters: [{ vendorId: 0x2341 }]
  });

  await device.open();
  try {
    if (device.configuration === null) {
      await device.selectConfiguration(1);
    }
    await device.claimInterface(0);

    const data = new TextEncoder().encode('LED_ON');
    const result = await device.transferOut(1, data);
    console.log(`Gesendet: ${result.bytesWritten} Bytes`);
  } finally {
    // Gibt Schnittstelle 0 frei und beendet die Sitzung
    await device.close();
    console.log('Geöffnet?', device.opened);
  }
};

document.querySelector('#connect').addEventListener('click', connectAndSend);

Gesendet: 6 Bytes Geöffnet? false

Trennen-Button mit Fehlerbehandlung

let currentDevice = null;

const disconnect = async () => {
  if (!currentDevice?.opened) {
    console.log('Kein geöffnetes Gerät.');
    return;
  }
  try {
    await currentDevice.close();
    console.log(`${currentDevice.productName} getrennt.`);
  } catch (err) {
    // z. B. NotFoundError, wenn das Kabel schon gezogen wurde
    console.error(`Schließen fehlgeschlagen: ${err.name}`);
  } finally {
    currentDevice = null;
  }
};

document.querySelector('#disconnect').addEventListener('click', disconnect);

Arduino Uno getrennt.

Beim Verlassen der Seite alle Geräte schließen

const closeAllDevices = async () => {
  const devices = await navigator.usb.getDevices();
  const open = devices.filter((d) => d.opened);
  const results = await Promise.allSettled(open.map((d) => d.close()));
  console.log(`${results.filter((r) => r.status === 'fulfilled').length} von ${open.length} Geräten geschlossen`);
};

// pagehide ist zuverlässiger als unload
window.addEventListener('pagehide', () => {
  closeAllDevices();
});

2 von 2 Geräten geschlossen

// Wichtig · Fallstricke

Browser-Kompatibilität: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera), und zwar in Desktop-Versionen und Chrome für Android. Firefox und Safari unterstützen die API nicht. Prüfen Sie die Unterstützung vorher mit 'usb' in navigator.
Sicherer Kontext: Die API funktioniert nur über HTTPS oder localhost. In iframes muss die Permissions-Policy usb sie erlauben.
Laufende Übertragungen: Wenn Sie close() aufrufen, während noch Übertragungen laufen (z. B. ein wartendes transferIn()), werden diese abgebrochen und ihre Promises abgelehnt. Fangen Sie diese Fehler in Lese-Schleifen ab.
Kein Aufräumen beim Neuladen: Wenn Sie ein Gerät nicht schließen, gibt der Browser es spätestens beim Schließen des Tabs frei. Rufen Sie close() trotzdem ausdrücklich auf, am besten in einem finally-Block. So ist das Gerät sofort wieder für andere Programme frei.
Getrennte Geräte: Wenn das Gerät physisch abgezogen wurde, kann close() mit NotFoundError fehlschlagen. Reagieren Sie auf navigator.usb-Ereignisse vom Typ disconnect.
close() entzieht die Berechtigung nicht. Dafür gibt es forget().

Siehe auch

USBDevice.open() USBDevice.claimInterface() USBDevice.releaseInterface() USBDevice.forget() USBDevice.opened USB.requestDevice() USBDevice