Navigator: requestMIDIAccess()-Methode

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.

Die requestMIDIAccess()-Methode des Navigator-Interfaces gibt ein Promise zurück, das eine Anforderung für den Zugriff auf MIDI-Geräte auf dem System eines Benutzers darstellt. Diese Methode ist Teil der Web MIDI API, die Zugriff auf, Auflistung von und Manipulation von MIDI-Geräten ermöglicht.

Diese Methode kann den Benutzer um Zugriff auf die auf seinem System verfügbaren MIDI-Geräte bitten oder eine zuvor festgelegte Präferenz verwenden, um den Zugriff zu gewähren oder zu verweigern. Wenn die Erlaubnis erteilt wird, wird das Promise aufgelöst und ein MIDIAccess-Objekt zurückgegeben.

Syntax

js
requestMIDIAccess()
requestMIDIAccess(MIDIOptions)

Parameter

MIDIOptions Optional

Ein Object, das Optionen darstellt, die in die Methode übergeben werden. Diese Optionen sind:

sysex

Ein Boolean-Wert, der, wenn auf true gesetzt, die Möglichkeit ermöglicht, Systemausschlussnachrichten (sysex) zu senden und zu empfangen. Der Standardwert ist false.

software

Ein Boolean-Wert, der, wenn auf true gesetzt, dem System ermöglicht, installierte Software-Synthesizer zu nutzen. Der Standardwert ist false.

Rückgabewert

Ein Promise das mit einem MIDIAccess-Objekt aufgelöst wird.

Ausnahmen

AbortError DOMException

Wird ausgelöst, wenn das Dokument oder die Seite aufgrund der Benutzernavigation geschlossen wird.

InvalidStateError DOMException

Wird ausgelöst, wenn das zugrunde liegende System Fehler verursacht.

NotSupportedError DOMException

Wird ausgelöst, wenn das System die Funktion oder Optionen nicht unterstützt.

SecurityError DOMException

Wird ausgelöst, wenn der Benutzer oder das System der Anwendung nicht erlaubt, ein MIDIAccess-Objekt mit den angeforderten Optionen zu erstellen, oder wenn das Dokument die Funktion nicht verwenden darf (zum Beispiel aufgrund einer Permission Policy, oder weil der Benutzer eine Berechtigungsanfrage zuvor abgelehnt hat).

Sicherheitsanforderungen

Der Zugriff auf die API unterliegt folgenden Einschränkungen:

  • Die Methode muss in einem sicheren Kontext aufgerufen werden.
  • Der Zugriff kann durch die HTTP-Permission Policy midi beschränkt werden.
  • Der Benutzer muss der Nutzung der API ausdrücklich zustimmen, entweder über einen benutzerspezifischen Mechanismus oder, wenn zuvor die Erlaubnis erteilt wurde. Beachten Sie, dass, wenn der Zugriff durch eine Berechtigungsrichtlinie verweigert wird, dies nicht durch eine Benutzererlaubnis gewährt werden kann.

Der Berechtigungsstatus kann mit der Permissions API-Methode navigator.permissions.query() abgefragt werden, wobei ein Berechtigungsdeskriptor mit der midi-Berechtigung und (optional) sysex-Eigenschaft übergeben wird:

js
navigator.permissions.query({ name: "midi", sysex: true }).then((result) => {
  if (result.state === "granted") {
    // Access granted.
  } else if (result.state === "prompt") {
    // Using API will prompt for permission
  }
  // Permission was denied by user prompt or permission policy
});

Beispiele

MIDI-Zugriff anfordern

Im folgenden Beispiel gibt die Methode Navigator.requestMIDIAccess() das MIDIAccess-Objekt zurück, welches Zugriff auf Informationen über die Ein- und Ausgabemidianschlüsse bietet.

js
navigator.requestMIDIAccess().then((access) => {
  // Get lists of available MIDI controllers
  const inputs = access.inputs.values();
  const outputs = access.outputs.values();
  // …
});

Spezifikationen

Specification
Web MIDI API
# dom-navigator-requestmidiaccess

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch