erp-print

# erp-print 一个基于 Hiprint + Vue3 + TypeScript + Element Plus 的现代化模打印组件库。 ### 安装 ```bash npm install erp-print ``` ### 环境要求 - Vue 3.x - Element Plus 2.x - TypeScript ### 快速上手 1. 导入并使用组件： ```vue <template> <PrintDesigner v-model="templateData" :config="designerConfig" @template-init="handleInit" @template-change="handleChange" @print-success="handlePrintSuccess" @business-fields-refresh="handleBusinessFieldsRefresh" /> </template> <script setup lang="ts"> import { ref } from 'vue' import { PrintDesigner } from 'erp-print' import type { PrintDesignerConfig, TemplateData } from 'erp-print' const templateData = ref<TemplateData>({ baseForm: { name: '我的模板' }, templateJson: {}, }) const designerConfig = ref<PrintDesignerConfig>({ upload: { action: '/api/upload', allowedTypes: ['image/jpeg', 'image/png'], maxSizeInMB: 5, }, businessFields: { fields: [], // 你的业务字段 async: true, // 启用异步模式以便进行加载状态管理 isLoading: false, // 在配置中管理加载状态 loadingText: '正在加载业务字段...', }, }) const handleInit = (printInstance) => { console.log('设计器初始化完成:', printInstance) } const handleChange = (data: TemplateData) => { console.log('模板数据变更:', data) } const handlePrintSuccess = (result) => { console.log('打印成功:', result) } const handleBusinessFieldsRefresh = () => { console.log('业务字段刷新请求') // 开始加载 if (designerConfig.value.businessFields) { designerConfig.value.businessFields.isLoading = true } // 模拟异步数据获取 setTimeout(() => { // 在这里更新您的业务字段 if (designerConfig.value.businessFields) { designerConfig.value.businessFields.fields = [ /* 您的新字段 */ ] // 结束加载 designerConfig.value.businessFields.isLoading = false } }, 1000) } </script> ``` 更多详细示例请查看源码中的 `ExampleDemo.vue` 文件。 ### 功能特性 - 🎨 现代化的打印模板设计器 - 📄 支持多种纸张尺寸和方向 - 🖼️ 丰富的元素类型 (文本, 图片, 表格等) - 🌐 多语言支持 - 📱 响应式设计 - 🔧 TypeScript 支持 - ⚡ 实时预览 - 📋 业务字段集成 ### API 参考 #### `PrintDesigner` 组件 ##### **Config 属性** `PrintDesigner` 组件通过 `config` 属性进行配置，它接受一个 `PrintDesignerConfig` 类型的对象。 ```typescript interface PrintDesignerConfig { // 图片上传配置 upload?: { action?: string allowedTypes?: string[] maxSizeInMB?: number headers?: Record<string, string> data?: Record<string, any> } // 用于拖拽的业务字段 businessFields?: { fields?: BusinessFieldGroup[] async?: boolean isLoading?: boolean loadingText?: string } // 侧边栏的自定义控件元素 customControlList?: ControlItem[] } ``` ##### **事件** | 事件名称 | 参数 | 描述 | | ------------------------- | ----------------------- | -------------- | | `template-init` | `(printInstance: any)` | 模板初始化完成 | | `template-change` | `(data: TemplateData)` | 模板数据变更 | | `template-error` | `(error: any)` | 模板更新出错 | | `print-success` | `(result: object)` | 打印成功 | | `print-error` | `(error: object)` | 打印失败 | | `export-success` | `(result: object)` | 导出成功 | | `export-error` | `(error: object)` | 导出失败 | | `business-fields-refresh` | `()` | 刷新业务字段 | | `cancel` | `()` | 取消操作 | | `save` | `(printInstance, data)` | 保存模板 | ##### **暴露方法** 当您获取 `PrintDesigner` 组件的 `ref` 引用时，可以调用以下方法： ```vue <script setup lang="ts"> import { ref, onMounted } from 'vue' import { PrintDesigner } from 'erp-print' const designerRef = ref<InstanceType<typeof PrintDesigner>>() onMounted(() => { // 组件挂载后调用方法 designerRef.value?.init() }) </script> ``` | 方法名称 | 参数 | 描述 | | ------------------------- | ------------------ | ------------------------- | | `init()` | `void` | 初始化设计器 | | `getPrintInstance()` | `void` | 获取底层的 hiprint 实例 | | `getConfig()` | `void` | 获取当前解析后的配置 | | `refreshBusinessFields()` | `void` | 刷新业务字段 (异步模式下) | | `printAction()` | `(params: object)` | 通过编程方式触发打印 | | `exportPDF()` | `(params: object)` | 通过编程方式触发 PDF 导出 | ##### **插槽** | 插槽名称 | 描述 | | ------------------- | -------------------- | | `custom-header-btn` | 自定义头部按钮 | | `custom-form` | 侧边栏中的自定义表单 | --- #### `TemplatePreview` 组件 `TemplatePreview` 组件是一个用于预览、打印和导出 hiprint 模板的对话框。它通过 `ref` 引用及其 `show` 方法来控制。 ##### **用法** ```vue <template> <div> <el-button @click="showPreview">显示预览</el-button>  <TemplatePreview ref="previewRef" /> </div> </template> <script setup lang="ts"> import { ref } from 'vue' import { TemplatePreview, hiprint } from 'erp-print' import type { TemplateData } from 'erp-print' // 1. 获取组件的 ref 引用 const previewRef = ref<InstanceType<typeof TemplatePreview>>() // 2. 准备您的模板 JSON 和数据 // 在实际应用中，您会从 PrintDesigner 或后端获取这些数据 const templateJson = { panels: [ /* ... 您的模板 json ... */ ], } const printData: TemplateData = { baseForm: { name: '预览' }, templateJson: templateJson } // 创建一个 hiprint 模板实例 const hiprintTemplate = new hiprint.PrintTemplate({ template: printData.templateJson, }) // 3. 调用 show 方法打开对话框 const showPreview = () => { previewRef.value?.show(hiprintTemplate, printData) } </script> ``` ##### **暴露方法** | 方法名称 | 参数 | 描述 | | -------- | ------------------------------------------------ | -------------- | | `show()` | `(hiprintTemplate, printData, options?: object)` | 显示预览对话框 | ### 类型支持该库使用 TypeScript 编写，并导出了所有必要的类型，以提供完整的类型化开发体验。您可以直接从包中导入它们。 ```typescript import type { PrintDesignerConfig, TemplateData, BusinessFieldGroup, ControlItem, // ... 以及其他类型 } from 'erp-print' ``` ### 模板功能 #### 1. 纸张类型支持 - 标准纸张尺寸 (A4, A3, Letter 等) - 自定义纸张尺寸，单位为毫米 (mm) - 支持纸张旋转 #### 2. 元素类型 - **文本 (Text)**: 基本的文本元素 - **长文本 (Long Text)**: 多行文本 - **图片 (Image)**: 图片上传和显示 - **表格 (Table)**: 可自定义列的数据表格 - **矩形 (Rectangle)**: 矩形形状 - **水平线 (Horizontal Line)**: 水平分割线 - **垂直线 (Vertical Line)**: 垂直分割线 - **椭圆 (Oval)**: 椭圆形状 - **HTML**: 自定义 HTML 内容 #### 3. 业务字段类型 - **配置字段**: 标准的业务数据字段 - **表格字段**: 动态的表格列 #### 4. 操作 - **缩放调整**: 放大/缩小 - **纸张旋转**: 旋转模板 - **清空模板**: 移除所有元素 - **JSON 视图**: 查看模板结构 - **打印预览**: 打印前进行预览 - **导出为 PDF**: 支持多种导出格式 - **撤销/重做**: 操作历史记录 ### 开发 ```bash # 安装依赖 npm install # 启动开发服务器 npm run dev # 构建库 npm run build # 构建演示 npm run build-demo # 类型检查 npm run type-check # 代码检查和格式化 npm run lint npm run format # 打包并发布 npm run package # 补丁版本 npm run package:minor # 次要版本 npm run package:major # 主要版本 npm run package:beta # Beta 版本 ``` ### 国际化 (i18n) erp-print 支持多语言，并与 hiprint 自动同步。 #### 支持的语言 - `cn` - 简体中文 - `en` - English - `de` - Deutsch (German) - `es` - Español (Spanish) - `fr` - Français (French) - `it` - Italiano (Italian) - `ja` - 日本語 (Japanese) - `ru` - Русский (Russian) - `cn_tw` - 繁體中文 (Traditional Chinese) #### 语言特性 - 🔄 **与 hiprint 自动同步** - 💾 **持久化存储** - 🌐 **浏览器语言检测** - 🔧 **编程式控制** - 📦 **内置翻译** 语言系统由 `PrintDesigner` 组件自动管理。用户可以使用工具栏中内置的语言下拉菜单切换语言。 ### 高级配置对于复杂的业务场景，您可以使用自定义配置来扩展组件： ```typescript // 高级业务字段配置 const advancedConfig: PrintDesignerConfig = { upload: { action: '/api/upload', headers: { Authorization: 'Bearer your-token', }, // 自定义上传数据转换 data: { module: 'print-templates', category: 'invoices', }, }, businessFields: { fields: [ { id: 'invoice', typeName: '发票字段', variables: [ { id: '1', name: '发票号', field: 'invoiceNo', fieldType: 'normal', defaultValue: 'INV-001', }, // ... 更多字段 ], defaultExpand: true, }, ], async: true, loadingText: '正在加载业务字段...', }, } ``` ### 最佳实践 1. **类型安全** ```typescript // 始终使用 TypeScript 以获得更好的开发体验 import type { PrintDesignerConfig } from 'erp-print' ``` 2. **性能** ```typescript // 对大型业务字段数据集使用异步加载 const config = { businessFields: { async: true, fields: [], // 动态加载 }, } ``` 3. **错误处理** ```vue <PrintDesigner @template-error="handleError" @print-error="handlePrintError" /> ``` ## 未来计划 - **静默打印**: 增加对直接打印功能的支持，无需用户交互，适用于批处理和自动化工作流程。 - **更多元素类型**: 引入新的元素，如图表。 - **高级样式**: 提供对元素样式和布局更精细的控制。 - **性能提升**: 持续优化大型复杂模板的性能。 ## 许可证 MIT 许可证