HIDDevice.close() — Methode · JavaScript-Referenz

Signatur

HIDDevice.prototype.close()

Beschreibung

Die Methode close() der HIDDevice-Schnittstelle aus der WebHID-API beendet eine zuvor mit open() hergestellte Verbindung zu einem HID-Gerät (Human Interface Device), etwa einem Gamepad, einem Barcode-Scanner, einem Makro-Keypad oder einem Gerät mit eigener Firmware. Danach ist device.opened wieder false.

Nach dem Schließen kann die Seite keine Reports mehr senden (sendReport(), sendFeatureReport()) oder empfangen (inputreport-Events). Die Berechtigung für das Gerät bleibt dabei erhalten: Mit open() lässt sich die Verbindung ohne erneuten Auswahldialog wiederherstellen. Soll auch die Berechtigung entzogen werden, verwendet man forget().

Man ruft close() auf, wenn die Kommunikation abgeschlossen ist, beim Verlassen der Seite, beim Wechsel auf ein anderes Gerät oder um das Gerät für andere Anwendungen bzw. Tabs freizugeben. Sauberes Schließen verhindert, dass das Gerät unnötig belegt bleibt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Verbindung geschlossen ist. Danach gilt device.opened === false.

Beispiele

Gerät öffnen, Report senden und wieder schließen

const connectButton = document.querySelector('#connect');

connectButton.addEventListener('click', async () => {
  // Auswahldialog – nur nach Nutzerinteraktion erlaubt
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: 0x046d }]
  });
  if (!device) return;

  await device.open();
  console.log('Geöffnet:', device.opened);

  // Beispiel-Report an Report-ID 1 senden
  await device.sendReport(0x01, new Uint8Array([0x10, 0xff]));

  await device.close();
  console.log('Geöffnet:', device.opened);
});

Geöffnet: true Geöffnet: false

Sicheres Schließen mit try/finally

const withDevice = async (device, task) => {
  if (!device.opened) await device.open();
  try {
    return await task(device);
  } finally {
    // Wird auch bei Fehlern ausgeführt
    if (device.opened) await device.close();
  }
};

const [device] = await navigator.hid.getDevices();
if (device) {
  await withDevice(device, async (d) => {
    const data = await d.receiveFeatureReport(0x02);
    console.log('Feature-Report-Länge:', data.byteLength);
  });
  console.log('Nach Abschluss geöffnet?', device.opened);
}

Feature-Report-Länge: 8 Nach Abschluss geöffnet? false

Listener entfernen und beim Verlassen der Seite schließen

const [device] = await navigator.hid.getDevices();

const onInput = (event) => {
  const { reportId, data } = event;
  console.log(`Report ${reportId}:`, new Uint8Array(data.buffer));
};

if (device) {
  await device.open();
  device.addEventListener('inputreport', onInput);

  window.addEventListener('pagehide', () => {
    device.removeEventListener('inputreport', onInput);
    // Promise kann hier nicht zuverlässig abgewartet werden
    device.close();
  });
}

// Wichtig · Fallstricke

Browser-Kompatibilität: WebHID ist nur in Chromium-Browsern (Chrome, Edge, Opera) ab Version 89 auf dem Desktop verfügbar. Firefox und Safari unterstützen die API nicht. Vorher mit 'hid' in navigator prüfen.
Die API steht nur in einem sicheren Kontext (HTTPS oder localhost) zur Verfügung und kann per Permissions-Policy (hid) für iframes gesperrt werden.
close() entzieht keine Berechtigung. Das Gerät erscheint weiterhin in navigator.hid.getDevices(). Zum Entziehen dient HIDDevice.forget().
Nach close() werfen sendReport() und ähnliche Methoden einen InvalidStateError. Vor dem Senden daher device.opened prüfen oder erneut open() aufrufen.
Laufende, noch nicht abgeschlossene Sende- oder Empfangsaufrufe können beim Schließen mit einem Fehler abgebrochen werden. Warte vor dem Schließen die offenen Promises ab.
Wird das Gerät physisch getrennt, wird es automatisch geschlossen und auf navigator.hid das Event disconnect ausgelöst. Ein zusätzliches close() ist dann nicht nötig.
Event-Listener für inputreport bleiben am Objekt registriert. Entferne sie selbst, um Speicherlecks und doppelte Handler nach einem erneuten open() zu vermeiden.

Siehe auch

HIDDevice HIDDevice.open() HIDDevice.forget() HIDDevice.opened HIDDevice.sendReport() HID.requestDevice() HID.getDevices()