pixijs-scene-dom-container

DOMContainer はPixiJSキャンバスの上にHTMLエレメントを配置し、そのCSS変形をシーングラフから駆動させます。ネイティブ入力、iframe、ビデオ、またはディスプレイオブジェクトの位置に追従する必要があるリッチなHTMLに使用します。デフォルトの pixi.js ブラウザバンドルは DOMPipe を自動的に登録します。カスタムビルドではサイドエフェクト import 'pixi.js/dom' を追加してください。

DOMContainer はPixiJS v8ではEXPERIMENTALとしてマークされています。マイナーリリース間でAPIが変更される可能性があります。

pixijs-scene-core-concepts に精通していることを前提としています。DOMContainer は ViewContainer を拡張しているため、リーフです。内部にPixiJSの子を追加しないでください。DOMコンテンツをHTMLエレメント自体の内部に追加するか、複数の DOMContainer インスタンスを Container でラップしてください。Web Workersでは利用できません。ワーカーには重ねるDOMがありません。

クイックスタート

import "pixi.js/dom";

const input = document.createElement("input");
input.type = "text";
input.placeholder = "Enter name...";

const dom = new DOMContainer({
  element: input,
  anchor: 0.5,
});
dom.position.set(app.screen.width / 2, app.screen.height / 2);

app.stage.addChild(dom);

関連スキル: pixijs-scene-core-concepts (シーングラフの基礎)、pixijs-scene-container (複数のDOM重ねをラップ)、pixijs-events (キャンバス対DOMでのポインターハンドリング)、pixijs-accessibility (スクリーンリーダーオーバーレイ)。

コンストラクタオプション

すべての Container オプション (position、scale、tint、label、filters、zIndex など) もここで有効です。詳細は skills/pixijs-scene-core-concepts/references/constructor-options.md を参照してください。

DOMContainerOptions によって追加されるリーフ固有のオプション:

オプション	型	デフォルト	説明
element	HTMLElement	document.createElement('div')	コンテナが駆動するHTMLエレメント。任意のエレメントが有効: input、textarea、iframe、video、div など。省略された場合、空の <div> が作成されます。
anchor	PointData | number	0	エレメント自身の寸法に対する相対的な原点。0 は左上、0.5 は中央、1 は右下。単一の数値は両軸を設定します。{ x, y } は各軸を個別に設定します。

tint、filters、mask、blendMode は受け入れられますが (Container から継承)、視覚的な効果はありません。DOMエレメントはWebGL/WebGPUパイプラインの外に存在します。これらの効果については CSS を使ってエレメントのスタイルを設定してください。

コアパターン

セットアップとサイドエフェクトインポート

import "pixi.js/dom";
import { DOMContainer } from "pixi.js";

またはパイプを登録してクラスを再エクスポートする統合インポートを使用してください:

import { DOMContainer } from "pixi.js/dom";

デフォルトの pixi.js ブラウザバンドルは既に browserAll.ts 経由で pixi.js/dom をインポートしているため、DOMContainer は一般的なブラウザアプリで既成のまま動作します。skipExtensionImports: true (カスタムビルド) をオプトアウトする場合、またはブラウザ以外のバンドルで実行する場合のみ、明示的な import 'pixi.js/dom' 行が必要です。

変形、アンカー、アルファ

const dom = new DOMContainer({
  element: document.createElement("div"),
  anchor: 0.5,
});
dom.position.set(400, 300);
dom.scale.set(1.5);
dom.rotation = Math.PI / 8;
dom.alpha = 0.5;

DOMContainer 上の変形はエレメントにCSS transform として伝播します。anchor はエレメント自身の寸法に対してエレメントの原点をシフトします: 0 は左上、0.5 は中央、1 は右下です。単一の数値は両軸を設定します。オブジェクト { x, y } は各軸を個別に設定します。alpha (継承された親のアルファを含む) はフレームごとにエレメントの style.opacity に書き込まれます。

element が提供されない場合、デフォルトで <div> が作成されます。

エレメントを直接スタイルする

const panel = document.createElement("div");
panel.innerHTML = "<h2>Score</h2><p>1500</p>";
panel.style.color = "white";
panel.style.fontFamily = "Arial";
panel.style.pointerEvents = "none";

