# 证书编辑器

**Repository Path**: zjqspace/certificate-editor

## Basic Information

- **Project Name**: 证书编辑器
- **Description**: 一个功能强大的基于 Vue 3 的可视化证书编辑器，支持拖拽编辑、系统字段关联、模板管理、图片/二维码处理等功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# z-certificate-editor

一个功能强大的基于 Vue 3 的可视化证书编辑器，支持拖拽编辑、系统字段关联、模板管理、图片/二维码处理等功能。

## 📦 安装

```bash
npm install z-certificate-editor
```

或使用 yarn：

```bash
yarn add z-certificate-editor
```

或使用 pnpm：

```bash
pnpm add z-certificate-editor
```

## 🚀 快速开始

### 基础使用

```vue
<template>
  <CertificateEditor @save="handleSave" />
</template>

<script setup>
import { CertificateEditor } from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

const handleSave = (certificateData) => {
  console.log('证书配置数据：', certificateData)
}
</script>
```

### 使用自定义系统字段

```vue
<template>
  <CertificateEditor 
    :system-fields="customSystemFields"
    @save="handleSave"
  />
</template>

<script setup>
import {
  CertificateEditor,
  SYSTEM_FIELDS
} from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

const customSystemFields = [
  {
    key: 'studentId',
    label: '学号',
    placeholder: '{{学号}}',
    category: '学生信息',
    description: '学生的学号'
  },
  ...SYSTEM_FIELDS
]

const handleSave = (certificateData) => {
  console.log('证书配置数据：', certificateData)
}
</script>
```

### 通过组件引用获取数据

```vue
<template>
  <CertificateEditor 
    ref="certificateEditorRef"
    @save="handleSave"
  />
  <button @click="getCurrentData">获取当前配置</button>
</template>

<script setup>
import { ref } from 'vue'
import { CertificateEditor } from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

const certificateEditorRef = ref(null)

const handleSave = (certificateData) => {
  console.log('保存的数据：', certificateData)
}

const getCurrentData = () => {
  if (certificateEditorRef.value) {
    const data = certificateEditorRef.value.getCertificateData()
    console.log('当前配置：', data)
  }
}
</script>
```

### 配置服务器上传

```vue
<template>
  <CertificateEditor 
    :upload-config="uploadConfig"
    @save="handleSave"
  />
</template>

<script setup>
import { ref } from 'vue'
import { CertificateEditor } from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

// 上传配置
const uploadConfig = ref({
  url: 'http://localhost:8000/api/upload', // 上传接口地址
  method: 'POST', // 请求方法
  fileField: 'file', // 文件字段名
  params: {
    // 额外的表单参数（可选）
    type: 'image',
    category: 'certificate'
  },
  headers: {
    // 请求头（可选）
    'Authorization': 'Bearer your-token-here',
    'X-Custom-Header': 'value'
  }
})

const handleSave = (certificateData) => {
  console.log('证书配置数据：', certificateData)
}
</script>
```

## 📖 完整文档

以下是完整的项目文档和使用说明。

## ✨ 功能特性

### 核心功能

- 🎨 **可视化编辑**: 直观的拖拽式编辑界面，所见即所得
- 📝 **文本元素**: 支持短文本和长文本元素，丰富的格式化选项
- 🖼️ **图片元素**: 支持本地上传（服务器上传或Base64）、URL输入、关联系统字段（如用户头像）
- 🔲 **二维码元素**: 支持文本内容、图片上传（服务器上传或Base64）、URL输入、关联系统字段（如证书编号、身份证号）
- ☁️ **服务器上传**: 支持配置上传接口，所有图片上传可自动上传到服务器并获取网络URL
- 🎯 **系统字段关联**: 动态关联系统字段，实现证书内容的自动化填充
- ⚙️ **自定义系统字段**: 支持通过 props 传入自定义系统字段配置，灵活适配不同业务场景
- 📐 **精确定位**: 支持精确的位置（X、Y）和尺寸（宽度、高度）设置
- 🎨 **丰富的文本格式**: 字体大小、字体族、粗体、斜体、下划线、颜色、对齐方式、行高等

### 模板管理

