Back to Details

pixijs-scene-dom-container

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
DOMContainer
positions an HTML element over the PixiJS canvas and drives its CSS transform from the scene graph. Use it for native inputs, iframes, videos, or rich HTML that needs to follow a display object's position. The default 
pixi.js
browser bundle registers the 
DOMPipe
automatically; custom builds add a side-effect 
import 'pixi.js/dom'
.
DOMContainer
is marked EXPERIMENTAL in PixiJS v8. The API may change between minor releases.
Assumes familiarity with 
pixijs-scene-core-concepts
. 
DOMContainer
extends 
ViewContainer
, so it's a leaf: do not nest PixiJS children inside it. Nest DOM content inside the HTML element itself, or wrap multiple 
DOMContainer
instances in a 
Container
. Not available in Web Workers; a worker has no DOM to overlay.
DOMContainer
用于将HTML元素定位在PixiJS画布上方，并通过场景图控制其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环境下不可用，因为Worker没有可叠加的DOM。

Quick Start

快速开始

ts
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);
Related skills: 
pixijs-scene-core-concepts
(scene graph basics), 
pixijs-scene-container
(wrap multiple DOM overlays), 
pixijs-events
(pointer handling on canvas vs DOM), 
pixijs-accessibility
(screen-reader overlays).
ts
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
（屏幕阅读器叠加层）。

Constructor options

构造函数选项

All 
Container
options (
position
, 
scale
, 
tint
, 
label
, 
filters
, 
zIndex
, etc.) are also valid here — see 
skills/pixijs-scene-core-concepts/references/constructor-options.md
.
Leaf-specific options added by 
DOMContainerOptions
:
OptionTypeDefaultDescription
element
HTMLElement
document.createElement('div')
The HTML element the container drives. Any element is valid: 
input
, 
textarea
, 
iframe
, 
video
, 
div
, etc. If omitted, a bare 
<div>
is created.
anchor
PointData | number
0
Origin of the element relative to its own dimensions. 
0
is top-left, 
0.5
centers, 
1
is bottom-right. A single number sets both axes; 
{ x, y }
sets each independently.
tint
, 
filters
, 
mask
, and 
blendMode
are accepted (inherited from 
Container
) but have no visual effect — DOM elements live outside the WebGL/WebGPU pipeline. Style the element via CSS for those effects.
所有
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轴；
{ x, y }
对象可分别设置两个轴的锚点。
tint
、
filters
、
mask
和
blendMode
是继承自
Container
的选项，但对DOM元素没有视觉效果——因为DOM元素位于WebGL/WebGPU渲染管线之外。如需这些效果，请通过CSS为元素设置样式。

Core Patterns

核心模式

Setup and the side-effect import

设置与副作用导入

ts
import "pixi.js/dom";
import { DOMContainer } from "pixi.js";
Or use the combined import that registers the pipe and re-exports the class:
ts
import { DOMContainer } from "pixi.js/dom";
The default 
pixi.js
browser bundle already imports 
pixi.js/dom
for you via 
browserAll.ts
, so 
DOMContainer
works out of the box in a typical browser app. You only need the explicit 
import 'pixi.js/dom'
line when you set 
skipExtensionImports: true
(custom builds) or when running under a non-browser bundle.
ts
import "pixi.js/dom";

import { DOMContainer } from "pixi.js";
或者使用组合导入，自动注册管道并导出类：
ts
import { DOMContainer } from "pixi.js/dom";
默认的
pixi.js
浏览器包已通过
browserAll.ts
自动导入
pixi.js/dom
，因此在典型的浏览器应用中
DOMContainer
可直接使用。只有当你设置
skipExtensionImports: true
（自定义构建）或在非浏览器包环境下运行时，才需要显式添加
import 'pixi.js/dom'
语句。

Transforms, anchor, and alpha

变换、锚点与透明度

ts
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;
Transforms on the 
DOMContainer
propagate to the element as CSS 
transform
. 
anchor
shifts the element's origin relative to its own dimensions: 
0
is top-left, 
0.5
centers, 
1
is bottom-right. A single number sets both axes; an object 
{ x, y }
sets each independently. 
alpha
(including inherited parent alpha) is written to the element's 
style.opacity
every frame.
If no 
element
is provided, a 
<div>
is created by default.
ts
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>
元素。

Styling the element directly

直接为元素设置样式

ts
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 does not interfere with CSS styling on the element. The shared root 
<div>
is set to 
pointer-events: none
, and each attached element defaults to 
pointer-events: auto
. Override to 
none
on purely decorative overlays so the canvas still receives clicks underneath them.
ts
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
，这样画布仍能接收到下方的点击事件。

Visibility and cleanup

可见性与清理

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

dom.destroy();
Setting 
visible = false
or removing the 
DOMContainer
from the scene graph detaches the element from the DOM. Restoring visibility re-attaches it. 
destroy()
removes the element from its parent node and nulls internal references; the HTML element itself is preserved, so you can re-attach it elsewhere:
ts
const element = dom.element;
dom.destroy();
document.body.appendChild(element);
ts
dom.visible = false;
dom.visible = true;

dom.destroy();
设置
visible = false
或从场景图中移除
DOMContainer
会将元素从DOM中分离。恢复可见性会重新附加元素。
destroy()
方法会将元素从其父节点移除并清空内部引用；HTML元素本身会被保留，因此你可以将其重新附加到其他位置：
ts
const element = dom.element;
dom.destroy();
document.body.appendChild(element);

The DOM container root

