HID.requestDevice() — Methode · JavaScript-Referenz

Signatur

HID.prototype.requestDevice(options)

Beschreibung

Die Methode requestDevice() der Schnittstelle HID (erreichbar über navigator.hid) gehört zur WebHID-API. Mit ihr bittet eine Webanwendung den Nutzer um die Erlaubnis, auf ein Human Interface Device zuzugreifen – zum Beispiel auf Gamepads, Makro-Tastaturen, Stream-Decks, Barcodescanner oder spezielle Mess- und Steuergeräte, für die es keinen eigenen Browser-Treiber gibt.

Beim Aufruf zeigt der Browser eine Geräteauswahl an. Über das Pflichtfeld filters legst du fest, welche Geräte darin erscheinen, etwa anhand von vendorId, productId, usagePage und usage. Wählt der Nutzer ein Gerät aus, wird das Promise mit einem Array von HIDDevice-Objekten erfüllt. Bricht er ab, ist das Array leer – es wird also kein Fehler ausgelöst.

Die zurückgegebenen Geräte sind noch nicht geöffnet. Bevor du Reports senden oder empfangen kannst, musst du device.open() aufrufen. Die Erlaubnis bleibt gespeichert; bei späteren Besuchen erhältst du bereits freigegebene Geräte ohne Dialog über navigator.hid.getDevices().

Die Methode darf nur in einem sicheren Kontext (HTTPS) und nur als Reaktion auf eine Nutzeraktion aufgerufen werden, z. B. in einem click-Handler (transiente Nutzeraktivierung).

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Konfigurationsobjekt für die Geräteauswahl.
$options.filters Pflicht	Array<Object>		Liste von Filtern. Ein Gerät wird angezeigt, wenn es zu mindestens einem Filter passt. Jeder Filter kann `vendorId` (number), `productId` (number), `usagePage` (number) und `usage` (number) enthalten. Ein leeres Array `[]` zeigt alle verfügbaren Geräte an.
$options.exclusionFilters	Array<Object>	[]	Filter mit demselben Aufbau wie `filters`. Passende Geräte werden aus der Auswahl ausgeschlossen, z. B. bekannte fehlerhafte Firmware-Versionen (ab Chrome 114).

Rückgabewert

Typ

Promise<HIDDevice[]>

Beschreibung

Ein Promise, das mit einem Array der vom Nutzer ausgewählten HIDDevice-Objekte erfüllt wird. Bricht der Nutzer den Dialog ab, ist das Array leer. Bei einem Aufruf ohne Nutzeraktivierung oder in einem unsicheren Kontext wird das Promise mit einem SecurityError (DOMException) abgelehnt.

Beispiele

Nintendo Joy-Con per Klick anfordern und öffnen

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

connectButton.addEventListener('click', async () => {
  if (!('hid' in navigator)) {
    console.warn('WebHID wird von diesem Browser nicht unterstützt.');
    return;
  }

  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        { vendorId: 0x057e, productId: 0x2006 }, // Joy-Con (L)
        { vendorId: 0x057e, productId: 0x2007 }  // Joy-Con (R)
      ]
    });

    if (devices.length === 0) {
      console.log('Keine Auswahl getroffen.');
      return;
    }

    const [device] = devices;
    await device.open();
    console.log(`Verbunden mit: ${device.productName}`);
  } catch (err) {
    console.error('Zugriff fehlgeschlagen:', err.name, err.message);
  }
});

Verbunden mit: Joy-Con (R)

Nach Geräteklasse filtern (usagePage/usage) und Input-Reports lesen

// Usage Page 0x01 (Generic Desktop), Usage 0x05 = Gamepad
const gamepadFilter = { usagePage: 0x01, usage: 0x05 };

document.querySelector('#pick-gamepad').addEventListener('click', async () => {
  const [device] = await navigator.hid.requestDevice({
    filters: [gamepadFilter]
  });
  if (!device) return;

  await device.open();

  device.addEventListener('inputreport', (event) => {
    const { reportId, data } = event; // data ist ein DataView
    const bytes = new Uint8Array(data.buffer);
    console.log(`Report ${reportId}:`, bytes);
  });
});

Report 1: Uint8Array(8) [0, 128, 127, 0, 0, 0, 0, 0]

Bereits erlaubte Geräte wiederverwenden, sonst Dialog anzeigen

const VENDOR_ID = 0x0fd9; // Elgato

const getDevice = async () => {
  // Ohne Dialog: bereits freigegebene Geräte
  const known = await navigator.hid.getDevices();
  const match = known.find((d) => d.vendorId === VENDOR_ID);
  if (match) return match;

  // Mit Dialog (muss in einer Nutzeraktion laufen)
  const [picked] = await navigator.hid.requestDevice({
    filters: [{ vendorId: VENDOR_ID }],
    exclusionFilters: [{ vendorId: VENDOR_ID, productId: 0x0060 }] // altes Modell ausschließen
  });
  return picked ?? null;
};

document.querySelector('#connect').addEventListener('click', async () => {
  const device = await getDevice();
  if (!device) return console.log('Kein Gerät verfügbar.');
  if (!device.opened) await device.open();
  console.log(`Bereit: ${device.productName} (opened: ${device.opened})`);
});

Bereit: Stream Deck MK.2 (opened: true)

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Desktop-Browser (Chrome, Edge, Opera ab Version 89). Firefox und Safari unterstützen WebHID nicht, auf Android fehlt die API ebenfalls. Prüfe die Unterstützung vorab mit 'hid' in navigator.
Nutzeraktivierung erforderlich: Ohne vorherige Nutzeraktion (z. B. bei direktem Aufruf beim Laden der Seite) wird das Promise mit einem SecurityError abgelehnt. Vor dem Aufruf keine langen await-Ketten einbauen, sonst kann die Aktivierung ablaufen.
Abbruch ist kein Fehler: Schließt der Nutzer den Dialog, erhältst du ein leeres Array. Prüfe also immer devices.length.
Gesperrte Geräte: Standard-Tastaturen und -Mäuse sowie einige sicherheitskritische Geräte (z. B. FIDO-Sicherheitsschlüssel) werden vom Browser gesperrt oder nur eingeschränkt angeboten, damit keine Eingaben mitgeschnitten werden können.
Sicherer Kontext und Berechtigungsrichtlinie: Die API funktioniert nur über HTTPS. In iframes muss sie über allow="hid" freigegeben sein. In Web Workern ist requestDevice() nicht verfügbar (dort gibt es nur getDevices(), falls unterstützt).
Unter Linux können fehlende udev-Regeln verhindern, dass ein Gerät geöffnet werden kann, obwohl es im Dialog angezeigt wird.

Siehe auch

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