HIDDevice.productName — Eigenschaft · JavaScript-Referenz

Signatur

HIDDevice.productName

Beschreibung

Die Eigenschaft productName eines HIDDevice-Objekts enthält den Produktnamen, den das Gerät über seinen USB- bzw. Bluetooth-Produkt-String-Deskriptor meldet, z. B. "Joy-Con (L)" oder "USB Gaming Mouse". Sie ist schreibgeschützt und steht schon zur Verfügung, bevor das Gerät mit open() geöffnet wurde.

Am besten eignet sie sich für die Anzeige in der Oberfläche, etwa in einer Liste bereits freigegebener Geräte, in Statusmeldungen oder in Logs. Um ein Gerät eindeutig zu erkennen, sollte man dagegen vendorId und productId verwenden. Der Name ist ein frei wählbarer Text des Herstellers: Er kann bei verschiedenen Firmware-Versionen anders lauten, bei mehreren gleichen Geräten identisch sein oder ganz fehlen.

Ein HIDDevice erhält man über navigator.hid.requestDevice() (erfordert eine Nutzergeste), über navigator.hid.getDevices() für bereits erlaubte Geräte oder über die Events connect und disconnect.

Rückgabewert

Typ

string

Beschreibung

Der Produktname des Geräts. Meldet das Gerät keinen Namen, ist der Wert ein leerer String "".

Beispiele

Gerät auswählen und Namen anzeigen

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

button.addEventListener('click', async () => {
  // requestDevice erfordert eine Nutzergeste
  const [device] = await navigator.hid.requestDevice({
    filters: [{ vendorId: 0x057e }] // Nintendo
  });
  if (!device) return;
  console.log(`Ausgewählt: ${device.productName}`);
});

Ausgewählt: Joy-Con (L)

Freigegebene Geräte mit Ersatznamen auflisten

const hex = (n) => n.toString(16).padStart(4, '0');

const listDevices = async () => {
  const devices = await navigator.hid.getDevices();
  return devices.map((d) =>
    d.productName ||
    `Unbekanntes Gerät (${hex(d.vendorId)}:${hex(d.productId)})`
  );
};

listDevices().then(console.log);

["USB Gaming Mouse", "Unbekanntes Gerät (1234:abcd)"]

Verbinden und Trennen protokollieren

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

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

Verbunden: Joy-Con (L) Getrennt: Joy-Con (L)

// Wichtig · Fallstricke

Kompatibilität: Die WebHID-API gibt es nur in Chromium-Desktop-Browsern (Chrome, Edge, Opera ab Version 89). Firefox und Safari unterstützen sie nicht. Prüfen Sie die Verfügbarkeit vorher mit 'hid' in navigator.
Die API steht nur in einem sicheren Kontext (HTTPS oder localhost) zur Verfügung. In iframes wird sie nur mit der Permissions Policy hid freigeschaltet.
productName kann ein leerer String sein. Planen Sie deshalb einen Ersatznamen ein, zum Beispiel aus vendorId/productId.
Der Name ist nicht eindeutig: Zwei gleiche Geräte liefern denselben Wert. Für die Zuordnung sollten Sie das HIDDevice-Objekt selbst oder die IDs verwenden.
Der Text kommt vom Gerät. Fügen Sie ihn per textContent und nicht per innerHTML ins DOM ein, sonst droht XSS durch manipulierte Firmware.

Siehe auch

HIDDevice HIDDevice.vendorId HIDDevice.productId HIDDevice.opened HIDDevice.prototype.open() HID.prototype.requestDevice() HID.prototype.getDevices()