# Vue3 电子签名组件库

一个功能强大、易于使用的Vue3电子签名组件库，支持手写签名、触摸绘制和多种导出格式。

## ✨ 特性

- 🖊️ **流畅绘制** - 基于Canvas的高性能绘图引擎，连续流畅的书写体验
- 📱 **移动端支持** - 完美支持触摸设备和手势操作
- 🎨 **多种笔迹样式** - 适中笔迹（默认）、优雅笔迹、毛笔、铅笔等专业笔迹效果
- ✨ **智能渐变** - 优雅笔迹支持基于速度和压力的由粗到细渐变效果
- 🚫 **无闪烁渲染** - 所有笔迹样式都支持稳定的实时渲染，无闪烁干扰
- 📤 **多格式导出** - 支持PNG、JPEG、SVG、Base64等格式
- 🔄 **撤销重做** - 完整的操作历史管理
- 📏 **响应式设计** - 自适应容器尺寸
- 💪 **TypeScript** - 完整的类型定义支持
- 🎯 **压感模拟** - 根据绘制速度模拟压感效果
- 🖼️ **图像处理** - 内置裁剪、缩放、水印等功能
- 🎬 **签名回放** - 支持签名路径的录制和回放功能，保持笔迹样式一致性

## 📦 安装

```bash
npm install vue3-electronic-signature
```

或者使用 yarn：

```bash
yarn add vue3-electronic-signature
```

## 🚀 快速开始

### 全局注册

```typescript
import { createApp } from 'vue'
import Vue3ElectronicSignature from 'vue3-electronic-signature'
import App from './App.vue'

const app = createApp(App)
app.use(Vue3ElectronicSignature)
app.mount('#app')
```

### 局部引入

```vue
<template>
  <ElectronicSignature
    :width="400"
    :height="200"
    placeholder="请在此处签名"
    @signature-end="onSignatureEnd"
  />
</template>

<script setup lang="ts">
import { ElectronicSignature } from 'vue3-electronic-signature'
import type { SignatureData } from 'vue3-electronic-signature'

const onSignatureEnd = (data: SignatureData) => {
  console.log('签名完成', data)
}
</script>
```

## 📖 基础用法

### 简单签名

```vue
<template>
  <ElectronicSignature
    :width="400"
    :height="200"
    stroke-color="#000000"
    :stroke-width="2"
    placeholder="请在此处签名"
  />
</template>
```

### 笔迹样式选择

```vue
<template>
  <div>
    <!-- 样式选择器 -->
    <select v-model="selectedPenStyle">
      <option value="ballpoint">适中笔迹 - 连续流畅，商务首选（默认）</option>
      <option value="elegant">优雅笔迹 - 智能渐变，由粗到细</option>
      <option value="brush">毛笔 - 传统书法，自然变化</option>
      <option value="pencil">铅笔 - 稳定连续，素描效果</option>
      <option value="pen">钢笔 - 极细锐利，精准线条</option>
      <option value="marker">马克笔 - 超粗荧光，醒目标记</option>
    </select>

    <!-- 签名组件 -->
    <ElectronicSignature
      :width="400"
      :height="200"
      :pen-style="selectedPenStyle"
      stroke-color="#2c3e50"
      placeholder="选择不同笔迹样式体验"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ElectronicSignature } from 'vue3-electronic-signature'
import type { PenStyle } from 'vue3-electronic-signature'

const selectedPenStyle = ref<PenStyle>('ballpoint') // 默认适中笔迹
</script>
```

### 自定义样式

```vue
<template>
  <ElectronicSignature
    :width="500"
    :height="300"
    stroke-color="#2196F3"
    :stroke-width="3"
    background-color="#FFFEF7"
    border-style="2px solid #2196F3"
    border-radius="8px"
    :smoothing="true"
    :pressure-sensitive="true"
    placeholder="自定义样式签名"
  />
</template>
```

### 响应式签名

```vue
<template>
  <ElectronicSignature
    width="100%"
    :height="200"
    stroke-color="#4CAF50"
    placeholder="响应式签名区域"
  />
</template>
```

