z-certificate-editor 1.0.2 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 z-certificate-editor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,110 @@
-# 证书编辑器 (Certificate Editor)
+# 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/dist/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/dist/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/dist/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>
+```
+
+## 📖 完整文档
+
+以下是完整的项目文档和使用说明。
+
 ## ✨ 功能特性
 
 ### 核心功能
@@ -11,6 +114,7 @@
 - 🖼️ **图片元素**: 支持本地上传、URL输入、关联系统字段（如用户头像）
 - 🔲 **二维码元素**: 支持文本内容、URL输入、关联系统字段（如证书编号、身份证号）
 - 🎯 **系统字段关联**: 动态关联系统字段，实现证书内容的自动化填充
+- ⚙️ **自定义系统字段**: 支持通过 props 传入自定义系统字段配置，灵活适配不同业务场景
 - 📐 **精确定位**: 支持精确的位置（X、Y）和尺寸（宽度、高度）设置
 - 🎨 **丰富的文本格式**: 字体大小、字体族、粗体、斜体、下划线、颜色、对齐方式、行高等
 
@@ -60,95 +164,98 @@ drawcert/
 └── README.md
 ```
 
-## 📦 作为 npm 包使用
+## 🚀 安装和运行
 
-### 安装
+### 环境要求
+
+- Node.js >= 22.21.0
+- npm >= 11.6.2
+
+### 安装依赖
 
 ```bash
-npm install z-certificate-editor
+npm install
 ```
 
-### 在 Vue 3 项目中使用
-
-```vue
-<template>
-  <CertificateEditor />
-</template>
+### 开发模式
 
-<script setup>
-import CertificateEditor from 'z-certificate-editor'
-import 'z-certificate-editor/style.css'
-</script>
+```bash
+npm run dev
 ```
 
-### 按需导入组件
+启动后访问 `http://localhost:3000`（或终端显示的地址）
 
-```vue
-<template>
-  <div>
-    <DesignPanel @add-element="handleAddElement" />
-    <CanvasArea :elements="elements" />
-    <PropertiesPanel :element="selectedElement" />
-  </div>
-</template>
+### 构建生产版本
 
-<script setup>
-import { 
-  DesignPanel, 
-  CanvasArea, 
-  PropertiesPanel 
-} from 'z-certificate-editor'
-import 'z-certificate-editor/style.css'
-</script>
+```bash
+npm run build
 ```
 
-### 使用工具函数
-
-```javascript
-import { 
-  SYSTEM_FIELDS, 
-  replaceFields, 
-  extractFields,
-  PRESET_TEMPLATES 
-} from 'z-certificate-editor'
+构建产物将输出到 `dist` 目录
 
-// 使用系统字段
-console.log(SYSTEM_FIELDS)
+### 预览生产版本
 
-// 替换字段占位符
-const text = '{{姓名}}（{{性别称呼}}）'
-const fieldData = { name: '张三', gender: '先生' }
-const result = replaceFields(text, fieldData)
-// 结果: '张三（先生）'
-
-// 提取字段
-const fields = extractFields(text)
-// 结果: [{ key: 'name', label: '姓名', ... }, { key: 'gender', label: '性别称呼', ... }]
+```bash
+npm run preview
 ```
 
-## 🚀 本地开发
+## 📖 使用说明
 
-### 环境要求
+### 自定义系统字段
 
-- Node.js >= 22.21.0
-- npm >= 11.6.2
+`CertificateEditor` 组件支持通过 `systemFields` prop 传入自定义系统字段配置，实现灵活的字段管理。
 
-### 安装依赖
+#### 在 App.vue 中使用
 
-```bash
-npm install
+```vue
+<template>
+  <CertificateEditor :system-fields="customSystemFields" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import CertificateEditor from './components/CertificateEditor.vue'
+import { SYSTEM_FIELDS } from './utils/fieldManager.js'
+
+// 定义自定义系统字段
+const customSystemFields = ref([
+  // 添加自定义字段
+  {
+    key: 'studentId',
+    label: '学号',
+    placeholder: '{{学号}}',
+    category: '学生信息',
+    description: '学生的学号'
+  },
+  {
+    key: 'className',
+    label: '班级名称',
+    placeholder: '{{班级名称}}',
+    category: '学生信息',
+    description: '学生所在班级'
+  },
+  // 保留默认字段
+  ...SYSTEM_FIELDS
+])
+</script>
 ```
 
-### 开发模式
+#### 字段对象格式
 
-```bash
-npm run dev
-```
+每个系统字段对象必须包含以下属性：
 
-启动后访问 `http://localhost:3000`（或终端显示的地址）
+- `key` (String, 必需): 字段的唯一标识符，用于在代码中引用
+- `label` (String, 必需): 字段的显示名称，显示在界面上
+- `placeholder` (String, 必需): 字段的占位符格式，如 `{{姓名}}`
+- `category` (String, 可选): 字段的分类，用于分组显示
+- `description` (String, 可选): 字段的描述信息
 
+#### 注意事项
 
