pixijs/pixijs-environments

Was macht pixijs-environments?

Verwenden Sie diese Skill, wenn PixiJS v8 außerhalb eines Standardbrowsers ausgeführt wird: Web Worker, OffscreenCanvas, Node/SSR oder CSP-eingeschränkte Kontexte. Deckt DOMAdapter.set, BrowserAdapter, WebWorkerAdapter, benutzerdefinierte Adapter-Schnittstelle, pixi.js/unsafe-eval für striktes CSP ab. Auslöser: DOMAdapter, BrowserAdapter, WebWorkerAdapter, Web Worker, OffscreenCanvas, Node, headless, SSR, CSP, unsafe-eval, Adapter.

Übersicht

PixiJS v8 bietet eine flexible Architektur, die es ermöglicht, in verschiedenen Umgebungen zu laufen. Der Kernmechanismus dafür ist der DOMAdapter, eine abstrakte Schnittstelle, die die DOM-Interaktionen kapselt. Standardmäßig wird der BrowserAdapter verwendet, der für die Arbeit in einem normalen Browser optimiert ist. Für andere Umgebungen können Sie spezialisierte Adapter oder eigene Implementierungen verwenden.

Hauptkonzepte

DOMAdapter

Die Klasse DOMAdapter ist der zentrale Einstiegspunkt. Sie wird verwendet, um den aktiven Adapter zu setzen und auf ihn zuzugreifen.

import { DOMAdapter } from 'pixi.js';

// Aktuellen Adapter abrufen
const adapter = DOMAdapter.instance;

// Adapter setzen
DOMAdapter.instance = new MyCustomAdapter();

Verfügbare Adapter

Adapter	Verwendung
BrowserAdapter	Standardbrowser, Standardkonfiguration
WebWorkerAdapter	Web Worker und OffscreenCanvas
Benutzerdefiniert	Eigene Implementierung für Node.js, SSR oder andere Umgebungen

BrowserAdapter

Der BrowserAdapter ist der Standardadapter. Er wird automatisch verwendet, wenn PixiJS in einem Browser geladen wird.

import { BrowserAdapter } from 'pixi.js';

WebWorkerAdapter

Der WebWorkerAdapter ist für die Verwendung in Web Workern und mit OffscreenCanvas optimiert. Er bietet eine schlanke Implementierung, die ohne vollständiges DOM auskommt.

import { WebWorkerAdapter } from 'pixi.js';
import { DOMAdapter } from 'pixi.js';

// Adapter für Web Worker setzen
DOMAdapter.set(WebWorkerAdapter);

Benutzerdefinierte Adapter (Custom Adapter Interface)

Sie können Ihre eigenen Adapter implementieren, indem Sie die Adapter-Schnittstelle erfüllen. Dies ist nützlich für Umgebungen wie Node.js oder serverseitiges Rendering (SSR).

import { DOMAdapter, type Adapter } from 'pixi.js';

class NodeAdapter implements Adapter {
  // Implementieren Sie die erforderlichen Methoden
  createCanvas(width?: number, height?: number): HTMLCanvasElement {
    // Node.js-spezifische Canvas-Erstellung
  }
  getCanvasRenderingContext2D(): typeof CanvasRenderingContext2D {
    // ...
  }
  getWebGLRenderingContext(): typeof WebGLRenderingContext {
    // ...
  }
  getNavigator(): Navigator {
    // ...
  }
  getBaseUrl(): string {
    // ...
  }
  getFontFaceSet(): FontFaceSet | null {
    // ...
  }
  fetch(url: RequestInfo, options?: RequestInit): Promise<Response> {
    // ...
  }
}

// Benutzerdefinierten Adapter setzen
DOMAdapter.set(new NodeAdapter());

CSP (Content Security Policy) & unsafe-eval

Wenn Ihre Anwendung eine strenge Content Security Policy (CSP) verwendet, die die Verwendung von eval() verbietet, benötigen Sie den speziellen Importpfad pixi.js/unsafe-eval. Dieser Pfad exportiert eine Version von PixiJS, die keine eval()-Aufrufe enthält.

// Statt:
// import * as PIXI from 'pixi.js';

// Verwenden Sie:
import * as PIXI from 'pixi.js/unsafe-eval';

// Jetzt können Sie PixiJS normal verwenden, ohne CSP-Verstöße zu riskieren
const app = new PIXI.Application();

Verwendung in spezifischen Umgebungen

Web Worker / OffscreenCanvas

// worker.ts
import { WebWorkerAdapter } from 'pixi.js';
import { DOMAdapter } from 'pixi.js';

// Adapter setzen
DOMAdapter.set(WebWorkerAdapter);

// PixiJS-Anwendung im Worker starten
import { Application } from 'pixi.js';

const app = new Application();
// ...

Node.js / SSR (Server-Side Rendering)

Für Node.js oder SSR benötigen Sie einen benutzerdefinierten Adapter oder ein Paket wie pixi.js-node (falls verfügbar). Die Grundstruktur bleibt gleich:

import { DOMAdapter } from 'pixi.js';

// Benutzerdefinierten Node-Adapter setzen
DOMAdapter.set(new MyNodeAdapter());

// PixiJS normal verwenden
import { Application } from 'pixi.js';

Zusammenfassung

• DOMAdapter.set() ist der zentrale Mechanismus zum Wechseln der Umgebung.
• Verwenden Sie BrowserAdapter für Standardbrowser (Standard).
• Verwenden Sie WebWorkerAdapter für Web Worker/OffscreenCanvas.
• Implementieren Sie die Adapter-Schnittstelle für Node.js, SSR oder andere benutzerdefinierte Umgebungen.
• Verwenden Sie pixi.js/unsafe-eval für strenge CSP-Umgebungen.
• Importieren Sie immer den richtigen Adapter vor dem Erstellen von PixiJS-Instanzen.