erp-print

一个基于 Hiprint + Vue3 + TypeScript + Element Plus 的现代化模打印组件库。

安装

npm install erp-print

环境要求

• Vue 3.x
• Element Plus 2.x
• TypeScript

快速上手

1. 导入并使用组件：

<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 类型的对象。

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 引用时，可以调用以下方法：

<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 方法来控制。

用法

<template>
  <div>
    <el-button @click="showPreview">显示预览</el-button>
    <!--
      预览组件可以放置在模板的任何位置。
      在调用 show 方法之前，它是不可见的。
    -->
    <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 编写，并导出了所有必要的类型，以提供完整的类型化开发体验。您可以直接从包中导入它们。

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: 支持多种导出格式
• 撤销/重做: 操作历史记录

开发

# 安装依赖
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 组件自动管理。用户可以使用工具栏中内置的语言下拉菜单切换语言。

高级配置

对于复杂的业务场景，您可以使用自定义配置来扩展组件：

// 高级业务字段配置
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 以获得更好的开发体验
   import type { PrintDesignerConfig } from 'erp-print'

2. 性能

   // 对大型业务字段数据集使用异步加载
   const config = {
     businessFields: {
       async: true,
       fields: [], // 动态加载
     },
   }

3. 错误处理

   <PrintDesigner @template-error="handleError" @print-error="handlePrintError" />

未来计划

• 静默打印: 增加对直接打印功能的支持，无需用户交互，适用于批处理和自动化工作流程。
• 更多元素类型: 引入新的元素，如图表。
• 高级样式: 提供对元素样式和布局更精细的控制。
• 性能提升: 持续优化大型复杂模板的性能。

许可证

MIT 许可证