vg-print 1.0.20 → 1.0.201

package/README.md

@@ -1,252 +1,282 @@
-# 打印设计器插件（Vue3）
+# 打印设计器组件库使用说明书
 
-可视化打印设计器，基于 `hiprint` 封装，支持组件式与函数式调用，提供 `Designer`、`Header`、`Preview`、`DragBox` 组件与常用 API。包名：`vg-print`。
+本项目已改造为可发布的 Vue3 组件库，提供 `Designer`、`Header`、`Preview`、`DragBox` 四个 UI 组件，并同时暴露 `hiprint` 工具能力，满足“可视化设计 + 打印/导出/直接打印”的完整链路。
 
 ## 安装
 
-- 安装依赖：`npm i vg-print`
-- 引入样式：在应用入口引入 `dist/style.css`
-- 注入打印锁样式：调用 `injectPrintLock()`
+```bash
+npm i vg-print
+```
+
+必须在宿主站点的 `index.html` 引入打印样式，以保证浏览器打印版式稳定：
+
+```html
+<link rel="stylesheet" type="text/css" media="print" href="/print-lock.css" />
+```
+
+或使用 CDN：
 
-```js
+```html
+<link rel="stylesheet" type="text/css" media="print" href="https://cdn.jsdelivr.net/npm/vue-plugin-hiprint@latest/dist/print-lock.css" />
+```
+
+## 快速开始
+
+```ts
+// main.ts
 import { createApp } from 'vue'
 import App from './App.vue'
-import 'vg-print/style.css'
-import { hiPrintPlugin, injectPrintLock } from 'vg-print'
+import HiprintDesigner from 'vg-print'
+import 'vg-print/dist/style.css'
 
 const app = createApp(App)
-app.use(hiPrintPlugin)
-injectPrintLock()
+app.use(HiprintDesigner, { name: '$hiPrint', autoConnect: true })
 app.mount('#app')
 ```
 
-## 快速上手
-
 ```vue
 <template>
-  <Designer :template="template" @onDesigned="onDesigned">
+  <Designer
+    :template="template"
+    :designOptions="{ grid: true, activePanel: true }"
+    :providers="providers"
+    :providerMap="{ container: '.hiprintEpContainer', value: 'defaultModule' }"
+    :plugins="plugins"
+    authKey=""
+    @onDesigned="onDesigned"
+  >
     <template #header>
-      <Header title="sv-print" />
+      <Header :title="'sv-print'" :menuList="['预览']" @preview="openPreview" />
+    </template>
+    <template #other>
+      <DragBox target="SVPrint" drag-key="test" drag-style="width:200px;height:200px;left:238px;top:95px" :show="true">
+        <template #iconTitle>
+          <i class="svicon sv-print"></i><span>自定义拖拽框</span>
+        </template>
+        <template #body>
+          <div>自定义拖拽框内容</div>
+        </template>
+      </DragBox>
     </template>
   </Designer>
-</template>
 
+  <Preview ref="previewRef" :modalShow="false" />
+</template>
 <script setup>
 import { ref } from 'vue'
-import { Designer, Header } from 'vg-print'
-import templateJson from './template.json'
+import { defaultElementTypeProvider } from 'vg-print'
+import { Designer, Header, Preview, DragBox } from 'vg-print'
 
-const template = ref(templateJson)
+const template = ref({})
+const previewRef = ref(null)
 const onDesigned = (e) => {
-  const { hiprint, designerUtils } = e.detail
-  const tpl = designerUtils.printTemplate
+  // e.detail.hiprint / e.detail.designerUtils.printTemplate
+}
+const openPreview = () => {
+  const tpl = previewRef.value.getTarget()
+  previewRef.value.init(tpl, { name: 'i不简' })
+  previewRef.value.show()
 }
-</script>
-```
-
-### 完整示例（含 providers、plugins、Preview、DragBox）
-
-```vue
-<template>
-  <div style="width: 100vw; height: 97vh;">
-    <Designer
-      :template="template"
-      :printData="printData"
-      :providers="providers"
-      :providerMap="providerMap"
-      :plugins="plugins"
-      :designOptions="{ grid: true, activePanel: true }"
-      :lang="'cn'"
-      authKey=""
-      @onDesigned="onDesigned"
-    >
-      <template #header>
-        <Header title="vg-print" :menuList="['预览','导出']" @preview="openPreview" />
-      </template>
-      <template #other>
-        <DragBox target="SVPrint" drag-key="test" drag-style="width:200px;height:200px;left:238px;top:95px" :show="true">
-          <template #iconTitle>
-            <span>自定义拖拽框</span>
-          </template>
-          <template #body>
-            <div>扩展内容</div>
-          </template>
-        </DragBox>
-      </template>
-    </Designer>
-
-    <Preview ref="previewRef" />
-  </div>
-  <button @click="openPreview">显示预览</button>
-  <button @click="exportPdf">导出PDF</button>
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import { Designer, Header, Preview, DragBox, hiprint } from 'vg-print'
-import provider from './provider.js'
-import templateJson from './template.json'
-
-const template = ref(templateJson)
-const printData = ref({ name: '测试' })
-const providers = ref([provider])
-const providerMap = ref({ container: '.hiprintEpContainer', value: 'defaultModule' })
-const plugins = ref([])
-const previewRef = ref(null)
-let tpl = null
 