## 🔧 API 文档

### Props 属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| width | number \| string | '100%' | 画布宽度 |
| height | number \| string | 300 | 画布高度 |
| **penStyle** | **PenStyle** | **'ballpoint'** | **笔迹样式：'ballpoint'（适中） \| 'elegant'（优雅） \| 'brush'（毛笔） \| 'pencil'（铅笔） \| 'pen'（钢笔） \| 'marker'（马克笔）** |
| strokeColor | string | '#000000' | 画笔颜色 |
| strokeWidth | number | 2 | 画笔粗细（部分样式会覆盖此设置） |
| backgroundColor | string | 'transparent' | 背景颜色 |
| disabled | boolean | false | 是否禁用 |
| placeholder | string | '请在此处签名' | 占位符文本 |
| smoothing | boolean | true | 是否启用平滑绘制（部分样式会覆盖此设置） |
| pressureSensitive | boolean | false | 是否启用压感效果（部分样式会覆盖此设置） |
| minStrokeWidth | number | 1 | 最小画笔宽度（压感模式） |
| maxStrokeWidth | number | 4 | 最大画笔宽度（压感模式） |
| borderStyle | string | '1px solid #ddd' | 边框样式 |
| borderRadius | string | '4px' | 圆角大小 |
| showToolbar | boolean | false | 是否显示工具栏 |
| replayMode | boolean | false | 是否启用回放模式 |
| replayData | SignatureReplay | - | 回放数据 |
| replayOptions | ReplayOptions | - | 回放选项配置 |

### Events 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| signature-start | - | 开始签名时触发 |
| signature-drawing | (data: SignatureData) | 签名进行中触发 |
| signature-end | (data: SignatureData) | 签名结束时触发 |
| signature-clear | - | 清除签名时触发 |
| signature-undo | (data: SignatureData) | 撤销操作时触发 |
| signature-redo | (data: SignatureData) | 重做操作时触发 |
| replay-start | - | 回放开始时触发 |
| replay-progress | (progress: number, currentTime: number) | 回放进度更新时触发 |
| replay-pause | - | 回放暂停时触发 |
| replay-resume | - | 回放恢复时触发 |
| replay-stop | - | 回放停止时触发 |
| replay-complete | - | 回放完成时触发 |
| replay-path-start | (pathIndex: number, path: SignaturePath) | 笔画开始时触发 |
| replay-path-end | (pathIndex: number, path: SignaturePath) | 笔画结束时触发 |
| replay-speed-change | (speed: number) | 回放速度改变时触发 |

### Methods 方法

| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| clear() | - | void | 清除签名 |
| undo() | - | void | 撤销上一步操作 |
| redo() | - | void | 重做操作 |
| save(options?) | ExportOptions | string | 保存签名 |
| isEmpty() | - | boolean | 判断签名是否为空 |
| fromDataURL(dataURL) | string | Promise\<void\> | 从数据URL加载签名 |
| getSignatureData() | - | SignatureData | 获取签名数据 |
| setSignatureData(data) | SignatureData | void | 设置签名数据 |
| resize(width?, height?) | number?, number? | void | 调整画布尺寸 |
| startReplay(data, options?) | SignatureReplay, ReplayOptions? | void | 开始回放签名 |
| getReplayData() | - | SignatureReplay \| null | 获取回放数据 |
| setReplayMode(enabled) | boolean | void | 设置回放模式 |
| play() | - | void | 播放回放 |
| pause() | - | void | 暂停回放 |
| stop() | - | void | 停止回放 |
| seek(time) | number | void | 跳转到指定时间 |
| setSpeed(speed) | number | void | 设置回放速度 |
| getState() | - | ReplayState | 获取回放状态 |
| getCurrentTime() | - | number | 获取当前回放时间 |
| getTotalDuration() | - | number | 获取总回放时长 |
| getProgress() | - | number | 获取回放进度(0-1) |

### 🎨 笔迹样式详解