- 📄 **预设模板**: 提供横版和竖版预设证书模板
- 🔄 **模板切换**: 支持横版/竖版模板快速切换
- 📤 **自定义模板**: 支持上传自定义背景图片（JPG、JPEG、PNG等格式，最大10MB），支持服务器上传
- 📏 **智能尺寸建议**: 根据模板类型（横版/竖版）自动推荐合适的尺寸

### 数据管理

- 📊 **字段数据管理**: 可视化编辑和预览字段数据
- 🔍 **字段分类**: 系统字段按类别组织（基本信息、考试信息、证书信息、日期信息等）
- 💾 **配置保存**: 一键保存证书配置（模板、元素、字段数据）到控制台
- 👁️ **实时预览**: 支持预览最终证书效果，自动替换字段占位符为实际数据

### 交互功能

- 🖱️ **拖拽移动**: 选中元素后可拖拽移动位置
- 🔄 **调整大小**: 选中元素后拖动四角控制点调整大小
- ✏️ **属性编辑**: 右侧属性面板实时编辑选中元素的各项属性
- 🗑️ **元素删除**: 支持删除不需要的元素

## 📁 项目结构

```
drawcert/
├── src/
│   ├── components/
│   │   ├── CertificateEditor.vue    # 主编辑器组件（核心组件）
│   │   ├── DesignPanel.vue          # 左侧设计面板（元素添加、模板管理）
│   │   ├── CanvasArea.vue           # 中间画布区域（证书展示和编辑）
│   │   ├── PropertiesPanel.vue      # 右侧属性编辑面板
│   │   ├── FieldDataPanel.vue       # 字段数据管理面板
│   │   ├── FieldDialog.vue          # 字段关联对话框
│   │   └── CertificatePreview.vue   # 证书预览组件（模态框）
│   ├── utils/
│   │   ├── fieldManager.js          # 系统字段管理和工具函数
│   │   ├── templateManager.js        # 模板管理和工具函数
│   │   └── common.js                 # 公共工具函数（上传功能等）
│   ├── App.vue                      # 根组件
│   ├── main.js                      # 入口文件
│   └── style.css                    # 全局样式
├── index.html
├── package.json
├── vite.config.js
└── README.md
```

## 🚀 安装和运行

### 环境要求

- Node.js >= 22.21.0
- npm >= 11.6.2

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run dev
```

启动后访问 `http://localhost:3000`（或终端显示的地址）

### 构建生产版本

```bash
npm run build
```

构建产物将输出到 `dist` 目录

### 预览生产版本

```bash
npm run preview
```

## 📖 使用说明

### 自定义系统字段

`CertificateEditor` 组件支持通过 `systemFields` prop 传入自定义系统字段配置，实现灵活的字段管理。

#### 在项目中使用

```vue
<template>
  <CertificateEditor :system-fields="customSystemFields" />
</template>

<script setup>
import { ref } from 'vue'
import {
  CertificateEditor,
  SYSTEM_FIELDS
} from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

// 定义自定义系统字段
const customSystemFields = ref([
  // 添加自定义字段
  {
    key: 'studentId',
    label: '学号',
    placeholder: '{{学号}}',
    category: '学生信息',
    description: '学生的学号'
  },
  {
    key: 'className',
    label: '班级名称',
    placeholder: '{{班级名称}}',
    category: '学生信息',
    description: '学生所在班级'
  },
  // 保留默认字段
  ...SYSTEM_FIELDS
])
</script>
```

#### 字段对象格式

每个系统字段对象必须包含以下属性：

- `key` (String, 必需): 字段的唯一标识符，用于在代码中引用
- `label` (String, 必需): 字段的显示名称，显示在界面上
- `placeholder` (String, 必需): 字段的占位符格式，如 `{{姓名}}`
- `category` (String, 可选): 字段的分类，用于分组显示
- `description` (String, 可选): 字段的描述信息

#### 注意事项

- 如果不传入 `systemFields` prop，组件将使用默认的 `SYSTEM_FIELDS`
- 自定义字段的 `key` 必须唯一，避免与默认字段冲突
- 字段的 `placeholder` 格式必须为 `{{字段名}}` 的形式
- 自定义字段会自动在字段选择对话框、属性面板等位置显示

### 基本操作流程

1. **选择模板**
   - 点击左侧面板的"底图模板"标签
   - 选择横版或竖版预设模板，或上传自定义背景图片
   - 模板背景将自动铺满整个证书画布

