# sign

**Repository Path**: dzy_gitee/sign

## Basic Information

- **Project Name**: sign
- **Description**: 跨平台的uniapp签名文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-08-19
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 手写签名组件 (uni-app)

一个功能完整、跨平台的手写签名组件，基于 uni-app 开发，支持 H5、小程序等多个平台。提供流畅的手写体验、丰富的配置选项和完善的功能特性。

## ✨ 功能特性

- 🎨 **流畅手写体验** - 支持平滑线条绘制，可调节线条粗细和颜色
- 📱 **跨平台支持** - 完美适配 H5、微信小程序、支付宝小程序等平台
- 🎯 **丰富配置选项** - 支持画布尺寸、背景色、线条样式等多项配置
- 💾 **多种保存方式** - 支持保存到相册、下载到本地、上传到服务器
- 🔄 **撤销重做功能** - 支持多步撤销操作，可配置历史记录长度
- 🖼️ **预览功能** - 实时预览签名效果
- 📤 **文件上传** - 内置上传管理器，支持重试机制和错误处理
- 🎛️ **灵活API** - 提供完整的事件回调和方法调用

## 🛠️ 技术栈

- **框架**: uni-app (Vue 2.x)
- **构建工具**: Vite
- **样式**: 原生CSS + uni-app样式
- **平台支持**: H5、微信小程序、支付宝小程序、App等
- **依赖管理**: npm/pnpm

## 📦 安装和运行

### 环境要求

- Node.js >= 14.0.0
- npm >= 6.0.0 或 pnpm >= 6.0.0

### 快速开始

```bash
# 克隆项目
git clone <repository-url>
cd sign

# 安装依赖
npm install
# 或使用 pnpm
pnpm install

# 运行开发服务器
# H5 平台
npm run dev:h5

# 微信小程序
npm run dev:mp-weixin

# 支付宝小程序
npm run dev:mp-alipay

# App 平台
npm run dev:app
```

### 构建生产版本

```bash
# 构建 H5
npm run build:h5

# 构建微信小程序
npm run build:mp-weixin

# 构建支付宝小程序
npm run build:mp-alipay

# 构建 App
npm run build:app
```

## 🚀 使用方法

### 基础用法

```vue
<template>
  <view class="container">
    <sign-component
      ref="signRef"
      :canvas-width="400"
      :canvas-height="300"
      :line-color="'#000000'"
      :bg-color="'#ffffff'"
      @complete="onSignComplete"
    />
  </view>
</template>

<script>
import SignComponent from '@/components/sign.vue'

export default {
  components: {
    SignComponent
  },
  methods: {
    onSignComplete(result) {
      if (result.success) {
        console.log('签名完成:', result.filePath)
      } else {
        console.error('签名失败:', result.error)
      }
    },
    
    // 清空画布
    clearCanvas() {
      this.$refs.signRef.clearCanvas()
    },
    
    // 撤销操作
    undoCanvas() {
      this.$refs.signRef.undo()
    },
    
    // 保存签名
    saveSignature() {
      this.$refs.signRef.saveCanvasAsImg()
    },
    
    // 预览签名
    previewSignature() {
      this.$refs.signRef.previewCanvasImg()
    }
  }
}
</script>
```

## 📋 API 文档

### Props 配置选项

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `canvasWidth` | Number | 300 | 画布宽度(px) |
| `canvasHeight` | Number | 200 | 画布高度(px) |
| `lineColor` | String | '#1A1A1A' | 线条颜色 |
| `bgColor` | String | 'transparent' | 背景颜色 |
| `minWidth` | Number | 2 | 最小线条宽度 |
| `maxWidth` | Number | 6 | 最大线条宽度 |
| `minSpeed` | Number | 1.5 | 影响线条粗细的最小速度 |
| `maxWidthDiffRate` | Number | 20 | 线条宽度变化率(%) |
| `maxHistoryLength` | Number | 20 | 最大历史记录长度 |
| `openSmooth` | Boolean | true | 是否开启平滑绘制 |
| `uploadUrl` | String | '' | 上传接口地址 |
| `uploadConfig` | Object | {} | 上传配置选项 |

### 上传配置 (uploadConfig)

```javascript
{
  method: 'POST',           // 请求方法
  name: 'file',            // 文件字段名
  header: {},              // 请求头
  formData: {},            // 额外表单数据
  timeout: 30000,          // 超时时间(ms)
  maxRetries: 3,           // 最大重试次数
  retryDelay: 1000         // 重试延迟(ms)
}
```

### 方法 (Methods)

| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| `clearCanvas()` | - | - | 清空画布 |
| `undo()` | - | Boolean | 撤销上一步操作 |
| `isEmpty()` | - | Boolean | 检查画布是否为空 |
| `saveCanvasAsImg()` | - | - | 保存签名图片 |
| `previewCanvasImg()` | - | - | 预览签名图片 |
| `complete()` | - | - | 完成签名并上传 |
| `setLineColor(color)` | String | - | 设置线条颜色 |

### 事件 (Events)

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `complete` | `{success, filePath, error, response}` | 签名完成事件 |
| `upload-progress` | `{progress, total}` | 上传进度事件 |
| `canvas-ready` | - | 画布初始化完成 |
| `drawing-start` | `{x, y}` | 开始绘制 |
| `drawing-end` | - | 结束绘制 |

