Signature Canvas

一个轻量级、高性能的Web电子签名库，支持鼠标和触摸输入，提供平滑的绘制体验。

✨ 特性

• 🎨 高性能绘制 - 基于Canvas API，流畅的绘制体验
• 📱 跨平台支持 - 同时支持鼠标和触摸输入
• ✏️ 平滑曲线 - 使用贝塞尔曲线算法，绘制更自然
• 📦 轻量级 - 无外部依赖，体积小
• 🔧 TypeScript - 完整的类型定义
• 🎯 多种导出 - 支持PNG、SVG、Blob格式
• ⚡ 高DPI适配 - 自动适配Retina等高DPI屏幕
• 🎯 框架无关 - 可在 Vue 2/3、React、Angular 等任何框架中使用

📦 安装

npm install signature-kit

🚀 快速开始

基础使用

import { SignatureCanvas } from 'signature-kit';

// 创建签名画布
const canvas = new SignatureCanvas(document.getElementById('container'), {
  width: 800,
  height: 400,
  penColor: '#000000',
  penWidth: 2
});

// 清除签名
canvas.clear();

// 检查是否为空
if (!canvas.isEmpty()) {
  // 导出为PNG
  const png = canvas.toDataURL('image/png');
  
  // 导出为SVG
  const svg = canvas.toSVG();
  
  // 导出为Blob
  canvas.toBlob((blob) => {
    // 上传到服务器
    console.log(blob);
  });
}

Vue 3 示例

<template>
  <div ref="containerRef"></div>
</template>

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { SignatureCanvas } from 'signature-kit';

const containerRef = ref<HTMLElement>();
let canvas: SignatureCanvas | null = null;

onMounted(() => {
  if (containerRef.value) {
    canvas = new SignatureCanvas(containerRef.value, {
      width: 800,
      height: 400,
    });
  }
});

onBeforeUnmount(() => {
  canvas?.destroy();
});
</script>

Vue 2 示例

<template>
  <div ref="container"></div>
  <button @click="clear">清除</button>
  <button @click="save">保存</button>
</template>

<script>
import { SignatureCanvas } from 'signature-kit';

export default {
  data() {
    return {
      canvas: null,
    };
  },
  mounted() {
    if (this.$refs.container) {
      this.canvas = new SignatureCanvas(this.$refs.container, {
        width: 800,
        height: 400,
        penColor: '#000000',
        penWidth: 2,
      });
    }
  },
  beforeDestroy() {
    if (this.canvas) {
      this.canvas.destroy();
    }
  },
  methods: {
    clear() {
      this.canvas?.clear();
    },
    save() {
      if (this.canvas && !this.canvas.isEmpty()) {
        const png = this.canvas.toDataURL('image/png');
        console.log(png);
      }
    },
  },
};
</script>

注意：Vue 2 中务必在 beforeDestroy 钩子里调用 canvas.destroy() 以清理事件和资源。完整封装组件示例见 examples/vue2/SignaturePad.vue。

React 示例

import { useRef, useEffect } from 'react';
import { SignatureCanvas } from 'signature-kit';

function SignatureComponent() {
  const containerRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<SignatureCanvas | null>(null);

  useEffect(() => {
    if (containerRef.current) {
      canvasRef.current = new SignatureCanvas(containerRef.current, {
        width: 800,
        height: 400,
      });
    }
    return () => canvasRef.current?.destroy();
  }, []);

  return <div ref={containerRef} />;
}

📖 API文档

SignatureCanvas

构造函数

new SignatureCanvas(container: HTMLElement, options?: SignatureOptions)

方法

clear(): void

清除画布上的所有签名。

isEmpty(): boolean

检查画布是否为空（没有签名）。

toDataURL(format?: ExportFormat, quality?: number): string

将签名导出为DataURL字符串。

• format: 图片格式，可选值：'image/png' | 'image/jpeg' | 'image/webp'，默认 'image/png'
• quality: 图片质量（0-1），仅对JPEG和WebP有效

toBlob(callback: (blob: Blob | null) => void, format?: ExportFormat, quality?: number): void

将签名导出为Blob对象。

toSVG(): string

将签名导出为SVG字符串。

fromDataURL(dataURL: string): void

从DataURL加载签名图片。

on(event: SignatureEventType, handler: SignatureEventHandler): void

监听事件。

off(event: SignatureEventType, handler: SignatureEventHandler): void

移除事件监听。

destroy(): void

销毁实例，清理资源。

updateOptions(options: Partial<SignatureOptions>): void

更新配置选项。

事件

• begin: 开始绘制时触发
• end: 结束绘制时触发
• clear: 清除画布时触发

SignatureOptions

interface SignatureOptions {
  width?: number;              // 画布宽度（像素），默认 800
  height?: number;             // 画布高度（像素），默认 400
  backgroundColor?: string;     // 背景颜色，默认 '#ffffff'
  penColor?: string;           // 笔触颜色，默认 '#000000'
  penWidth?: number;           // 笔触宽度（像素），默认 2
  minWidth?: number;           // 最小笔触宽度，默认 0.5
  maxWidth?: number;           // 最大笔触宽度，默认 2.5
  throttle?: number;           // 节流时间（毫秒），默认 16
  minDistance?: number;        // 最小绘制距离（像素），默认 2
  velocityFilterWeight?: number; // 速度过滤权重（0-1），默认 0.7
}

🛠️ 开发

安装依赖

npm install

构建

npm run build

开发模式（监听文件变化）

npm run dev

测试

npm test

类型检查

npm run type-check

📝 许可证

MIT

🤝 贡献

欢迎提交Issue和Pull Request！