-const onDesigned = (e) => { tpl = e.detail.designerUtils.printTemplate }
-const openPreview = () => { previewRef.value.init(tpl, printData.value); previewRef.value.show() }
-const exportPdf = () => { tpl && tpl.toPdf(printData.value, '导出', {}) }
+const providers = [new (defaultElementTypeProvider())()]
+const plugins = []
 </script>
 ```
 
-## 组件与 API
+## 组件与属性
 
 ### Designer
 
-- 基础参数：
-  - `template: object` 模板 json 或模板对象
-  - `printData: object` 设计预览数据
-  - `designOptions: object` 设计参数，默认 `{ grid: true, activePanel: true }`
-  - `providers: array` 自定义可拖拽元素 provider 列表
-  - `provider: function` 单 provider 工厂，默认内置 `defaultElementTypeProvider`
-  - `providerMap: object` `{ container: '.hiprintEpContainer', value: 'defaultModule' }`
-  - `plugins: array` 插件注册列表
-  - `authKey: string` 授权 key
-  - `lang: string` 语言
-- 事件：
-  - `onDesigned(e)` 返回 `{ hiprint, designerUtils }`，包含 `designerUtils.printTemplate`
-- 插槽：
-  - `header` 顶部区域
-  - `other` 扩展区域
-
-示例：
+- `template` object 模板 json/对象
+- `printData` object 预览/打印数据
+- `templateKey` string 本地缓存键（`localStorage`）
+- `title` string 默认导出名称
+- `designOptions` object 设计参数：`{ grid: true, activePanel: true }`
+- `paperList` string[] 纸张列表（A/B 系列）
+- `config` object 统一配置（同 `hiprint.setConfig`）
+- `plugins` object[] 插件注册（扩展打印元素）
+- `authKey` string 授权 key（无则体验版水印）
+- `providers` object[] 可拖拽元素 provider 列表
+- `providerMap` object 构建容器与键 `{ container: '.hiprintEpContainer', value: 'defaultModule' }`
 
-```vue
-<Designer :template="template" :plugins="plugins" :providerMap="{ container: '.hiprintEpContainer', value: 'defaultModule' }" @onDesigned="onDesigned" />
-```
+事件与插槽：
+
+- 事件：`onDesigned({ detail: { hiprint, designerUtils } })`，其中 `designerUtils.printTemplate` 为当前模板实例
+- 插槽：`#header` 顶部区域；`#other` 其他扩展区域
 
 ### Header
 
-- 参数：
-  - `logoHtml: string` 左侧 logo html
-  - `title: string` 标题
-  - `reEle: boolean|string` 是否重建元素
-  - `eleList: array` 元素列表
-  - `reMenu: boolean|string` 是否重建菜单
-  - `menuList: array` 菜单列表
-  - `onPreviewClick: function` 预览点击回调，返回 `true` 阻止默认
-- 事件：
-  - `preview` 默认预览点击事件
-- 插槽：
-  - `headerLeft` 左侧内容
-  - `headerCenter` 中间内容
-  - `headerRight` 右侧内容
+- `logoHtml` string 左侧 logo html
+- `title` string 左侧标题
+- `reEle` boolean 是否重建元素（true 则以 `eleList` 为准）
+- `eleList` string[] 元素列表
+- `reMenu` boolean 是否重建菜单（true 则以 `menuList` 为准）
+- `menuList` string[] 菜单列表
+- `onPreviewClick(e): boolean` 预览点击；返回 `true` 阻止默认行为
+
+插槽：`#headerLeft`、`#headerCenter`、`#headerRight`
 
 ### Preview
 
