# 3dsvg 中文文档

规范地址：https://npmcn.com/package/3dsvg/

版本：0\.2\.1
npm 元数据更新时间：2026-04-09T07:40:24.588Z
中文译文更新时间：2026-11-06T14:33:38.413Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/3dsvg
原文对照：https://npmcn.com/package/3dsvg/?lang=original
项目主页：https://3dsvg.design/
源码仓库：https://github.com/renatoworks/3dsvg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：112 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18，react-dom \>=18，three \>=0\.160\.0，@react-three/fiber \>=9，@react-three/drei \>=10
- 首次发布：2026-04-03T08:06:17.572Z
- 最新版本发布：2026-04-09T07:40:24.478Z
- 近 30 天下载量：2985（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

将 SVG 转换为交互式 React 3D 组件的最简单方式

## 安装

```sh
npm install 3dsvg
```

也可以使用：`pnpm add 3dsvg`、`yarn add 3dsvg`、`bun add 3dsvg`

## README

# 3个dsvg

![3dsvg](https://raw.githubusercontent.com/renatoworks/3dsvg/main/.github/assets/demo.png)

将 SVG 转换成交互式 React 3D 组件的最简单方法.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/renatoworks/3dsvg/blob/main/LICENSE) [![npm](https://img.shields.io/npm/v/3dsvg)](https://www.npmjs.com/package/3dsvg) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/3dsvg)](https://bundlephobia.com/package/3dsvg)

## 安装

```bash
npm install 3dsvg
```

同伴依赖性 : `react`, (中文(简体) ), `react-dom`, (中文(简体) ), `three`, (中文(简体) ), `@react-three/fiber`, (中文(简体) ), `@react-three/drei`

## 快速启动

```tsx
import { SVG3D } from "3dsvg";

// 3D text
<SVG3D text="Hello" animate="spin" />

// SVG from your public folder
<SVG3D svg="/logo.svg" material="gold" animate="float" />

// Inline SVG markup
<SVG3D svg='<svg viewBox="0 0 24 24"><path d="M12 2L2 7l10 5 10-5z"/></svg>' />

// Remote URL
<SVG3D svg="https://cdn.example.com/icon.svg" material="metal" />
```

**下一个.js** - 与 `next/dynamic` 安保部门安全:

```tsx
const SVG3D = dynamic(
  () => import("3dsvg").then((m) => ({ default: m.SVG3D })),
  { ssr: false }
);
```

## 演示词编辑器( E)

设计 三维对象可视化并导出嵌入式代码 [3dsvg 设计](https://3dsvg.design/)。 。 。 .

## 道具

### 内容

提供其中之一 `text` 或者说 `svg`如果两者都给予, `svg` 优先处理.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | —— 说 | 要以 三维格式翻译的文本 |
| `font` | `string` | `"DM Sans"` | 谷歌字体名称( 见 [可用字体](https://npmcn.com/package/3dsvg/#readme-available-fonts)(中文(简体) ) |
| `svg` | `string` | —— 说 | SVG 标记或 URL (`/logo.svg`, (中文(简体) ), `https://...`, (中文(简体) ), `./path.svg`(中文(简体) ) |

### 形状

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `depth` | `number` | `1` | (0.5=平地;10=非常深地) |
| `smoothness` | `number` | `0.2` | 曲线和贝壳质量, 0-1 |
| `color` | `string` | `"#ffffff"` | 底色( 小时) |

### 材料

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `material` | `MaterialPreset` | `"default"` | 材料预设(见下文) |
| `metalness` | `number` | —— 说 | 覆盖预设的金属( 0-1) |
| `roughness` | `number` | —— 说 | 覆盖预设粗糙度 (0-1) |
| `opacity` | `number` | —— 说 | 覆盖预设不透明( 0– 1) |
| `wireframe` | `boolean` | `false` | 线框渲染模式 |

**材料预设 :**

| 预设 | 金属 | 粗糙度 | 页:1 |
| --- | --- | --- | --- |
| `default` | 0.15 (中文(简体) ) | 0.35 (简体中文) | 平衡起点 |
| `plastic` | 0.0 数据 | 0.3 (韩语) | 平滑、非反射 |
| `metal` | 0.9 (中文(简体) ) | 0.2 (韩语) | 破碎的金属 |
| `glass` | 0.1 数据 | 0.05 (简体中文) | 有折射的透明 |
| `rubber` | 0.0 数据 | 0.9 (中文(简体) ) | 马特,软 |
| `chrome` | 1.0 国家 | 0.05 (简体中文) | 镜像倒影 |
| `gold` | 1.0 国家 | 0.25 (中文(简体) ) | 自动应用金锡 |
| `clay` | 0.0 数据 | 1.0 国家 | 满分 |
| `emissive` | 0.0 数据 | 0.5 (韩语) | 自发发光 |
| `holographic` | 0.8 (简体中文) | 0.1 数据 | 透明而有清衣 |

### 纹理

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `texture` | `string` | —— 说 | 映射到 三维表面的图像 URL |
| `textureRepeat` | `number` | `1` | 纹理瓦片数倍 |
| `textureRotation` | `number` | `0` | 弧度纹理旋转 |
| `textureOffset` | `[number, number]` | `[0, 0]` | 页:1 `[x, y]` |

当纹理被设定时,基色被上覆为白色,因此纹理在完全忠贞时会得到.

### 照明

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `lightPosition` | `[number, number, number]` | `[5, 8, 5]` | 关键光位置 `[x, y, z]` |
| `lightIntensity` | `number` | `1.2` | 关键亮度 |
| `ambientIntensity` | `number` | `0.3` | 环境填充光 |
| `shadow` | `boolean` | `true` | 显示联系人阴影 |

### 相机

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `rotationX` | `number` | `0` | 初始 X 旋转(弧度) |
| `rotationY` | `number` | `0` | 初始 Y 旋转(弧度) |
| `zoom` | `number` | `8` | 相机距离 |
| `fov` | `number` | `50` | 视野(度) |

相机在窄/相相上自动调整——它按比例放大,使3D对象总是适合可见区域.

### 互动

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `interactive` | `boolean` | `true` | 师傅切换.. `false` 禁用拖放、缩放和轨道 |
| `cursorOrbit` | `boolean` | `true` | 对象潜入光标 |
| `orbitStrength` | `number` | `0.15` | 对象跟随光标的强度(弧度) |
| `draggable` | `boolean` | `true` | 允许拖动旋转 |
| `scrollZoom` | `boolean` | `false` | 允许卷轴缩放( 默认情况下关闭, 这样嵌入不会劫持页面卷轴) |
| `resetOnIdle` | `boolean` | `false` | 不活动后返回默认位置 |
| `resetDelay` | `number` | `2` | 重置触发前秒数 |

### 动画

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `animate` | `AnimationType` | `"none"` | 循环动画类型(见下文) |
| `animateSpeed` | `number` | `1` | 速度乘数 |
| `animateReverse` | `boolean` | `false` | 倒转方向 |

**动画类型 :** `none` • 妇女 `spin` • 妇女 `float` • 妇女 `pulse` • 妇女 `wobble` • 妇女 `spinFloat` • 妇女 `swing`

### 介绍

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `intro` | `string` | `"zoom"` | 内置动画 : `zoom` • 妇女 `fade` • 妇女 `none` |
| `introDuration` | `number` | `2.5` | 持续时间( 秒) |
| `introFrom` | `object` | `{ zoom: 18, opacity: 0 }` | 开始状态 |
| `introTo` | `object` | `{ zoom: 8, opacity: 1 }` | 结束状态 |

### 版式

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `width` | `string | number` | `"100%"` | 容器宽度 |
| `height` | `string | number` | `"100%"` | 集装箱高度 |
| `background` | `string` | `"transparent"` | 帆布背景颜色 |
| `className` | `string` | —— 说 | 包装器上的 CSS 课 |

### 活动

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `onReady` | `() => void` | 当WebGL 上下文准备就绪, 第一个帧被打开时开火 |
| `onAnimationComplete` | `() => void` | 动画完成后会起火 |
| `onLoadingChange` | `(loading: boolean, progress: number) => void` | 在几何处理过程中随加载状态和进度而起火 (0-100). 用它来显示自定义加载 UI . |

几何处理是同步的——复杂的SVG分批处理,以保持浏览器的响应性. 这个 `onLoadingChange` 回调让您跟踪进度并显示加载指标 :

```tsx
<SVG3D
  svgString={complexSvg}
  onLoadingChange={(loading, progress) => {
    if (loading) console.log(`Processing: ${progress}%`);
    else console.log("Done");
  }}
/>
```

## 可用字体

DM Sans · Bebas Neue · 游戏展会 · 正确 · 黑色操作 1 · 永久标记 · Rubik Mono One · Pacifico · Oswald · Archivo Black

## 许可证

麻省理工学院 - [雷纳托·科斯塔](https://renato.works/)

赚到的 [蓝莓](https://meetblueberry.com/) 🫐

## 常见问题

### 3dsvg 是什么？

将 SVG 转换为交互式 React 3D 组件的最简单方式

### 如何安装 3dsvg？

在项目目录运行 npm install 3dsvg，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）、three（\>=0\.160\.0）、@react-three/fiber（\>=9）、@react-three/drei（\>=10）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### 3dsvg 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### 3dsvg 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### 3dsvg 可以商用吗？

3dsvg 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### 3dsvg 的下载量有多少？

根据 npm 官方下载统计，3dsvg 在 2026/10/04 – 2026/11/02 这 30 天内被下载 2,985 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### 3dsvg 还在维护吗？

最新版本 0\.2\.1 发布于 2026/04/09（6 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/04/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。