react-three-fiber

@json-render/react-three-fiber

json-render 的 React Three Fiber 渲染器。内置 19 个 3D 组件。

两个入口点

入口点	导出内容	用途
@json-render/react-three-fiber/catalog	threeComponentDefinitions	目录架构（不依赖 R3F，可安全用于服务器）
@json-render/react-three-fiber	threeComponents、ThreeRenderer、ThreeCanvas、架构	R3F 实现和渲染器

使用模式

从标准定义中选择所需的 3D 组件：

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { threeComponentDefinitions } from "@json-render/react-three-fiber/catalog";
import { defineRegistry } from "@json-render/react";
import { threeComponents, ThreeCanvas } from "@json-render/react-three-fiber";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Box: threeComponentDefinitions.Box,
    Sphere: threeComponentDefinitions.Sphere,
    AmbientLight: threeComponentDefinitions.AmbientLight,
    DirectionalLight: threeComponentDefinitions.DirectionalLight,
    OrbitControls: threeComponentDefinitions.OrbitControls,
  },
  actions: {},
});

// Registry: pick matching implementations
const { registry } = defineRegistry(catalog, {
  components: {
    Box: threeComponents.Box,
    Sphere: threeComponents.Sphere,
    AmbientLight: threeComponents.AmbientLight,
    DirectionalLight: threeComponents.DirectionalLight,
    OrbitControls: threeComponents.OrbitControls,
  },
});

渲染

ThreeCanvas（便捷封装组件）

<ThreeCanvas
  spec={spec}
  registry={registry}
  shadows
  camera={{ position: [5, 5, 5], fov: 50 }}
  style={{ width: "100%", height: "100vh" }}
/>

手动设置 Canvas

import { Canvas } from "@react-three/fiber";
import { ThreeRenderer } from "@json-render/react-three-fiber";

<Canvas shadows>
  <ThreeRenderer spec={spec} registry={registry}>
    {/* Additional R3F elements */}
  </ThreeRenderer>
</Canvas>

可用组件（19 个）

基本图元（7 个）

• Box -- 宽度、高度、深度、材质
• Sphere -- 半径、宽度分段、高度分段、材质
• Cylinder -- 顶部半径、底部半径、高度、材质
• Cone -- 半径、高度、材质
• Torus -- 半径、管径、材质
• Plane -- 宽度、高度、材质
• Capsule -- 半径、长度、材质

所有基本图元都共享以下属性：position、rotation、scale、castShadow、receiveShadow、material。

灯光（4 个）

• AmbientLight -- 颜色、强度
• DirectionalLight -- 位置、颜色、强度、投射阴影
• PointLight -- 位置、颜色、强度、距离、衰减
• SpotLight -- 位置、颜色、强度、角度、半影

其他（8 个）

• Group -- 带位置／旋转／缩放属性的容器，支持子元素
• Model -- 通过 url 属性加载 GLTF/GLB
• Environment -- HDRI 环境贴图（预设、背景、模糊度、强度）
• Fog -- 线性雾（颜色、近裁剪面、远裁剪面）
• GridHelper -- 参考网格（大小、分段数、颜色）
• Text3D -- SDF 文本（文本、字体大小、颜色、anchorX、anchorY）
• PerspectiveCamera -- 摄像机（位置、fov、near、far、makeDefault）
• OrbitControls -- 轨道控制（enableDamping、enableZoom、autoRotate）

共享架构

用于自定义 3D 目录定义的可复用 Zod 架构：

import { vector3Schema, materialSchema, transformProps, shadowProps } from "@json-render/react-three-fiber";
import { z } from "zod";

// Custom 3D component
const myComponentDef = {
  props: z.object({
    ...transformProps,
    ...shadowProps,
    material: materialSchema.nullable(),
    myCustomProp: z.string(),
  }),
  description: "My custom 3D component",
};

材质架构

materialSchema = z.object({
  color: z.string().nullable(),         // default "#ffffff"
  metalness: z.number().nullable(),     // default 0
  roughness: z.number().nullable(),     // default 1
  emissive: z.string().nullable(),      // default "#000000"
  emissiveIntensity: z.number().nullable(), // default 1
  opacity: z.number().nullable(),       // default 1
  transparent: z.boolean().nullable(),  // default false
  wireframe: z.boolean().nullable(),    // default false
});

规范格式

3D 规范采用标准的 json-render 扁平元素格式：

{
  "root": "scene",
  "elements": {
    "scene": {
      "type": "Group",
      "props": { "position": [0, 0, 0] },
      "children": ["light", "box"]
    },
    "light": {
      "type": "AmbientLight",
      "props": { "intensity": 0.5 },
      "children": []
    },
    "box": {
      "type": "Box",
      "props": {
        "position": [0, 0.5, 0],
        "material": { "color": "#4488ff", "metalness": 0.3, "roughness": 0.7 }
      },
      "children": []
    }
  }
}

依赖项

所需的对等依赖：

• @react-three/fiber >= 8.0.0
• @react-three/drei >= 9.0.0
• three >= 0.160.0
• react ^19.0.0
• zod ^4.0.0