vue3-print

Vue 3 打印模板设计器与打印运行时。面向需要可视化编辑标签、发票、物流面单、 条码/二维码、表格并进行浏览器/客户端/中转远程打印的业务系统。

本仓库已与上游兼容分支彻底脱离，是基于 Vue 3.4+ / Vite / TypeScript 的独立重写： 模块化源码、Pinia 状态、Zod schema 校验、键盘快捷键、动态业务字段、模板持久化 钩子与中转打印支持。

• 网站演示：https://amdosion.github.io/vue3-print/
• 仓库：https://github.com/amDosion/vue3-print
• npm 包名：@amdosion/vue3-print
• 运行时要求：Vue ^3.4.0、Node.js >=18

功能特性

• 可视化设计器 — 工具栏、纸张画布、标尺/网格、组件面板、元素列表、属性面板、 多面板管理、撤销/重做、复制/粘贴、缩放、对齐分布、右键菜单。
• 内置元素 — 文本、长文本、图片、HTML、表格/空表格、横竖线、矩形、椭圆、 条形码（bwip-js / JsBarcode）、二维码、发票区块、签名、常用电商字段。
• 数据绑定 — 模板 JSON 与业务数据分离；嵌套字段路径、formatter、 dataType/format 转换、联系人（寄/收件人）预设。
• 输出链路 — 浏览器打印、PDF 导出（jspdf）、图片光栅化 （按物理毫米 + DPI 计算点阵，适配移动端/蓝牙直打）、模板缩略图。
• 远程打印 — 通过 electron-hiprint 客户端直打，或经 node-hiprint-transit 中转连接多客户端。
• 宿主集成 — 动态字段 Provider、模板持久化 mock 契约、宿主 i18n 桥、 快捷键设置持久化、HTML sanitizer 策略覆写。

安装

npm install @amdosion/vue3-print

源码开发：

git clone https://github.com/amDosion/vue3-print.git
cd vue3-print
npm install
npm run dev   # demo dev server, 默认 http://localhost:8080

包入口

| 入口 | 用途 | | --- | --- | | @amdosion/vue3-print | 完整入口（设计器 + 打印 + 全部 API） | | @amdosion/vue3-print/print | 仅打印/输出运行时（无设计器 UI，体积更小） | | @amdosion/vue3-print/designer | 设计器入口 | | @amdosion/vue3-print/mock | 持久化 mock 契约（联调后端前的前端 DTO 形状） |

必需样式（应用入口导入一次）：

import '@amdosion/vue3-print/dist/vue3-print.css'
import '@amdosion/vue3-print/dist/print-lock.css'

生产打印页可将 print-lock.css 作为 print-only 样式表：

<link rel="stylesheet" media="print" href="/print-lock.css" />

快速开始：最小设计器

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import {
  hiprint,
  defaultElementTypeProvider,
  type ToolbarController,
} from '@amdosion/vue3-print'

import '@amdosion/vue3-print/dist/vue3-print.css'
import '@amdosion/vue3-print/dist/print-lock.css'

let designer: ToolbarController | undefined

onMounted(() => {
  hiprint.init({
    providers: [new defaultElementTypeProvider()],
    lang: 'zh-CN',
  })

  designer = hiprint.buildDesigner('#hiprintDesigner', {
    templateOptions: {
      template: {
        panels: [{ paperType: 'A4', width: 210, height: 297, printElements: [] }],
      },
      history: true,
    },
    toolbarOptions: {
      showPanelManager: true,
      onSave(template) {
        const json = template.getJson()
        // 持久化到后端
      },
      onPrint(template) {
        template.print({})
      },
    },
  }) as ToolbarController
})

onUnmounted(() => {
  // hiprint 不随 Vue 卸载自动销毁，必须手动 destroy
  designer?.destroy?.()
})
</script>

<template>
  <div id="hiprintDesigner" style="height: 100vh; min-height: 720px"></div>