2. **添加元素**
   - 点击左侧面板的"设计元素"标签
   - 选择要添加的元素类型：
     - **短文本**: 适合标题、姓名等简短文本
     - **长文本**: 适合描述、说明等较长文本
     - **图片**: 支持上传图片或关联用户头像字段
     - **二维码**: 支持文本内容或关联证书编号等字段

3. **编辑元素**
   - 点击画布上的元素进行选择（选中后显示边框和控制点）
   - 在右侧属性面板编辑元素的各种属性
   - 可以拖拽移动元素位置
   - 可以拖动四角控制点调整元素大小

4. **关联系统字段**
   - 对于文本元素：点击内容输入框右侧的"+"按钮，打开字段关联对话框
   - 选择要关联的系统字段，字段占位符将插入到文本中
   - 在字段数据面板中编辑字段的实际值

5. **预览和保存**
   - 点击顶部工具栏的"预览"按钮，查看最终证书效果
   - 点击"保存"按钮，将当前配置保存到浏览器控制台

### 文本元素

#### 文本格式化选项

- **字体大小**: 从下拉菜单选择预设大小（12px - 72px）
- **字体**: 选择字体族（如：宋体、微软雅黑、Arial等）
- **样式**: 
  - 粗体 (B)
  - 斜体 (I)
  - 下划线 (U)
- **颜色**: 点击颜色选择器设置文字颜色
- **对齐**: 左对齐、居中、右对齐、两端对齐
- **行高**: 设置文本行高（1.0 - 3.0）

#### 字段关联

- 在文本内容中插入字段占位符，如：`{{姓名}}`、`{{考试名称}}`
- 系统会自动识别并高亮显示字段占位符
- 在字段数据面板中编辑字段的实际值

### 图片元素

#### 图片来源

1. **本地上传**
   - 点击"本地上传"按钮选择本地图片文件
   - 支持格式：JPG、JPEG、PNG、GIF、WEBP、SVG、BMP
   - 文件大小限制：最大 2MB
   - 如果配置了 `uploadConfig`，会上传到服务器并获取网络URL
   - 如果未配置 `uploadConfig`，会自动转换为 Base64 格式

2. **URL输入**
   - 在URL输入框中输入图片的网络地址
   - 支持 http/https 协议的图片链接
   - 支持协议相对URL（// 开头），会自动转换为完整URL

3. **关联字段**
   - 选择关联的系统字段（如：头像、照片、头像图片）
   - 系统会使用字段数据中的图片URL或Base64数据

#### 图片尺寸

- 可以自由设置图片的宽度和高度
- 支持像素（px）单位

### 二维码元素

#### 二维码内容来源

1. **本地上传**
   - 点击"本地上传"按钮选择二维码图片
   - 支持格式：JPG、JPEG、PNG、GIF、WEBP、SVG、BMP
   - 文件大小限制：最大 2MB
   - 如果配置了 `uploadConfig`，会上传到服务器并获取网络URL
   - 如果未配置 `uploadConfig`，会自动转换为 Base64 格式

2. **URL/内容输入**
   - 输入文本内容（将生成二维码）
   - 输入图片URL（直接显示二维码图片）
   - 支持协议相对URL（// 开头），会自动转换为完整URL

3. **关联字段**
   - 选择关联的系统字段（如：证书编号、身份证号、链接地址、考试名称）
   - 系统会使用字段数据中的内容生成二维码

#### 二维码尺寸

- 可以自由设置二维码的宽度和高度
- 支持像素（px）单位

### 模板管理

#### 预设模板

- 系统提供多套预设的横版和竖版证书模板
- 点击"底图模板"标签切换到模板管理
- 点击模板类型按钮（"竖版"或"横版"）筛选模板
- 点击模板卡片选择并应用模板

#### 自定义模板上传

1. 点击"上传自定义模板"按钮
2. 选择要上传的背景图片文件
3. 系统会根据当前选择的模板类型（横版/竖版）自动设置推荐尺寸
4. 如果配置了 `uploadConfig`，会上传到服务器并获取网络URL
5. 如果未配置 `uploadConfig`，会自动转换为 Base64 格式
6. 上传成功后，模板将自动应用