-## 📖 使用说明
+- 如果不传入 `systemFields` prop，组件将使用默认的 `SYSTEM_FIELDS`
+- 自定义字段的 `key` 必须唯一，避免与默认字段冲突
+- 字段的 `placeholder` 格式必须为 `{{字段名}}` 的形式
+- 自定义字段会自动在字段选择对话框、属性面板等位置显示
 
 ### 基本操作流程
 
@@ -284,7 +391,8 @@ npm run dev
 
 - 点击顶部工具栏的"保存"按钮
 - 系统会将当前证书配置（模板、元素列表、字段数据）输出到浏览器控制台
-- 打开浏览器开发者工具（F12）查看保存的数据
+- 同时触发 `save` 事件，将数据传递给父组件
+- 父组件可以通过事件处理函数接收保存的数据
 
 **保存的数据结构**:
 ```json
@@ -317,6 +425,113 @@ npm run dev
 }
 ```
 
+#### 在父组件中获取保存的数据
+
+有两种方式可以在父组件中获取证书配置数据：
+
+**方式一：通过事件监听（推荐）**
+
+当用户点击保存按钮时，组件会触发 `save` 事件，父组件可以通过监听该事件获取数据：
+
+```vue
+<template>
+  <CertificateEditor 
+    :system-fields="customSystemFields"
+    @save="handleSave"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import CertificateEditor from './components/CertificateEditor.vue'
+
+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 './components/CertificateEditor.vue'
+
+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 from './components/CertificateEditor.vue'
+import { SYSTEM_FIELDS } from './utils/fieldManager.js'
+
+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
@@ -328,6 +543,43 @@ npm run dev
 - 协调各子组件的通信
 - 提供预览和保存功能
 
+**Props**:
+- `systemFields` (Array, 可选): 自定义系统字段配置数组
+  - 如果不传入，将使用默认的 `SYSTEM_FIELDS`
+  - 字段对象格式：
+    ```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
 
 左侧设计面板，提供元素添加和模板管理功能。
@@ -357,6 +609,7 @@ npm run dev
 - `selectedElement`: Object | null - 当前选中的元素
 - `fieldData`: Object - 字段数据对象
 - `template`: Object - 当前选中的模板
+- `systemFields`: Array - 系统字段配置数组（从 CertificateEditor 传递）
 
 **Events**:
 - `select-element`: 选择元素时触发
@@ -374,6 +627,7 @@ npm run dev
 
 **Props**:
 - `element`: Object - 当前选中的元素
+- `systemFields`: Array - 系统字段配置数组（从 CertificateEditor 传递）
 
 **Events**:
 - `update-element`: 更新元素时触发
@@ -402,6 +656,13 @@ npm run dev
 - 支持搜索字段
 - 插入字段占位符到文本内容
 
+**Props**:
+- `visible`: Boolean - 对话框显示状态
+- `currentText`: String - 当前文本内容
+- `selectionStart`: Number - 文本选择起始位置
+- `selectionEnd`: Number - 文本选择结束位置
+- `systemFields`: Array - 系统字段配置数组（从 PropertiesPanel 传递）
+
 ### CertificatePreview
 
 证书预览组件，以模态框形式显示最终证书效果。
@@ -411,6 +672,13 @@ npm run dev
 - 自动替换所有字段占位符为实际数据
 - 支持关闭预览
 
+**Props**:
+- `visible`: Boolean - 预览对话框显示状态
+- `elements`: Array - 元素列表
+- `template`: Object - 当前选中的模板
+- `fieldData`: Object - 字段数据对象
+- `systemFields`: Array - 系统字段配置数组（从 CertificateEditor 传递）
+
 ## 🛠️ 技术栈
 
 - **Vue 3**: 使用 Composition API 进行组件开发
@@ -418,6 +686,71 @@ npm run dev
 - **原生 CSS**: 无第三方CSS框架，纯原生样式
 - **Canvas/HTML**: 基于HTML和CSS的渲染，非Canvas绘制
 
+## 🔌 API 参考
+
+### CertificateEditor Props
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `systemFields` | `Array` | `SYSTEM_FIELDS` | 自定义系统字段配置数组 |
+
+### 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
+}
+```
+
 ## 📋 系统字段列表
 
 系统内置了丰富的字段类型，按类别组织：
@@ -474,6 +807,7 @@ npm run dev
 - [x] 图片元素（本地上传、URL、关联字段）
 - [x] 二维码元素（文本内容、URL、关联字段）
 - [x] 系统字段关联
+- [x] 自定义系统字段支持（通过 props 传入）
 - [x] 预设模板管理
 - [x] 自定义模板上传
 - [x] 字段数据管理
@@ -493,10 +827,24 @@ npm run dev
 - [ ] 模板收藏和分类
 - [ ] 响应式设计适配
 
+
 ## 📄 许可证
 
 MIT
 
+## 📝 版本历史
+
+### 1.0.3
+- 初始版本发布
+- 支持可视化证书编辑
+- 支持系统字段关联
+- 支持模板管理
+- 支持图片和二维码元素
+- 支持保存和预览功能
+- 支持自定义系统字段
+- 支持通过事件和方法获取保存的数据
+- 发布为 npm 包，支持 ES 模块和 UMD 格式
+
 ## 👨‍💻 开发说明
 
 ### 核心概念