HIDDevice.opened — Eigenschaft · JavaScript-Referenz

Signatur

HIDDevice.opened

Beschreibung

Die Eigenschaft opened der Schnittstelle HIDDevice gehört zur WebHID-API. Sie zeigt an, ob die Seite gerade eine offene Verbindung zum Gerät hält. Nur dann lassen sich Reports mit sendReport(), sendFeatureReport() oder receiveFeatureReport() austauschen, und nur dann werden inputreport-Ereignisse ausgelöst.

Ein Gerät, das du über navigator.hid.requestDevice() oder navigator.hid.getDevices() bekommst, ist anfangs nicht geöffnet (opened === false). Erst wenn das Promise von device.open() erfüllt ist, wechselt der Wert auf true. Nach device.close(), device.forget() oder wenn das Gerät abgesteckt wird, ist er wieder false.

Typischerweise prüfst du opened vor einem Aufruf von open(). So vermeidest du einen InvalidStateError, den ein zweites open() auf einem schon geöffneten Gerät auslösen würde. Außerdem kannst du damit vor dem Senden sicherstellen, dass die Verbindung noch besteht.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Verbindung zum Gerät offen ist, sonst false.

Beispiele

Gerät auswählen und Verbindungsstatus prüfen

// Muss durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: 0x046d }] // Beispiel: Logitech
  });
  if (!device) return;

  console.log('Vor open():', device.opened);
  await device.open();
  console.log('Nach open():', device.opened);
});

Vor open(): false Nach open(): true

Sicheres Öffnen ohne InvalidStateError

const ensureOpen = async (device) => {
  if (!device.opened) {
    await device.open();
  }
  return device;
};

const [device] = await navigator.hid.getDevices();
if (device) {
  await ensureOpen(device);
  await ensureOpen(device); // zweiter Aufruf öffnet nicht erneut
  console.log(device.productName, 'offen:', device.opened);
}

<Produktname> offen: true

Report nur bei offener Verbindung senden und danach schließen

const sendCommand = async (device, reportId, bytes) => {
  if (!device.opened) {
    console.warn('Gerät ist nicht geöffnet – Senden abgebrochen.');
    return false;
  }
  await device.sendReport(reportId, new Uint8Array(bytes));
  return true;
};

const [device] = await navigator.hid.getDevices();
if (device) {
  await device.open();
  await sendCommand(device, 0x01, [0xff, 0x00, 0x00]);
  await device.close();
  console.log('Nach close():', device.opened);
}

Nach close(): false

// Wichtig · Fallstricke

Kompatibilität: WebHID gibt es nur in Chromium-basierten Desktop-Browsern (Chrome, Edge, Opera ab Version 89). Firefox und Safari unterstützen die API nicht. Prüfe die Unterstützung vorab mit 'hid' in navigator.
Sicherer Kontext: Die API ist nur über HTTPS (oder localhost) verfügbar. Mit der Permissions-Policy hid lässt sie sich zum Beispiel in iframes sperren.
opened ist schreibgeschützt. Eine Zuweisung wie device.opened = true hat keine Wirkung und öffnet keine Verbindung. Nutze dafür open().
Wird das Gerät physisch getrennt, wechselt opened auf false, und navigator.hid löst ein disconnect-Ereignis aus. Beim erneuten Einstecken musst du das Gerät neu öffnen.
Solange open() noch läuft, ist der Wert noch false. Warte also immer mit await auf das Promise, bevor du Reports sendest.
Manche Geräteklassen (z. B. Tastaturen, FIDO-Sicherheitsschlüssel) sperrt der Browser. Sie lassen sich gar nicht öffnen.

Siehe auch

HIDDevice HIDDevice.open() HIDDevice.close() HIDDevice.sendReport() HID.requestDevice() MediaDeviceInfo.deviceId