const dom = new DOMContainer({ element: panel });
dom.position.set(50, 50);
app.stage.addChild(dom);

PixiJS はエレメント上のCSSスタイルに干渉しません。共有ルート <div> は pointer-events: none に設定され、各接続エレメントはデフォルトで pointer-events: auto です。純粋に装飾的なオーバーレイでは none をオーバーライドして、キャンバスがその下のクリックを受け取るようにしてください。

可視性とクリーンアップ

dom.visible = false;
dom.visible = true;

dom.destroy();

visible = false を設定するか、シーングラフから DOMContainer を削除すると、エレメントはDOMから切り離されます。可視性を復元するとリアタッチします。destroy() はエレメントを親ノードから削除し、内部参照をnullにします。HTMLエレメント自体は保持されるため、別の場所に再アタッチできます:

const element = dom.element;
dom.destroy();
document.body.appendChild(element);

DOMコンテナルート

DOMPipeは z-index: 1000 の共有ルート <div> を使用し、すべての接続エレメントをホストします。これは app.domContainerRoot (HTMLDivElement) として公開されます。すべての DOMContainer エレメントはキャンバスコンテンツ上にレンダリングされます。PixiJSのドロー呼び出しの間にDOMエレメントをインターリーブすることはできません。

接続された DOMContainer を持つ最初のレンダリングで、パイプはキャンバスの親ノードに自動的にルートを追加します。キャンバスを共有ラッパーが他のレイヤーコンテンツと一緒に使用されている場合など、DOMツリーに明示的で安定した配置が必要な場合は、app.canvas の隣に自分自身で追加してください:

document.body.appendChild(app.canvas);
document.body.appendChild(app.domContainerRoot);

ルートは絶対位置を使用し、その変形はキャンバス getBoundingClientRect() から ResizeObserver 経由で再計算されるため、CSSでスケールされたキャンバスは余分な作業なしで配置され続けます。

一般的な間違い

[MEDIUM] カスタムビルドで pixi.js/dom インポートを欠落させる

デフォルトブラウザバンドルは DOMPipe を自動登録するため、ほとんどのアプリは明示的なインポートを必要としません。これは自動インポートをオプトアウトする場合にのみ必要です:

await app.init({ skipExtensionImports: true });
// これを自分で追加する必要があります:
import "pixi.js/dom";

カスタムビルド下で登録がない場合、DOMContainer は引き続きインポート可能ですが、レンダラーには処理するパイプがありません。エレメントはシーングラフと同期しませんし、表示されません。

[MEDIUM] DOMエレメントに影響を与えるフィルター、マスク、またはブレンドモードを期待する

間違い:

const dom = new DOMContainer();
dom.filters = [new BlurFilter()];

正解:

dom.element.style.filter = "blur(4px)";

DOMエレメントはCSSトランスフォームを介して配置されるHTMLオーバーレイです。WebGL/WebGPUパイプラインの外に存在します。PixiJSフィルター、マスク、ブレンドモードはそれらに影響を与えません。CSSフィルターとCSS mix-blend-mode をエレメント上で直接使用してください。

[MEDIUM] DOMContainerの内部に子をネストしない

間違い:

const dom = new DOMContainer();
dom.addChild(new Sprite(texture));

正解:

const group = new Container();
group.addChild(dom, new Sprite(texture));

DOMContainer は ViewContainer を拡張し、allowChildren = false を設定します。PixiJSシーングラフ内のリーフです。PixiJSの子については、DOMContainer をそれらと一緒にプレーン Container でラップしてください。ネストされたHTMLについては、エレメント自体の内部にネストしてください (element.appendChild(...))。

[LOW] 中央配置のアンカー設定を忘れる

デフォルトアンカーは (0, 0) で、エレメントの左上隅をコンテナの位置に配置します。UI要素をそのシーングラフ位置に中央配置するには、anchor: 0.5 を設定してください:

const dom = new DOMContainer({ element: myElement, anchor: 0.5 });
dom.position.set(400, 300);

APIリファレンス

• DOMContainer
• DOMContainerOptions
• ViewContainer
• Container