pixijs-scene-dom-container

DOMContainer 將 HTML 元素定位在 PixiJS 畫布上方，並透過場景圖驅動其 CSS 變形。適用於需要跟隨顯示物件位置的原生輸入框、iframe、影片或豐富 HTML。預設的 pixi.js 瀏覽器套件會自動註冊 DOMPipe；自訂建置則需加入副作用匯入 import 'pixi.js/dom'。

DOMContainer 在 PixiJS v8 中標記為實驗性功能。API 可能在小版本間變動。

假設已熟悉 pixijs-scene-core-concepts。DOMContainer 繼承自 ViewContainer，因此它是葉節點：請勿在內部巢狀放置 PixiJS 子物件。請在 HTML 元素本身內部巢狀放置 DOM 內容，或將多個 DOMContainer 實例包裝在 Container 中。不適用於 Web Worker；worker 沒有 DOM 可疊加。

快速開始

import "pixi.js/dom";

const input = document.createElement("input");
input.type = "text";
input.placeholder = "請輸入姓名...";

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>分數</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() 會將元素從其父節點移除並清空內部參考；HTML 元素本身會被保留，因此你可以將其重新附加到其他地方：

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

DOM 容器根節點

DOMPipe 使用一個共享的根 <div>（z-index: 1000）來容納所有附加的元素。該根節點以 app.domContainerRoot（一個 HTMLDivElement）的形式暴露。所有 DOMContainer 元素都繪製在畫布內容之上；你無法在 PixiJS 繪製呼叫之間交錯放置 DOM 元素。

在首次渲染具有附加 DOMContainer 時，管線會自動將根節點附加到畫布的父節點。如果你需要在 DOM 樹中明確且穩定地放置根節點（例如，當畫布與其他分層內容共用一個包裝元素時），請自行將其附加在 app.canvas 旁邊：

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

根節點使用絕對定位，其變形會透過 ResizeObserver 根據畫布的 getBoundingClientRect() 重新計算，因此 CSS 縮放的畫布無需額外處理即可保持對齊。

常見錯誤

[中等] 在自訂建置中遺漏 pixi.js/dom 匯入

預設的瀏覽器套件會自動註冊 DOMPipe，因此大多數應用程式不需要明確匯入。僅在選擇退出自動匯入時才需要：

await app.init({ skipExtensionImports: true });
// 現在你必須自行加入：
import "pixi.js/dom";

在自訂建置中若未註冊，DOMContainer 仍可匯入，但渲染器沒有管線可處理它；元素永遠不會與場景圖同步，也不會顯示。

[中等] 預期濾鏡、遮罩或混合模式會影響 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。

[中等] 不要在 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(...)）。

[低] 忘記為置中定位設定錨點

預設錨點為 (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