vg-print

一个开箱即用的打印设计器组件库（Vue 3）。现在聚焦于单一组件 FullDesigner，同时暴露底层 hiprint 能力与客户端直连（hiwebSocket）配置，便于快速集成模板设计、预览、浏览器打印、导出 PDF/图片、直接打印等功能。

您可以直接安装引入体验功能. 没有域名限制,无网可用. 提供一对一技术支持. npm搜索vg-print. 授权或购买源码: 联系我加 QQ: 984239686

特性

• 全功能页面组件 FullDesigner，直接使用，无需拼装子组件
• 支持预览、浏览器打印、导出 PDF/图片、直接打印（需客户端）
• 通过属性配置 hiwebSocket 的 host、token 与自动连接
• 暴露实例方法：预览、打印、导出、连接控制等，外部可直接调用
• 集成并导出 hiprint，可进行模板对象级的高级定制

安装

npm i vg-print

样式引入（确保设计与打印样式生效）：

// 全局样式（组件库样式）
import 'vg-print/style.css'

// 打印锁样式（推荐；保证打印时样式稳定）
// 在 `index.html` 中引入：

环境要求：Vue 3、Node >= 18.18。无需单独安装 vue-plugin-hiprint，本库已内置并导出 hiprint 能力。

快速开始

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import vgPrint from 'vg-print'
import 'vg-print/style.css'

createApp(App).use(vgPrint).mount('#app')

<template>
  

  预览
  浏览器打印
  导出 PDF
  导出图片
  直接打印（需客户端）
</template>

API（FullDesigner）

属性（Props，含描述）

• hi-host: string 客户端服务地址；示例 https://127.0.0.1:17521，用于直连打印
• hi-token: string 客户端鉴权令牌；与客户端配置一致时方可直连打印
• hi-auto-connect: boolean 是否自动连接客户端；默认 true，为 false 时需手动调用 connect()
• initial-template: object 初始化模板 JSON；为空时使用内置示例模板
• initial-print-data: object | array 初始化打印数据；支持对象或数组，运行时变更会即时生效
• default-lang: string 默认语言；支持 cn、en、de、es、fr、it、ja、ru、cn_tw；默认 cn

以上属性支持运行时动态修改；组件内部已监听并应用。

方法（通过组件 ref 调用，含描述）

• preView() 打开预览弹窗；将当前模板与数据渲染为预览 HTML
• printView() 浏览器打印；不依赖客户端，调起系统打印对话框
• print() 直接打印；需客户端已连接，按当前选定打印机输出
• toPdf() 导出 PDF；使用内置 A4 排版示例参数导出
• toImage() 导出图片；使用内置 A4 排版示例参数导出
• setHiwebSocket(host: string, token?: string, cb?: Function) 设置客户端地址与令牌并尝试重连；cb(status, msg) 为连接回调
• connect(cb?: Function) 主动连接客户端；cb(status, msg) 为连接回调
• disconnect() 断开客户端连接
• disAutoConnect() 关闭自动连接策略；阻止自动重连

事件（Emits，含描述）

• save 保存模板与数据；回调参数结构：

{
  template,   // 模板 JSON
  data,       // 当前打印数据（对象或数组）
  templateId  // 模板标识（若存在）
}

示例：

<template>
  
</template>

快捷键

• 保存：Ctrl/Command + S
• 编辑模板 JSON：Ctrl/Command + E
• 编辑打印数据：Ctrl/Command + Shift + E

语言与国际化

• 通过 default-lang 设置初始语言（cn 默认为中文）；内部会同步 vue-i18n 与 hiprint 的语言。
• 运行时可在页面右上角语言切换菜单切换（无需刷新）。

高级用法（hiprint）

本库导出 hiprint，可直接创建与操作模板对象（hiprint.PrintTemplate）：

