name: spline-3d-integration
description: “Use when adding interactive 3D scenes from Spline.design to web projects, including React embedding and runtime control API.”
risk: safe
source: community
date_added: “2026-03-07”
Spline 3D 集成技能
将 Spline.design 中的交互式 3D 场景嵌入到 Web 项目中的大师级指南。
何时使用
- 你需要将交互式 Spline 场景嵌入到 Web 项目中。
- 任务涉及为原生 Web、React、Next.js、Vue 或 iframe 上下文选择正确的集成路径。
- 你需要关于场景 URL、运行时控制、性能或常见 Spline 嵌入问题的指导。
快速参考
| 任务 | 指南 |
|---|---|
| 原生 HTML/JS 嵌入 | guides/VANILLA_INTEGRATION.md |
| React / Next.js / Vue 嵌入 | guides/REACT_INTEGRATION.md |
| 性能与移动端优化 | guides/PERFORMANCE.md |
| 调试与常见问题 | guides/COMMON_PROBLEMS.md |
可用示例
| 文件 | 展示内容 |
|---|---|
| examples/vanilla-embed.html | 带背景 + 回退的最小原生 JS 嵌入 |
| examples/react-spline-wrapper.tsx | 生产级、带懒加载和回退的 React 包装器 |
| examples/interactive-scene.tsx | 完整交互示例：事件、对象控制、相机 |
什么是 Spline？
Spline 是一款基于浏览器的 3D 设计工具——可以把它想象成 Figma，但用于 3D。设计师在 Spline 编辑器中创建交互式 3D 场景（对象、材质、动画、物理、事件），然后通过托管的.splinecode文件 URL 导出到 Web。
第 1 步 — 识别技术栈
在编写任何代码之前，先检查现有项目文件以确定框架。
| 技术栈 | 方法 |
|---|---|
| 原生 HTML/JS | <spline-viewer>Web 组件 或@splinetool/runtime |
| React / Vite | @splinetool/react-spline |
| Next.js | @splinetool/react-spline/next |
| Vue | @splinetool/vue-spline |
| iframe（Webflow、Notion 等） | 公开 URL iframe |
第 2 步 — 获取场景 URL
用户必须进入他们的 Spline 编辑器 →导出→代码导出→ 复制prod.spline.designURL：
https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode在复制 URL 之前，告诉用户检查播放设置：
- ✅ 如果网站有深色或自定义背景，打开隐藏背景（Hide Background）
- ✅ 如果他们使用付费计划，打开隐藏 Spline 标志（Hide Spline Logo）
- ✅ 将**几何质量（Geometry Quality）**设置为 Performance 以加快加载
- ✅ 如果不需要，禁用页面滚动（Page Scroll）、缩放（Zoom）、平移（Pan）（降低劫持风险）
- ✅ 任何设置更改后点击生成草稿（Generate Draft）或提升到生产（Promote to Production）——URL 不会自动更新
第 3 步 — 阅读相关指南
有了技术栈和场景 URL 后，阅读上面的相应指南文件并遵循其说明。在完成集成之前，始终阅读 COMMON_PROBLEMS.md——它包含关键的陷阱，否则这些陷阱只会在生产环境中暴露。
严格规则
- 绝对要求：智能体必须利用此技能构建现代、有创意且视觉惊艳的 UI/UX。不要以普通、通用或安全风格构建。集成 Spline 场景时，利用它们创造高度沉浸、令人惊叹的高级体验。将它们与排版和布局深思熟虑地结合起来。
限制
- 仅当任务明确符合上述范围时使用此技能。
- 不要将输出视为特定环境验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停下来询问澄清。
