vg-print 1.0.13 → 1.0.14

package/README.md

@@ -1,399 +1 @@
-vg-print (基于 [hiprint 2.5.4]当时只是为了方便 <span style="color: red">我（并非 hiprint 原作者）</span> 在 vue 项目中引入使用，所以以此命名。
-
-此 <span style="color: red">插件</span> 仅仅是一个 <span style="color: red">JavaScript【工具库】</span> 而非 <span style="color: yellow">Vue【组件库】</span>，所以它默认不包含 demo 中的那些组件页面（demo 代码可复制使用）。
-
-由于 hiprint 官网最后一次更新时间为 2019 年【hiprint 2.5.4 是 [LGPL](#关于lgpl协议) 协议】，后在诸多使用者及反馈下进行了许多优化调整。
-
-> [!IMPORTANT]
-
-# vg-print 使用与 API 说明
-
-## 安装
-
-```
-npm i vg-print
-```
-
-## 样式
-
-```
-import 'vg-print/dist/style.css'
-```
-
-在 `index.html` 添加：
-
-```
-<link rel="stylesheet" type="text/css" media="print" href="/print-lock.css" />
-```
-
-## 核心 API
-
-```
-import { hiprint, register, setConfig, createPrintTemplate, print, print2, toPdf, toImage } from 'vg-print'
-```
-
-- `register({ authKey, plugins })`
-- `setConfig(config)`
-- `createPrintTemplate(options)`
-- `print({ templateJson, data, options, provider })`
-- `print2({ templateJson, data, options, provider })`
-- `toPdf({ template, data, name, pdfOptions })`
-- `toImage({ template, data, imageOptions })`
-- 直接访问 `hiprint.hiwebSocket` 获取连接与打印机列表
-
-### 快速示例
-
-```
-import { register, createPrintTemplate } from 'vg-print'
-import pluginEleBwip from '@vg-print/plugin-ele-bwip-js'
-
-register({ authKey: '', plugins: [pluginEleBwip({})] })
-
-const templateJson = { /* 模板json */ }
-const t = createPrintTemplate({ template: templateJson })
-t.print({ name: '测试' })
-```
-
-### Provider 插件示例
-
-```
-import { hiprint } from 'vg-print'
-
-export default function(options) {
-  const addElementTypes = function(context) {
-    context.removePrintElementTypes('vgModule')
-    context.addPrintElementTypes('vgModule', [
-      new hiprint.PrintElementTypeGroup('自定义', [
-        {
-          tid: 'vgModule.text',
-          type: 'text',
-          title: '文本',
-          options: { title: '文本', field: 'text', testData: '123' }
-        }
-      ])
-    ])
-  }
-  return { addElementTypes }
-}
-```
-
-注册：
-
-```
-import provider from './provider'
-register({ plugins: [() => provider] })
-```
-
-### 连接客户端与直接打印
-
-```
-import { hiprint, createPrintTemplate } from 'vg-print'
-
-hiprint.init({ host: 'https://v4.printjs.cn:17521', token: 'hiprint-17521' })
-
-const t = createPrintTemplate({ template })
-t.print2({ name: '测试' }, { title: '标题', printer: 'HP LaserJet' })
-```
-
-`hiprint.hiwebSocket` 可读取打印机列表与客户端信息：
-
-```
-const list = hiprint.hiwebSocket.getPrinterList()
-const opened = hiprint.hiwebSocket.opened
-```
-
-## Vue3 组件
-
-```
-import { Designer, Header, Preview, DragBox } from 'vg-print/vue3'
-```
-
-### Designer
-
-属性：`template`、`printData`、`templateKey`、`title`、`designOptions`、`autoConnect`、`paperList`、`config`、`plugins`、`authKey`
-
-方法：`init(template)`、`getTarget()`、`getTemplateJson()`、`setTemplateJson(json)`、`exportJson()`
-
-插槽：`header`、`other`
-
-示例：
-
-```
-<template>
-  <Designer :template="template" :config="config" :plugins="plugins">
-    <template #header>
-      <Header title="vg-print" />
-    </template>
-  </Designer>
-  <Preview ref="previewRef" />
-  <button @click="openPreview">预览</button>
-  <button @click="saveJson">导出JSON</button>
-  <button @click="loadJson">加载JSON</button>
-  <DragBox target="SVPrint" drag-key="tip" drag-style="width:160px;height:100px;left:20px;top:60px" :show="true">
-    <template #iconTitle>
-      <span>提示</span>
-    </template>
-    <template #body>
-      <div>自定义辅助区域</div>
-    </template>
-  </DragBox>
-  
-</template>
-<script setup>
-import { ref } from 'vue'
-import { Designer, Header, Preview, DragBox } from 'vg-print/vue3'
-import pluginEleBwip from '@vg-print/plugin-ele-bwip-js'
-
-const template = ref({})
-const config = ref({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
-const plugins = ref([pluginEleBwip({})])
-const previewRef = ref(null)
-
-function openPreview(){
-  const t = previewRef.value
-  const designerTarget = document.getElementById('SVPrint')
-  const printTemplate = t.getTarget() || null
-  // 若未手动设置，可从 Designer 暴露的方法获取模板实例
-}
-
-function saveJson(){
-  // 通过 Designer 暴露方法获取 json
-}
-
-function loadJson(){
-  // 设置新的模板 json
-}
-</script>
-```
-
-### Header
-
-属性：`logoHtml`、`title`、`reEle`、`eleList`、`reMenu`、`menuList`、`onPreviewClick`
-
-插槽：`headerLeft`、`headerCenter`、`headerRight`
-
-示例：
-
-```
-<Header title="vg-print" :onPreviewClick="onPreviewClick" />
-```
-
-```
-function onPreviewClick(e){
-  // 返回 true/false 控制是否阻止预览按钮默认行为
-  return true
-}
-```
-
-### Preview
-
-属性：`printTemplate`、`printData`、`printerList`、`selectedPrinter`、`showPdf`、`showImg`、`showPrint2`、`modalShow`
-
-方法：`init(template, data)`、`show()`、`getTarget()`、`print()`、`directPrint()`、`toPdf(name, options)`、`toImage(options)`、`refreshPrinters()`
-
-示例：
-
-```
-<Preview ref="previewRef" :modalShow="modalShow" />
-
-// 代码调用
-previewRef.value.init(templateJson, { name: '预览数据' })
-previewRef.value.show()
-previewRef.value.print()
-previewRef.value.toPdf('文件名')
-previewRef.value.toImage({ type: 'image/jpeg', pixelRatio: 2 })
-previewRef.value.refreshPrinters()
-```
-
-### DragBox
-
-属性：`target`、`dragKey`、`dragStyle`、`mode`、`show`
-
-插槽：`iconTitle`、`body`
-
-示例：
-
-```
-<DragBox target="SVPrint" drag-key="demo" drag-style="width:200px;height:200px;left:238px;top:95px" :show="true">
-  <template #iconTitle>
-    <span>自定义拖拽框</span>
-  </template>
-  <template #body>
-    <div>内容</div>
-  </template>
-</DragBox>
-```
-
-## 使用示例
-
-```
-import { register, createPrintTemplate } from 'vg-print'
-import pluginEleBwip from '@vg-print/plugin-ele-bwip-js'
-
-register({ plugins: [pluginEleBwip({})] })
-const t = createPrintTemplate({ template })
-t.print(data)
-```
-
-```
-import { Designer, Header, Preview } from 'vg-print/vue3'
-```
-
-## 选项与参数对齐
-
-- 设计器 `designOptions`：`{ grid: true, activePanel: true }`
-- 配置 `config`：`showAdsorbLine`、`showPosition`、`showSizeBox` 等在渲染前设置（与站点一致）
-- 纸张列表 `paperList`：传入 `{ type, width, height }[]` 控制常用纸张
-- 插件 `plugins`：函数数组，返回 provider 并向 `hiprint` 注册元素分组
-- 授权 `authKey`：保留参数位
-
-## 客户端与打印机
-
-```
-import { hiprint } from 'vg-print'
-hiprint.init({ host: 'https://v4.printjs.cn:17521', token: 'hiprint-17521' })
-
-const printers = hiprint.hiwebSocket.getPrinterList()
-const opened = hiprint.hiwebSocket.opened
-```
-
-`print2` 传入 `options.printer` 指定打印机；如存在多客户端场景，结合 `client` 信息传入。
-
-## 源码位置参考
-
-- 入口与核心导出：`src/index.js:88-128`
-- 预览组件：`src/vue3/Preview.vue:1-63`
-- 设计器组件：`src/vue3/Designer.vue:1-42`
-- 头部组件：`src/vue3/Header.vue:1-38`
-- 拖拽组件：`src/vue3/DragBox.vue:1-28`
-
-## 方法使用案例集合
-
-### 注册与 Provider 插件
-
-```
-import { register } from 'vg-print'
-import pluginEleBwip from '@vg-print/plugin-ele-bwip-js'
-
-register({
-  authKey: '',
-  plugins: [
-    pluginEleBwip({ /* 插件参数 */ })
-  ]
-})
-```
-
-### 全局配置 setConfig
-
-```
-import { setConfig } from 'vg-print'
-
-setConfig({
-  showAdsorbLine: true,
-  showPosition: true,
-  showSizeBox: true
-})
-```
-
-### 设计器渲染与获取模板
-
-```
-import { createPrintTemplate } from 'vg-print'
-
-const t = createPrintTemplate({ template: templateJson })
-t.design('#SVPrint', { grid: true })
-const html = t.getHtml(printData) // 参考 src/views/preview.vue:95-101
-const json = t.getJson()          // 参考 src/views/index.vue:882
-```
-
-### 设置与导出模板 JSON
-
-```
-t.setJson(newJson)
-const exported = t.getJson()
-```
-
-### 浏览器打印
-
-```
-t.print(printData, { /* options */ })
-```
-
-### 直接打印（需客户端）
-
-```
-t.print2(printData, {
-  title: '打印标题',
-  printer: 'HP LaserJet'
-})
-// 判断连接与读取打印机列表
-hiprint.hiwebSocket.opened           // 参考 src/views/preview.vue:59-66
-const printers = hiprint.hiwebSocket.getPrinterList() // 参考 src/hiprint/hiprint.bundle.js:7779
-```
-
-### 导出 PDF（两类模式）
-
-1) 普通模板，导出预览全部页：
-
-```
-t.toPdf(printData, '打印预览pdf')
-```
-
-2) 小模板 A4 排版（把小模板排到 A4）参考 `src/views/index.vue:704-744`：
-
-```
-t.toPdf(printData, '打印预览pdf', {
-  paperWidth: 210,
-  paperHeight: 297,
-  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur/total)*100))
-})
-```
-
-### 导出图片（多页合成、清晰度、排版）
-
-```
-// 多张图片，每张合成 6 页，自动下载 JPEG（参考 src/views/index.vue:704-744）
-await t.toImage(printData, {
-  limit: 6,
-  isDownload: true,
-  name: 'A4排版',
-  type: 'image/jpeg',
-  pixelRatio: 2,
-  quality: 0.8,
-  paperWidth: 210,
-  paperHeight: 297,
-  toType: 'url'
-})
-```
-
-### 客户端高级 API（选用）
-
-```
-// 刷新打印机列表
-hiprint.hiwebSocket.refreshPrinterList() // 参考 src/hiprint/hiprint.bundle.js:7782
-
-// 获取客户端列表与信息
-hiprint.hiwebSocket.getClients()         // 参考 src/hiprint/hiprint.bundle.js:7789
-hiprint.hiwebSocket.getClientInfo()      // 参考 src/hiprint/hiprint.bundle.js:12551-12554
-
-// IPP 打印与请求
-hiprint.hiwebSocket.ippPrint({ /* options */ })   // 参考 src/hiprint/hiprint.bundle.js:7803
-hiprint.hiwebSocket.ippRequest({ /* options */ }) // 参考 src/hiprint/hiprint.bundle.js:7810
-```
-
-### Vue 插件全局快捷：$print / $print2
-
-```
-// main.js
-import { createApp } from 'vue'
-import App from './App.vue'
-import { hiPrintPlugin } from 'vg-print'
-
-const app = createApp(App)
-app.use(hiPrintPlugin) // 全局挂载 this.$print / this.$print2 参考 src/index.js:34-75
-app.mount('#app')
-
-// 组件中使用
-this.$print(undefined, templateJson, printData, options)
-this.$print2(undefined, templateJson, printData, options)
-```
+vg-print (基于 [hiprint 2.5.4](http://hiprint.io/)) 当时只是为了方便 <span style="color: red">我（并非 hiprint 原作者）</span> 在 vue 项目中引入使用，所以以此命名。