import { hiprint, defaultElementTypeProvider } from 'vg-print'
// 全局配置
hiprint.setConfig({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
// 注册插件
hiprint.register({ authKey: '', plugins: [] })
// 初始化元素提供器 （默认元素提供器）
hiprint.init({ 
  providers: [new defaultElementTypeProvider()],
  host: 'https://localhost:17521',
  token: '',
  lang: 'en'
})
// 创建模板对象
const tpl = new hiprint.PrintTemplate({ template: {} })
// 设计模板
tpl.design('#hiprint-printTemplate', { grid: true })
// 打印（需客户端已连接）
tpl.print({ name: '示例' })
// 打印2（需客户端已连接）
tpl.print2({ name: '示例' }, { printer: '' })
// 导出 PDF（内置示例参数）
tpl.toPdf({ name: '示例' }, '打印预览pdf', { paperWidth: 210, paperHeight: 297, scale: 2, perPage: 6 })
// 导出图片（内置示例参数） 
tpl.toImage({ name: '示例' }, { isDownload: true, name: '图片', limit: 1, type: 'image/jpeg', pixelRatio: 2 })

水印与授权行为说明：设计态与运行态分离。设计态不自动显示默认水印（由面板设置项决定）；运行态按授权和面板内容合并控制。

授权密钥（authKey）与默认水印

• 行为说明：

  • 设计态（FullDesigner 设计界面）：不自动注入默认水印；是否显示水印由面板中的“水印功能”设置项决定，与 authKey 无关。
  • 运行态（预览、浏览器打印、导出 PDF/图片、直连打印）：
    • 无授权（未注册 authKey）：
      • 面板未填写内容 → 显示默认水印 { content: 'vg-print', timestamp: true }
      • 面板填写了内容 → 显示“用户内容 + 试用版”并带时间戳；默认水印不再显示
    • 有授权（注册有效 authKey）：不显示默认水印；面板填写什么就显示什么，未填写则不显示
  • 适用于所有入口：完整设计器组件、直接 new hiprint.PrintTemplate(...)、以及轻量运行时 API（createTemplate）。

• 全局注册授权密钥：

import { hiprint } from 'vg-print'

// 注册授权 key（建议在应用启动时调用）
hiprint.register({ authKey: '你的key' })

// 有授权 key → 运行态默认水印移除（设计态由面板设置项决定）
const tpl = new hiprint.PrintTemplate({ template: {} })

• 轻量运行时 API 使用授权：

import { hiprint, createTemplate, printBrowser } from 'vg-print'

hiprint.register({ authKey: 'YOUR_AUTH_KEY' })
const tpl = createTemplate(tmplJson) // 不再自动注入默认水印
printBrowser(tpl, data)

• 自定义或显式控制水印：

// 无授权时，库会注入默认水印；如需自定义水印样式/内容
const tpl = new hiprint.PrintTemplate({
  template: {},
  watermarkOptions: { content: 'your-brand', timestamp: true, rotate: 20 }
})

// 有授权时，运行态不会注入默认水印；若仍需水印，请显式传入
const tpl2 = createTemplate(tmplJson, {
  watermarkOptions: { content: 'your-brand', timestamp: true }
})

// 设计态由面板设置项决定水印，不受 authKey 控制。
// 运行态的默认水印由授权控制，不建议通过传入空对象取消；如需取消，请注册有效 authKey。
const tpl3 = new hiprint.PrintTemplate({ template: {}, watermarkOptions: { content: 'your-brand', timestamp: true } })

• 插件注册（可选）：

import { hiprint } from 'vg-print'

// 两种形式的插件均支持
function pluginFn(h) { /* 扩展逻辑 */ }
const pluginObj = { install(h) { /* 扩展逻辑 */ } }

hiprint.register({
  authKey: 'YOUR_AUTH_KEY',
  plugins: [pluginFn, pluginObj]
})

默认水印参数参考：

{ content: 'vg-print', timestamp: true }
}

 


## 轻量运行时 API（无需设计器 UI）

当你只想“拿模板 + 数据”直接做预览、浏览器打印、导出 PDF/图片或进行客户端直连打印，而不引入页面设计器时，使用以下 API：

```js
import {
  createTemplate,
  getHtml,
  printBrowser,
  exportPdf,
  exportImage,
  getPrinterList,
  setHiwebSocket,
  connect,
  disconnect
} from 'vg-print'

// 1) 创建模板实例（可复用）
const tpl = createTemplate(tmplJson)

// 2) 生成预览 HTML，自行渲染到容器
const preview = async () => {
  visible.value = true // 弹出框容器显示
  await nextTick() // 等容器渲染出来

  const tpl = createTemplate(tmplJson)
  const html = getHtml(tpl, printData) // 始终为字符串

  const container = document.getElementById('preview_content_custom') // 显示内容的div的id
  if (!container) {
    console.warn('预览容器不存在')
    return
  }
  container.innerHTML = html
}

// 3) 浏览器打印（不需要客户端）
printBrowser(tpl, printData)

// 4) 导出 PDF（示例参数）
exportPdf(tpl, printData, '打印预览pdf', {
  paperWidth: 210,
  paperHeight: 297,
  scale: 2,
  perPage: 6,
  leftOffset: -1,
  topOffset: -1,
  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur/total)*100))
})

// 5) 导出图片（示例参数）
await exportImage(tpl, printData, {
  isDownload: true,
  name: 'A4排版',
  limit: 1, // 导出多张时设置每张合成的页数；不传或设为 0 合成整图
  type: 'image/jpeg',
  pixelRatio: 2,
  quality: 0.8,
  toType: 'url',
  onProgress: (cur, total) => console.log('toImage 进度', Math.floor((cur/total)*100))
})

// 6) 客户端直连打印（需要本地客户端）
setHiwebSocket('https://127.0.0.1:17521', 'your-token')
connect()
// 可选：查看打印机列表
const printers = getPrinterList(tpl)
// 使用模板对象直接发起直连打印
tpl.print2(printData, { printer: printers?.[0]?.name || '' })

// 7) 断开连接
disconnect()

导出 PDF 两种模式

• 普通导出（按模板自身纸张与分页设置）：

// 不传纸张尺寸，使用模板的面板尺寸与分页配置
exportPdf(tpl, printData, '打印预览pdf', {
  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur/total)*100))
})

• A4 排版导出（把小模板排到指定纸张）：

// 传入纸张尺寸与排版参数，将多个模板排到一张 A4
exportPdf(tpl, printData, '打印预览pdf', {
  paperWidth: 210,      // mm
  paperHeight: 297,     // mm
  scale: 2,             // 缩放系数（影响清晰度与排版）
  perPage: 6,           // 每页排版的模板数量
  leftOffset: -1,       // 左对齐偏移（mm）
  topOffset: -1,        // 上对齐偏移（mm）
  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur/total)*100))
})

导出图片 两种模式

• 普通导出（按模板自身纸张与分页设置）：

// 不传纸张尺寸，按模板分页导出图片
await exportImage(tpl, printData, {
  isDownload: true,
  name: '图片',
  limit: 1,              // 多少页合成一张图片；0 或不传则导出整图
  type: 'image/jpeg',    // 或 'image/png'
  pixelRatio: 2,         // 像素比例（清晰度）
  quality: 0.8,          // 仅 JPEG 有效（0-1）
  toType: 'url',         // 不下载时返回类型：'url' 或 'blob'
  onProgress: (cur, total) => console.log('toImage 进度', Math.floor((cur/total)*100))
})

• A4 排版导出（把小模板排到指定纸张）：

// 传入纸张尺寸以 A4 方式排版导出
await exportImage(tpl, printData, {
  paperWidth: 210,       // mm
  paperHeight: 297,      // mm
  limit: 6,              // 每张合成 6 页
  isDownload: true,
  name: 'A4排版',
  type: 'image/jpeg',
  pixelRatio: 2,
  quality: 0.8
})

参数说明（PDF/图片通用，含描述）

• paperWidth、paperHeight 纸张尺寸（mm）；传入后按该纸张排版，不传则使用模板自身尺寸与分页
• scale 渲染缩放（PDF）；提升清晰度或控制排版密度
• perPage 每页模板数量（PDF）；用于小模板排版到大纸张
• leftOffset、topOffset 对齐偏移（mm）；微调整体排版位置（PDF）
• limit 图片合并页数；1 表示每张 1 页，6 表示每张 6 页；0/不传导出整图
• type 图片格式；'image/jpeg' 或 'image/png'
• pixelRatio 像素比例（图片）；越大越清晰但文件更大
• quality 图片质量（0-1，仅 JPEG 有效）
• toType 返回类型（不下载时）；'url' 或 'blob'
• isDownload 是否直接下载图片文件
• name 文件名或下载名
• onProgress(cur, total) 导出进度回调；以 cur/total 计算百分比

导入说明（含描述）

• 所有运行时 API 由库入口直接导出；无需另装 vue-plugin-hiprint
• 如需自定义元素提供器，在调用前执行 hiprint.init({ providers: [...] })；默认已初始化内置提供器

适用场景（含描述）

• 后台页面、弹窗、任务流：仅需“模板 + 数据”的预览/打印/导出能力
• 脚本或批量任务：结合 exportPdf/exportImage 实现批量导出

注意事项

• 建议在 index.html 注入 print-lock.css，保证打印样式稳定
• 直接打印需配套客户端（Electron 或服务端），跨域部署需启用 HTTPS
• 若使用自定义 host/token，确保客户端配置一致且网络可达
• SSR 兼容：插件安装仅在浏览器环境执行（typeof window !== 'undefined'），在 SSR 框架中引入不会因 window 未定义报错。

构建

开发与构建：

npm run dev      # 开发
npm run build    # 应用构建
npm run build:lib# 组件库构建

源码位置

• 入口与导出：packages/index.ts
• 完整页面组件：src/views/index.vue

完整示例

<template>
  

  <div style="margin-top: 12px;">
    
    
    应用连接参数
    预览
    浏览器打印
  </div>
</template>