**上传要求**:
- 支持格式：JPG、JPEG、PNG、GIF、WEBP、SVG、BMP
- 文件大小：最大 2MB
- 建议尺寸：
  - 竖版：972 x 1378 px 或相近比例
  - 横版：1303 x 897 px 或相近比例

### 字段数据管理

- 在右侧面板底部的"字段数据"区域管理字段值
- 系统会根据证书中使用的字段自动显示相应的输入框
- 编辑字段值后，画布上的占位符会自动更新（预览模式）

### 服务器上传配置

组件支持配置上传接口，所有图片上传（模板背景、图片元素、二维码元素）都可以自动上传到服务器并获取网络URL。

#### 配置上传接口

```vue
<template>
  <CertificateEditor 
    :upload-config="uploadConfig"
    @save="handleSave"
  />
</template>

<script setup>
import { ref } from 'vue'
import { CertificateEditor } from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

// 上传配置
const uploadConfig = ref({
  url: 'http://localhost:8000/api/upload', // 上传接口地址（必需）
  method: 'POST', // 请求方法，默认 'POST'
  fileField: 'file', // 文件字段名，默认 'file'
  params: {
    // 额外的表单参数（可选）
    type: 'image',
    category: 'certificate'
  },
  headers: {
    // 请求头（可选）
    'Authorization': 'Bearer your-token-here',
    'X-Custom-Header': 'value'
  }
})

const handleSave = (certificateData) => {
  console.log('证书配置数据：', certificateData)
}
</script>
```

#### 服务器返回格式

组件支持多种服务器返回格式，会自动识别并提取图片URL：

```javascript
// 格式1：直接返回 url 字段
{ "url": "http://example.com/image.jpg" }

// 格式2：嵌套在 data.file 中
{ 
  "data": { 
    "file": { 
      "full_url": "http://example.com/image.jpg",
      "url": "http://example.com/image.jpg"
    } 
  } 
}

// 格式3：嵌套在 data 中
{ "data": { "url": "http://example.com/image.jpg" } }

// 格式4：直接返回 URL 字符串
{ "data": "http://example.com/image.jpg" }

// 格式5：直接返回字符串
"http://example.com/image.jpg"
```

#### 兼容性说明

- 如果未配置 `uploadConfig` 或设置为 `null`，所有图片上传会自动使用 Base64 方式
- 保持向后兼容，不影响现有功能
- 支持协议相对URL（`//` 开头），会自动转换为完整URL

### 预览功能

- 点击顶部工具栏的"预览"按钮打开预览模态框
- 预览模式下，所有字段占位符会被替换为实际字段数据
- 预览的证书即为最终效果

### 保存功能

- 点击顶部工具栏的"保存"按钮
- 系统会将当前证书配置（模板、元素列表、字段数据）输出到浏览器控制台
- 同时触发 `save` 事件，将数据传递给父组件
- 父组件可以通过事件处理函数接收保存的数据

**保存的数据结构**:
```json
{
  "template": {
    "id": "template-id",
    "name": "模板名称",
    "background": "背景图片或颜色",
    "width": 972,
    "height": 1378
  },
  "elements": [
    {
      "id": 1234567890,
      "type": "text",
      "content": "{{姓名}}（{{性别称呼}}）",
      "x": 100,
      "y": 200,
      "width": 300,
      "fontSize": 24,
      // ... 其他属性
    }
  ],
  "fieldData": {
    "name": "张三",
    "gender": "先生",
    // ... 其他字段数据
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

#### 在父组件中获取保存的数据

有两种方式可以在父组件中获取证书配置数据：

**方式一：通过事件监听（推荐）**

当用户点击保存按钮时，组件会触发 `save` 事件，父组件可以通过监听该事件获取数据：

```vue
<template>
  <CertificateEditor 
    :system-fields="customSystemFields"
    @save="handleSave"
  />
</template>

<script setup>
import { ref } from 'vue'
import { CertificateEditor } from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

const handleSave = (certificateData) => {
  console.log('接收到保存的数据：', certificateData)
  
  // 在这里可以处理保存的数据，例如：
  // - 发送到服务器
  // - 保存到本地存储
  // - 进行数据验证
  // 等等...
}
</script>
```

**方式二：通过组件方法主动获取**

父组件可以通过组件引用调用 `getCertificateData()` 方法，随时获取当前的证书配置数据（无需点击保存按钮）：

```vue
<template>
  <CertificateEditor 
    ref="certificateEditorRef"
    :system-fields="customSystemFields"
  />
  <button @click="getData">获取当前配置</button>
