# @axah/react-svg-editor 中文文档

规范地址：https://npmcn.com/package/%40axah/react-svg-editor/

版本：2\.2\.1
npm 元数据更新时间：2026-09-18T08:34:42.798Z
中文译文更新时间：2026-11-07T17:26:26.442Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40axah/react-svg-editor
原文对照：https://npmcn.com/package/%40axah/react-svg-editor/?lang=original
项目主页：https://github.com/axa-health/svg-editor#readme
源码仓库：https://github.com/axa-health/svg-editor

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

- 包体积（解压后）：368 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19，react-dom \>=19，pdfjs-dist \>=6
- 首次发布：2021-02-01T12:59:29.681Z
- 最新版本发布：2026-09-18T08:34:42.175Z
- 近 30 天下载量：3649（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 9 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @axah/react-svg-editor
```

也可以使用：`pnpm add @axah/react-svg-editor`、`yarn add @axah/react-svg-editor`、`bun add @axah/react-svg-editor`

## README

# @axah/ react-svg-编辑器

一个可堆肥的 React SVG 编辑器库. 支持绘制形状,自由手路径,文本,裁剪,缩放,并拖动——都在一个由PDF或图像源支持的可缩放的SVG画布内.

## 安装

```bash
pnpm add @axah/react-svg-editor
# or
npm install @axah/react-svg-editor
```

**同伴依赖关系** (分别安装):

```bash
pnpm add react react-dom pdfjs-dist
```

* * *

## 快速示例

```tsx
import { useState } from 'react';
import {
  BackgroundSource,
  UncontrolledEditor,
  Artboard,
  Drawables,
  Cropables,
  translateDrawable,
  resizeDrawable,
} from '@axah/react-svg-editor';
import type { Drawable, Crop } from '@axah/react-svg-editor';

const pdfjs = async () => {
  const lib = await import('pdfjs-dist');
  lib.GlobalWorkerOptions.workerSrc = (
    await import('pdfjs-dist/build/pdf.worker?worker&url')
  ).default;
  return lib;
};

export default function App() {
  const [drawMode, setDrawMode] = useState<'rect' | 'pen' | 'ellipse' | 'line' | 'text' | 'crop' | null>(null);
  const [drawables, setDrawables] = useState<ReadonlyArray<Drawable>>([]);
  const [crop, setCrop] = useState<Crop | undefined>();

  return (
    <BackgroundSource source="/document.pdf" pdfjs={pdfjs} hqPdf>
      {(source) => {
        if (source.state !== 'LOADED') return <div>{source.state}</div>;

        return (
          <UncontrolledEditor
            allowDrag={drawMode === null}
            drawMode={drawMode}
            backgroundUrl={source.url}
            width={source.width}
            height={source.height}
            rotate={0}
          >
            <Artboard
              drawMode={drawMode}
              width={source.width}
              height={source.height}
              drawingFill="transparent"
              drawingStroke="#027180"
              drawingStrokeWidth={4}
              text={['Hello', 'World']}
              fontSize={16}
              minWidth={0}
              minHeight={0}
              onDrawStart={() => {}}
              onDrawEnd={(d) => setDrawables((prev) => [...prev, d])}
              onCropStart={() => {}}
              onCropEnd={setCrop}
            >
              <Drawables
                drawables={drawables}
                diStrokeWidth={3}
                width={source.width}
                height={source.height}
                onSelectDrawable={() => {}}
                onDrawableTranslate={(id, x, y) =>
                  setDrawables((prev) =>
                    prev.map((d) => (d.id === id ? translateDrawable(d, x, y) : d)),
                  )
                }
                onResizeDrawable={(_e, id, hX, hY, nX, nY) =>
                  setDrawables((prev) =>
                    prev.map((d) => (d.id === id ? resizeDrawable(d, hX, hY, nX, nY) : d)),
                  )
                }
              />
              <Cropables
                width={source.width}
                height={source.height}
                diStrokeWidth={3}
                crop={crop}
                canTransformCrop={drawMode === 'crop'}
                onCropTranslate={(x, y) =>
                  setCrop((c) => c && { ...c, x: c.x + x, y: c.y + y })
                }
                onResizeCrop={(hX, hY, nX, nY) => {
                  /* resize crop logic */
                }}
                onRemoveCrop={() => setCrop(undefined)}
                onConfirmCrop={() => setDrawMode(null)}
              />
            </Artboard>
          </UncontrolledEditor>
        );
      }}
    </BackgroundSource>
  );
}
```

* * *

## 关键概念

| 构成部分 | 目的 |
| --- | --- |
| `BackgroundSource` | 装入 PDF 或图像 URL , 并提供尺寸 + blob URL |
| `Editor` | 以缩放、平板、旋转方式控制 SVG 帆布 |
| `UncontrolledEditor` | 环绕 `Editor` 内部管理缩放/翻译状态 |
| `Artboard` | 路线绘制事件到活动绘图模式( R)`rect`, (中文(简体) ), `ellipse`, (中文(简体) ), `line`, (中文(简体) ), `pen`, (中文(简体) ), `text`, (中文(简体) ), `crop`(中文(简体) ) |
| `Drawables` | 带有选择和调整手柄大小的所有绘图形状 |
| `Cropables` | 作物区域覆盖和管理 |
| `translateDrawable` | 翻译可画的纯助手 `(x, y)` |
| `resizeDrawable` | 通过手柄角调整可绘图大小的纯助手 |

* * *

## 发展

```bash
# install dependencies
pnpm install

# start the dev preview app
pnpm start

# type-check
pnpm lint

# build the library
pnpm build

# check package exports compatibility
pnpm check:types
```

预览应用程序位于 `src/App.tsx` 并装入本地 PDF 从 `public/pdf-test.pdf`。 。 。 .

图书馆来源在 `lib/`。 。 。 .

* * *

## 释放

释放是通过 [更改](https://github.com/changesets/changesets)。 。 。 .

```bash
# create a changeset
pnpm changeset

# publish (runs lint + type checks + build first)
pnpm release
```

## 常见问题

### 如何安装 @axah/react-svg-editor？

在项目目录运行 npm install @axah/react-svg-editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19）、react-dom（\>=19）、pdfjs-dist（\>=6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @axah/react-svg-editor 支持 TypeScript 吗？

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

### @axah/react-svg-editor 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @axah/react-svg-editor 可以商用吗？

@axah/react-svg-editor 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @axah/react-svg-editor 的下载量有多少？

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

### @axah/react-svg-editor 还在维护吗？

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