Web 图形与 3D / 系统课时
三维热点怎样同步详情面板
三维热点怎样同步详情面板
点击三维模型上的热点后,网页详情面板应显示对应部件的信息;切换热点时,旧部件必须取消高亮,关闭面板时场景也要复原。本篇用两个示例网格实现完整交互,打通射线拾取、产品数据映射与网页状态更新。
学习目标
- 用稳定的部件 ID 关联三维热点、模型节点和产品详情。
- 通过 Raycaster 将点击命中转换为侧边栏内容。
- 在切换与关闭时恢复模型材质和热点状态。
用稳定 ID 连接场景与产品数据
一个热点至少关联三类对象:可点击的三维标记、需要高亮的模型网格、用于展示的业务数据。不要把详情文案写进鼠标事件处理函数,也不要依赖可能被建模工具重命名的 mesh.name;使用业务定义的 partId 作唯一键。
| partId | 模型部件 | 详情面板 |
|---|---|---|
shell |
蓝色机身外壳 | 铝合金,高度 130 mm |
stand |
灰色支架底座 | 钢制,直径 120 mm |
本例将 partId 写入热点的 userData.partId,再用 Map 找到同一 ID 的网格、标题和详情。唯一的 selected 保存当前选中项;新热点被点击前先恢复旧项,关闭时也调用相同的恢复逻辑。

