Web 图形与 3D / 系统课时

CSS2DRenderer 放置模型标签

CSS2DRenderer 放置模型标签

在 Three.js 产品展示中,名称和说明标签需要跟随模型移动,同时保持网页文字清晰。本课使用 CSS2DObject 将 HTML 标签绑定到三维模型,通过 CSS2DRenderer 同步投影到屏幕,并处理标签锚点、容器尺寸、网页元素遮挡和鼠标交互冲突。

学习目标

  • 理解 CSS2DObject 与 CSS2DRenderer 的职责,以及它们与 WebGLRenderer 的关系。
  • 为模型绑定包含名称和说明的 HTML 标签,实现相机移动时的同步定位。
  • 正确处理标签锚点、响应式尺寸、CSS 层级和指针事件。

理解双渲染器的协作关系

CSS2DRenderer 是 Three.js 的附加渲染器,专门将场景中的 CSS2DObject 转换为屏幕上的 HTML 元素位置。它不绘制三维网格,也不替代 WebGLRenderer。

一个产品展示页面通常同时使用两套渲染器:

  • WebGLRenderer:绘制模型、材质、灯光和三维场景。
  • CSS2DRenderer:计算标签锚点在屏幕上的位置,并管理对应的 DOM 元素。
  • CSS2DObject:将 HTML 元素包装成 Object3D,使标签可以挂载到模型节点并继承父节点的变换。

例如,一个高度为 1.6 个世界单位的产品模型,其名称标签可以放在模型局部坐标 (0, 1.02, 0)。当模型平移或相机旋转时,标签会跟随投影位置变化,而文字仍按 CSS 像素尺寸显示。

三维模型标签绑定、相机投影和网页渲染层的关系

CSS2DRenderer 主要支持平移和二维旋转,不会把 HTML 标签真正变成具有三维透视缩放的平面。对于产品名称、零件编号、展品介绍和设备状态标识,这通常正是需要的效果。

创建可运行的产品标签页面

下面使用 Three.js 0.186.1、原生 HTML 和浏览器 Import Map 构建示例,不需要额外的 UI 框架。页面包含一个可移动产品方块、绑定在模型上方的双行标签,以及一个始终显示在标签层之上的网页按钮。

将代码保存为 index.html,在文件所在目录运行 python3 -m http.server 8000,然后通过浏览器访问 http://localhost:8000。首次加载需要能够访问示例中的 CDN。

