Agent Skills
返回列表
💻

JSON Render 三维场景渲染

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/vercel-labs-json-render-react-three-fiber。

技能介绍

要解决什么问题

若你已经在用 json-render 用 JSON 描述 UI,却要在同一套「声明式规格」里驱动 Three.js 场景,手写 R3F 组件映射会很快变成维护负担:catalog schema、运行时渲染、材质与相机控制往往散落在多处。

@json-render/react-three-fiber 把 json-render 的扁平元素格式接到 React Three Fiber 上,提供现成的组件定义与 ThreeRenderer,让你从规格里直接挂载 Box、灯光、GLTF 模型、OrbitControls 等,而不必每个属性都自己桥接。

技能如何工作

包提供 两个入口,用途要分清:

  • @json-render/react-three-fiber/catalog 只导出 threeComponentDefinitions,不依赖 R3F,适合在服务端或构建阶段生成 catalog schema。
  • @json-render/react-three-fiber 导出 threeComponents、ThreeRenderer、ThreeCanvas 与相关 schemas,用于浏览器内实际渲染。

使用上先从标准定义里挑选需要的 3D 组件,再 either 用便利封装 ThreeCanvas,要么自行搭建 Canvas 并挂 ThreeRenderer。内置 19 个组件 覆盖常见场景:

  • 图元(7):Box、Sphere、Cylinder、Cone、Torus、Plane、Capsule,统一支持 position / rotation / scale、阴影与 material。
  • 灯光(4):环境光、平行光、点光、聚光灯。
  • 其它(8):Group 子树、Model(GLTF/GLB URL)、Environment(HDRI)、Fog、GridHelper、Text3D(SDF 文字)、PerspectiveCamera、OrbitControls。

3D 规格遵循 json-render 的 扁平元素格式;另有可复用的 Material 等 Zod schema,便于在自定义 catalog 里扩展定义,并与类型校验对齐。

边界与注意点

这是 渲染适配层,不是通用 3D 编辑器:未列在 19 个内置组件内的 Three.js 能力需要自己扩展 catalog 与实现。运行时要求满足对等依赖版本(如 @react-three/fiber、@react-three/drei、three、react、zod)。在 Node 侧只做 schema 时务必走 catalog 入口,避免把 R3F 打进服务端 bundle。

使用场景

  • 产品预览页要用 JSON 配置展示 GLTF 模型、环境光与 OrbitControls,而不为每个 mesh 写独立 R3F 组件
  • 在 Next 等服务端路由里只生成 json-render 的 3D catalog schema,浏览器端再用 ThreeRenderer 挂载同一套规格
  • 运维或配置后台需要把相机、雾效、GridHelper 写进可版本化的 JSON,供前端 ThreeCanvas 一键还原场景
  • 已有 json-render 的 UI 与 3D 混排需求,希望图元与 Group 子树用同一扁平元素格式描述

适合人员

  • 维护 json-render 产物、要把新页面类型扩展到三维预览的前端工程师
  • 负责可配置 3D 展台或数字孪生原型、规格需从后端 JSON 下发的全栈开发者
  • 在构建流水线里校验 3D catalog、又要在客户端用 R3F 渲染的实现者
  • 用 Zod 约束 AI 或编辑器输出的场景 JSON、避免非法材质与相机参数的团队