# HTMLSource — DOM 渲染为纹理

PixiJS v8.19 引入了实验性的 HTML-in-Canvas 支持，通过 HTMLSource 可以把可交互的 DOM 元素实时渲染成 GPU 纹理，同时保留输入框编辑、按钮点击、CSS 动画等原生能力。

# 什么是 HTMLSource？ {#what-is-htmlsource}

传统做法里，PixiJS 只能渲染 Canvas/WebGL 图形，复杂 UI 往往要手写或用 DOM 覆盖层。HTMLSource 则把两者打通：

特性	说明
实时镜像	DOM 变化自动同步到 Sprite 纹理
保持交互	输入框可编辑、链接可点击
可选导入	通过 `pixi.js/html-source` 按需加载，不影响现有项目
快照模式	`ElementImageSource` 可捕获不可变快照

需要 PixiJS v8.19+，并依赖浏览器 HTML-in-Canvas 实验 API（目前以 Chrome 为主）。

# 基本用法 {#basic-usage}

import { Application, Sprite, Texture } from 'pixi.js';
// npm 项目：import { HTMLSource } from 'pixi.js/html-source' 会自动执行 init
import { HTMLSource } from 'pixi.js/html-source';

const app = new Application();
await app.init({ width: 800, height: 600, backgroundColor: 0x1a1a2e });
document.body.appendChild(app.canvas);

// 1. 创建 DOM 元素
const card = document.createElement('div');
card.innerHTML = `
  <label>昵称 <input type="text" value="PixiJS" /></label>
  <button type="button">提交</button>
`;
card.style.cssText = 'padding:16px;background:#fff;border-radius:12px;';

// 2. 必须是 canvas 的直接子元素
app.canvas.appendChild(card);

// 3. 用 HTMLSource 创建纹理（注意：CDN 分包场景请用 new Texture({ source })）
const source = new HTMLSource({ resource: card, autoUpdate: true });
const texture = new Texture({ source });
const sprite = new Sprite(texture);

sprite.x = 100;
sprite.y = 80;
app.stage.addChild(sprite);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 关键约束 {#constraints}

DOM 必须是 app.canvas 的直接子元素，否则无法捕获
需要显式 import { HTMLSource } from 'pixi.js/html-source' 注册扩展
若 Sprite 发生位移/旋转，需同步更新 DOM 的 transform，才能保证点击区域对齐（见 Demo）

# HTMLSource vs ElementImageSource {#html-vs-snapshot}

import { HTMLSource, ElementImageSource } from 'pixi.js/html-source';

// 实时、可交互 — 适合表单、动态 UI
const live = new HTMLSource({ resource: element, autoUpdate: true });

// 不可变快照 — 适合截图、缩略图
const snapshot = app.canvas.captureElementImage(element);
const frozen = new ElementImageSource({ resource: snapshot, autoClose: true });

1
2
3
4
5
6
7
8

类型	适用场景	是否可交互
`HTMLSource`	表单、实时 UI、CSS 动画	✅
`ElementImageSource`	截图预览、静态卡片	❌

# 配合滤镜 {#with-filters}

HTMLSource 纹理与普通 Sprite 一样，可以叠加滤镜：

import { BlurFilter } from 'pixi.js';

const blur = new BlurFilter({ strength: 2 });
sprite.filters = [blur];

// 滑块控制模糊强度
slider.addEventListener('input', () => {
  blur.strength = Number(slider.value) / 25;
});

1
2
3
4
5
6
7
8
9

# Texture.from 自动识别 {#texture-from}

导入 pixi.js/html-source 后，Texture.from 会把 HTML 元素解析为 HTMLSource：

import 'pixi.js/html-source';

// 以前会抛错，现在自动走 HTMLSource
const texture = Texture.from(document.querySelector('#my-card'));

1
2
3
4

# CDN 引入 {#cdn}

<!-- 浏览器 Demo：用 UMD 包，避免 ESM 裸模块依赖无法解析 -->
<script src="https://cdn.jsdelivr.net/npm/pixi.js@8.19.0/dist/pixi.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/pixi.js@8.19.0/dist/packages/html-source.min.js"></script>
<script>
  const { Application, Sprite, Texture, HTMLSource } = PIXI;
  // html-source.min.js 会自动注册扩展
</script>

1
2
3
4
5
6
7

# 浏览器支持 {#browser-support}

HTMLSource 依赖 HTML-in-Canvas 实验特性。Demo 会自动检测：支持则走 GPU 镜像，不支持则降级为 PixiJS + DOM 覆盖层 方案（交互仍可用）。

# 开启 Chrome 实验特性

地址栏输入 chrome://flags/#canvas-draw-element
将 Enable the new drawElement API for Canvas 设为 Enabled
重启浏览器

Brave 用户可用 brave://flags/#canvas-draw-element。也支持 Chrome Canary / Brave Stable（Chromium 147+）。

控制台里 content_main.js Failed to fetch 通常来自浏览器扩展，与 Demo 无关，可忽略。

推荐环境：

Chrome Canary / Brave + 上述 Flag
生产环境使用前请先在目标浏览器实测

# 在线 Demo {#online-demo}

拖动卡片、编辑输入框、拖动滑块调整模糊 — DOM 与 PixiJS 纹理实时同步。

← 小游戏实战