spline-3d-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spline 3D Integration Skill

Spline 3D集成技能

Master guide for embedding interactive 3D scenes from Spline.design into web projects.

将来自Spline.design的交互式3D场景嵌入Web项目的权威指南。

Quick Reference

快速参考

Task	Guide
Vanilla HTML/JS embed	guides/VANILLA_INTEGRATION.md
React / Next.js / Vue embed	guides/REACT_INTEGRATION.md
Performance & mobile optimization	guides/PERFORMANCE.md
Debugging & common problems	guides/COMMON_PROBLEMS.md

任务	指南
原生HTML/JS嵌入	guides/VANILLA_INTEGRATION.md
React / Next.js / Vue嵌入	guides/REACT_INTEGRATION.md
性能与移动端优化	guides/PERFORMANCE.md
调试与常见问题	guides/COMMON_PROBLEMS.md

Working Examples

实战示例

File	What it shows
examples/vanilla-embed.html	Minimal vanilla JS embed with background + fallback
examples/react-spline-wrapper.tsx	Production-ready lazy-loaded React wrapper with fallback
examples/interactive-scene.tsx	Full interactive example: events, object control, camera

文件	展示内容
examples/vanilla-embed.html	包含背景与降级方案的极简原生JS嵌入示例
examples/react-spline-wrapper.tsx	生产环境可用的懒加载React封装组件（含降级方案）
examples/interactive-scene.tsx	完整交互示例：事件、对象控制、相机操作

What Is Spline?

什么是Spline？

Spline is a browser-based 3D design tool — think Figma, but for 3D. Designers create interactive 3D scenes (objects, materials, animations, physics, events) in the Spline editor, then export them for the web via a hosted

.splinecode

file URL.

Spline是一款基于浏览器的3D设计工具——可以理解为3D版的Figma。设计师在Spline编辑器中创建交互式3D场景（包含对象、材质、动画、物理效果、交互事件），然后通过托管的

.splinecode

文件URL导出到Web端使用。

STEP 1 — Identify the Stack

步骤1 — 确定技术栈

Before writing any code, check the existing project files to determine the framework.

Stack	Method
Vanilla HTML/JS	`<spline-viewer>` web component OR `@splinetool/runtime`
React / Vite	`@splinetool/react-spline`
Next.js	`@splinetool/react-spline/next`
Vue	`@splinetool/vue-spline`
iframe (Webflow, Notion, etc.)	Public URL iframe

在编写代码前，先检查现有项目文件以确定所使用的框架。

技术栈	实现方式
原生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

STEP 2 — Get the Scene URL

步骤2 — 获取场景URL

The user must go to their Spline editor → Export → Code Export → copy the

prod.spline.design

URL:

https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode

Before copying the URL, tell the user to check Play Settings:

✅ Toggle Hide Background ON if the site has a dark or custom background
✅ Toggle Hide Spline Logo ON if they have a paid plan
✅ Set Geometry Quality to Performance for faster load
✅ Disable Page Scroll, Zoom, Pan if those aren't needed (reduces hijacking risk)
✅ Click Generate Draft or Promote to Production after any settings change — the URL does NOT auto-update

用户需要进入自己的Spline编辑器 → 导出 → 代码导出 → 复制

prod.spline.design

格式的URL：

https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode

复制URL前，请告知用户检查播放设置：

✅ 如果网站使用深色或自定义背景，请开启隐藏背景选项
✅ 如果用户拥有付费套餐，请开启隐藏Spline标识选项
✅ 将几何质量设置为“性能优先”以加快加载速度
✅ 如果不需要页面滚动、缩放、平移功能，请禁用这些选项（降低事件劫持风险）
✅ 更改任何设置后，请点击生成草稿或发布到生产环境——URL不会自动更新

STEP 3 — Read the Relevant Guide

步骤3 — 阅读对应指南

Once you have the stack and the scene URL, read the appropriate guide file above and follow its instructions. Always read COMMON_PROBLEMS.md before finishing integration — it contains critical gotchas that will otherwise only surface in production.

确定技术栈并获取场景URL后，阅读上方对应的指南文件并按照说明操作。完成集成前务必阅读COMMON_PROBLEMS.md——其中包含了关键的注意事项，否则这些问题可能只会在生产环境中暴露。

Strict Rules

严格规则

ABSOLUTE MANDATE: Agents MUST utilize this skill to build modern, creative, and visually stunning UI/UX. DO NOT build in common, generic, or safe styles. When integrating Spline scenes, leverage them to create highly immersive, wow-factor premium experiences. Combine them thoughtfully with typography and layout.

强制要求：Agent必须使用本技能来构建现代、创意且视觉惊艳的UI/UX。禁止使用普通、通用或保守的风格。集成Spline场景时，要利用它们打造高度沉浸式、具有震撼效果的高端体验。将其与排版和布局进行合理结合。