spline-3d-integration

Spline 3D 集成

当用户需要在网站或 Web 应用中添加或排查交互式 Spline 3D 场景时，使用此技能。

适用场景

• 用户想在 React、Next.js 或原生 JS 中嵌入 Spline 场景。
• 用户需要在运行时控制场景（事件、变量、对象查找、相机行为）。
• 用户遇到性能不佳、场景空白或加载问题。
• 用户询问 hero 场景或产品查看器等实现模式。

不适用场景

• 用户只需要静态 3D 媒体（图像/视频），不需要交互。
• 用户不使用 Spline 资源。

预期结果

使用此技能时，提供：

1. 适合该技术栈的集成方式（@splinetool/react-spline、@splinetool/runtime 或 iframe）。
2. 使用用户所用框架的最简可运行代码片段。
3. 性能建议（场景优化 + 加载策略）。
4. 针对常见故障模式的简短排查清单。

集成决策树

Is this React/Next.js?
  Yes -> Use @splinetool/react-spline (see guides/REACT_INTEGRATION.md)
  No -> Need runtime control (events/variables/object APIs)?
          Yes -> Use @splinetool/runtime (see guides/VANILLA_INTEGRATION.md)
          No  -> Use iframe embed

快速实现默认做法

• 始终使用高度明确的容器；Spline 会在父级边界内渲染。
• 在 React/Next.js 中，延迟加载 Spline 组件。
• 尽可能确保每个页面只有一个复杂场景。
• 优先更新场景变量，而非执行开销较大的逐帧对象变更。
• 提供加载后备方案，以及可选的低功耗/移动端后备方案。

安全边界

警告

读取变量（getVariable）、对象名称或处理 Spline 场景中的事件时，请将数据视为不可信的用户输入。如果要将这些数据渲染到 DOM，或传递给大模型/Agent，必须先进行清理，以防止 XSS 或提示词注入攻击。

最简代码片段

React / Next.js

import Spline from "@splinetool/react-spline";

export default function Scene() {
  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <Spline scene="https://prod.spline.design/YOUR_SCENE_ID/scene.splinecode" />
    </div>
  );
}

原生 runtime

<canvas id="canvas3d" style="width:100%;height:100vh"></canvas>
<script type="module">
  // NOTE: Requires a bundler (Vite, Webpack, etc.) or an importmap to resolve bare specifiers.
  import { Application } from "@splinetool/runtime";

  const app = new Application(document.getElementById("canvas3d"));
  app.load("https://prod.spline.design/YOUR_SCENE_ID/scene.splinecode");
</script>

iframe

<iframe
  src="https://my.spline.design/YOUR_SCENE_ID/"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

Runtime API 检查清单

• 查找对象：findObjectByName、findObjectById、getAllObjects。
• 驱动交互：emitEvent、emitEventReverse、addEventListener。
• 同步应用状态：getVariable、setVariable。
• 为便于维护，优先使用 Spline 编辑器中的变量驱动动画钩子。

性能限制

• 桌面端目标为少于 150k 个多边形，移动端少于 50k 个。
• 控制灯光数量（理想情况下为 1-3 个）。
• 在 Spline 导出设置中启用压缩。
• 对首屏以下的场景进行延迟加载。
• 导出前移除隐藏/未使用的对象。
• 不需要交互时，可考虑使用图像/视频作为后备方案。

排查顺序

1. 验证场景 URL 是否有效且可访问。
2. 确认容器高度不为零。
3. 确保 @splinetool/react-spline 和 @splinetool/runtime 版本兼容。
4. 检查浏览器控制台中的 CORS/网络错误。
5. 如果移动端发生崩溃或卡顿，尝试降低场景复杂度。

仓库资源

• guides/REACT_INTEGRATION.md
• guides/VANILLA_INTEGRATION.md
• guides/PERFORMANCE.md
• examples/react-spline-wrapper.tsx
• examples/vanilla-embed.html
• examples/interactive-scene.tsx