react-three-fiber

用途

@json-render/react-three-fiber 是 json-render 的 React Three Fiber 渲染器，用于把 JSON 规格（spec）渲染成 3D 场景。它内置 19 个 3D 组件，适合在 React 应用中用声明式 JSON 描述并动态生成三维内容。

两个入口点

该包提供两个入口，用途不同：

@json-render/react-three-fiber/catalog：导出 threeComponentDefinitions，即 catalog schema。不依赖 R3F，可安全用于服务端。
@json-render/react-three-fiber：导出 threeComponents、ThreeRenderer、ThreeCanvas、schemas，即 R3F 实现与渲染器。

使用方式

基本模式是先从标准定义中挑选需要的 3D 组件构建 catalog，再挑选匹配的实现构建 registry。示例：

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：width、height、depth、material
Sphere：radius、widthSegments、heightSegments、material
Cylinder：radiusTop、radiusBottom、height、material
Cone：radius、height、material
Torus：radius、tube、material
Plane：width、height、material
Capsule：radius、length、material

所有几何体共享：position、rotation、scale、castShadow、receiveShadow、material。

灯光（4 个）：

AmbientLight：color、intensity
DirectionalLight：position、color、intensity、castShadow
PointLight：position、color、intensity、distance、decay
SpotLight：position、color、intensity、angle、penumbra

其他（8 个）：

Group：容器，支持 position/rotation/scale，可包含子元素
Model：通过 url 属性加载 GLTF/GLB
Environment：HDRI 环境贴图（preset、background、blur、intensity）
Fog：线性雾（color、near、far）
GridHelper：参考网格（size、divisions、color）
Text3D：SDF 文字（text、fontSize、color、anchorX、anchorY）
PerspectiveCamera：相机（position、fov、near、far、makeDefault）
OrbitControls：轨道控制（enableDamping、enableZoom、autoRotate）

共享 Schema

提供可复用的 Zod schema，用于自定义 3D catalog 定义：

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",
};

材质 schema 定义：

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
});

Spec 格式

3D spec 使用标准 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": []
    }
  }
}

依赖

需要以下 peer 依赖：

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

适用场景与限制

适用于需要在 React 中通过 JSON 规格动态构建 3D 场景的项目，例如由数据驱动生成三维可视化或交互式 3D 内容。catalog 入口不依赖 R3F，可在服务端安全使用，便于服务端生成或校验组件定义。限制方面：资料未提供收费、价格、平台支持范围、性能表现或具体使用步骤之外的额外说明，暂未提供相关信息。