vg-print 1.0.16 → 1.0.17

package/README.md

@@ -1 +1,252 @@
-vg-print (基于 [hiprint 2.5.4](http://hiprint.io/)) 当时只是为了方便 <span style="color: red">我（并非 hiprint 原作者）</span> 在 vue 项目中引入使用，所以以此命名。
+# 打印设计器插件（Vue3）
+
+可视化打印设计器，基于 `hiprint` 封装，支持组件式与函数式调用，提供 `Designer`、`Header`、`Preview`、`DragBox` 组件与常用 API。包名：`vg-print`。
+
+## 安装
+
+- 安装依赖：`npm i vg-print`
+- 引入样式：在应用入口引入 `dist/style.css`
+- 注入打印锁样式：调用 `injectPrintLock()`
+
+```js
+import { createApp } from 'vue'
+import App from './App.vue'
+import 'vg-print/dist/style.css'
+import { hiPrintPlugin, injectPrintLock } from 'vg-print'
+
+const app = createApp(App)
+app.use(hiPrintPlugin)
+injectPrintLock()
+app.mount('#app')
+```
+
+## 快速上手
+
+```vue
+<template>
+  <Designer :template="template" @onDesigned="onDesigned">
+    <template #header>
+      <Header title="sv-print" />
+    </template>
+  </Designer>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { Designer, Header } from 'vg-print'
+import templateJson from './template.json'
+
+const template = ref(templateJson)
+const onDesigned = (e) => {
+  const { hiprint, designerUtils } = e.detail
+  const tpl = designerUtils.printTemplate
+}
+</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, '导出', {}) }
+</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` 扩展区域
+
+示例：
+
+```vue
+<Designer :template="template" :plugins="plugins" :providerMap="{ container: '.hiprintEpContainer', value: 'defaultModule' }" @onDesigned="onDesigned" />
+```
+
+### Header
+
+- 参数：
+  - `logoHtml: string` 左侧 logo html
+  - `title: string` 标题
+  - `reEle: boolean|string` 是否重建元素
+  - `eleList: array` 元素列表
+  - `reMenu: boolean|string` 是否重建菜单
+  - `menuList: array` 菜单列表
+  - `onPreviewClick: function` 预览点击回调，返回 `true` 阻止默认
+- 事件：
+  - `preview` 默认预览点击事件
+- 插槽：
+  - `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()` 客户端直接打印
+
+示例：
+
+```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'
+
+const previewRef = ref(null)
+const testPreview = () => {
+  previewRef.value.init(templateJson, { name: 'i不简' })
+  previewRef.value.show()
+}
+</script>
+```
+
+### DragBox
+
+- 参数：
+  - `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` 内容
+
+示例：
+
+```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>
+```
+
+## 函数式 API
+
+```js
+import { print, print2, defaultElementTypeProvider } from 'vg-print'
+
+const tpl = print(defaultElementTypeProvider, templateJson, { data: {} })
+const tpl2 = print2(defaultElementTypeProvider, templateJson, { data: {} })
+```
+
+## 可拖拽元素 Provider
+
+```js
+import { hiprint } from 'vg-print'
+
+export default function(options){
+  var 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' }
+      }])
+    ])
+  }
+  return { addElementTypes }
+}
+```
+
+在 `Designer` 中传入 `providers` 或使用 `providerMap` 构建左侧容器。
+
+## 注意事项
+
+- 需要在入口引入库样式，并调用 `injectPrintLock()` 注入打印锁样式。
+- 依赖 `jquery` 与 `element-plus`；请在应用中安装并初始化 UI 库。
+- 若使用客户端直连打印，请确保客户端组件可用并已连接。