2026/9/18 15:29:53
FEATURED · 精选文章 
PixiJS v8 DOMContainer 实战指南在 WebGL 画布上无缝叠加 HTML 元素【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijsDOMContainer是 PixiJS v8 提供的实验性场景图节点它把原生 HTML 元素如input、textarea、iframe、video挂接到场景图上并逐帧用 CSStransform同步节点的位置、旋转、缩放与透明度。本指南以 skills/pixijs-scene-dom-container/SKILL.md 为骨架结合 src/dom 源码与 测试用例带你掌握其构造参数、DOMPipe注册机制、可见性同步原理与常见坑位从而在游戏 UI、交互表单与富文本叠加等场景中直接落地。认识 DOMContainer为什么需要它在纯 WebGL/WebGPU 渲染管线里输入框、iframe、视频这类“原生交互型”HTML 内容很难靠 PixiJS 自绘实现。DOMContainer的思路是保留 DOM 元素的原生能力但让它的位置由场景图驱动——你把它当作普通节点加入app.stage移动、旋转、缩放它它对应的 HTML 元素就会以 CSStransform跟随。它继承自ViewContainer见 DOMContainer.ts是场景图的叶子节点不要在其中嵌套 PixiJS 子节点。它只在浏览器 DOM 环境中可用Web Worker 中不可用Worker 没有 DOM 可叠加。官方标记为EXPERIMENTAL源码注释见 DOMContainer.tsAPI 可能在 minor 版本间变化。快速开始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);仓库自带的可运行示例 examples/dom-container_html_text-area.ts 展示了完整用法创建一个textarea以anchor: 0.5居中放在画布中心随后在app.ticker中每帧domContainer.rotation 0.01即可看到元素随场景图旋转——这正是“HTML 跟随场景图”的直观演示。构造选项DOMContainerOptionsDOMContainerOptions继承自ViewContainerOptions源码见 DOMContainer.ts因此所有Container通用选项position、scale、tint、label、filters、zIndex等依然有效可参考 constructor-options.md。叶子节点专属的选项只有两个OptionTypeDefaultDescriptionelementHTMLElementdocument.createElement(div)容器驱动的 HTML 元素。input、textarea、iframe、video、div等任意元素均可用省略时自动创建一个裸div源码 DOMContainer.ts。anchorPointData \| number0元素相对自身尺寸的原点。0为左上角0.5居中1为右下角传数字同时设置 x/y 两轴传{ x, y }可分别设置。anchor的 setter 实现DOMContainer.ts明确区分两种输入数字用Point.set(value)同设两轴点对象用copyFrom分别拷贝。测试 DOMContainer.test.ts 验证了数字、Point、PointData三种赋值方式。需要注意tint、filters、mask、blendMode虽然被接受但没有任何视觉效果——DOM 元素活在 WebGL/WebGPU 管线之外这类效果请用 CSS 实现。核心用法模式副作用导入与 DOMPipe 注册import pixi.js/dom; import { DOMContainer } from pixi.js;或者用合并导入一步完成注册与类导出import { DOMContainer } from pixi.js/dom;注册机制的底层依据src/dom/init.ts通过extensions.add(DOMPipe)把DOMPipe注册进扩展系统而DOMPipe.extension同时声明了WebGLPipes、WebGPUPipes、CanvasPipes三种渲染管线类型见 DOMPipe.ts所以三种渲染器都能处理它。默认浏览器包pixi.js在 browserAll.ts 中已经import ../dom/init开箱即用只有当你设置skipExtensionImports: true自定义构建或使用非浏览器 bundle 时才需要显式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上的变换会传播到元素上成为 CSStransform。DOMPipe在每次渲染后的postrender阶段DOMPipe.ts执行核心同步const wt domContainer.worldTransform; const ax domContainer.width * anchor.x; const ay domContainer.height * anchor.y; element.style.transformOrigin ${ax}px ${ay}px; element.style.transform matrix(${wt.a}, ${wt.b}, ${wt.c}, ${wt.d}, ${wt.tx - ax}, ${wt.ty - ay}); element.style.opacity domContainer.groupAlpha.toString();即先把世界变换矩阵worldTransform展开为matrix(...)再按锚点偏移量(ax, ay)修正transformOrigin和平移量。alpha含父级继承的组透明度groupAlpha每帧写入style.opacity。测试用例精确断言了这一点位置(100, 100)、锚点0.5、alpha0.5时最终得到transform: matrix(1, 0, 0, 1, 50, 50)、transformOrigin: 50px 50px、opacity: 0.5见 DOMContainer.test.ts。直接样式化元素const panel document.createElement(div); panel.innerHTML h2Score/h2p1500/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: noneDOMPipe.ts而每个挂载的元素默认被写成pointer-events: autoDOMPipe.ts。纯装饰性叠加层请覆盖为none这样其下方的画布仍能收到点击事件。可见性与清理dom.visible false; dom.visible true; dom.destroy();设置visible false或把DOMContainer移出场景图会将该元素从 DOM 中移除恢复可见性则重新挂载。DOMPipe.postrender中用globalDisplayStatus 0b111判断是否可显示不可见或已脱离父节点的容器会被移除并清理出内部数组DOMPipe.ts。destroy()会把元素从父节点移除并置空内部引用但HTML 元素本身被保留可重新挂到别处const element dom.element; dom.destroy(); document.body.appendChild(element);对应的destroy实现见 DOMContainer.ts测试也验证了元素会被移出父节点、element与_anchor被置空DOMContainer.test.ts。DOM 容器根节点domContainerRootDOMPipe使用一个共享根div承载所有挂载元素其样式为position: absolute; top: 0; left: 0; pointer-events: none; z-index: 1000DOMPipe.ts。它通过app.domContainerRootHTMLDivElement暴露getter 直接取renderer.renderPipes.dom?._domElementApplication.ts。所有DOMContainer元素都渲染在画布内容之上你无法把 DOM 元素穿插在 PixiJS 绘制调用之间。首次渲染存在已挂载的DOMContainer时pipe 会通过CanvasObserver.ensureAttached()自动把根节点追加到 canvas 的父节点下DOMPipe.ts如果 canvas 与其它分层内容共享一个 wrapper建议手动显式放置document.body.appendChild(app.canvas); document.body.appendChild(app.domContainerRoot);根节点使用绝对定位其变换由CanvasObserver依据 canvas 的getBoundingClientRect()计算公式为translate(tx, ty) scale(sx, sy)CanvasObserver.ts并通过ResizeObserver监听尺寸变化——CSS 缩放的画布无需额外处理即可保持对齐。测试验证了 canvas 被 CSS 放大到 2 倍时根节点变换为translate(0px, 0px) scale(2, 2)DOMContainer.test.ts。若环境不支持ResizeObserverCanvasObserver会回退到Ticker.shared的UPDATE_PRIORITY.HIGH回调持续同步CanvasObserver.ts。常见错误[MEDIUM] 自定义构建漏掉 pixi.js/dom 导入默认浏览器包已自动注册DOMPipe多数应用无需显式导入。只有当你主动关闭自动导入时才需要await app.init({ skipExtensionImports: true }); // 此时必须自行导入 import pixi.js/dom;未注册时DOMContainer仍可导入但渲染器没有对应的 pipe 处理它元素永远不会与场景图同步也永远不会显示。[MEDIUM] 期望 filters / masks / blendMode 作用于 DOM 元素错误写法const dom new DOMContainer(); dom.filters [new BlurFilter()];正确写法dom.element.style.filter blur(4px);DOM 元素是通过 CSS transform 定位的 HTML 叠加层位于 WebGL/WebGPU 管线之外PixiJS 的滤镜、遮罩、混合模式对它们无效。请在元素上直接使用 CSSfilter与 CSSmix-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 子对象请与它一起放进普通ContainerHTML 嵌套内容请在元素内部自行element.appendChild(...)。[LOW] 忘记为居中定位设置锚点默认锚点是(0, 0)即元素左上角对齐到容器位置。要让 UI 元素以场景图位置为中心请设置anchor: 0.5const dom new DOMContainer({ element: myElement, anchor: 0.5 }); dom.position.set(400, 300);与其它技能的配合pixijs-scene-core-concepts场景图基础父级变换、世界变换。pixijs-scene-container用普通Container包裹多个 DOM 叠加层。pixijs-events画布与 DOM 上的指针事件分工。pixijs-accessibility屏幕阅读器叠加层方案。源码研读指引想深入理解实现可依次阅读DOMContainer.ts节点类本体含anchorgetter/setter、elementsetter触发onViewUpdate、基于offsetWidth/offsetHeight的updateBounds。DOMPipe.ts渲染管线实现含扩展注册、共享根节点、postrender阶段的世界变换矩阵同步与可见性清理。CanvasObserver.ts根节点与 canvas 的坐标/缩放对齐ResizeObserverTicker回退。DOMContainer.test.ts默认值、anchor 赋值、变换矩阵、CSS 缩放画布对齐等行为的权威验证。dom-container_html_text-area.ts可直接运行的完整示例。【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PixiJS v8 DOMContainer 实战指南：在 WebGL 画布上无缝叠加 HTML 元素
PixiJS v8 DOMContainer 实战指南在 WebGL 画布上无缝叠加 HTML 元素【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijsDOMContainer是 PixiJS v8 提供的实验性场景图节点它把原生 HTML 元素如input、textarea、iframe、video挂接到场景图上并逐帧用 CSStransform同步节点的位置、旋转、缩放与透明度。本指南以 skills/pixijs-scene-dom-container/SKILL.md 为骨架结合 src/dom 源码与 测试用例带你掌握其构造参数、DOMPipe注册机制、可见性同步原理与常见坑位从而在游戏 UI、交互表单与富文本叠加等场景中直接落地。认识 DOMContainer为什么需要它在纯 WebGL/WebGPU 渲染管线里输入框、iframe、视频这类“原生交互型”HTML 内容很难靠 PixiJS 自绘实现。DOMContainer的思路是保留 DOM 元素的原生能力但让它的位置由场景图驱动——你把它当作普通节点加入app.stage移动、旋转、缩放它它对应的 HTML 元素就会以 CSStransform跟随。它继承自ViewContainer见 DOMContainer.ts是场景图的叶子节点不要在其中嵌套 PixiJS 子节点。它只在浏览器 DOM 环境中可用Web Worker 中不可用Worker 没有 DOM 可叠加。官方标记为EXPERIMENTAL源码注释见 DOMContainer.tsAPI 可能在 minor 版本间变化。快速开始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);仓库自带的可运行示例 examples/dom-container_html_text-area.ts 展示了完整用法创建一个textarea以anchor: 0.5居中放在画布中心随后在app.ticker中每帧domContainer.rotation 0.01即可看到元素随场景图旋转——这正是“HTML 跟随场景图”的直观演示。构造选项DOMContainerOptionsDOMContainerOptions继承自ViewContainerOptions源码见 DOMContainer.ts因此所有Container通用选项position、scale、tint、label、filters、zIndex等依然有效可参考 constructor-options.md。叶子节点专属的选项只有两个OptionTypeDefaultDescriptionelementHTMLElementdocument.createElement(div)容器驱动的 HTML 元素。input、textarea、iframe、video、div等任意元素均可用省略时自动创建一个裸div源码 DOMContainer.ts。anchorPointData \| number0元素相对自身尺寸的原点。0为左上角0.5居中1为右下角传数字同时设置 x/y 两轴传{ x, y }可分别设置。anchor的 setter 实现DOMContainer.ts明确区分两种输入数字用Point.set(value)同设两轴点对象用copyFrom分别拷贝。测试 DOMContainer.test.ts 验证了数字、Point、PointData三种赋值方式。需要注意tint、filters、mask、blendMode虽然被接受但没有任何视觉效果——DOM 元素活在 WebGL/WebGPU 管线之外这类效果请用 CSS 实现。核心用法模式副作用导入与 DOMPipe 注册import pixi.js/dom; import { DOMContainer } from pixi.js;或者用合并导入一步完成注册与类导出import { DOMContainer } from pixi.js/dom;注册机制的底层依据src/dom/init.ts通过extensions.add(DOMPipe)把DOMPipe注册进扩展系统而DOMPipe.extension同时声明了WebGLPipes、WebGPUPipes、CanvasPipes三种渲染管线类型见 DOMPipe.ts所以三种渲染器都能处理它。默认浏览器包pixi.js在 browserAll.ts 中已经import ../dom/init开箱即用只有当你设置skipExtensionImports: true自定义构建或使用非浏览器 bundle 时才需要显式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上的变换会传播到元素上成为 CSStransform。DOMPipe在每次渲染后的postrender阶段DOMPipe.ts执行核心同步const wt domContainer.worldTransform; const ax domContainer.width * anchor.x; const ay domContainer.height * anchor.y; element.style.transformOrigin ${ax}px ${ay}px; element.style.transform matrix(${wt.a}, ${wt.b}, ${wt.c}, ${wt.d}, ${wt.tx - ax}, ${wt.ty - ay}); element.style.opacity domContainer.groupAlpha.toString();即先把世界变换矩阵worldTransform展开为matrix(...)再按锚点偏移量(ax, ay)修正transformOrigin和平移量。alpha含父级继承的组透明度groupAlpha每帧写入style.opacity。测试用例精确断言了这一点位置(100, 100)、锚点0.5、alpha0.5时最终得到transform: matrix(1, 0, 0, 1, 50, 50)、transformOrigin: 50px 50px、opacity: 0.5见 DOMContainer.test.ts。直接样式化元素const panel document.createElement(div); panel.innerHTML h2Score/h2p1500/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: noneDOMPipe.ts而每个挂载的元素默认被写成pointer-events: autoDOMPipe.ts。纯装饰性叠加层请覆盖为none这样其下方的画布仍能收到点击事件。可见性与清理dom.visible false; dom.visible true; dom.destroy();设置visible false或把DOMContainer移出场景图会将该元素从 DOM 中移除恢复可见性则重新挂载。DOMPipe.postrender中用globalDisplayStatus 0b111判断是否可显示不可见或已脱离父节点的容器会被移除并清理出内部数组DOMPipe.ts。destroy()会把元素从父节点移除并置空内部引用但HTML 元素本身被保留可重新挂到别处const element dom.element; dom.destroy(); document.body.appendChild(element);对应的destroy实现见 DOMContainer.ts测试也验证了元素会被移出父节点、element与_anchor被置空DOMContainer.test.ts。DOM 容器根节点domContainerRootDOMPipe使用一个共享根div承载所有挂载元素其样式为position: absolute; top: 0; left: 0; pointer-events: none; z-index: 1000DOMPipe.ts。它通过app.domContainerRootHTMLDivElement暴露getter 直接取renderer.renderPipes.dom?._domElementApplication.ts。所有DOMContainer元素都渲染在画布内容之上你无法把 DOM 元素穿插在 PixiJS 绘制调用之间。首次渲染存在已挂载的DOMContainer时pipe 会通过CanvasObserver.ensureAttached()自动把根节点追加到 canvas 的父节点下DOMPipe.ts如果 canvas 与其它分层内容共享一个 wrapper建议手动显式放置document.body.appendChild(app.canvas); document.body.appendChild(app.domContainerRoot);根节点使用绝对定位其变换由CanvasObserver依据 canvas 的getBoundingClientRect()计算公式为translate(tx, ty) scale(sx, sy)CanvasObserver.ts并通过ResizeObserver监听尺寸变化——CSS 缩放的画布无需额外处理即可保持对齐。测试验证了 canvas 被 CSS 放大到 2 倍时根节点变换为translate(0px, 0px) scale(2, 2)DOMContainer.test.ts。若环境不支持ResizeObserverCanvasObserver会回退到Ticker.shared的UPDATE_PRIORITY.HIGH回调持续同步CanvasObserver.ts。常见错误[MEDIUM] 自定义构建漏掉 pixi.js/dom 导入默认浏览器包已自动注册DOMPipe多数应用无需显式导入。只有当你主动关闭自动导入时才需要await app.init({ skipExtensionImports: true }); // 此时必须自行导入 import pixi.js/dom;未注册时DOMContainer仍可导入但渲染器没有对应的 pipe 处理它元素永远不会与场景图同步也永远不会显示。[MEDIUM] 期望 filters / masks / blendMode 作用于 DOM 元素错误写法const dom new DOMContainer(); dom.filters [new BlurFilter()];正确写法dom.element.style.filter blur(4px);DOM 元素是通过 CSS transform 定位的 HTML 叠加层位于 WebGL/WebGPU 管线之外PixiJS 的滤镜、遮罩、混合模式对它们无效。请在元素上直接使用 CSSfilter与 CSSmix-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 子对象请与它一起放进普通ContainerHTML 嵌套内容请在元素内部自行element.appendChild(...)。[LOW] 忘记为居中定位设置锚点默认锚点是(0, 0)即元素左上角对齐到容器位置。要让 UI 元素以场景图位置为中心请设置anchor: 0.5const dom new DOMContainer({ element: myElement, anchor: 0.5 }); dom.position.set(400, 300);与其它技能的配合pixijs-scene-core-concepts场景图基础父级变换、世界变换。pixijs-scene-container用普通Container包裹多个 DOM 叠加层。pixijs-events画布与 DOM 上的指针事件分工。pixijs-accessibility屏幕阅读器叠加层方案。源码研读指引想深入理解实现可依次阅读DOMContainer.ts节点类本体含anchorgetter/setter、elementsetter触发onViewUpdate、基于offsetWidth/offsetHeight的updateBounds。DOMPipe.ts渲染管线实现含扩展注册、共享根节点、postrender阶段的世界变换矩阵同步与可见性清理。CanvasObserver.ts根节点与 canvas 的坐标/缩放对齐ResizeObserverTicker回退。DOMContainer.test.ts默认值、anchor 赋值、变换矩阵、CSS 缩放画布对齐等行为的权威验证。dom-container_html_text-area.ts可直接运行的完整示例。【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
