Worklet.addModule() — Methode · JavaScript-Referenz

Signatur

Worklet.prototype.addModule(moduleURL, options)

Beschreibung

addModule() ist der einzige Weg, Code in ein Worklet zu laden. Die Methode holt das angegebene Skript als ES-Modul, führt es in jedem WorkletGlobalScope des Worklets aus und löst ihr Promise auf, sobald das Modul überall geladen und ausgewertet ist. Erst danach sind die im Modul registrierten Klassen (z. B. über registerProcessor() oder registerPaint()) nutzbar.

In der Praxis ruft man die Methode nicht auf einem allgemeinen Worklet auf, sondern auf einer konkreten Instanz: audioContext.audioWorklet (Web Audio API), CSS.paintWorklet (CSS Painting API), CSS.layoutWorklet oder CSS.animationWorklet. Man kann die Methode mehrmals aufrufen, um mehrere Module in dasselbe Worklet zu laden.

Da Worklet-Code immer als Modul läuft, gelten die Modulregeln: strikter Modus, import-Anweisungen sind erlaubt, und Skripte anderer Herkunft müssen per CORS freigegeben sein. Über options.credentials steuert man, ob Cookies und HTTP-Authentifizierung mitgesendet werden.

Parameter

Name	Typ	Default	Beschreibung
$moduleURL Pflicht	string \| URL		URL der zu ladenden Moduldatei (relativ zum Dokument oder absolut). Auch eine `blob:`-URL ist möglich.
$options	Object	{}	Optionales Objekt mit Einstellungen.
$options.credentials	"omit" \| "same-origin" \| "include"	"same-origin"	Legt fest, ob Anmeldedaten (Cookies, HTTP-Auth) beim Laden gesendet werden. Standard ist `"same-origin"`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined aufgelöst wird, sobald das Modul geladen und ausgewertet ist. Es wird mit einem AbortError (DOMException) abgelehnt, wenn das Laden fehlschlägt oder das Modul einen Syntaxfehler enthält.

Beispiele

AudioWorklet-Prozessor laden und verwenden

// Datei: rauschen-prozessor.js
// class RauschProzessor extends AudioWorkletProcessor {
//   process(inputs, outputs) {
//     for (const channel of outputs[0]) {
//       for (let i = 0; i < channel.length; i++) channel[i] = Math.random() * 2 - 1;
//     }
//     return true;
//   }
// }
// registerProcessor('rauschen', RauschProzessor);

const startButton = document.querySelector('#start');

startButton.addEventListener('click', async () => {
  const ctx = new AudioContext();
  await ctx.audioWorklet.addModule('rauschen-prozessor.js');
  const node = new AudioWorkletNode(ctx, 'rauschen');
  node.connect(ctx.destination);
  console.log('Rauschgenerator läuft');
});

Rauschgenerator läuft

CSS Paint Worklet mit Feature-Erkennung registrieren

// Datei: schachbrett.js
// registerPaint('schachbrett', class {
//   paint(ctx, size) {
//     const s = 16;
//     for (let y = 0; y < size.height / s; y++)
//       for (let x = 0; x < size.width / s; x++)
//         if ((x + y) % 2 === 0) ctx.fillRect(x * s, y * s, s, s);
//   }
// });

if ('paintWorklet' in CSS) {
  CSS.paintWorklet.addModule('schachbrett.js');
  document.body.style.backgroundImage = 'paint(schachbrett)';
} else {
  console.warn('CSS Painting API nicht unterstützt');
}

Modul aus einem Blob laden mit Fehlerbehandlung

const code = `
  registerProcessor('stumm', class extends AudioWorkletProcessor {
    process() { return true; }
  });
`;
const url = URL.createObjectURL(new Blob([code], { type: 'text/javascript' }));

const ctx = new AudioContext();
try {
  await ctx.audioWorklet.addModule(url, { credentials: 'omit' });
  console.log('Modul geladen');
} catch (err) {
  console.error('Laden fehlgeschlagen:', err.name);
} finally {
  URL.revokeObjectURL(url);
}

Modul geladen

// Wichtig · Fallstricke

Erst warten, dann nutzen: Wer new AudioWorkletNode() erzeugt, bevor das Promise aufgelöst ist, bekommt einen InvalidStateError, weil der Prozessorname noch nicht registriert ist.
Sicherer Kontext: Worklets gibt es nur über HTTPS bzw. localhost.
CORS und CSP: Module anderer Herkunft brauchen passende CORS-Header. Die Direktive script-src der Content Security Policy gilt auch für Worklet-Module; bei blob:-URLs muss blob: erlaubt sein.
MIME-Typ: Der Server muss das Skript mit einem JavaScript-MIME-Typ ausliefern (z. B. text/javascript), sonst wird das Laden abgelehnt.
Eingeschränkte Umgebung: Im Worklet-Scope gibt es kein DOM und kein fetch(); bei Paint Worklets ist der Scope zustandslos und kann jederzeit neu erzeugt werden.
Kompatibilität: audioWorklet.addModule() läuft in allen modernen Browsern. CSS.paintWorklet gibt es nur in Chromium-Browsern, layoutWorklet und animationWorklet nur als experimentelle Funktionen.

Siehe auch

Worklet Worker.terminate() Cache.addAll() Document.adoptNode() FormData.delete()