DOM 内容

阅读时间：3分钟更新于 2026-06-02 17:45

DOM 内容渲染插件支持将 HTML/CSS 片段渲染为纹理并挂载到场景中已有的元素上，适合在运行时动态拼装的内容（如金额、券面、营销文案），可直接复用前端 CSS 排版与字体能力。

插件引入

需要额外接入插件（请确保插件版本号与 @galcean/effects 版本号一致）。

$ npm i @galacean/effects-plugin-dom-content --save
import { Player } from '@galacean/effects';
// 确保在 @galacean/effects 引入之后再引入插件, 插件版本保持和 @galacean/effects 一致
import '@galacean/effects-plugin-dom-content';

基本使用

  1. 在编辑器中放置一个普通 Sprite 图片作为占位（例如命名为 place_holder），导出场景 JSON。

  1. 运行时通过 addComponent(DomContentComponent) 替换其纹理：
import { Player } from '@galacean/effects';
import '@galacean/effects-plugin-dom-content';
import { DomContentComponent } from '@galacean/effects-plugin-dom-content';

const player = new Player({ container });
const composition = await player.loadScene('https://.../scene.json');
const item = composition.items.find(i => i.name === 'place_holder')!;
const dom = item.addComponent(DomContentComponent);

dom.setContent(
      `<style>
  .card {
    width: 300px;
    height: 600px;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border-radius: 16px;
    display: flex;
    align-items: center;
    justify-content: center;
    color: #fff;
    font-family: -apple-system, BlinkMacSystemFont, sans-serif;
    font-size: 56px;
    font-weight: 800;
    box-sizing: border-box;
  }
</style>
  <div class="card">¥88.88</div>`, // html内容均为示例，请根据实际业务场景更改
  300,                      // 内容宽（CSS 像素）
  600,                      // 内容高
  window.devicePixelRatio,  // 倍率，建议传 dpr 以保证清晰度
);

可以得到以下渲染效果：

组件挂载后会自动检测同一 item 上的其它 MaskableGraphic 组件（如有），并用 DOM 渲染结果覆盖其原本的纹理；组件销毁时自动还原原始纹理。

API

DomContentComponent

成员

类型

默认值

说明

setContent(html, width?, height?, scale?)

method

—

设置/更新HTML，触发异步重渲染

htmlContent

string

''

当前 HTML

contentWidth/contentHeight

number

300/200

内容尺寸（CSS 像素）

contentScale

number

1

渲染倍率，最终纹理尺寸为 min(width × scale, 2048)

setContent 可多次调用，内部按版本号丢弃过期的异步结果，慢请求不会覆盖快请求。

进阶能力

外链字体 / 图片

setContent 阶段把 <img>、CSS background-image、@font-face 中的外链资源抓回来转为base64，资源服务需允许跨域（Access-Control-Allow-Origin: *）。

SVG 滤镜 / 渐变

CSS 中 filter: url(#glow)、fill: url(#grad) 这类引用会被 extractSVGDefs 从宿主文档中提取并嵌入。常见用法是在 index.html 全局放一个隐藏的 <svg><defs>...</defs></svg>，多个卡片复用同一套定义：

<linearGradient id="grad">...</linearGradient>
</defs>

注意事项

  • 单次 setContent 接受的 HTML 上限为 1MB，超出会被截断
  • 单张纹理上限 2048×2048，超出会按比例自动下调倍率
  • 出于安全考虑，以下内容会被自动移除：<script> <iframe> <object> <embed> <link>
    <base> <meta> <template> <noscript> 及嵌套的 <foreignObject>，on*
    事件属性，javascript: / vbscript: 协议，非 image/ font/ MIME 的 data: URL
  • 请开发人员注意，与设计师提前沟通好需要被替换成DOM卡片的占位图的名称、尺寸大小、长宽比例
    • 如果占位图和实际DOM内容的长宽比不一致，渲染效果可能会被拉伸/模糊
Preview