WorkletGlobalScope — Schnittstelle · JavaScript-Referenz

Signatur

interface WorkletGlobalScope

Beschreibung

WorkletGlobalScope ist die gemeinsame, abstrakte Basis aller globalen Objekte, in denen Worklet-Code läuft. Wenn du mit worklet.addModule(url) ein Modul lädst, wird es nicht im Window ausgeführt, sondern in einem eigenen, stark eingeschränkten globalen Kontext. Das globale Objekt dort (globalThis) ist eine Instanz einer Unterklasse von WorkletGlobalScope.

Konkrete Unterklassen sind:

AudioWorkletGlobalScope: für eigene Audioverarbeitung mit der Web Audio API (registerProcessor(), sampleRate, currentTime, currentFrame).
PaintWorkletGlobalScope: für die CSS Painting API (registerPaint(), devicePixelRatio).
LayoutWorkletGlobalScope und AnimationWorkletGlobalScope: experimentell (Houdini), in Browsern kaum verfügbar.

WorkletGlobalScope selbst definiert keine eigenen Eigenschaften oder Methoden. Die Schnittstelle legt aber die gemeinsamen Regeln fest: Code wird immer als ES-Modul im Strict Mode ausgeführt. Es gibt kein DOM, kein fetch(), kein XMLHttpRequest, kein setTimeout() und kein importScripts(). Außerdem darf der Browser beliebig viele Instanzen des Scopes erzeugen und wieder verwerfen.

Du verwendest die Schnittstelle nie direkt. Sie ist wichtig, damit du verstehst, welche Möglichkeiten und Grenzen dein Worklet-Code hat. Die Klasse selbst brauchst du höchstens für eine Typprüfung, etwa globalThis instanceof WorkletGlobalScope.

Rückgabewert

Typ

WorkletGlobalScope

Beschreibung

Kein Konstruktor verfügbar. Instanzen (genauer: Instanzen einer Unterklasse) stehen nur innerhalb eines Worklet-Moduls als globalThis zur Verfügung.

Beispiele

AudioWorklet: Modul laden und Scope nutzen (Hauptthread)

// main.js – läuft im Window
const ctx = new AudioContext();
await ctx.audioWorklet.addModule('gain-processor.js');

const node = new AudioWorkletNode(ctx, 'gain-processor');
const osc = new OscillatorNode(ctx);
osc.connect(node).connect(ctx.destination);
osc.start();

AudioWorklet-Modul: Code im AudioWorkletGlobalScope

// gain-processor.js – globalThis ist hier ein AudioWorkletGlobalScope
console.log(globalThis instanceof WorkletGlobalScope); // true
console.log(typeof window, typeof document, typeof fetch);
console.log('Samplerate:', sampleRate);

class GainProcessor extends AudioWorkletProcessor {
  process(inputs, outputs) {
    const input = inputs[0];
    const output = outputs[0];
    for (let ch = 0; ch < input.length; ch++) {
      for (let i = 0; i < input[ch].length; i++) {
        output[ch][i] = input[ch][i] * 0.5; // halbe Lautstärke
      }
    }
    return true; // Prozessor aktiv halten
  }
}

registerProcessor('gain-processor', GainProcessor);

true undefined undefined undefined Samplerate: 48000

PaintWorklet: CSS-Hintergrund im PaintWorkletGlobalScope

// checker.js – globalThis ist ein PaintWorkletGlobalScope
registerPaint('checker', class {
  paint(ctx, size) {
    const tile = 16;
    for (let y = 0; y < size.height; y += tile) {
      for (let x = 0; x < size.width; x += tile) {
        if ((x / tile + y / tile) % 2 === 0) ctx.fillRect(x, y, tile, tile);
      }
    }
  }
});

// main.js (Hauptthread):
// if ('paintWorklet' in CSS) await CSS.paintWorklet.addModule('checker.js');
// CSS: .box { background-image: paint(checker); }

Feature-Erkennung vor dem Laden eines Worklets

const support = {
  audio: typeof AudioWorkletNode !== 'undefined',
  paint: typeof CSS !== 'undefined' && 'paintWorklet' in CSS
};
console.log(support);

{ audio: true, paint: true } // z. B. in Chrome; in Firefox/Safari paint: false

// Wichtig · Fallstricke

Kein Zustand, auf den man sich verlassen kann: Der Browser darf mehrere Scopes parallel erzeugen (bei PaintWorklets mindestens zwei) und sie jederzeit verwerfen. Globale Variablen und Klassenfelder eignen sich deshalb nicht als dauerhafter Speicher oder Cache.
Eingeschränkte API: Kein DOM, kein fetch, keine Timer, kein importScripts(). Nur statische und dynamische import-Anweisungen im Rahmen der Modul-Regeln. Mit dem Hauptthread kommunizierst du bei AudioWorklets über den MessagePort (this.port) des Prozessors.
Sicherer Kontext: addModule() funktioniert nur über HTTPS oder localhost. Das Modul wird unter Beachtung von CORS geladen; die Option credentials steuert, ob Cookies mitgesendet werden.
Kompatibilität: AudioWorkletGlobalScope gibt es in allen modernen Browsern. PaintWorkletGlobalScope gibt es nur in Chromium-Browsern. Layout- und Animation-Worklets sind experimentell. Prüfe deshalb immer vorher, ob die Funktion vorhanden ist.
console ist in Worklets meist verfügbar, die Ausgabe erscheint aber je nach Browser in einem eigenen Kontext der Entwicklerwerkzeuge.

Siehe auch

Worklet SharedStorageWorkletGlobalScope WorkerGlobalScope AudioWorkletGlobalScope PaintWorkletGlobalScope