| 样式 | 特点 | 视觉效果 | 适用场景 |
|------|------|----------|----------|
| **ballpoint** ⭐ | 连续流畅线条(2px) | 简洁专业，圆润收笔 | 商务签名、日常使用（默认） |
| **elegant** ✨ | 智能渐变(0.3-15px) | 由粗到细，速度感应 | 艺术签名、书法体验 |
| **brush** 🖌️ | 传统毛笔(1-20px) | 自然变化，书法韵味 | 传统书法、艺术创作 |
| **pencil** ✏️ | 稳定连续(2-5px) | 简洁清晰，无纹理 | 草稿签名、自然书写 |
| **pen** 🖊️ | 极细锐利线条(1px) | 商务精准，无圆角端点 | 精密绘图、技术签名 |
| **marker** 🖍️ | 超粗荧光效果(12px) | 荧光光晕，醒目标记 | 重点标记、醒目签名 |

#### 笔迹样式配置

```typescript
import { getAllPenStyles, getPenStyleConfig } from 'vue3-electronic-signature'

// 获取所有可用样式
const allStyles = getAllPenStyles()

// 获取特定样式配置
const penConfig = getPenStyleConfig('elegant')
console.log(penConfig)
// {
//   name: '优雅笔迹',
//   description: '智能渐变，由粗到细，速度感应',
//   strokeWidth: 3,
//   smoothing: true,
//   pressure: { enabled: true, min: 1, max: 16 },
//   lineCap: 'round',
//   lineJoin: 'round',
//   recommendedColor: '#2c3e50'
// }
```

## 📋 类型定义

### PenStyle

```typescript
type PenStyle = 'ballpoint' | 'elegant' | 'brush' | 'pencil' | 'pen' | 'marker'
```

### PenStyleConfig

```typescript
interface PenStyleConfig {
  name: string                    // 样式名称
  description: string             // 样式描述
  strokeWidth: number             // 基础线宽
  smoothing: boolean              // 是否启用平滑
  pressure: {                     // 压感配置
    enabled: boolean
    min: number
    max: number
  }
  lineCap: CanvasLineCap          // 线条端点样式
  lineJoin: CanvasLineJoin        // 线条连接样式
  recommendedColor?: string       // 推荐颜色
}
```

### SignatureData

```typescript
interface SignatureData {
  paths: SignaturePath[]        // 签名路径集合
  canvasSize: {                // 画布尺寸
    width: number
    height: number
  }
  timestamp: number            // 创建时间戳
  isEmpty: boolean             // 是否为空
}
```

### ExportOptions

```typescript
interface ExportOptions {
  format: 'png' | 'jpeg' | 'svg' | 'base64'  // 导出格式
  quality?: number                            // 图片质量(0-1)
  size?: {                                   // 导出尺寸
    width: number
    height: number
  }
  backgroundColor?: string                    // 背景颜色
}
```

### SignatureReplay

```typescript
interface SignatureReplay {
  paths: SignaturePath[]                     // 带时间信息的路径集合
  totalDuration: number                      // 总回放时长（毫秒）
  speed: number                              // 回放速度倍率
  metadata: {                                // 签名元数据
    deviceType: 'mouse' | 'touch' | 'pen'
    averageSpeed: number                     // 平均书写速度（像素/秒）
    totalDistance: number                    // 总绘制距离（像素）
    averagePauseTime: number                 // 笔画间平均停顿时间（毫秒）
  }
}
```

### ReplayOptions

```typescript
interface ReplayOptions {
  speed?: number                             // 回放速度倍率
  loop?: boolean                             // 是否循环播放
  showControls?: boolean                     // 是否显示控制条
  autoPlay?: boolean                         // 是否自动开始播放
  startTime?: number                         // 回放开始时间（毫秒）
  endTime?: number                           // 回放结束时间（毫秒）
}
```

### ReplayState

```typescript
type ReplayState = 'idle' | 'playing' | 'paused' | 'stopped' | 'completed'
```

## � 签名回放功能

### 基础回放