## 🌐 平台兼容性

| 平台 | 支持状态 | 特殊说明 |
|------|----------|----------|
| H5 | ✅ 完全支持 | 保存功能为下载到本地 |
| 微信小程序 | ✅ 完全支持 | 可保存到相册，需要用户授权 |
| 支付宝小程序 | ✅ 完全支持 | 可保存到相册，需要用户授权 |
| 百度小程序 | ✅ 完全支持 | 可保存到相册，需要用户授权 |
| 字节小程序 | ✅ 完全支持 | 可保存到相册，需要用户授权 |
| QQ小程序 | ✅ 完全支持 | 可保存到相册，需要用户授权 |
| App (iOS/Android) | ✅ 完全支持 | 可保存到相册，需要权限 |

### 平台差异说明

#### H5 平台
- 保存功能：触发浏览器下载
- 文件格式：PNG
- 权限要求：无

#### 小程序平台
- 保存功能：保存到系统相册
- 文件格式：PNG
- 权限要求：需要用户授权相册权限
- 注意事项：首次保存需要用户手动授权

#### App 平台
- 保存功能：保存到系统相册
- 文件格式：PNG
- 权限要求：需要相册写入权限
- 注意事项：需要在 manifest.json 中配置相关权限

## 🔧 高级配置

### 自定义样式

```vue
<template>
  <sign-component class="custom-sign" />
</template>

<style>
.custom-sign {
  border: 2px solid #007AFF;
  border-radius: 8px;
  box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
</style>
```

### 上传配置示例

```vue
<template>
  <sign-component
    :upload-url="uploadUrl"
    :upload-config="uploadConfig"
    @complete="handleComplete"
  />
</template>

<script>
export default {
  data() {
    return {
      uploadUrl: 'https://api.example.com/upload',
      uploadConfig: {
        method: 'POST',
        name: 'signature',
        header: {
          'Authorization': 'Bearer your-token'
        },
        formData: {
          userId: '12345',
          type: 'signature'
        },
        timeout: 60000,
        maxRetries: 3,
        retryDelay: 2000
      }
    }
  },
  methods: {
    handleComplete(result) {
      if (result.success) {
        console.log('上传成功:', result.response)
      } else {
        console.error('上传失败:', result.error)
      }
    }
  }
}
</script>
```

## ❓ 常见问题

### Q: H5 平台下 canvas.toDataURL 报错？
**A:** 这是因为 uni-app H5 环境下的 canvas 不是标准 HTML5 canvas 元素。组件已统一使用 `uni.canvasToTempFilePath` API 解决此问题。

### Q: 小程序保存到相册失败？
**A:** 请检查以下几点：
1. 确保用户已授权相册权限
2. 检查小程序是否有相册访问权限
3. 确保画布有内容（非空）

### Q: 上传功能不工作？
**A:** 请检查：
1. `uploadUrl` 是否正确配置
2. 服务器接口是否正常
3. 网络连接是否正常
4. 上传配置是否正确

### Q: 画布显示异常或无法绘制？
**A:** 请确保：
1. 画布尺寸设置合理
2. 组件已正确挂载
3. 检查控制台是否有错误信息

### Q: 如何自定义线条样式？
**A:** 可以通过以下 props 调整：
- `lineColor`: 线条颜色
- `minWidth`/`maxWidth`: 线条粗细范围
- `openSmooth`: 是否平滑绘制

### Q: 如何处理不同屏幕尺寸？
**A:** 建议使用响应式设计：
```javascript
// 根据屏幕宽度动态设置画布尺寸
const systemInfo = uni.getSystemInfoSync()
const canvasWidth = systemInfo.windowWidth * 0.9
const canvasHeight = canvasWidth * 0.6
```

## 📁 项目结构

```
sign/
├── src/
│   ├── components/
│   │   └── sign.vue              # 主签名组件
│   ├── pages/
│   │   └── index/
│   │       └── index.vue         # 测试页面
│   └── utils/                    # 工具模块
│       ├── canvasAdapter.js      # Canvas适配器
│       ├── canvasUtils.js        # Canvas工具函数
│       ├── configManager.js      # 配置管理
│       ├── drawingEngine.js      # 绘制引擎
│       ├── drawingHistory.js     # 绘制历史管理
│       ├── eventManager.js       # 事件管理
│       ├── mathUtils.js          # 数学计算工具
│       ├── messageUtils.js       # 消息提示工具
│       ├── uploadManager.js      # 上传管理器
│       └── validationUtils.js    # 验证工具
├── dist/                         # 构建输出目录
├── docs/                         # 文档目录
├── package.json                  # 项目配置
├── vite.config.js               # Vite配置
├── manifest.json                # uni-app配置
├── pages.json                   # 页面配置
└── README.md                    # 项目说明
```

## 🤝 贡献指南

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](LICENSE) 文件了解详情。

## 🆘 技术支持

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

1. 查看本文档的常见问题部分
2. 提交 Issue 描述问题
3. 查看项目源码和注释
4. 参考示例代码

---

**注意**: 本组件基于 uni-app 框架开发，使用前请确保您的项目环境支持 uni-app。