</template>

打印与输出

import {
  PrintTemplate,
  templateToHtml,
  templateToPdfBlob,
  templateToImagePages,
  templateToThumbnail,
} from '@amdosion/vue3-print'

const tpl = new PrintTemplate({ template: savedJson })
tpl.print(data)                       // 浏览器打印
tpl.print2(data, { printer, client }) // 客户端 / 中转直打
await tpl.toPdf(data, '面单.pdf')      // PDF 下载

// 无设计器输出（服务于宿主自有 UI / 移动端）
const html = templateToHtml(savedJson, { data })
const pdf = await templateToPdfBlob(savedJson, { data })
const pages = await templateToImagePages(savedJson, { data, dpi: 203 })
const thumb = await templateToThumbnail(savedJson, { widthPx: 320 })

templateToImagePages 的点阵尺寸由物理毫米 + dpi 计算（60×40mm @203dpi → 480×320 dots），与浏览器缩放/devicePixelRatio 无关，适合热敏标签机直打。

动态业务字段

字段来自宿主后端，无需在插件内硬编码：

import { hiprint, createDynamicFieldGroupsFromMetadata } from '@amdosion/vue3-print'

const metadata = await fetch('/api/print/business/fields').then((r) => r.json())
const groups = createDynamicFieldGroupsFromMetadata(metadata, {
  moduleName: 'product-listing',
})
hiprint.setDynamicFields('product-listing', groups)

字段拖到选中表格上会作为表格列加入；否则创建为独立打印元素。

远程打印部署

| 组件 | 职责 | | --- | --- | | vue3-print | 设计器、模板 JSON、打印载荷、打印机选择 UI | | electron-hiprint | 桌面客户端，管理本机打印机与可选文件导出目录 | | node-hiprint-transit | 公网/内网中转，连接 Web 应用与多客户端 |

部署步骤：中转服务（服务器/Unraid GHCR 镜像）→ 各打印机所在电脑安装客户端 → 统一 transit URL + token → 设计器或宿主配置远程打印设置。生产环境必须使用强 token（默认 token 仅限本机回环）。详见 docs/TRANSIT-PRINTING.md 与 docs/TRANSIT-VPS-DEPLOYMENT.md。

安全模型

HTML 渲染按来源分信任级别（完整契约见 docs/SECURITY.md）：

• field 绑定的运行时业务数据默认转义；模板 opt-in 为 HTML 后仍强制经 DOMPurify sanitize（SEC-001/SEC-002）。
• formatter / options.content / ToolbarExtraButton.html / htmlToImagePages 属设计期可信输入，按约定原样渲染——不可信内容必须先经导出的 sanitizeHtml() 处理。
• 图片 src 协议白名单（拒绝 javascript: / file:）；远程打印 token 不落 localStorage。

import { sanitizeHtml, setHtmlSanitizer } from '@amdosion/vue3-print'

文档

| 文档 | 内容 | | --- | --- | | docs/API-REFERENCE.md | 公开 API 速查 | | docs/SECURITY.md | HTML 信任边界与 XSS 防护契约 | | docs/VUE-ADMIN-HANDOFF-INTEGRATION.md | 宿主完整集成指南 | | docs/BACKEND-MOCK-CONTRACT.md | 持久化后端契约 | | docs/TRANSIT-PRINTING.md | 远程打印 | | docs/RELEASE-CHECKLIST.md | 发布检查清单 |

开发与验证

npm run typecheck     # tsc 严格类型检查（src + config）
npm run test:unit     # vitest 单元测试
npm run test:e2e      # Playwright 端到端测试
npm run build         # 库构建 + 类型声明
node --check dist/vue3-print.cjs
node --check dist/vue3-print.esm.js

发布：bump package.json.version 后 npm publish --access public --tag latest。 完整流程见 docs/RELEASE-CHECKLIST.md。

License

MIT，见 LICENSE。