```vue
<template>
  <div>
    <!-- 签名组件 -->
    <ElectronicSignature
      ref="signatureRef"
      :width="400"
      :height="200"
      @signature-end="onSignatureEnd"
    />

    <!-- 回放组件 -->
    <ElectronicSignature
      :width="400"
      :height="200"
      :replay-mode="true"
      :replay-data="replayData"
      :replay-options="replayOptions"
      @replay-complete="onReplayComplete"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { SignatureMethods, SignatureData, SignatureReplay } from 'vue3-electronic-signature'

const signatureRef = ref<SignatureMethods>()
const replayData = ref<SignatureReplay | null>(null)

const replayOptions = {
  speed: 1,
  loop: false,
  showControls: true,
  autoPlay: true
}

const onSignatureEnd = (data: SignatureData) => {
  // 从签名数据生成回放数据
  replayData.value = signatureRef.value?.getReplayData() || null
}

const onReplayComplete = () => {
  console.log('回放完成')
}
</script>
```

### 手动控制回放

```vue
<template>
  <div>
    <ElectronicSignature
      ref="replayRef"
      :width="400"
      :height="200"
      :replay-mode="true"
      :replay-data="replayData"
      :replay-options="{ showControls: false, autoPlay: false }"
      @replay-progress="onProgress"
    />

    <!-- 自定义控制按钮 -->
    <div class="custom-controls">
      <button @click="play">播放</button>
      <button @click="pause">暂停</button>
      <button @click="stop">停止</button>
      <button @click="setSpeed(0.5)">0.5x</button>
      <button @click="setSpeed(1)">1x</button>
      <button @click="setSpeed(2)">2x</button>
    </div>

    <div>进度: {{ Math.round(progress * 100) }}%</div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { SignatureMethods } from 'vue3-electronic-signature'

const replayRef = ref<SignatureMethods>()
const progress = ref(0)

const play = () => replayRef.value?.play()
const pause = () => replayRef.value?.pause()
const stop = () => replayRef.value?.stop()
const setSpeed = (speed: number) => replayRef.value?.setSpeed(speed)

const onProgress = (progressValue: number) => {
  progress.value = progressValue
}
</script>
```

### 回放事件监听

```vue
<template>
  <ElectronicSignature
    :replay-mode="true"
    :replay-data="replayData"
    @replay-start="onReplayStart"
    @replay-path-start="onPathStart"
    @replay-path-end="onPathEnd"
    @replay-complete="onReplayComplete"
  />
</template>

<script setup lang="ts">
import type { SignaturePath } from 'vue3-electronic-signature'

const onReplayStart = () => {
  console.log('开始回放签名')
}

const onPathStart = (pathIndex: number, path: SignaturePath) => {
  console.log(`开始绘制第 ${pathIndex + 1} 笔画`, path)
}

const onPathEnd = (pathIndex: number, path: SignaturePath) => {
  console.log(`完成绘制第 ${pathIndex + 1} 笔画`, path)
}

const onReplayComplete = () => {
  console.log('签名回放完成')
}
</script>
```

## �🎯 高级用法

### 获取和设置签名数据

```vue
<template>
  <ElectronicSignature ref="signatureRef" />
  <button @click="saveSignature">保存</button>
  <button @click="loadSignature">加载</button>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { SignatureMethods, SignatureData } from 'vue3-electronic-signature'

const signatureRef = ref<SignatureMethods>()
let savedData: SignatureData | null = null

const saveSignature = () => {
  if (signatureRef.value) {
    savedData = signatureRef.value.getSignatureData()
    console.log('签名已保存', savedData)
  }
}

const loadSignature = () => {
  if (signatureRef.value && savedData) {
    signatureRef.value.setSignatureData(savedData)
    console.log('签名已加载')
  }
}
</script>
```

### 导出不同格式

```typescript
// 导出PNG格式
const pngData = signatureRef.value?.save({ format: 'png' })

// 导出高质量JPEG
const jpegData = signatureRef.value?.save({ 
  format: 'jpeg', 
  quality: 0.9 
})

// 导出SVG矢量格式
const svgData = signatureRef.value?.save({ format: 'svg' })

// 导出指定尺寸
const resizedData = signatureRef.value?.save({
  format: 'png',
  size: { width: 800, height: 400 },
  backgroundColor: '#ffffff'
})
```

