vg-print 1.0.208 → 1.0.209

package/README.md

@@ -1,288 +1,196 @@
-# 打印设计器组件库使用说明书
+# vg-print-designer
 
-本项目已改造为可发布的 Vue3 组件库，提供 `Designer`、`Header`、`Preview`、`DragBox` 四个 UI 组件，并同时暴露 `hiprint` 工具能力，满足“可视化设计 + 打印/导出/直接打印”的完整链路。
+一个基于 `vue-plugin-hiprint` 的打印设计器组件库（Vue 3）。将项目中的设计页封装为可复用组件，提供 `Designer`、`Header`、`Preview`、`DragBox` 四个组件，方便在任何业务项目中快速集成打印模板设计、预览与导出能力。
+
+## 特性
+
+- 可视化拖拽设计打印模板，支持网格线、面板激活等配置
+- 预览支持导出 PDF/图片、浏览器打印、直接打印（需客户端）
+- 插件机制可扩展元素类型，与 `vue-plugin-hiprint` 完整兼容
+- 组件化封装，按需组合 `Header/Designer/Preview/DragBox`
 
 ## 安装
 
-```bash
+```
 npm i vg-print
 ```
 
-必须在宿主站点的 `index.html` 引入打印样式，以保证浏览器打印版式稳定：
+样式引入（确保设计器与打印样式生效）：
 
-```html
-<link rel="stylesheet" type="text/css" media="print" href="/print-lock.css" />
 ```
+// 全局样式（组件库样式）
+import 'vg-print/style.css'
 
-或使用 CDN：
-
-```html
+// 打印锁样式（可选；库已内置常用样式，如需严格 media="print" 可额外添加）
+在 `index.html` 中引入打印锁样式：
 <link rel="stylesheet" type="text/css" media="print" href="https://cdn.jsdelivr.net/npm/vue-plugin-hiprint@latest/dist/print-lock.css" />
 ```
 
+环境要求：Vue 3、Node >= 18.18。无需单独安装 `vue-plugin-hiprint`，本插件已内置并导出 `hiprint` 能力。
+
 ## 快速开始
 
-```ts
+```js
 // main.ts
 import { createApp } from 'vue'
 import App from './App.vue'
-import HiprintDesigner from 'vg-print'
+import vgPrint from 'vg-print'
 import 'vg-print/style.css'
-import 'element-plus/dist/index.css'
 
-const app = createApp(App)
-app.use(HiprintDesigner, { name: '$hiPrint', autoConnect: true })
-app.mount('#app')
+createApp(App).use(vgPrint).mount('#app')
 ```
 
 ```vue
 <template>
-  <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'" :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>
-
-  <Preview ref="previewRef" :modalShow="false" />
+  <div style="width: 100vw; height: 97vh;">
+    <Designer :template="template" :printData="printData" :config="config" :plugins="plugins" @ready="onReady">
+      <template #header>
+        <Header title="打印设计器" />
+      </template>
+      <template #other>
+        <DragBox target="SVPrint" drag-key="demo" drag-style="width:200px;height:200px;left:238px;top:95px" :show="true" />
+      </template>
+    </Designer>
+
+    <Preview ref="previewRef" />
+    <el-button @click="showPreview">显示预览</el-button>
+  </div>
 </template>
+
 <script setup>
 import { ref } from 'vue'
-import { defaultElementTypeProvider } from 'vg-print'
-import { Designer, Header, Preview, DragBox } from 'vg-print'
+import { hiprint } from 'vue-plugin-hiprint'
 
 const template = ref({})
+const printData = ref({ name: '示例' })
+const config = ref({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
+const plugins = ref([])
 const previewRef = ref(null)
-const onDesigned = (e) => {
-  // e.detail.hiprint / e.detail.designerUtils.printTemplate
-}
-const openPreview = () => {
-  const tpl = previewRef.value.getTarget()
-  previewRef.value.init(tpl, { name: 'i不简' })
+
+const onReady = (tpl) => {}
+const showPreview = () => {
+  const tpl = new hiprint.PrintTemplate({ template: template.value })
+  previewRef.value.init(tpl, printData.value)
   previewRef.value.show()
 }
-
-const providers = [new defaultElementTypeProvider()]
-const plugins = []
 </script>
 ```
 
