JSON Render 三维场景渲染
将以下提示词粘贴到你的 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、避免非法材质与相机参数的团队