Back to Details

react-three-fiber

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

@json-render/react-three-fiber

@json-render/react-three-fiber

React Three Fiber renderer for json-render. 19 built-in 3D components.
适用于json-render的React Three Fiber渲染器，内置19个3D组件。

Two Entry Points

两个入口点

Entry PointExportsUse For
@json-render/react-three-fiber/catalog
threeComponentDefinitions
Catalog schemas (no R3F dependency, safe for server)
@json-render/react-three-fiber
threeComponents
, 
ThreeRenderer
, 
ThreeCanvas
, schemas		R3F implementations and renderer
入口点导出内容适用场景
@json-render/react-three-fiber/catalog
threeComponentDefinitions
目录模式（无R3F依赖，可安全用于服务器端）
@json-render/react-three-fiber
threeComponents
, 
ThreeRenderer
, 
ThreeCanvas
, schemas		R3F实现与渲染器

Usage Pattern

使用模式

Pick the 3D components you need from the standard definitions:
typescript
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,
  },
});
从标准定义中选择你需要的3D组件：
typescript
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,
  },
});

Rendering

渲染

ThreeCanvas (convenience wrapper)

ThreeCanvas（便捷封装）

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

Manual Canvas setup

手动Canvas设置

tsx
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>
tsx
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>

Available Components (19)

可用组件（19个）

Primitives (7)

基础几何体（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
All primitives share: 
position
, 
rotation
, 
scale
, 
castShadow
, 
receiveShadow
, 
material
.
  • Box
    -- 宽度、高度、深度、材质
  • Sphere
    -- 半径、宽度分段数、高度分段数、材质
  • Cylinder
    -- 顶部半径、底部半径、高度、材质
  • Cone
    -- 半径、高度、材质
  • Torus
    -- 半径、管半径、材质
  • Plane
    -- 宽度、高度、材质
  • Capsule
    -- 半径、长度、材质
所有基础几何体共享属性：
position
、
rotation
、
scale
、
castShadow
、
receiveShadow
、
material
。

Lights (4)

灯光（4个）

  • AmbientLight
    -- color, intensity
  • DirectionalLight
    -- position, color, intensity, castShadow
  • PointLight
    -- position, color, intensity, distance, decay
  • SpotLight
    -- position, color, intensity, angle, penumbra
  • AmbientLight
    -- 颜色、强度
  • DirectionalLight
    -- 位置、颜色、强度、投射阴影
  • PointLight
    -- 位置、颜色、强度、距离、衰减
  • SpotLight
    -- 位置、颜色、强度、角度、半影

Other (8)

其他组件（8个）

  • Group
    -- container with position/rotation/scale, supports children
  • Model
    -- GLTF/GLB loader via url prop
  • Environment
    -- HDRI environment map (preset, background, blur, intensity)
  • Fog
    -- linear fog (color, near, far)
  • GridHelper
    -- reference grid (size, divisions, color)
  • Text3D
    -- SDF text (text, fontSize, color, anchorX, anchorY)
  • PerspectiveCamera
    -- camera (position, fov, near, far, makeDefault)
  • OrbitControls
    -- orbit controls (enableDamping, enableZoom, autoRotate)
  • Group
    -- 带有位置/旋转/缩放属性的容器，支持子组件
  • Model
    -- 通过url属性加载GLTF/GLB模型
  • Environment
    -- HDRI环境贴图（预设、背景、模糊、强度）
  • Fog
    -- 线性雾（颜色、近距、远距）
  • GridHelper
    -- 参考网格（尺寸、分段数、颜色）
  • Text3D
    -- SDF文本（文本内容、字体大小、颜色、X轴锚点、Y轴锚点）
  • PerspectiveCamera
    -- 透视相机（位置、视野、近裁剪面、远裁剪面、设为默认）
  • OrbitControls
    -- 轨道控制器（启用阻尼、启用缩放、自动旋转）

Shared Schemas

共享模式

Reusable Zod schemas for custom 3D catalog definitions:
typescript
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",
};
可复用的Zod模式，用于自定义3D目录定义：
typescript
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",
};

Material Schema

材质模式

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

规格格式

3D specs use the standard json-render flat element format:
json
{
  "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": []
    }
  }
}
3D规格使用标准的json-render扁平化元素格式：
json
{
  "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": []
    }
  }
}

Dependencies

依赖

Peer dependencies required:
  • @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-three/fiber
    >= 8.0.0
  • @react-three/drei
    >= 9.0.0
  • three
    >= 0.160.0
  • react
    ^19.0.0
  • zod
    ^4.0.0