new HIDConnectionEvent() — Methode · JavaScript-Referenz

Signatur

new HIDConnectionEvent(type, options)

Beschreibung

Der Konstruktor HIDConnectionEvent() erzeugt ein Ereignisobjekt der WebHID-API. Normalerweise legt der Browser solche Objekte selbst an und löst sie auf navigator.hid aus, sobald ein freigegebenes HID-Gerät (z. B. Gamepad, Tastatur mit Sonderfunktionen, Barcode-Scanner, Stream-Deck) angeschlossen (connect) oder getrennt (disconnect) wird.

Selbst aufrufen muss man den Konstruktor nur selten. Nützlich ist das vor allem in Unit-Tests und beim Simulieren von Geräteereignissen: Man übergibt ein bereits vorhandenes HIDDevice und löst das Ereignis per dispatchEvent() auf einem eigenen EventTarget aus, um die Handler-Logik ohne echtes Ab- und Anstecken zu prüfen.

Das Wörterbuch options muss die Eigenschaft device enthalten, sonst wirft der Konstruktor einen TypeError. Zusätzlich werden die üblichen EventInit-Felder (bubbles, cancelable, composed) akzeptiert.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"connect"` oder `"disconnect"`. Zwischen Groß- und Kleinschreibung wird unterschieden.
$options Pflicht	HIDConnectionEventInit		Objekt mit der Pflicht-Eigenschaft `device` (ein `HIDDevice`) sowie den optionalen `EventInit`-Feldern `bubbles`, `cancelable` und `composed` (jeweils Standard `false`).

Rückgabewert

Typ

HIDConnectionEvent

Beschreibung

Ein neues HIDConnectionEvent, dessen schreibgeschützte Eigenschaft device auf das übergebene HIDDevice verweist.

Beispiele

Echte connect-/disconnect-Ereignisse empfangen

// Der Browser erzeugt die HIDConnectionEvent-Objekte selbst
navigator.hid.addEventListener('connect', (event) => {
  console.log(`Verbunden: ${event.device.productName}`);
});

navigator.hid.addEventListener('disconnect', (event) => {
  console.log(`Getrennt: ${event.device.productName}`);
});

Verbunden: USB Gamepad

Ereignis manuell erzeugen (z. B. für Tests)

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

if (device) {
  const event = new HIDConnectionEvent('connect', { device });
  console.log(event.type);                 // "connect"
  console.log(event.device === device);    // true
  console.log(event instanceof Event);     // true
}

connect true true

Geräteverwaltung ohne echtes Abstecken testen

class DeviceManager extends EventTarget {
  #devices = new Set();

  constructor() {
    super();
    this.addEventListener('connect', (e) => this.#devices.add(e.device));
    this.addEventListener('disconnect', (e) => this.#devices.delete(e.device));
  }

  get count() { return this.#devices.size; }
}

const manager = new DeviceManager();
const [device] = await navigator.hid.requestDevice({ filters: [] });

manager.dispatchEvent(new HIDConnectionEvent('connect', { device }));
console.log(manager.count); // 1

manager.dispatchEvent(new HIDConnectionEvent('disconnect', { device }));
console.log(manager.count); // 0

1 0

Fehlendes device führt zu TypeError

try {
  new HIDConnectionEvent('connect', {});
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Kompatibilität: WebHID ist experimentell und nur in Chromium-basierten Desktop-Browsern (Chrome/Edge/Opera ab 89) verfügbar. Firefox und Safari unterstützen die API nicht. Vorher mit 'hid' in navigator prüfen.
Sicherer Kontext: Verfügbar nur über HTTPS bzw. localhost. In iframes ist zusätzlich die Permissions-Policy hid nötig.
Ein gültiges HIDDevice lässt sich nicht selbst konstruieren. Man bekommt es nur über navigator.hid.requestDevice() (erfordert eine Nutzeraktion) oder navigator.hid.getDevices(). Fehlt device oder ist es kein HIDDevice, wird ein TypeError geworfen.
Selbst erzeugte Ereignisse haben isTrusted === false. Außerdem ändert ein manuell auf navigator.hid ausgelöstes Ereignis nichts am tatsächlichen Verbindungsstatus des Geräts.
In Web-Workern ist WebHID erst ab neueren Chromium-Versionen verfügbar (Dedicated Worker, Service Worker in Erweiterungen).

Siehe auch

HIDConnectionEvent HIDConnectionEvent.device HIDDevice HID EventTarget.prototype.dispatchEvent()