DOM容器根节点

The DOMPipe uses a shared root 
<div>
with 
z-index: 1000
that hosts every attached element. It's exposed as 
app.domContainerRoot
(an 
HTMLDivElement
). All 
DOMContainer
elements render above canvas content; you can't interleave DOM elements between PixiJS draw calls.
On the first render that has an attached 
DOMContainer
, the pipe automatically appends the root to the canvas's parent node. Append it yourself next to 
app.canvas
if you need explicit, stable placement in the DOM tree (for example, when the canvas shares a wrapper with other layered content):
ts
document.body.appendChild(app.canvas);
document.body.appendChild(app.domContainerRoot);
The root uses absolute positioning and its transform is recomputed from the canvas 
getBoundingClientRect()
via a 
ResizeObserver
, so CSS-scaled canvases stay aligned without extra work.
DOMPipe使用一个共享的根节点
<div>
（
z-index: 1000
）来托管所有附加的元素。它可以通过
app.domContainerRoot
（一个
HTMLDivElement
）访问。所有
DOMContainer
元素都会渲染在画布内容上方；你无法在PixiJS绘制调用之间插入DOM元素。
当首次渲染附加了
DOMContainer
的内容时，管道会自动将根节点附加到画布的父节点。如果你需要在DOM树中明确、稳定的位置（例如当画布与其他分层内容共享一个容器时），可以手动将其附加到
app.canvas
旁边：
ts
document.body.appendChild(app.canvas);
document.body.appendChild(app.domContainerRoot);
根节点使用绝对定位，其变换会通过
ResizeObserver
从画布的
getBoundingClientRect()
重新计算，因此经过CSS缩放的画布无需额外操作即可保持对齐。

Common Mistakes

常见错误

[MEDIUM] Missing the pixi.js/dom import in custom builds

[MEDIUM] 自定义构建中缺少pixi.js/dom导入

The default browser bundle auto-registers 
DOMPipe
, so most apps do not need an explicit import. It is only required when you opt out of auto-imports:
ts
await app.init({ skipExtensionImports: true });
// Now you must add this yourself:
import "pixi.js/dom";
Without registration under a custom build, 
DOMContainer
is still importable but the renderer has no pipe to process it; elements never synchronize with the scene graph and never appear.
默认浏览器包会自动注册
DOMPipe
，因此大多数应用无需显式导入。只有当你禁用自动导入时才需要添加：
ts
await app.init({ skipExtensionImports: true });
// 现在你必须手动添加：
import "pixi.js/dom";
在自定义构建环境下，如果未注册
DOMPipe
，
DOMContainer
仍然可以导入，但渲染器没有处理它的管道；元素将无法与场景图同步，也不会显示出来。

[MEDIUM] Expecting filters, masks, or blend modes to affect DOM elements

[MEDIUM] 认为滤镜、遮罩或混合模式会影响DOM元素

Wrong:
ts
const dom = new DOMContainer();
dom.filters = [new BlurFilter()];
Correct:
ts
dom.element.style.filter = "blur(4px)";
DOM elements are HTML overlays positioned via CSS transforms; they exist outside the WebGL/WebGPU pipeline. PixiJS filters, masks, and blend modes have no effect on them. Use CSS filters and CSS 
mix-blend-mode
on the element directly.
错误示例：
ts
const dom = new DOMContainer();
dom.filters = [new BlurFilter()];
正确示例：
ts
dom.element.style.filter = "blur(4px)";
DOM元素是通过CSS变换定位的HTML叠加层；它们位于WebGL/WebGPU渲染管线之外。PixiJS的滤镜、遮罩和混合模式对它们没有效果。请直接在元素上使用CSS滤镜和CSS 
mix-blend-mode
。

[MEDIUM] Do not nest children inside a DOMContainer

[MEDIUM] 不要在DOMContainer中嵌套子元素

Wrong:
ts
const dom = new DOMContainer();
dom.addChild(new Sprite(texture));
Correct:
ts
const group = new Container();
group.addChild(dom, new Sprite(texture));
DOMContainer
extends 
ViewContainer
, which sets 
allowChildren = false
. It is a leaf in the PixiJS scene graph. For PixiJS children, wrap the 
DOMContainer
alongside them in a plain 
Container
. For nested HTML, nest inside the element itself (
element.appendChild(...)
).
错误示例：
ts
const dom = new DOMContainer();
dom.addChild(new Sprite(texture));
正确示例：
ts
const group = new Container();
group.addChild(dom, new Sprite(texture));
DOMContainer
继承自
ViewContainer
，后者设置了
allowChildren = false
。它是PixiJS场景图中的叶子节点。如需添加PixiJS子元素，请将
DOMContainer
与它们一起包装在普通的
Container
中。如需嵌套DOM内容，请直接在元素内部嵌套（
element.appendChild(...)
）。

[LOW] Forgetting to set anchor for centered positioning

[LOW] 忘记设置锚点以实现居中定位

The default anchor is 
(0, 0)
, placing the element's top-left corner at the container's position. For centering a UI element on its scene-graph position, set 
anchor: 0.5
:
ts
const dom = new DOMContainer({ element: myElement, anchor: 0.5 });
dom.position.set(400, 300);
默认锚点为
(0, 0)
，即元素的左上角会对齐容器的位置。如果要让UI元素相对于场景图位置居中，请设置
anchor: 0.5
：
ts
const dom = new DOMContainer({ element: myElement, anchor: 0.5 });
dom.position.set(400, 300);

API Reference

API参考