html
<!doctype html>
<html lang='zh-CN'>
<head>
  <meta charset='UTF-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>Three.js 模型标签</title>
  <style>
    body { margin: 0; font-family: Arial, sans-serif; }
    #stage {
      position: relative;
      width: 100%;
      height: 480px;
      overflow: hidden;
      background: #f4f8fb;
    }
    .product-label {
      display: grid;
      gap: 4px;
      padding: 9px 14px;
      border: 1px solid #9dc9c5;
      border-radius: 8px;
      background: rgba(255, 255, 255, 0.95);
      color: #263b4c;
      white-space: nowrap;
      pointer-events: none;
    }
    .product-label small { color: #607481; }
    .toolbar {
      position: absolute;
      top: 16px;
      right: 16px;
      z-index: 2;
      padding: 8px 12px;
      cursor: pointer;
    }
  </style>
  <script type='importmap'>
  {
    "imports": {
      "three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.1/examples/jsm/"
    }
  }
  </script>
</head>
<body>
  <div id='stage'>
    <button id='changeColor' class='toolbar'>切换模型颜色</button>
  </div>
  <script type='module'>
    import * as THREE from 'three';
    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
    import { CSS2DRenderer, CSS2DObject } from 'three/addons/renderers/CSS2DRenderer.js';

    const stage = document.querySelector('#stage');
    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
    camera.position.set(4, 3, 6);

    const renderer = new THREE.WebGLRenderer({ antialias: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    stage.appendChild(renderer.domElement);

    // 标签层覆盖在画布之上,但不阻断画布的鼠标操作。
    const labelRenderer = new CSS2DRenderer();
    labelRenderer.domElement.style.cssText =
      'position:absolute;top:0;left:0;z-index:1;pointer-events:none';
    stage.appendChild(labelRenderer.domElement);

    const controls = new OrbitControls(camera, renderer.domElement);
    controls.target.set(0, 0.8, 0);
    controls.enableDamping = true;

    scene.add(new THREE.HemisphereLight(0xffffff, 0x64748b, 2));
    const light = new THREE.DirectionalLight(0xffffff, 2);
    light.position.set(3, 5, 4);
    scene.add(light);

    const material = new THREE.MeshStandardMaterial({
      color: 0x279d96,
      metalness: 0.25,
      roughness: 0.35
    });
    const product = new THREE.Mesh(
      new THREE.BoxGeometry(1.6, 1.6, 1.6),
      material
    );
    product.position.y = 0.8;
    scene.add(product);

    // 用 textContent 写入业务文字,避免把外部数据当作 HTML 解析。
    const labelElement = document.createElement('div');
    labelElement.className = 'product-label';
    const name = document.createElement('strong');
    name.textContent = '展示机型 A';
    const description = document.createElement('small');
    description.textContent = '铝合金外壳 · 演示模型';
    labelElement.append(name, description);

    const label = new CSS2DObject(labelElement);
    label.position.set(0, 1.02, 0);
    label.center.set(0.5, 1);
    product.add(label);

    document.querySelector('#changeColor').addEventListener('click', () => {
      material.color.setHex(0xea9d62);
    });

    // 两个渲染器和相机必须使用一致的视口尺寸。
    function resize() {
      const width = stage.clientWidth;
      const height = stage.clientHeight;
      camera.aspect = width / height;
      camera.updateProjectionMatrix();
      renderer.setSize(width, height);
      labelRenderer.setSize(width, height);
    }
    new ResizeObserver(resize).observe(stage);
    resize();

    function animate(time) {
      // 让产品左右移动,直观验证标签继承模型的位置变换。
      product.position.x = Math.sin(time * 0.0007) * 0.5;
      controls.update();
      renderer.render(scene, camera);
      labelRenderer.render(scene, camera);
    }
    renderer.setAnimationLoop(animate);
  </script>
</body>
</html>

预期结果: 浏览器显示一个青绿色三维方块,其上方有白色圆角标签,第一行是“展示机型 A”,第二行是“铝合金外壳 · 演示模型”。方块左右移动时,标签同步跟随;拖动鼠标可旋转观察视角。右上角“切换模型颜色”按钮始终可点击,点击后模型变为橙色。

这里的关键操作是 product.add(label)。标签使用模型局部坐标,不需要每帧手工计算屏幕上的 left 和 top。在动画循环中调用 labelRenderer.render(scene, camera),即可更新 HTML 标签的位置。

控制标签锚点与网页遮挡

CSS2D 标签的定位要同时考虑三维局部坐标、二维锚点和网页层级。三者分别解决“标签跟谁走”“文字相对锚点怎么摆”和“谁显示在谁上面”的问题。

模型局部锚点

示例方块高度为 1.6,局部顶部位于 y = 0.8。标签使用 position.set(0, 1.02, 0),因此锚点高出方块顶部 0.22 个世界单位。

label.center.set(0.5, 1) 表示使用标签 DOM 矩形的底边中心对准三维锚点。这样标签宽度变化时仍保持水平居中,并向锚点上方展开。

如果需要在模型侧面标注零件,可以改为 (0.8, 0, 0) 等局部位置。注意:这些数值受模型实际单位、缩放和父节点变换影响,不是 CSS 像素。

渲染层与操作层

示例的 #stage 设置 position: relative,使 CSS2DRenderer 的绝对定位层以同一个容器为参照。两套渲染器使用相同宽高,避免标签与模型投影发生偏移。

层级设置遵循以下规则:

  1. WebGL Canvas 位于底层,负责三维画面和 OrbitControls 指针事件。
  2. CSS2DRenderer 的 DOM 容器设置 z-index: 1,负责覆盖绘制标签。
  3. 页面操作按钮设置 z-index: 2,保证产品配置、关闭和切换按钮显示在标签之上。
  4. 标签层设置 pointer-events: none,使鼠标拖动和点击能够穿透非交互标签到达画布。

如果标签自身需要按钮或链接,可以对具体交互元素设置 pointer-events: auto,并根据实际交互阻止不必要的事件传播。此时鼠标位于交互标签上时,不应期待拖动事件仍自动传递给 WebGL Canvas。

检查标签是否真正同步

完成页面后,按照下面的顺序进行验收,能够快速区分场景绑定错误和 CSS 层级错误。

  1. 移动模型:观察方块左右移动时标签是否保持在顶部,验证父子节点绑定。
  2. 旋转相机:拖动鼠标改变视角,确认标签始终朝向屏幕并跟随模型投影位置。
  3. 改变窗口宽度:确认模型和标签仍然对齐,验证 camera.aspect、renderer.setSize() 与 labelRenderer.setSize() 同步更新。
  4. 检查操作按钮:点击右上角按钮,确认模型变色,验证 DOM 层级与指针事件配置。

常见异常可以按下面的方法处理:

现象 主要检查点 修正方法
标签完全不显示 标签是否挂入场景树,是否调用第二次渲染 确认 product.add(label) 和 labelRenderer.render(scene, camera)
标签跟随相机但不跟随模型 标签是否直接加入了 scene 将标签挂到对应模型节点,使用局部坐标
缩放窗口后标签偏移 两套渲染器尺寸或定位容器不一致 同步更新宽高,检查容器的定位与 CSS 偏移
无法拖动模型视角 标签层拦截指针事件 对非交互标签层设置 pointer-events: none
网页按钮被标签盖住 CSS 堆叠顺序不正确 为按钮所在层设置更高的 z-index,检查祖先堆叠上下文
标签透过前方模型显示 CSS 标签不参与三维深度测试 根据遮挡射线检测结果控制标签显隐

还要注意,CSS2DRenderer 官方实现要求浏览器和显示缩放处于 100% 的正常使用条件;在非 100% 缩放、对画布额外应用 CSS transform: scale(...) 或将两个渲染层放入不同布局容器时,可能出现位置偏差。应优先通过容器尺寸和相机参数调整展示布局,而不是单独缩放其中一层。

对于产品名称、设备编号和展厅说明,CSS2DObject 适合承载文字清晰、与模型位置关联但不需要真实三维透视的内容。实际项目中,只要保持模型父子绑定、双渲染器尺寸一致,并明确 HTML 交互层和三维遮挡的边界,就能让标签与产品展示场景协调工作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

CSS2DRenderer 放置模型标签

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通