2026年8月18日 · 指南页面

3DViewer 模型嵌入指南

统一的 3D 模型查看入口，支持 SPZ / GLB / STEP 等格式，并可直接内嵌到页面或博客中。

3DViewer 是什么？

3DViewer 是当前博客项目统一的 3D 模型浏览入口，基于 Three.js 与 OrbitControls 构建，支持直接打开本地或公开 URL 的 SPZ、GLB、STEP / STP 文件，并提供常用的 相机操作、光源控制、导出与 URL 参数 机制。

它的定位不是单一的高斯泼溅播放器，而是统一 3D 模型查看器：无论模型格式是什么，都走同一个入口 /ToolBase/3DViewer/3DViewer.html。这让文章中的嵌入方式保持一致，也避免继续维护旧的 /ToolBase/spz/spzViewer.html 方案。

核心能力

多格式支持：.spz、.glb、.step、.stp
交互操作：鼠标旋转 / 平移 / 缩放，适配 OrbitControls
光照调节：主光 / 环境光 / 跟随相机 / 显示方向
辅助网格：参考地面网格可按需隐藏
导出能力：支持导出到 GLB / STEP 等目标格式
URL 参数化：可直接嵌入预设相机、光源、UI 状态

最小嵌入方式

直接把 3DViewer.html 作为 iframe 的目标页即可，URL 参数中传入模型地址即可：

html

<div class="splat-viewer-wrapper">
  <iframe
    src="/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fspz%2FDingZheng.spz"
    class="splat-viewer-iframe"
    frameborder="0"
    allowfullscreen
    loading="lazy"
    style="width:100%;height:480px;display:block;border-radius:12px;"
  ></iframe>
</div>

同样适用于 GLB / STEP：

html

/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fstep%2F3D_PCB3_1_2026-08-18.step
/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fglb%2Fexample.glb

实时演示

下面的示例直接展示当前项目自带的 SPZ 模型，说明 3DViewer 的页面嵌入方式。

说明：iframe 中的浏览器会按当前模型文件加载并显示 3D 场景；若资源不可访问，请确认路径和公开权限正确。

常见 URL 参数

3DViewer 支持通过查询参数直接定义初始相机、目标和界面显示状态。下面是常用参数速查：

参数	含义	示例
`url`	模型文件 URL	`/ToolBase/3DViewer/spz/DingZheng.spz`
`camera` / `cameraPos` / `cameraPosition`	相机位置	`camera=18,12,18`
`target` / `lookAt`	观察目标	`target=0,0,0`
`ui=0` / `hideUI=1` / `uiHidden=1`	隐藏 UI	`?ui=0`
`grid=0` / `hideGrid=1` / `gridHidden=1`	隐藏参考网格	`?grid=0`
`light` / `lightPosition`	主光位置	`light=12,16,8`
`lightIntensity`	主光强度	`lightIntensity=2.4`
`ambient`	环境光强度	`ambient=1.6`
`lightFollow=1`	主光跟随相机	`lightFollow=1`

完整示例：

url

/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fstep%2F3D_PCB3_1_2026-08-18.step&camera=18,15,18&target=0,0,0&light=12,18,8&lightIntensity=2.5&ambient=1.3&ui=0&grid=0

点击加载版（省流量）

如果模型较大、首屏不必立刻加载，也可以先渲染一个占位区，再点击后注入 iframe。这个模式常见于演示页和文章中的大模型嵌入；实现思路与 tool-editor-article.astro 里 DOM.spzInsertBtn 的写法一致：先放一个占位盒子，点击时再执行 iframe.src = ...。

javascript

const iframe = document.createElement('iframe');
iframe.src = '/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fspz%2FDingZheng.spz';
iframe.className = 'splat-viewer-iframe';
iframe.loading = 'lazy';
container.appendChild(iframe);