Signatur
Beschreibung
Die Eigenschaft device eines HIDConnectionEvent verweist auf das HIDDevice-Objekt, dessen Verbindungsstatus sich geändert hat. Solche Ereignisse feuert navigator.hid, wenn ein Gerät, auf das die Seite bereits Zugriff hat, angeschlossen (connect) oder entfernt (disconnect) wird.
Brauchen tust du die Eigenschaft, um ein Gerät zu erkennen (etwa über vendorId, productId oder productName), es nach dem Wiederanschließen erneut mit open() zu öffnen oder beim Trennen den Zustand deiner Anwendung aufzuräumen.
Der Wert ist schreibgeschützt und wird beim Erzeugen des Ereignisses über das Initialisierungsobjekt ({ device }) festgelegt. Beim Ereignis disconnect ist das Gerät schon getrennt: Du kannst seine Metadaten noch lesen, aber keine Berichte mehr senden oder empfangen.
Rückgabewert
HIDDevice, das mit dem Ereignis verknüpft ist, mit Eigenschaften wie vendorId, productId, productName, opened und collections.Beispiele
Angeschlossene und getrennte Geräte protokollieren
if ('hid' in navigator) {
navigator.hid.addEventListener('connect', (event) => {
const { productName, vendorId, productId } = event.device;
console.log(`Verbunden: ${productName} (${vendorId.toString(16)}:${productId.toString(16)})`);
});
navigator.hid.addEventListener('disconnect', (event) => {
console.log(`Getrennt: ${event.device.productName}`);
});
} else {
console.warn('WebHID wird von diesem Browser nicht unterstützt.');
}Bekanntes Gerät nach dem Wiederanschließen automatisch öffnen
const ZIEL_VENDOR = 0x046d; // Beispiel: Logitech
const handleInputReport = (e) => {
console.log('Bericht', e.reportId, new Uint8Array(e.data.buffer));
};
navigator.hid.onconnect = async ({ device }) => {
if (device.vendorId !== ZIEL_VENDOR) return;
if (!device.opened) {
await device.open();
}
device.addEventListener('inputreport', handleInputReport);
console.log(`${device.productName} ist bereit.`);
};Beim Trennen den Anwendungszustand aufräumen
let aktivesGeraet = null;
const waehleGeraet = async () => {
const [device] = await navigator.hid.requestDevice({ filters: [] });
if (device) {
await device.open();
aktivesGeraet = device;
}
};
navigator.hid.addEventListener('disconnect', (event) => {
// Objekte vergleichen: dasselbe Gerät liefert dieselbe HIDDevice-Instanz
if (event.device === aktivesGeraet) {
aktivesGeraet = null;
console.log('Aktives Gerät wurde getrennt.');
}
});
document.querySelector('#verbinden')?.addEventListener('click', waehleGeraet);Ereignis synthetisch erzeugen (z. B. für Tests)
const [device] = await navigator.hid.getDevices();
if (device) {
const event = new HIDConnectionEvent('connect', { device });
console.log(event.device === device, event.type);
}// Wichtig · Fallstricke
- Browser-Kompatibilität: WebHID gibt es nur in Chromium-basierten Desktop-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen die API nicht. Prüfe deshalb immer vorher mit
'hid' in navigator. - Sicherer Kontext: Die API funktioniert nur über HTTPS (oder
localhost). Eine Permissions-Policy (hid) kann sie in iframes sperren. - Nur berechtigte Geräte:
connect/disconnectwerden nur für Geräte ausgelöst, für die der Nutzer der Seite schon perrequestDevice()Zugriff gegeben hat. Unbekannte Geräte lösen kein Ereignis aus. - Nach
disconnectistdevice.openedgleichfalse. Aufrufe wiesendReport()schlagen dann fehl. Nach dem Wiederanschließen musst du das Gerät erneut mitopen()öffnen. - Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. wirft im Strict Mode einen
TypeError. - In Chrome-Erweiterungen ist WebHID auch in Service Workers verfügbar (ab Chrome 117).