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。
<!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 的绝对定位层以同一个容器为参照。两套渲染器使用相同宽高,避免标签与模型投影发生偏移。
层级设置遵循以下规则:
- WebGL Canvas 位于底层,负责三维画面和 OrbitControls 指针事件。
- CSS2DRenderer 的 DOM 容器设置
z-index: 1,负责覆盖绘制标签。 - 页面操作按钮设置
z-index: 2,保证产品配置、关闭和切换按钮显示在标签之上。 - 标签层设置
pointer-events: none,使鼠标拖动和点击能够穿透非交互标签到达画布。
如果标签自身需要按钮或链接,可以对具体交互元素设置 pointer-events: auto,并根据实际交互阻止不必要的事件传播。此时鼠标位于交互标签上时,不应期待拖动事件仍自动传递给 WebGL Canvas。
检查标签是否真正同步
完成页面后,按照下面的顺序进行验收,能够快速区分场景绑定错误和 CSS 层级错误。
- 移动模型:观察方块左右移动时标签是否保持在顶部,验证父子节点绑定。
- 旋转相机:拖动鼠标改变视角,确认标签始终朝向屏幕并跟随模型投影位置。
- 改变窗口宽度:确认模型和标签仍然对齐,验证
camera.aspect、renderer.setSize()与labelRenderer.setSize()同步更新。 - 检查操作按钮:点击右上角按钮,确认模型变色,验证 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 交互层和三维遮挡的边界,就能让标签与产品展示场景协调工作。