-- 参数：
-  - `printTemplate: object|string` 模板对象或 json
-  - `printData: object` 打印数据
-  - `printerList: array` 打印机列表
-  - `selectedPrinter: string` 默认打印机
-  - `showPdf: boolean` 是否显示导出 PDF 按钮
-  - `showImg: boolean` 是否显示导出图片按钮
-  - `showPrint2: boolean` 是否显示直接打印按钮
-  - `modalShow: boolean` 是否显示
-- 方法：
-  - `init(template, data)` 初始化模板与数据
-  - `show()` 显示预览并渲染
-  - `getTarget()` 返回内部模板对象
-  - `print()` 浏览器打印
-  - `toPdf()` 导出 PDF
-  - `toImage()` 导出图片
-  - `directPrint()` 客户端直接打印
-
-示例：
+- `printTemplate` 模板 json/对象或 `hiprint.PrintTemplate` 实例
+- `printData` json 打印数据
+- `printerList` array 打印机列表
+- `selectedPrinter` string 默认打印机名称
+- `showPdf` boolean 显示导出 PDF
+- `showImg` boolean 显示导出图片
+- `showPrint2` boolean 显示直接打印
+- `modalShow` boolean 是否显示
 
-```vue
-<template>
-  <button @click="testPreview">显示预览</button>
-  <Preview ref="previewRef" />
-</template>
-<script setup>
-import { ref } from 'vue'
-import { Preview } from 'vg-print'
-import templateJson from './template.json'
+方法：`getTarget()`、`init(tpl, data)`、`show()`、`print()`、`toPdf()`、`toImage(options)`、`directPrint()`
 
-const previewRef = ref(null)
-const testPreview = () => {
-  previewRef.value.init(templateJson, { name: 'i不简' })
-  previewRef.value.show()
-}
-</script>
+### DragBox
+
+- `target` string 容器 Id 或 ClassName
+- `dragKey` string 拖拽标识
+- `dragStyle` string 默认位置/大小（`left/top/width/height` 内联样式字符串）
+- `mode` string `default|top|left|bottom|right|fixed`
+- `show` boolean 是否显示
+
+插槽：`#iconTitle`、`#body`
+
+## 插件注册与扩展
+
+注册第三方元素插件（如 bwip-js 条码）：
+
+```bash
+npm i @sv-print/plugin-ele-bwip-js
 ```
 
-### DragBox
+```ts
+import { hiprint } from 'vg-print'
+import pluginEleBwip from '@sv-print/plugin-ele-bwip-js'
 
-- 参数：
-  - `target: string` 目标容器 Id 或 ClassName（配合 `Designer` 的 `other` 插槽使用）
-  - `dragKey: string` 拖拽标识
-  - `dragStyle: string` 初始位置大小，如 `width:200px;height:200px;left:238px;top:95px`
-  - `mode: string` `default|top|left|bottom|right|fixed`
-  - `show: boolean` 是否显示
-- 插槽：
-  - `iconTitle` 头部图标与标题
-  - `body` 内容
+hiprint.register({ authKey: '', plugins: [ pluginEleBwip({}) ] })
+```
 
-示例：
+也可在 `Designer` 组件通过 `:plugins` 传入：
 
 ```vue
-<Designer>
-  <template #other>
-    <DragBox target="SVPrint" drag-key="test" drag-style="width:200px;height:200px;left:238px;top:95px" :show="true">
-      <template #iconTitle>
-        <span>自定义拖拽框</span>
-      </template>
-      <template #body>
-        <div>内容</div>
-      </template>
-    </DragBox>
-  </template>
-  <template #header>
-    <Header title="sv-print" />
-  </template>
-</Designer>
+<Designer :plugins="[pluginEleBwip({})]" authKey="" />
 ```
 
-## 函数式 API
+配置设计器 UI：
 
-```js
-import { print, print2, defaultElementTypeProvider } from 'vg-print'
+```ts
+import { hiprint } from 'vg-print'
 
-const tpl = print(defaultElementTypeProvider, templateJson, { data: {} })
-const tpl2 = print2(defaultElementTypeProvider, templateJson, { data: {} })
+hiprint.setConfig({
+  showAdsorbLine: true,
+  showPosition: true,
+  showSizeBox: true,
+})
 ```
 
-## 可拖拽元素 Provider
+构建可拖拽元素 provider：
 
-```js
+```ts
 import { hiprint } from 'vg-print'
 
-export default function(options){
-  var addElementTypes = function(context){
+const provider = function(options) {
+  const addElementTypes = function(context) {
     context.removePrintElementTypes('ibujianModule')
     context.addPrintElementTypes('ibujianModule', [
-      new hiprint.PrintElementTypeGroup('i不简',[{
-        tid:'ibujianModule.text', type:'text', title:'文本', options:{ title:'文本2', field:'text', testData:'123' }
-      }])
+      new hiprint.PrintElementTypeGroup('i不简', [
+        {
+          tid: 'ibujianModule.text',
+          type: 'text',
+          title: '文本',
+          options: { title: '文本2', field: 'text', testData: '123' }
+        }
+      ])
     ])
   }
   return { addElementTypes }
 }
+
+// 传入 Designer
+<Designer :providers="[provider]" :providerMap="{ container: '.hiprintEpContainer', value: 'ibujianModule' }" />
 ```
 
