HID: Methode requestDevice()
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.
Die requestDevice()
-Methode der HID
-Schnittstelle fordert den Zugriff auf ein HID-Gerät an.
Der User Agent präsentiert ein Berechtigungsdialogfenster, das eine Liste der verbundenen Geräte enthält, und bittet den Benutzer, eines dieser Geräte auszuwählen und die Berechtigung zu erteilen.
Syntax
requestDevice(options)
Parameter
options
-
Ein Objekt, das ein Array von Filterobjekten für mögliche Geräte enthält, mit denen eine Paarung erfolgen soll. Jedes Filterobjekt kann die folgenden Eigenschaften haben:
vendorId
Optional-
Eine ganze Zahl, die die vendorId des angeforderten HID-Geräts darstellt.
productId
Optional-
Eine ganze Zahl, die die productId des angeforderten HID-Geräts darstellt.
usagePage
Optional-
Eine ganze Zahl, die die Nutzerseite-Komponente der HID-Nutzung des angeforderten Geräts darstellt. Die Nutzung für eine oberste Sammlung wird verwendet, um den Gerätetyp zu identifizieren.
Standard-HID-Nutzungswerte sind im Dokument HID Usage Tables zu finden.
usage
Optional-
Eine ganze Zahl, die die Usage-ID-Komponente der HID-Nutzung des angeforderten Geräts darstellt.
Hinweis: Die Gerätefilter werden verwendet, um die Liste der dem Benutzer angezeigten Geräte einzugrenzen. Wenn keine Filter vorhanden sind, werden alle verbundenen Geräte angezeigt. Wenn ein oder mehrere Filter eingeschlossen sind, wird ein Gerät eingeschlossen, wenn ein Filter passt. Um einen Filter zu erfüllen, müssen alle in diesem Filter enthaltenen Regeln übereinstimmen.
Rückgabewert
Ausnahmen
SecurityError
DOMException
-
Wird ausgelöst, wenn die Seite keinen Zugriff auf die HID-Funktion erlaubt.
Sicherheit
Eingeschränkte Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.
Beispiele
Übereinstimmung mit einem Gerät mit allen vier Filterregeln
Im folgenden Beispiel wird ein HID-Gerät angefordert, das eine Anbieter-ID von 0xABCD
, eine Produkt-ID von 0x1234
, eine Nutzungsseite 0x0C
und eine Nutzungs-ID von 0x01
hat. Nur Geräte, die alle diese Regeln erfüllen, werden angezeigt.
let requestButton = document.getElementById("request-hid-device");
requestButton.addEventListener("click", async () => {
let device;
try {
const devices = await navigator.hid.requestDevice({
filters: [
{
vendorId: 0xabcd,
productId: 0x1234,
usagePage: 0x0c,
usage: 0x01,
},
],
});
device = devices[0];
} catch (error) {
console.log("An error occurred.");
}
if (!device) {
console.log("No device was selected.");
} else {
console.log(`HID: ${device.productName}`);
}
});
Ein Beispiel mit zwei Filtern
Dieses nächste Beispiel enthält zwei Filter. Geräte werden angezeigt, wenn sie einem dieser Filter entsprechen.
// Filter on devices with the Nintendo Switch Joy-Con USB Vendor/Product IDs.
const filters = [
{
vendorId: 0x057e, // Nintendo Co., Ltd
productId: 0x2006, // Joy-Con Left
},
{
vendorId: 0x057e, // Nintendo Co., Ltd
productId: 0x2007, // Joy-Con Right
},
];
// Prompt user to select a Joy-Con device.
const [device] = await navigator.hid.requestDevice({ filters });
Spezifikationen
Specification |
---|
WebHID API # dom-hid-requestdevice |