FreeDraw 一个基于svg的移动端react自定义画图工具

介绍

前端绘画工具，可以在屏幕上自由绘画，基于 Pointer Events 实现，同时支持触摸、鼠标和触控笔（含压感）。

使用

基础用法（命令式 API）

import { FreeDraw } from 'free-draw-svg';

const App = () => {
  const drawer = FreeDraw({
    strokeColor: 'red',
  });

  setTimeout(() => {
    drawer.destroy();
  }, 5000);
  return (
    <></>
  );
};

命令式 API 应在事件回调（如 onClick、useEffect）中调用，不要在渲染期间直接调用。

声明式用法（组件 + ref）

import { useRef } from 'react';
import { FreeDrawCanvas, FreeDrawRef } from 'free-draw-svg';

const App = () => {
  const ref = useRef<FreeDrawRef>(null);

  return (
    <>
      <FreeDrawCanvas ref={ref} strokeColor="red" strokeWidth={5} />
      <button onClick={() => ref.current?.undo()}>撤销</button>
    </>
  );
};

支持多笔绘制

默认只保留最新一笔，抬手重新落笔会清空上一笔。传入 multiple 可以叠加保留多笔：

FreeDraw({
  strokeColor: 'red',
  multiple: true,
});

自定义线条颜色、宽度和背景

const drawer = FreeDraw({
  strokeColor: 'red',
  strokeWidth: 5,
  backgroundColor: 'rgba(0, 0, 0, .5)',
});

在背景图片上绘制（批注场景）

const drawer = FreeDraw({
  backgroundImage: 'https://example.com/photo.png',
});

压感支持

在支持压感的设备（如触控笔）上，根据按压力度动态调整线宽：

const drawer = FreeDraw({
  pressureSensitive: true,
});

撤销 / 重做

drawer.undo();
drawer.redo();

导出

const svgString = drawer.toSVGString();
const pngDataUrl = await drawer.toDataURL();

清除画布内容 / 销毁实例

drawer.clear();   // 仅清空已绘制内容，画布保留
drawer.destroy(); // 卸载并移除画布

API

方法

| 参数 | 说明 | 类型 | 返回值 | | --- | --- | --- | --- | | FreeDraw | 绘图（命令式） | (opts: FreeDrawProps) => FreeDrawController | FreeDrawController | | FreeDrawCanvas | 绘图（声明式组件，配合 ref 使用） | React.ForwardRefExoticComponent | - |

FreeDrawController（FreeDraw(opts) 的返回值）

| 方法 | 说明 | | --- | --- | | clear | 清空当前已绘制内容，画布保留 | | undo | 撤销最后一笔 | | redo | 重做最后一次被撤销的笔迹 | | toSVGString | 导出当前内容为 SVG 字符串 | | toDataURL(type?, quality?) | 导出当前内容为图片 dataURL（Promise） | | destroy | 卸载并移除画布（替代旧版的 clear） |

Options

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | strokeColor | 线条颜色 | string | #000 | | strokeWidth | 线条宽度 | number | 3 | | backgroundColor | 背景颜色 | string | transparent | | backgroundImage | 背景图片地址 | string | - | | multiple | 是否支持绘制多笔（默认只保留最新一笔） | boolean | false | | pressureSensitive | 是否根据压感调整线宽 | boolean | false | | disabled | 是否禁用绘制 | boolean | false | | style | 自定义样式，与内置样式合并 | CSSProperties | - | | zIndex | 指定层级 | number | 9999 | | teleport | 指定挂载的节点（仅命令式 API） | HTMLElement|(() => HTMLElement) | body |

Events

| 事件名 | 说明 | 回调参数 | | ---------------- | -------------------------- | -------------- | | onDrawStart | 点击/落笔开始绘画触发 | event: PointerEvent | | onDrawMove | 滑动绘制时触发 | event: PointerEvent | | onDrawEnd | 结束绘制事件 | (event: PointerEvent, clientRect: DOMRect) |

类型定义

组件导出以下类型定义：

import type {
  FreeDrawProps,
  FreeDrawInstance,
  FreeDrawRef,
  FreeDrawController,
} from 'free-draw-svg';