</template>

<script setup>
import { ref } from 'vue'
import { CertificateEditor } from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

const certificateEditorRef = ref(null)

const getData = () => {
  if (certificateEditorRef.value) {
    const data = certificateEditorRef.value.getCertificateData()
    console.log('当前证书配置：', data)
    // 处理数据...
  }
}
</script>
```

**完整示例**：

```vue
<template>
  <CertificateEditor 
    ref="certificateEditorRef"
    :system-fields="customSystemFields"
    @save="handleSave"
  />
  <button @click="getCurrentData">获取当前配置</button>
</template>

<script setup>
import { ref } from 'vue'
import {
  CertificateEditor,
  SYSTEM_FIELDS
} from 'z-certificate-editor'
import 'z-certificate-editor/style.css'

const customSystemFields = ref([...SYSTEM_FIELDS])
const certificateEditorRef = ref(null)

// 方式一：监听保存事件
const handleSave = (certificateData) => {
  console.log('用户点击保存，数据：', certificateData)
  
  // 示例：保存到本地存储
  localStorage.setItem('certificateConfig', JSON.stringify(certificateData))
  
  // 示例：发送到服务器
  // fetch('/api/certificate/save', {
  //   method: 'POST',
  //   headers: { 'Content-Type': 'application/json' },
  //   body: JSON.stringify(certificateData)
  // })
}