-## 组件与属性
+## 组件概览
 
 ### Designer
 
-- `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' }`
-
-事件与插槽：
-
-- 事件：`onDesigned({ detail: { hiprint, designerUtils } })`，其中 `designerUtils.printTemplate` 为当前模板实例
-- 插槽：`#header` 顶部区域；`#other` 其他扩展区域
+- `template` object 模板 json 或模板对象，默认 `{}`
+- `printData` object 打印数据，默认 `{}`
+- `templateKey` string 本地缓存键，默认 `default-template`
+- `title` string 默认导出文件名，默认 `默认模板.json`
+- `designOptions` object 设计参数，如 `{ grid: true, activePanel: true }`
+- `paperList` array 可选纸张列表
+- `config` object `hiprint.setConfig` 参数，需在渲染前设置
+- `plugins` object[] 插件数组，`hiprint.register({ authKey, plugins })`
+- `authKey` string 插件授权 key
+- 事件：`ready(hiprintTemplate)`
+- 插槽：`header`、`other`
 
 ### Header
 
-- `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`
+- `logoHtml` string 左侧 logo HTML，默认 `<i class="svp-header-logo svicon sv-print"></i>`
+- `title` string 左侧标题，默认 `sv-print`
+- `onPreviewClick: (e) => boolean` 返回 `true` 阻止默认行为
+- 事件：`preview`
+- 插槽：`headerLeft`、`headerCenter`、`headerRight`
 
 ### Preview
 
-- `printTemplate` 模板 json/对象或 `hiprint.PrintTemplate` 实例
-- `printData` json 打印数据
+- `printTemplate` object 模板对象（`hiprint.PrintTemplate`）
+- `printData` object 打印数据
 - `printerList` array 打印机列表
-- `selectedPrinter` string 默认打印机名称
-- `showPdf` boolean 显示导出 PDF
-- `showImg` boolean 显示导出图片
-- `showPrint2` boolean 显示直接打印
-- `modalShow` boolean 是否显示
-
-方法：`getTarget()`、`init(tpl, data)`、`show()`、`print()`、`toPdf()`、`toImage(options)`、`directPrint()`
+- `selectedPrinter` string 默认选中打印机名称，支持 `v-model:selectedPrinter`
+- `showPdf`/`showImg`/`showPrint2` boolean 控制按钮
+- `modalShow` boolean 控制显示
+- 方法：`init(template, data)`、`getTarget()`、`show()`
 
 ### DragBox
 
 - `target` string 容器 Id 或 ClassName
 - `dragKey` string 拖拽标识
-- `dragStyle` string 默认位置/大小（`left/top/width/height` 内联样式字符串）
-- `mode` string `default|top|left|bottom|right|fixed`
+- `dragStyle` string 初始位置与大小，如 `width:200px;height:200px;left:238px;top:95px`
+- `mode` string `default | top | left | bottom | right | fixed`
 - `show` boolean 是否显示
+- 插槽：`iconTitle`、`body`
 
-插槽：`#iconTitle`、`#body`
+## 与 hiprint 的集成
 
-## 插件注册与扩展
+初始化与配置：
 
