new MIDIConnectionEvent() — Methode · JavaScript-Referenz

Signatur

new MIDIConnectionEvent(type, options)

Beschreibung

Der Konstruktor MIDIConnectionEvent() erzeugt ein Ereignisobjekt der Web MIDI API. Normalerweise legt der Browser solche Objekte selbst an und feuert sie als statechange-Ereignis auf MIDIAccess und dem betroffenen MIDIPort. Das passiert, wenn ein MIDI-Gerät angeschlossen oder entfernt wird oder wenn sich der Verbindungszustand eines Ports ändert (open, closed, pending).

Selbst aufrufen braucht man den Konstruktor vor allem in Tests und Simulationen. Damit lassen sich Anschluss-Ereignisse nachstellen, ohne dass ein echtes Gerät angeschlossen ist. Man kann damit auch eigene Ereignis-Logik innerhalb einer Anwendung weiterleiten.

Das neue Objekt enthält in der schreibgeschützten Eigenschaft port den übergebenen MIDIPort. Wurde kein Port übergeben, ist port null. Weil MIDIConnectionEvent von Event erbt, stehen auch alle üblichen Event-Optionen wie bubbles und cancelable zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, Groß- und Kleinschreibung zählt. Der Browser verwendet dafür immer `"statechange"`.
$options	object	{}	Objekt zur Initialisierung. Es enthält alle Felder von `EventInit` (`bubbles`, `cancelable`, `composed`) und zusätzlich `port`.
$options.port	MIDIPort \| null	null	Der `MIDIInput` oder `MIDIOutput`, der angeschlossen oder getrennt wurde.

Rückgabewert

Typ

MIDIConnectionEvent

Beschreibung

Ein neues MIDIConnectionEvent-Objekt. Seine Eigenschaft port ist entsprechend gesetzt.

Beispiele

Einfaches Ereignisobjekt erzeugen

// Ohne Port: port ist null
const event = new MIDIConnectionEvent('statechange');
console.log(event.type, event.port);

statechange null

Echte statechange-Ereignisse abhören

const access = await navigator.requestMIDIAccess();

access.addEventListener('statechange', (event) => {
  const { name, type, state, connection } = event.port;
  console.log(`${type} "${name}": ${state} / ${connection}`);
});

// Alternativ über die on-Eigenschaft:
// access.onstatechange = (event) => { ... };

input "USB MIDI Keyboard": connected / closed

Anschluss eines Geräts in einem Test simulieren

const access = await navigator.requestMIDIAccess();
const [firstInput] = access.inputs.values();

const handler = (event) => {
  console.log('Simuliert:', event.port?.name ?? 'kein Port');
};
access.addEventListener('statechange', handler);

// Künstliches Ereignis mit einem echten Port auslösen
const fake = new MIDIConnectionEvent('statechange', { port: firstInput ?? null });
access.dispatchEvent(fake);

access.removeEventListener('statechange', handler);

Simuliert: USB MIDI Keyboard

// Wichtig · Fallstricke

Browser-Unterstützung: Die Web MIDI API funktioniert in Chromium-Browsern und seit Version 108 in Firefox. Safari unterstützt sie nicht. Prüfe vorher mit 'MIDIConnectionEvent' in window oder navigator.requestMIDIAccess, ob die API vorhanden ist.
Sicherer Kontext: Die API steht nur unter HTTPS oder auf localhost zur Verfügung. Außerdem ist eine Berechtigung nötig: Firefox verlangt ein Site-Permission-Add-on, und mit sysex: true fragt der Browser zusätzlich nach.
Ereignisse, die du selbst per dispatchEvent() auslöst, haben isTrusted === false. Sie ändern auch nichts am tatsächlichen Zustand des Ports.
Der Wert für port muss ein echter MIDIPort sein. Einfache Objekte führen zu einem TypeError. Einen eigenen MIDIPort kann man nicht erzeugen, weil sein Konstruktor nicht aufrufbar ist.
Beim Öffnen eines Ports (open()) wird ebenfalls statechange ausgelöst. Ein Handler bekommt also nicht nur Anschluss-Ereignisse, sondern auch Änderungen von connection.

Siehe auch

MIDIConnectionEvent MIDIConnectionEvent.port MIDIAccess MIDIPort Navigator.requestMIDIAccess() MIDIMessageEvent