Signatur
Beschreibung
usbVersionMajor ist eine schreibgeschützte Eigenschaft des Interfaces USBDevice aus der WebUSB-API. Der Wert ist eine Ganzzahl und gibt die Hauptversion des USB-Protokolls an, das das Gerät unterstützt. Zusammen mit usbVersionMinor und usbVersionSubminor ergibt sich die vollständige Versionsnummer, z. B. 2.1.0 oder 3.2.0.
Der Wert stammt aus dem Feld bcdUSB des Gerätedeskriptors (Device Descriptor). Das Gerät meldet ihn selbst bei der Enumeration. Der Browser kennt ihn deshalb sofort, sobald das USBDevice-Objekt vorliegt. Du musst das Gerät dafür weder mit open() öffnen noch ein Interface beanspruchen.
Typische Anwendungsfälle:
- Diagnose- und Info-Oberflächen, die Gerätedetails anzeigen
- Protokollierung von Gerätedaten
- Entscheidungen über Funktionen, die von der Version abhängen, etwa der Hinweis, dass WebUSB-Plattformdeskriptoren (BOS) erst ab USB 2.1 verfügbar sind
Beachte: Der Wert zeigt nur, welche Version das Gerät laut eigener Angabe unterstützt. Er sagt nichts darüber aus, mit welcher Geschwindigkeit die Verbindung tatsächlich läuft. Diese hängt auch vom Host-Port und vom Kabel ab.
Rückgabewert
1, 2 oder 3.Beispiele
Gerät auswählen und USB-Version anzeigen
const button = document.querySelector('#connect');
button.addEventListener('click', async () => {
try {
// requestDevice() funktioniert nur nach einer Nutzeraktion wie einem Klick
const device = await navigator.usb.requestDevice({ filters: [] });
const version = `${device.usbVersionMajor}.${device.usbVersionMinor}.${device.usbVersionSubminor}`;
console.log(`${device.productName ?? 'Unbekanntes Gerät'}: USB ${version}`);
} catch (err) {
console.warn('Kein Gerät ausgewählt:', err.message);
}
});Alle freigegebenen Geräte als Tabelle ausgeben
const listDevices = async () => {
// getDevices() liefert nur Geräte, die bereits freigegeben wurden
const devices = await navigator.usb.getDevices();
console.table(devices.map((d) => ({
name: d.productName,
vendorId: d.vendorId.toString(16).padStart(4, '0'),
usb: `${d.usbVersionMajor}.${d.usbVersionMinor}`
})));
};
listDevices();Prüfen, ob das Gerät BOS-Deskriptoren unterstützen kann (ab USB 2.1)
const supportsBos = (device) =>
device.usbVersionMajor > 2 ||
(device.usbVersionMajor === 2 && device.usbVersionMinor >= 1);
const [device] = await navigator.usb.getDevices();
if (device) {
console.log(supportsBos(device)
? 'Gerät meldet USB ≥ 2.1 – BOS/WebUSB-Deskriptoren möglich'
: 'Gerät meldet USB < 2.1 – keine BOS-Deskriptoren');
}// Wichtig · Fallstricke
- Browser-Kompatibilität: WebUSB gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen es nicht. Prüfe die Unterstützung vorher mit
'usb' in navigator. - Sicherer Kontext: Die API ist nur über HTTPS oder
localhostverfügbar. Per Permissions Policy (usb) kann sie in iframes gesperrt sein. - Nutzeraktion nötig:
navigator.usb.requestDevice()muss durch eine Nutzeraktion ausgelöst werden, etwa einen Klick. Ohne diese Aktion gibt es keinUSBDevice-Objekt. - Selbstauskunft des Geräts: Der Wert kommt aus dem Feld
bcdUSB, das das Gerät selbst meldet. Er muss nicht der tatsächlichen Verbindungsgeschwindigkeit entsprechen. Ein USB-3-Gerät an einem USB-2-Port kann trotzdem3melden. - Kein Dezimalwert: Die Version steckt im BCD-Format (binär codierte Dezimalzahl), und der Browser zerlegt sie für dich in drei getrennte Zahlen. Um sie zu vergleichen, prüfe
usbVersionMajorundusbVersionMinornacheinander. Rechne nicht mit Gleitkommazahlen wie2.1. - Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert und löst im Strict Mode einen
TypeErroraus.