第2章 Spline 编辑器 Code 标签页详解:在 3D 场景中构建 Web UI 与逻辑
第2章:Code 标签页
Code 标签页存放 Spline 文件自身的代码。每个文件可以携带一份 HTML 文档——包含 markup、CSS 和 JavaScript——编辑器会在一个精确覆盖 3D 画布的沙箱 iframe 中渲染它。你在这里构建的一切都会叠加在实时场景之上,而注入的 spline API 则让这些代码能够读取并操控场景。
它承担两类工作:
- 叠加在场景上的 Web UI —— HUD、仪表盘、面板、表单和控件。
- 行为与动效代码 —— 动画循环、交互逻辑、游戏循环。文档也可以是无界面的:只有一个
<script>,没有任何可见内容。
这份文档是文件的一部分。它随文件一起保存、支持撤销、同步给协作者,并随导出一起发布。
这与 Web 上的 Code API 不同——后者是在你自己的网站上操控一个已发布的场景。Code 标签页则位于 Spline 文件内部,随文件走。
在哪里找到它
Code 标签页是编辑器顶部 Preview | Edit | Code 三个标签页之一,用于切换舞台的显示内容:
| 标签页 | 显示内容 |
|---|---|
| Preview | 场景叠加你的 HTML 运行——即访客看到的效果 |
| Edit | 纯粹的 3D 场景,无任何代码执行,可完整编辑 |
| Code | HTML 文档的源码,叠加在场景之上 |
打开 Code 标签页即可编写或修改文档。底部有一个 Console 条,会捕获你的 console.* 输出和报错,所以 console.log 就是你的调试方式。
文档
每个文件只有一份完整的 HTML 文档。你的 CSS 和 JavaScript 需内联写在文档本身里。
外部库可以用。<script src="…"> 和远程样式表都能正常加载,所以当某个图表库或动画库确实有用时尽管用。小功能尽量用内联代码:每多一个远程脚本,导出时就多一个可能加载失败的东西。
不要用 HTML 重建场景。3D 内容在你身后,那是 Spline 的事——不要自己建 WebGL canvas。
两条布局规则
- 页面背景保持透明。不要给
html或body设置背景——凡是你没涂色的地方,3D 场景都会透出来。要给背景加样式,请作用于你自己的面板和卡片。 - 指针事件可以穿透背景。落在
html/body上的点击会到达 3D 视口,所以旋转视角和场景交互在你各 UI 元素之间依然有效。你自己元素上的事件则归你处理——交互式 HTML 保持紧凑,让背后的场景始终可触达。
用 fixed 或 absolute 的 CSS 相对整个视口定位 UI——iframe 恰好覆盖整个画布。
与场景通信
一个 spline 对象会在你的脚本运行前注入文档。它是你的代码与文件 3D 内容之间的接口,双向可用:
- 读取场景 —— 变量、文件中的对象及其当前变换,以及 mesh 的实时几何数据。
- 操控场景 —— 移动、隐藏、重新设计对象样式,修改几何参数,写入变量。
- 运行时创建 —— 复制模板对象、克隆已有对象,或用代码新建 primitives、文本和灯光。
- 响应事件 —— 监听变量变化和你在对象上创建的事件,也可以自己触发这些事件。
- 超越图层系统 —— 提供自定义 three.js 材质,实现 Spline 材质图层无法表达的效果。
你的代码所做的所有修改都是临时的:它们只是运行时状态,不会保存到文件、不会进入撤销历史,刷新后会重置。对交互式控件来说这正是你想要的——但如果某个改动应当永久写入文件,请直接在场景里编辑。
Edit 模式 vs Play 模式
- 读取、更新对象、写入变量在编辑时也能用,你可以边编辑边对着场景构建。
- 你在对象上创建的事件只在 Play 模式下触发——编辑时交互系统是关闭的,强行触发只会在 console 里给出警告。
导出时包含什么
HTML 会随场景自动一起导出:
| 导出方式 | HTML 内容 |
|---|---|
| Public URL | ✅ |
<spline-viewer> embed | ✅ |
| 运行 Spline runtime 的 Code export | ✅ |
| three.js / react-three-fiber 代码导出 | ❌ —— 这些不使用 Spline 引擎 |
导出的场景始终运行在 play 模式,完整的事件系统都是生效的。
自定义 three.js 材质在编辑器和 Web 导出中可用,但 <spline-viewer> embed 不支持。如果用到了它们,请回退到分层材质,保证场景在任何地方都能正常显示。
让 Agent 来写
你不必手动编写这份文档。AI Agent 可以代为编写和修改——描述你想要的 UI 或行为,它会生成 markup 和 spline 调用,产出的源码你可以在 Code 标签页中继续编辑。
API Request Action
上一篇:如何导入内容——将 3D 模型、图片、视频和音频导入 Spline,以及支持哪些格式。