搭建可运行的热点与面板
使用满足当前 Vite 要求的 Node.js(官方文档列出的最低版本包括 20.19+ 或 22.12+)。创建原生 JavaScript 项目并安装 Three.js:
npm create vite@latest hotspot-demo -- --template vanilla
cd hotspot-demo
npm install
npm install three
npm run dev预期输出(开发服务器地址节选,实际端口可能不同):
Local: http://localhost:<PORT>/将项目根目录的 index.html 完整替换为下列内容。这里故意只把圆形热点加入射线检测列表,避免点击模型任何位置都弹出详情;右侧信息通过 textContent 填充,不解析产品文本中的 HTML。
<!doctype html>
<html lang='zh-CN'>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<title>三维热点与详情面板</title>
<style>
body { margin: 0; font: 16px system-ui; color: #243746; }
main { max-width: 980px; margin: 24px auto; padding: 0 16px;
display: grid; grid-template-columns: minmax(0,1fr) 250px; gap: 16px; }
#viewer { height: 420px; min-width: 0; }
canvas { display: block; touch-action: manipulation; }
aside { border: 1px solid #d8e2e8; border-radius: 10px; padding: 16px; }
[hidden] { display: none !important; }
button { padding: 8px 16px; cursor: pointer; }
@media (max-width: 640px) {
main { grid-template-columns: 1fr; }
#viewer { height: 320px; }
}
</style>
</head>
<body>
<main>
<div id='viewer' aria-label='三维模型展示区'></div>
<aside>
<p id='hint'>请点击模型上方的青绿色圆形热点。</p>
<section id='detail' hidden>
<h2 id='part-title'></h2>
<p id='part-detail'></p>
<button id='close' type='button'>关闭详情</button>
</section>
</aside>
</main>
<script type='module'>
import * as THREE from 'three';
const viewer = document.getElementById('viewer');
const hint = document.getElementById('hint');
const detail = document.getElementById('detail');
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf2f6f8);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(0, 1.3, 6);
camera.lookAt(0, 0, 0);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
viewer.appendChild(renderer.domElement);
scene.add(new THREE.HemisphereLight(0xffffff, 0xb8c5d2, 2));
const light = new THREE.DirectionalLight(0xffffff, 3);
light.position.set(3, 5, 4);
scene.add(light);
const parts = [
{ id: 'shell', title: '机身外壳',
info: '蓝色铝合金;示例高度 130 mm。', x: -1.25, color: 0x4b86ae },
{ id: 'stand', title: '支架底座',
info: '灰色钢件;示例直径 120 mm。', x: 1.25, color: 0x8596a5 }
];
const byId = new Map();
const markers = [];
let selected = null;
for (const part of parts) {
// 这里用简易网格模拟真实 glTF 中可高亮的产品部件。
const shape = part.id === 'shell'
? new THREE.BoxGeometry(1.1, 1.3, 0.8)
: new THREE.CylinderGeometry(0.6, 0.6, 0.3, 40);
const mesh = new THREE.Mesh(shape,
new THREE.MeshStandardMaterial({ color: part.color, roughness: 0.55 }));
mesh.position.x = part.x;
scene.add(mesh);
const marker = new THREE.Mesh(
new THREE.SphereGeometry(0.16, 20, 12),
new THREE.MeshBasicMaterial({ color: 0x00aa99 })
);
marker.position.set(part.x, 0.93, 0.5);
marker.userData.partId = part.id; // 点击命中后只传 ID,不传文案。
scene.add(marker);
markers.push(marker);
byId.set(part.id, {
...part, mesh, marker, originalColor: mesh.material.color.clone()
});
}
function render() { renderer.render(scene, camera); }
function clearSelection() {
if (!selected) return;
// 切换和关闭共用恢复逻辑,避免旧热点残留高亮。
selected.mesh.material.color.copy(selected.originalColor);
selected.marker.scale.setScalar(1);
selected = null;
}
function selectPart(id) {
const next = byId.get(id);
if (!next) return;
clearSelection();
selected = next;
next.mesh.material.color.setHex(0xffb45b);
next.marker.scale.setScalar(1.35);
document.getElementById('part-title').textContent = next.title;
document.getElementById('part-detail').textContent = next.info;
detail.hidden = false;
hint.hidden = true;
render();
}
const raycaster = new THREE.Raycaster();
renderer.domElement.addEventListener('pointerdown', (event) => {
if (event.pointerType === 'mouse' && event.button !== 0) return;
const rect = renderer.domElement.getBoundingClientRect();
// 必须相对 Canvas 计算 NDC,Y 轴方向与页面坐标相反。
const pointer = new THREE.Vector2(
((event.clientX - rect.left) / rect.width) * 2 - 1,
-((event.clientY - rect.top) / rect.height) * 2 + 1
);
raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(markers, false)[0];
if (hit) selectPart(hit.object.userData.partId);
});
document.getElementById('close').addEventListener('click', () => {
clearSelection();
detail.hidden = true;
hint.hidden = false;
render();
});
function resize() {
const width = viewer.clientWidth;
const height = viewer.clientHeight;
camera.aspect = width / height;
camera.updateProjectionMatrix();
renderer.setSize(width, height);
render();
}
window.addEventListener('resize', resize);
resize();
</script>
</body>
</html>预期结果:左侧出现蓝色立方体、灰色圆柱和两个青绿色热点。点击任一热点,右侧出现对应标题与材料参数,选中网格变为橙色、热点略微放大。示例是静态场景,因此只在交互和窗口变化时重绘,而非持续占用动画循环。
验证切换与关闭是否一致
在浏览器打开终端显示的本地地址,按以下顺序检查。每一步都检查面板内容和三维选中效果,不能只看文案是否变化。
| 操作 | 预期面板 | 预期三维状态 |
|---|---|---|
| 首次打开 | 仅显示点击提示 | 两个网格均为原色 |
点击 shell 热点 |
机身外壳、130 mm | 机身橙色,热点放大 |
再点击 stand 热点 |
支架底座、120 mm | 机身恢复蓝色,底座橙色 |
| 点击“关闭详情” | 详情隐藏,提示重现 | 底座恢复灰色,热点均为原大小 |
点击热点外的空白区域,本例保持当前选中项;如果产品要求点击空白处关闭,应在未命中时调用同一套关闭逻辑,而不是只隐藏 DOM。将浏览器宽度缩到 640px 以下再点击,仍应命中正确热点:射线坐标按 Canvas 实际边界计算,窗口变化后相机宽高比同步更新。
接入真实模型时处理这些边界
替换示例网格时,使用 GLTFLoader 加载的真实部件作为 byId 中的 mesh,并在资源制作或加载后明确关联业务 ID。不要只靠数组索引:导出模型增删节点后,索引可能变化。一个业务热点若要高亮多个网格,就把 mesh 改为网格数组,统一保存和恢复材质状态。
实际产品里还需检查两点。第一,glTF 不同网格可能共享同一个 material;直接改 material.color 会让未选中部件一起变色。给需要独立高亮的网格克隆材质,或使用单独的选中描边层,并妥善释放临时资源。第二,如果部件会旋转或播放动画,热点应绑定到相应模型节点的局部坐标系,不能一直固定在世界坐标 part.x 附近;否则详情虽正确,圆点却会与目标部件脱离。
保持“热点只提供 ID、数据表提供文案、唯一状态控制高亮与面板”这一分工,后续接入弹窗、商品配置器或 glTF 动画,都可以复用同一个选择与清除入口。