### 工具函数使用

组件库还提供了丰富的工具函数：

```typescript
import {
  getSignatureBounds,
  cropSignature,
  addWatermark,
  convertToGrayscale
} from 'vue3-electronic-signature'

// 获取签名边界
const bounds = getSignatureBounds(signatureData)

// 裁剪签名
const croppedCanvas = cropSignature(canvas, signatureData, 10)

// 添加水印
const watermarkedCanvas = addWatermark(canvas, '© 2024 公司名称', {
  position: 'bottom-right',
  fontSize: 12,
  opacity: 0.5
})

// 转换为灰度
const grayscaleCanvas = convertToGrayscale(canvas)
```

## 🎨 样式定制

### CSS 变量

组件支持通过CSS变量进行样式定制：

```css
.electronic-signature {
  --signature-border-color: #ddd;
  --signature-border-radius: 4px;
  --signature-placeholder-color: #999;
  --signature-toolbar-bg: #f5f5f5;
}
```

### 自定义主题

```vue
<template>
  <ElectronicSignature
    class="custom-signature"
    :width="400"
    :height="200"
  />
</template>

<style>
.custom-signature {
  border: 2px solid #2196F3;
  border-radius: 12px;
  box-shadow: 0 4px 12px rgba(33, 150, 243, 0.15);
}

.custom-signature canvas {
  border-radius: 10px;
}
</style>
```

## 📱 移动端优化

组件针对移动端进行了特别优化：

- 支持触摸绘制
- 防止页面滚动干扰
- 高DPI屏幕适配
- 触摸压感模拟

```vue
<template>
  <!-- 移动端推荐配置 -->
  <ElectronicSignature
    width="100%"
    :height="250"
    :stroke-width="3"
    :pressure-sensitive="true"
    :min-stroke-width="2"
    :max-stroke-width="6"
    stroke-color="#2196F3"
  />
</template>
```

## 🔧 开发指南

### 本地开发

```bash
# 克隆项目
git clone https://github.com/your-username/vue3-electronic-signature.git

# 安装依赖
cd vue3-electronic-signature
npm install

# 启动开发服务器
npm run dev

# 构建组件库
npm run build:lib
```

### 项目结构

```
vue3-electronic-signature/
├── src/                    # 源代码
│   ├── components/         # 组件
│   ├── types/             # 类型定义
│   ├── utils/             # 工具函数
│   └── index.ts           # 入口文件
├── examples/              # 示例应用
├── dist/                  # 构建输出
├── docs/                  # 文档
└── tests/                 # 测试文件
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目基于 [MIT](LICENSE) 许可证开源。


## 📞 支持

如果你觉得这个项目有用，请给我们一个 ⭐️！

- 📧 邮箱：852174914@qq.com
- 🐛 问题反馈：[GitHub Issues](https://github.com/wu852174914/vue3-electronic-signature/issues)

## 📝 更新日志

### v2.0.0 (最新版本)

#### 🎉 重大改进
- **删除所有断续效果** - 实现连续流畅的书写体验
- **优化优雅笔迹** - 增强由粗到细的渐变效果，删除黑色连接点
- **修复闪烁问题** - 毛笔和圆珠笔书写时的稳定渲染
- **默认笔迹调整** - 全局默认使用适中笔迹（ballpoint）

#### ✨ 笔迹样式优化
- **适中笔迹** - 连续流畅，简洁专业，商务首选（新默认）
- **优雅笔迹** - 智能渐变，由粗到细，速度感应（增强效果）
- **毛笔笔迹** - 传统书法，自然变化，稳定无闪烁
- **铅笔笔迹** - 稳定连续，简洁清晰，删除纹理效果
- **钢笔笔迹** - 极细锐利，精准线条
- **马克笔笔迹** - 超粗荧光，醒目标记

#### 🔧 技术改进
- **性能优化** - 删除复杂算法，文件大小减少至53.46kB
- **代码简化** - 移除断续效果和连接点算法
- **渲染一致性** - 实时书写与最终效果完全一致
- **回放稳定性** - 录制与回放效果完全相同

```