-注册第三方元素插件（如 bwip-js 条码）：
+```js
+import { hiprint, defaultElementTypeProvider } from 'vue-plugin-hiprint'
 
-```bash
-npm i @sv-print/plugin-ele-bwip-js
+hiprint.setConfig({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
+hiprint.register({ authKey: '', plugins: [] })
+hiprint.init({ providers: [new defaultElementTypeProvider()] })
 ```
 
-```ts
-import { hiprint } from 'vg-print'
-import pluginEleBwip from '@sv-print/plugin-ele-bwip-js'
+渲染与打印：
 
-hiprint.register({ authKey: '', plugins: [ pluginEleBwip({}) ] })
+```js
+const tpl = new hiprint.PrintTemplate({ template: {} })
+tpl.design('#hiprint-printTemplate', { grid: true })
+tpl.print({ name: '示例' })
+tpl.print2({ name: '示例' }, { printer: '' })
+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 })
 ```
 
-也可在 `Designer` 组件通过 `:plugins` 传入：
+## 完整示例（预览组件）
 
 ```vue
-<Designer :plugins="[pluginEleBwip({})]" authKey="" />
-```
-
-配置设计器 UI：
+<template>
+  <Preview ref="previewRef" :showPdf="true" :showImg="true" :showPrint2="true" v-model:selectedPrinter="selected" />
+  <el-button @click="open">预览</el-button>
+</template>
 
-```ts
-import { hiprint } from 'vg-print'
+<script setup>
+import { ref } from 'vue'
+import { hiprint } from 'vue-plugin-hiprint'
 
-hiprint.setConfig({
-  showAdsorbLine: true,
-  showPosition: true,
-  showSizeBox: true,
-})
-```
+const selected = ref('')
+const previewRef = ref(null)
 
-构建可拖拽元素 provider：
-
-```ts
-import { hiprint } from 'vg-print'
-
-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' }
-        }
-      ])
-    ])
-  }
-  return { addElementTypes }
+const open = () => {
+  const template = new hiprint.PrintTemplate({ template: {} })
+  previewRef.value.init(template, { name: '示例' })
+  previewRef.value.show()
 }
-
-// 传入 Designer
-<Designer :providers="[provider]" :providerMap="{ container: '.hiprintEpContainer', value: 'ibujianModule' }" />
+</script>
 ```
 
-可选：自定义 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`
+```
+npm run build:lib
+```
 
-- 全局对象：`this.$hiPrint`（或安装时自定义的 `name`）
-- 浏览器打印：`this.$print(provider, templateJson, printData, options)`
-- 直接打印：`this.$print2(provider, templateJson, printData, options)`（需客户端）
-- 连接控制：`autoConnect(cb)` / `disAutoConnect()`
+产物会生成到 `dist/`：`vg-print-designer.es.js`、`vg-print-designer.umd.js`。
 
-浏览器打印：
+发布到 npm：
 
-```ts
-import { defaultElementTypeProvider } from 'vg-print'
-this.$print(defaultElementTypeProvider, templateJson, { name: 'i不简' }, { importCss: true })
+```
+npm login
+npm publish
 ```
 
-直接打印（指定客户端与打印机）：
-
-```ts
-const clientId = 'AlBaUCNs3AIMFPLZAAAh'
-const client = this.$hiPrint.hiwebSocket.clients[clientId]
-const printer = client.printerList[0]
+如包名冲突，请在 `package.json` 中修改为未占用的名称。
 
-this.$print2(undefined, templateJson, { name: 'i不简' }, {
-  client: clientId,
-  printer: printer.name,
-  title: '打印预览'
-})
-```
+## 注意事项
 
-导出 PDF / 图片：
+- 必须在 `index.html` 注入 `print-lock.css`，保证打印样式稳定
+- 直接打印需配套客户端，跨域部署需启用 HTTPS
+- 建议在渲染前调用 `hiprint.setConfig` 配置设计器显示选项
 
-```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/交互
-- 报错 `defaultElementTypeProvider(...) is not a constructor`：请使用 `new defaultElementTypeProvider()`，不要先调用再 `new`
-- 导入样式 `import 'vg-print/style.css'` 报错：确认包已构建且 `node_modules/vg-print/dist/style.css` 存在；若从本地/仓库直接安装，先执行 `npm run build:lib` 或依赖包的 `prepare`
-- WebSocket `TransportError`：这是自动连接打印客户端失败的提示；如不使用客户端，安装时传入 `{ autoConnect: false }` 或在运行期调用 `disAutoConnect()`
-- 无样式/不可拖拽：请确保在应用入口已 `import 'vg-print/style.css'`，且安装了 `jquery` 依赖；如果使用 `pnpm`，也要确认 `jquery` 没被去重导致未被实际安装
-- 组件按钮/弹窗无样式：请在入口额外引入 Element Plus 样式 `import 'element-plus/dist/index.css'`
-
-## 打包与发布
-
-- 运行库打包：`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`
-
-## 代码位置索引
-
-- 组件安装入口：`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`
+- 入口与导出：`packages/index.ts`
+- 组件：`packages/components/Designer.vue`、`packages/components/Header.vue`、`packages/components/Preview.vue`、`packages/components/DragBox.vue`