-在 `Designer` 中传入 `providers` 或使用 `providerMap` 构建左侧容器。
+可选：自定义 provider 容器 UI 渲染（`providerMap.render`）：
+
+```ts
+const providerMap = {
+  container: '.hiprintEpContainer',
+  value: 'defaultModule',
+  render: (list) => {
+    const $ = globalThis.$
+    const container = $('<div class="hiprint-printElement-type"></div>')
+    list.forEach(function(item) {
+      const box = $(`<div class="draggable-ele-group"><span class="title">${ item.name }</span><div class="list"></div></div>`)
+      const typeList = box.find('.list')
+      item.printElementTypes.forEach(function(t) {
+        typeList.append(`<div class="draggable-ele" draggable="true" data-tid="${t.tid}">${t.title}</div>`)
+      })
+      container.append(box)
+    })
+    $(providerMap.container).empty().append(container)
+  }
+}
+```
+
+## 全局方法与案例
+
+安装时会挂载全局：`src/lib/index.js:9` 与 `src/index.js:34`
+
+- 全局对象：`this.$hiPrint`（或安装时自定义的 `name`）
+- 浏览器打印：`this.$print(provider, templateJson, printData, options)`
+- 直接打印：`this.$print2(provider, templateJson, printData, options)`（需客户端）
+- 连接控制：`autoConnect(cb)` / `disAutoConnect()`
+
+浏览器打印：
+
+```ts
+import { defaultElementTypeProvider } from 'vg-print'
+this.$print(defaultElementTypeProvider, templateJson, { name: 'i不简' }, { importCss: true })
+```
+
+直接打印（指定客户端与打印机）：
+
+```ts
+const clientId = 'AlBaUCNs3AIMFPLZAAAh'
+const client = this.$hiPrint.hiwebSocket.clients[clientId]
+const printer = client.printerList[0]
+
+this.$print2(undefined, templateJson, { name: 'i不简' }, {
+  client: clientId,
+  printer: printer.name,
+  title: '打印预览'
+})
+```
+
+导出 PDF / 图片：
+
+```ts
+const tpl = new this.$hiPrint.PrintTemplate({ template: templateJson })
+tpl.toPdf({ name: 'i不简' }, '导出PDF')
+await tpl.toImage({ name: 'i不简' }, { isDownload: true, type: 'image/jpeg', pixelRatio: 2 })
+```
+
+## 常见问题
+
+- 必须引入 `print-lock.css`，否则浏览器打印样式会错乱
+- 直接打印需安装并连接 `electron-hiprint` 客户端，线上使用需 `https` 以避免跨域连接失败
+- 模板资源（图片等）建议使用绝对可访问链接或 Base64
+- 纸张列表可参考 A/B 系列（来自 sv-print 文档）
+- 可通过 `hiprint.setConfig` 与组件插槽定制 UI/交互
+
+## 打包与发布
+
+- 运行库打包：`npm run build:lib`，产物：`dist/hiprint-designer.es.js`、`dist/hiprint-designer.umd.js`、`dist/style.css`
+- `package.json` 已配置 `main/module/exports` 指向库产物
+- 首次发布：`npm config set registry=https://registry.npmjs.org`、`npm adduser`、`npm publish`
 
-## 注意事项
+## 代码位置索引
 
-- 需要在入口引入库样式，并调用 `injectPrintLock()` 注入打印锁样式。
-- 依赖 `jquery` 与 `element-plus`；请在应用中安装并初始化 UI 库。
-- 若使用客户端直连打印，请确保客户端组件可用并已连接。
+- 组件安装入口：`src/lib/index.js:9`
+- 全局插件与方法：`src/index.js:34`
+- 设计器：`src/components/Designer.vue:16`
+- 预览：`src/components/Preview.vue:1`
+- 头部：`src/components/Header.vue:1`
+- 拖拽盒：`src/components/DragBox.vue:1`

package/dist/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>vue-plugin-hiprint-demo</title>
+    <link rel="icon" href="/favicon.ico" />
+    <link rel="stylesheet" type="text/css" media="print" href="/css/print-lock.css" />
+    <script type="module" crossorigin src="/static/js/index-DaZYVOmF.js"></script>
+    <link rel="stylesheet" crossorigin href="/static/css/index-BQgwTBxP.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>