USBConfiguration.configurationName — Eigenschaft · JavaScript-Referenz

Signatur

USBConfiguration.configurationName

Beschreibung

Die schreibgeschützte Eigenschaft configurationName eines USBConfiguration-Objekts enthält den für Menschen lesbaren Namen einer USB-Konfiguration. Diesen Namen liefert das Gerät selbst über den String-Deskriptor, auf den das Feld iConfiguration im Konfigurationsdeskriptor verweist.

Nützlich ist die Eigenschaft vor allem, wenn ein Gerät mehrere Konfigurationen anbietet, etwa einen Normalbetrieb und einen Firmware-Update-Modus. Du kannst die Namen in einer Auswahlliste anzeigen oder in Diagnose-Tools protokollieren, bevor du mit USBDevice.selectConfiguration() eine Konfiguration aktivierst.

An USBConfiguration-Objekte kommst du über USBDevice.configuration (die aktive Konfiguration) oder über USBDevice.configurations (alle verfügbaren Konfigurationen). Viele Geräte haben für die Konfiguration keinen String-Deskriptor. Dann ist der Wert null. Verlass dich deshalb nie auf diesen Namen, um eine Konfiguration zu erkennen. Dafür ist configurationValue gedacht.

Rückgabewert

Typ

string | null

Beschreibung

Der vom Gerät gemeldete Name der Konfiguration oder null, wenn das Gerät keinen Namen angibt.

Beispiele

Namen der aktiven Konfiguration ausgeben

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
document.querySelector('#connect').addEventListener('click', async () => {
  const device = await navigator.usb.requestDevice({ filters: [] });
  await device.open();

  // Manche Geräte haben nach open() noch keine aktive Konfiguration
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }

  const name = device.configuration.configurationName ?? '(kein Name)';
  console.log(`Aktive Konfiguration: ${name}`);
});

Aktive Konfiguration: Default Configuration

Alle Konfigurationen eines Geräts auflisten

const listConfigurations = (device) =>
  device.configurations.map((config) => ({
    wert: config.configurationValue,
    name: config.configurationName ?? `Konfiguration ${config.configurationValue}`,
    interfaces: config.interfaces.length,
  }));

const devices = await navigator.usb.getDevices();
for (const device of devices) {
  console.log(device.productName);
  console.table(listConfigurations(device));
}

Mein USB-Gerät ┌─────┬──────┬───────────────┬────────────┐ │ idx │ wert │ name │ interfaces │ │ 0 │ 1 │ Normalbetrieb │ 2 │ │ 1 │ 2 │ DFU-Modus │ 1 │ └─────┴──────┴───────────────┴────────────┘

Auswahlliste für Konfigurationen erzeugen

const fillConfigSelect = (device, select) => {
  select.replaceChildren(
    ...device.configurations.map((config) => {
      const option = document.createElement('option');
      option.value = String(config.configurationValue);
      // textContent statt innerHTML, weil der Name vom Gerät kommt
      option.textContent = config.configurationName ?? `Konfiguration ${config.configurationValue}`;
      return option;
    })
  );

  select.addEventListener('change', async () => {
    await device.selectConfiguration(Number(select.value));
    console.log('Gewählt:', device.configuration.configurationName);
  });
};

// Wichtig · Fallstricke

Kann null sein: Viele Geräte melden keinen Konfigurationsnamen. Sieh immer einen Ersatzwert vor, z. B. mit ??.
Nicht zur Identifikation nutzen: Der Name ist frei wählbar, nicht eindeutig und kann je nach Firmware anders sein. Für selectConfiguration() nimmst du configurationValue.
Nicht vertrauenswürdige Eingabe: Der String kommt vom Gerät. Füge ihn per textContent ein und nicht per innerHTML, damit kein XSS entsteht.
Kompatibilität: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera) und nur in einem sicheren Kontext (HTTPS). Firefox und Safari unterstützen es nicht. Prüfe das vorher mit 'usb' in navigator. Seiten dürfen die API außerdem per Permissions-Policy usb sperren.
device.configuration kann vor dem Aufruf von selectConfiguration() null sein. Prüfe das, bevor du auf configurationName zugreifst.

Siehe auch

USBConfiguration USBConfiguration.configurationValue USBConfiguration.interfaces USBDevice.configuration USBDevice.configurations USBDevice.selectConfiguration() PerformanceScriptTiming.sourceFunctionName