HID.getDevices() — Methode · JavaScript-Referenz

Signatur

HID.prototype.getDevices()

Beschreibung

Die Methode getDevices() gehört zur Schnittstelle HID, die über navigator.hid erreichbar ist. Sie gibt ein Promise zurück, das mit einem Array von HIDDevice-Objekten erfüllt wird. Das Array enthält nur Geräte, die gerade angeschlossen sind und für die der Benutzer der aktuellen Herkunft (Origin) schon einmal den Zugriff erlaubt hat, meist über den Auswahldialog von navigator.hid.requestDevice().

Typischerweise ruft man getDevices() beim Laden der Seite auf, um schon freigegebene Geräte (z. B. Gamepads, Barcode-Scanner, Stream-Decks oder Makro-Tastaturen) ohne erneuten Dialog wieder zu verbinden. Im Gegensatz zu requestDevice() braucht die Methode keine Benutzeraktivierung (Klick o. Ä.) und zeigt keinen Dialog an.

Die zurückgegebenen Geräte sind zunächst nicht geöffnet. Bevor man Reports senden oder empfangen kann, muss man device.open() aufrufen und device.opened prüfen. Ein Gerät mit mehreren HID-Schnittstellen (Top-Level-Collections) kann als mehrere HIDDevice-Einträge erscheinen.

Rückgabewert

Typ

Promise<HIDDevice[]>

Beschreibung

Ein Promise, das mit einem Array von HIDDevice-Objekten erfüllt wird. Ist kein freigegebenes Gerät angeschlossen, ist das Array leer ([]).

Beispiele

Freigegebene Geräte beim Seitenstart auflisten

const listDevices = async () => {
  if (!('hid' in navigator)) {
    console.log('WebHID wird von diesem Browser nicht unterstützt.');
    return;
  }
  const devices = await navigator.hid.getDevices();
  if (devices.length === 0) {
    console.log('Keine freigegebenen HID-Geräte verbunden.');
    return;
  }
  for (const device of devices) {
    console.log(`${device.productName} (VID 0x${device.vendorId.toString(16)}, PID 0x${device.productId.toString(16)})`);
  }
};

listDevices();

Stream Deck MK.2 (VID 0xfd9, PID 0x80)

Bekanntes Gerät automatisch wieder verbinden, sonst Dialog anbieten

const VENDOR_ID = 0x057e; // Beispiel: Nintendo
const PRODUCT_ID = 0x2009; // Beispiel: Switch Pro Controller

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

const openDevice = async (device) => {
  if (!device.opened) await device.open();
  device.addEventListener('inputreport', (event) => {
    console.log('Report', event.reportId, new Uint8Array(event.data.buffer));
  });
  console.log('Verbunden mit', device.productName);
};

// 1. Ohne Dialog: bereits freigegebene Geräte prüfen
const devices = await navigator.hid.getDevices();
const known = devices.find(
  (d) => d.vendorId === VENDOR_ID && d.productId === PRODUCT_ID
);

if (known) {
  await openDevice(known);
} else {
  // 2. Mit Dialog: erfordert Benutzeraktivierung (Klick)
  connectButton.addEventListener('click', async () => {
    const [device] = await navigator.hid.requestDevice({
      filters: [{ vendorId: VENDOR_ID, productId: PRODUCT_ID }]
    });
    if (device) await openDevice(device);
  });
}

Verbunden mit Pro Controller

Geräteliste bei connect/disconnect aktuell halten

const renderList = async () => {
  const devices = await navigator.hid.getDevices();
  const list = document.querySelector('#device-list');
  list.replaceChildren(
    ...devices.map((d) => {
      const li = document.createElement('li');
      li.textContent = `${d.productName} ${d.opened ? '(geöffnet)' : ''}`;
      return li;
    })
  );
};

navigator.hid.addEventListener('connect', renderList);
navigator.hid.addEventListener('disconnect', renderList);
renderList();

// Wichtig · Fallstricke

Browser-Kompatibilität: WebHID gibt es nur in Chromium-Browsern auf dem Desktop (Chrome, Edge, Opera). Firefox und Safari unterstützen die API nicht. Deshalb vorher mit 'hid' in navigator prüfen.
Sicherer Kontext: Die API ist nur über HTTPS (oder localhost) verfügbar. In iframes muss die Permissions-Policy hid erlaubt sein, sonst wird das Promise mit einem SecurityError abgelehnt.
In Web Workern steht navigator.hid nur in Service Workern von Browser-Erweiterungen bzw. neueren Chromium-Versionen zur Verfügung, in normalen Dedicated Workern nicht.
Ein leeres Array ist kein Fehler: Entweder wurde noch keine Freigabe erteilt, das Gerät ist abgesteckt oder der Benutzer hat die Berechtigung (z. B. über device.forget() oder die Browser-Einstellungen) widerrufen.
Die Geräte sind nicht automatisch geöffnet. Vor sendReport() immer open() aufrufen, sonst gibt es einen InvalidStateError.
Manche Geräteklassen (z. B. Tastaturen und Mäuse mit geschützten Usages oder FIDO-Sicherheitsschlüssel) blockiert der Browser. Sie tauchen nicht oder nur mit eingeschränkten Collections auf.
Ein physisches Gerät kann mehrere HIDDevice-Einträge mit gleicher vendorId/productId erzeugen. Deshalb bei Bedarf zusätzlich device.collections auswerten.

Siehe auch

HID HID.requestDevice() HIDDevice HIDDevice.open() HIDDevice.forget() USB.getDevices()