// 方式二：主动获取数据
const getCurrentData = () => {
  if (certificateEditorRef.value) {
    const data = certificateEditorRef.value.getCertificateData()
    console.log('当前配置数据：', data)
    return data
  }
}
</script>
```

## 🧩 组件说明

### CertificateEditor

主编辑器组件，负责整体的状态管理和组件协调。

**功能**:
- 管理元素列表、选中元素、字段数据、当前模板
- 协调各子组件的通信
- 提供预览和保存功能

**Props**:
- `systemFields` (Array, 可选): 自定义系统字段配置数组
  - 如果不传入，将使用默认的 `SYSTEM_FIELDS`
  - 字段对象格式：
- `uploadConfig` (Object, 可选): 上传配置对象
  - 如果配置了上传接口，所有图片上传都会请求服务器
  - 配置格式：
    ```javascript
    {
      url: 'http://example.com/api/upload', // 上传接口地址（必需）
      method: 'POST', // 请求方法，默认 'POST'
      fileField: 'file', // 文件字段名，默认 'file'
      params: {
        // 额外的表单参数（可选）
        type: 'image',
        category: 'certificate'
      },
      headers: {
        // 请求头（可选）
        'Authorization': 'Bearer token',
        'X-Custom-Header': 'value'
      }
    }
    ```
  - 如果不配置或设置为 `null`，则使用 Base64 方式
  - 服务器返回格式支持：
    - `{ url: '...' }`
    - `{ data: { file: { full_url: '...', url: '...' } } }`
    - `{ data: { url: '...' } }`
    - `{ data: '...' }`
    - 直接返回 URL 字符串
    ```javascript
    {
      key: '字段唯一标识',
      label: '字段显示名称',
      placeholder: '{{占位符}}',
      category: '字段分类',
      description: '字段描述'
    }
    ```
  - 示例：
    ```javascript
    const customFields = [
      {
        key: 'customField',
        label: '自定义字段',
        placeholder: '{{自定义字段}}',
        category: '其他',
        description: '这是一个自定义字段'
      },
      ...SYSTEM_FIELDS // 可以结合默认字段使用
    ]
    ```

**Events**:
- `save`: 当用户点击保存按钮时触发
  - 参数：`certificateData` (Object) - 证书配置数据对象
  - 数据结构包含：`template`、`elements`、`fieldData`、`timestamp`

**Exposed Methods**:
- `getCertificateData()`: 获取当前证书配置数据
  - 返回：`Object` - 证书配置数据对象
  - 使用方式：通过组件引用调用 `certificateEditorRef.value.getCertificateData()`

### DesignPanel

左侧设计面板，提供元素添加和模板管理功能。

**功能**:
- 切换"设计元素"和"底图模板"标签
- 提供元素添加按钮（短文本、长文本、图片、二维码）
- 管理预设模板和自定义模板上传

**Events**:
- `add-element`: 添加新元素时触发，参数为元素类型
- `select-template`: 选择模板时触发，参数为模板对象
- `upload-template`: 上传模板时触发，参数为模板对象

### CanvasArea

中间画布区域，显示证书模板和可编辑元素。

**功能**:
- 渲染证书背景模板
- 渲染和交互所有元素（文本、图片、二维码）
- 处理元素的拖拽和调整大小
- 替换字段占位符为实际数据

**Props**:
- `elements`: Array - 元素列表
- `selectedElement`: Object | null - 当前选中的元素
- `fieldData`: Object - 字段数据对象
- `template`: Object - 当前选中的模板
- `systemFields`: Array - 系统字段配置数组（从 CertificateEditor 传递）

**Events**:
- `select-element`: 选择元素时触发
- `update-element`: 更新元素时触发
- `delete-element`: 删除元素时触发

### PropertiesPanel

右侧属性编辑面板，编辑选中元素的属性。

**功能**:
- 根据元素类型动态显示相应的编辑选项
- 提供文本格式化、图片设置、二维码设置等功能
- 实时更新元素属性

**Props**:
- `element`: Object - 当前选中的元素
- `systemFields`: Array - 系统字段配置数组（从 CertificateEditor 传递）
- `uploadConfig`: Object - 上传配置对象（从 CertificateEditor 传递）

**Events**:
- `update-element`: 更新元素时触发

### FieldDataPanel

字段数据管理面板，显示和编辑字段数据。

**功能**:
- 显示当前使用的系统字段
- 提供字段值的输入框
- 实时更新字段数据

**Props**:
- `fieldData`: Object - 字段数据对象

**Events**:
- `update-field-data`: 更新字段数据时触发

### FieldDialog

字段关联对话框，用于在文本中插入系统字段。

**功能**:
- 显示系统字段列表（按类别分组）
- 支持搜索字段
- 插入字段占位符到文本内容

**Props**:
- `visible`: Boolean - 对话框显示状态
- `currentText`: String - 当前文本内容
- `selectionStart`: Number - 文本选择起始位置
- `selectionEnd`: Number - 文本选择结束位置
- `systemFields`: Array - 系统字段配置数组（从 PropertiesPanel 传递）

### CertificatePreview

证书预览组件，以模态框形式显示最终证书效果。

**功能**:
- 渲染完整的证书预览
- 自动替换所有字段占位符为实际数据
- 支持关闭预览

**Props**:
- `visible`: Boolean - 预览对话框显示状态
- `elements`: Array - 元素列表
- `template`: Object - 当前选中的模板
- `fieldData`: Object - 字段数据对象
- `systemFields`: Array - 系统字段配置数组（从 CertificateEditor 传递）

## 🛠️ 技术栈

- **Vue 3**: 使用 Composition API 进行组件开发
- **Vite**: 快速的前端构建工具
- **原生 CSS**: 无第三方CSS框架，纯原生样式
- **Canvas/HTML**: 基于HTML和CSS的渲染，非Canvas绘制

## 🔌 API 参考

### CertificateEditor Props

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `systemFields` | `Array` | `SYSTEM_FIELDS` | 自定义系统字段配置数组 |
| `uploadConfig` | `Object` | `null` | 上传配置对象，配置后所有图片上传会请求服务器 |
| `templates` | `Array` | `PRESET_TEMPLATES` | 自定义模板数组 |
| `initialData` | `Object` | `null` | 初始证书配置数据 |

### CertificateEditor Events

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `save` | `certificateData: Object` | 当用户点击保存按钮时触发，传递证书配置数据 |

### CertificateEditor Exposed Methods

| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| `getCertificateData()` | - | `Object` | 获取当前证书配置数据，无需点击保存按钮 |

### 系统字段对象格式

```typescript
interface SystemField {
  key: string          // 字段唯一标识
  label: string        // 字段显示名称
  placeholder: string  // 占位符格式，如 "{{姓名}}"
  category?: string    // 字段分类（可选）
  description?: string // 字段描述（可选）
}
```

### 证书配置数据格式

```typescript
interface CertificateData {
  template: {
    id: string
    name: string
    type: 'vertical' | 'horizontal'
    background: string
    width: number
    height: number
  }
  elements: Array<{
    id: number
    type: 'text' | 'longtext' | 'image' | 'qrcode'
    x: number
    y: number
    width: number
    height?: number
    content?: string
    style?: object
    imageSource?: 'url' | 'field'
    imageUrl?: string
    imageField?: string
    qrcodeSource?: 'url' | 'field'
    qrcodeContent?: string
    qrcodeField?: string
  }>
  fieldData: Record<string, any>
  timestamp: string
}
```

## 📋 系统字段列表

系统内置了丰富的字段类型，按类别组织：

### 基本信息
- 姓名 (name)
- 性别称呼 (gender)
- 账号 (account)

### 考试信息
- 考试名称 (examName)
- 成绩 (score)
- 成绩等级 (scoreLevel)
- 考试分数 (examScore)

### 证书信息
- 证书编号 (certificateNumber)
- 有效期 (validityPeriod)

### 日期信息
- 签发日期 (issueDate)
- 签发日期-年 (issueDateYear)
- 签发日期-月 (issueDateMonth)
- 签发日期-日 (issueDateDay)
- 生效日期 (effectiveDate)
- 到期日期 (expiryDate)

### 其他信息
- 身份证号 (idNumber)
- 手机号 (phone)
- 邮箱 (email)
- 地址 (address)
- 机构名称 (organization)
- 链接地址 (url)

### 图片字段
- 头像 (avatar)
- 照片 (photo)
- 头像图片 (headImage)

## 🌐 浏览器支持

- ✅ Chrome (最新版)
- ✅ Firefox (最新版)
- ✅ Safari (最新版)
- ✅ Edge (最新版)

## 📝 开发计划

### 已完成功能 ✅

- [x] 可视化拖拽编辑
- [x] 文本元素（短文本、长文本）
- [x] 图片元素（本地上传、URL、关联字段）
- [x] 二维码元素（文本内容、URL、关联字段）
- [x] 服务器上传功能（支持配置上传接口）
- [x] 系统字段关联
- [x] 自定义系统字段支持（通过 props 传入）
- [x] 预设模板管理
- [x] 自定义模板上传
- [x] 字段数据管理
- [x] 预览功能
- [x] 配置保存功能

### 计划中功能 🚧

- [ ] 二维码生成（根据文本内容自动生成二维码图片）
- [ ] 撤销/重做功能
- [ ] 元素复制/粘贴
- [ ] 元素对齐辅助线
- [ ] 导出功能（PNG、PDF）
- [ ] 导入功能（导入保存的配置）
- [ ] 元素层级管理（置顶、置底、上移、下移）
- [ ] 批量操作（多选、批量移动、批量删除）
- [ ] 模板收藏和分类
- [ ] 响应式设计适配


## 📄 许可证

MIT

## 📝 版本历史

### 1.0.3
- 初始版本发布
- 支持可视化证书编辑
- 支持系统字段关联
- 支持模板管理
- 支持图片和二维码元素
- 支持保存和预览功能
- 支持自定义系统字段
- 支持通过事件和方法获取保存的数据
- 发布为 npm 包，支持 ES 模块和 UMD 格式

### 1.0.4+
- 新增服务器上传功能
  - 支持配置上传接口（URL、请求方法、请求头、请求参数）
  - 所有图片上传（模板、图片元素、二维码元素）都支持服务器上传
  - 支持多种服务器返回格式
  - 未配置上传接口时自动使用 Base64 方式（向后兼容）
- 支持协议相对URL（// 开头），自动转换为完整URL
- 优化图片和二维码显示逻辑
- 提取上传功能到公共工具函数（`utils/common.js`）

## 👨‍💻 开发说明

### 核心概念

1. **元素系统**: 所有可编辑的元素（文本、图片、二维码）都遵循统一的数据结构
2. **字段系统**: 使用占位符（如 `{{姓名}}`）实现动态内容替换
3. **模板系统**: 支持预设模板和自定义模板，背景自动铺满画布
4. **状态管理**: 使用 Vue 3 Composition API 的 `ref` 和 `reactive` 管理状态

### 代码规范

- 使用 Composition API
- 组件采用单文件组件（SFC）格式
- 使用语义化的CSS类名
- 保持组件的单一职责原则

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题或建议，请提交 Issue。