new USBConfiguration() — Methode · JavaScript-Referenz

Signatur

new USBConfiguration(device, configurationValue)

Beschreibung

Der Konstruktor USBConfiguration() gehört zur WebUSB-API. Er erzeugt ein Objekt, das eine bestimmte Konfiguration eines USB-Geräts beschreibt. Welche Konfiguration gemeint ist, legt der configurationValue fest, also der Wert, den das Gerät in seinem Konfigurationsdeskriptor meldet. Das Objekt liefert den Konfigurationswert (configurationValue), den optionalen Namen (configurationName) und die Liste der verfügbaren Schnittstellen (interfaces, ein Array aus USBInterface-Objekten).

Den Konstruktor ruft man in der Praxis selten direkt auf. Meist genügen device.configuration für die aktive Konfiguration und device.configurations für alle Konfigurationen, die das Gerät anbietet. Sinnvoll ist der direkte Aufruf vor allem dann, wenn man die Konfiguration zu einem bekannten Wert gezielt nachschlagen will, zum Beispiel für ein Diagnose-Tool oder vor einem Aufruf von device.selectConfiguration().

Das USBDevice muss vorher über navigator.usb.requestDevice() oder navigator.usb.getDevices() beschafft worden sein. Der Aufruf funktioniert nur in einem sicheren Kontext (HTTPS).

Parameter

Name	Typ	Default	Beschreibung
$device Pflicht	USBDevice		Das USB-Gerät, zu dem die Konfiguration gehört. Es muss vorher über die WebUSB-API freigegeben worden sein.
$configurationValue Pflicht	number		Der Konfigurationswert (`bConfigurationValue` aus dem USB-Deskriptor), ein Ganzzahlwert zwischen 0 und 255. Er muss einer Konfiguration entsprechen, die das Gerät tatsächlich anbietet.

Rückgabewert

Typ

USBConfiguration

Beschreibung

Ein neues USBConfiguration-Objekt mit den Eigenschaften configurationValue, configurationName und interfaces.

Beispiele

Konfiguration eines freigegebenen Geräts nachschlagen

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

button.addEventListener('click', async () => {
  // Der Nutzer wählt ein Gerät aus (erfordert eine Nutzeraktion)
  const device = await navigator.usb.requestDevice({ filters: [] });

  // Konfiguration mit dem Wert 1 als Objekt erzeugen
  const config = new USBConfiguration(device, 1);

  console.log('Wert:', config.configurationValue);
  console.log('Name:', config.configurationName ?? '(kein Name)');
  console.log('Schnittstellen:', config.interfaces.length);
});

Wert: 1 Name: (kein Name) Schnittstellen: 2

Schnittstellen und Endpunkte auflisten

const describeConfiguration = (device, value) => {
  const config = new USBConfiguration(device, value);

  for (const iface of config.interfaces) {
    const alt = iface.alternate;
    console.log(`Schnittstelle ${iface.interfaceNumber}: Klasse 0x${alt.interfaceClass.toString(16)}`);
    for (const ep of alt.endpoints) {
      console.log(`  Endpunkt ${ep.endpointNumber} (${ep.direction}, ${ep.type})`);
    }
  }
};

const [device] = await navigator.usb.getDevices();
if (device) {
  await device.open();
  describeConfiguration(device, device.configuration?.configurationValue ?? 1);
}

Schnittstelle 0: Klasse 0xff Endpunkt 1 (in, bulk) Endpunkt 2 (out, bulk)

Ungültigen Konfigurationswert abfangen

const safeConfiguration = (device, value) => {
  try {
    return new USBConfiguration(device, value);
  } catch (err) {
    console.warn(`Konfiguration ${value} existiert nicht:`, err.name);
    return null;
  }
};

const [device] = await navigator.usb.getDevices();
if (device) {
  // Übliche Alternative ohne Konstruktor:
  const values = device.configurations.map((c) => c.configurationValue);
  console.log('Verfügbare Werte:', values);
  safeConfiguration(device, 42);
}

Verfügbare Werte: [1] Konfiguration 42 existiert nicht: RangeError

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen die API nicht. Prüfe vorher mit 'usb' in navigator, ob sie verfügbar ist.
WebUSB läuft nur in einem sicheren Kontext (HTTPS oder localhost). In iframes muss sie zusätzlich über die Berechtigungsrichtlinie usb erlaubt sein.
Gibt man einen configurationValue an, den das Gerät nicht anbietet, wirft der Konstruktor einen RangeError.
Das Erzeugen des Objekts aktiviert die Konfiguration nicht. Dafür ist device.selectConfiguration(value) auf einem geöffneten Gerät nötig.
In den meisten Fällen sind device.configuration und device.configurations einfacher und weniger fehleranfällig als der direkte Aufruf des Konstruktors.
Geräteklassen, die das Betriebssystem schützt (z. B. HID, Massenspeicher oder Audio), blockiert WebUSB. Deren Schnittstellen lassen sich nicht beanspruchen.

Siehe auch

USBConfiguration USBDevice USBDevice.selectConfiguration() USBDevice.configurations USBInterface USB.requestDevice() new DOMPointReadOnly()