vg-print 1.0.347 → 1.0.349

package/README.md

@@ -1,240 +1,761 @@
 # vg-print
 
-vg-print Vue3.x 支持拖拽(分页(不分页)、表头表脚、样式设置、复制粘贴、缩放、撤销重做)生成打印模板、导出json模板数据、静默打印/获取MAC地址(借助客户端)
+一个开箱即用的打印设计器组件库（Vue 3）。现在聚焦于单一组件 `FullDesigner`，同时暴露底层 `hiprint` 能力与客户端直连（`hiwebSocket`）配置，便于快速集成模板设计、预览、浏览器打印、导出 PDF/图片、直接打印等功能。
+![功能截图](https://gitee.com/gao111/electron-vg-print/raw/master/ScreenShot_2025-12-25_163332_128.png)
+您可以直接安装引入体验功能.
+没有域名限制,无网可用. 提供一对一技术支持.
+npm搜索vg-print.
+联系我加 QQ: 984239686 或使用首页有微信号加入
+
+# 静默打印客户端工具安装包
+
+![静默打印客户端工具](https://gitee.com/gao111/electron-vg-print/raw/master/electron-hiprint.png)
+
+更多信息与下载：<https://gitee.com/gao111/electron-vg-print>
+
+## 特性
+
+- 全功能页面组件 `FullDesigner`，直接使用，无需拼装子组件
+- 支持预览、浏览器打印、导出 PDF/图片、直接打印（需客户端）
+- 通过属性配置 `hiwebSocket` 的 `host`、`token` 与自动连接
+- 暴露实例方法：预览、打印、导出、连接控制等，外部可直接调用
+- 集成并导出 `hiprint`，可进行模板对象级的高级定制
 
 ## 安装
 
-```bash
-npm install vg-print --save
+```
+npm i vg-print
 ```
 
-## 引入
+## Header 顶部工具栏组件
 
-```javascript
-import { createApp } from 'vue'
-import App from './App.vue'
-import vgPrint from 'vg-print'
-import 'vg-print/dist/style.css'
+- 用于页面一级头部区域，内置常用操作按钮与打印机设置；支持通过 `props` 与 `slots` 定制。
+- 默认嵌入在 `FullDesigner` 中；也可单独使用。
 
-const app = createApp(App)
-app.use(vgPrint)
-app.mount('#app')
-```
+### 属性（Props）
+
+- `logoHtml: string` 左侧 Logo 区自定义 HTML 片段
+- `title: string` 左侧标题文本
+- `printCount: number` 打印份数，默认 `1`（支持 `v-model:printCount`）
+- `printerName: string` 当前选择的打印机名称（支持 `v-model:printerName`）
+- `printerList: Array<{ name: string; label: string }>` 打印机列表
+- `waitShowPrinter: boolean` 显示“浏览器打印”按钮的加载状态
+- `languages: Array<{ label: string; value: string }>` 语言切换下拉选项
+
+### 事件（Emits）
 
-## 组件列表
+- `preview` 打开预览
+- `print-view` 浏览器打印
+- `to-pdf` 导出 PDF
+- `to-image` 导出图片
+- `print` 直接打印（需客户端）
+- `clear-paper` 清空（带二次确认）
+- `save` 保存（拆分按钮的主键）
+- `edit-template` 打开“编辑模板数据”对话框
+- `edit-data` 打开“编辑打印数据”对话框
+- `lang-change` 语言切换（值为语言码：`cn`、`en`、`de`、`es`、`fr`、`it`、`ja`、`ru`、`cn_tw`）
+- `feedback` 反馈/帮助
 
-- `FullDesigner`: 完整设计器组件
-- `Header`: 头部组件
-- `Preview`: 预览组件
+### 插槽（Slots）
 
-## FullDesigner 使用
+- `headerLeft` 左侧区域（默认：logo + 标题）
+- `headerCenter` 中间自定义区域（默认空）
+- `headerRight` 右侧操作区（默认：打印机与一组按钮）
+
+### 使用示例：与 FullDesigner 配合
 
 ```vue
 <template>
-  <FullDesigner />
+  <FullDesigner
+    ref="designer"
+    :initial-template="tpl"
+    :initial-print-data="rows"
+    default-lang="cn"
+    :hi-host="host"
+    :hi-token="token"
+    :hi-auto-connect="true"
+    @save="onSave"
+  >
+    <!-- 顶部区域（Header 默认内置；也可通过 slot 定制） -->
+    <template #headerLeft>
+      <div style="display:flex;align-items:center;color:#fff;">
+        <img src="/logo.svg" style="height:24px;margin-right:8px;" />
+        <span>自定义标题</span>
+      </div>
+    </template>
+    <template #headerCenter>
+      <el-tag type="success">中间自定义区域</el-tag>
+    </template>
+    <!-- 保留默认按钮时无需提供 headerRight；若完全替换按钮则提供该插槽 -->
+    <template #headerRight>
+      <el-button size="small" @click="designer.value.preView()">预览</el-button>
+      <el-button size="small" @click="designer.value.printView()">浏览器打印</el-button>
+      <el-button type="primary" size="small" @click="designer.value.toPdf()">导出 PDF</el-button>
+      <el-button size="small" @click="designer.value.toImage()">导出图片</el-button>
+      <el-button size="small" @click="designer.value.print()">直接打印</el-button>
+      <el-button type="warning" size="small" @click="onClear()">清空</el-button>
+      <el-button type="success" size="small" @click="onSaveDirect()">保存</el-button>
+    </template>
+  </FullDesigner>
 </template>
+
+<script setup>
+import { ref } from 'vue'
+const designer = ref(null)
+const host = ref('http://127.0.0.1:17521')
+const token = ref('')
+const tpl = { panels: [ /* ... */ ] }
+const rows = [{ title: '病理图文报告', name: '东东' }]
+const onSave = ({ template, data }) => { /* 保存到后端 */ }
+const onClear = () => { /* 清空数据/元素 */ }
+const onSaveDirect = () => designer.value?.save()
+</script>
 ```
 
-## 注意事项
+### 使用示例：单独使用 Header
 
-- 直接打印需配套客户端（Electron 或服务端），跨域部署需启用 HTTPS
-- 若使用自定义 `host/token`，确保客户端配置一致且网络可达
-- SSR 兼容：插件安装仅在浏览器环境执行（`typeof window !== 'undefined'`），在 SSR 框架中引入不会因 `window` 未定义报错。
+```vue
+<template>
+  <Header
+    v-model:printCount="count"
+    v-model:printerName="printer"
+    :printerList="printers"
+    :waitShowPrinter="loading"
+    :languages="langs"
+    title="打印设计器"
+    @preview="onPreview"
+    @print-view="onPrintView"
+    @to-pdf="onToPdf"
+    @to-image="onToImage"
+    @print="onPrint"
+    @clear-paper="onClear"
+    @save="onSave"
+    @lang-change="onLangChange"
+    @feedback="onFeedback"
+  />
+</template>
+```
 
-## 构建
+### 响应式策略（已内置）
 
-开发与构建：
+- 窗口缩小时自动隐藏中间区域与次要按钮，保留右侧“保存”和“反馈”等关键操作；左侧 logo/标题不受影响。
+- 断点规则：
+  - `≤1600px` 隐藏中间区域
+  - `≤1400px` 隐藏打印份数、打印机选择、预览、浏览器打印、导出 PDF、导出图片
+  - `≤1200px` 隐藏直接打印、语言切换
+  - `≤992px` 隐藏清空
+  - `≤768px` 隐藏标题文本（保留 Logo）
 
-```
-npm run dev      # 开发
-npm run build    # 应用构建
-npm run build:lib# 组件库构建
-```
+> 提示：如需完全自定义按钮，请提供 `headerRight` 插槽实现自己的按钮布局。
+
+---
+
+## Preview 预览组件
+
+- 独立的预览弹窗组件，支持渲染模板 HTML、选择打印机、导出 PDF/图片、直接打印等。
+- 可单独使用或与 `FullDesigner` 搭配。
+
+### 属性（Props）
 
-## 源码位置
+- `printTemplate: object` 模板对象（`hiprint.PrintTemplate` 或 `createTemplate` 返回值）
+- `printData: object | array` 打印数据
+- `printerList: Array<{ name: string; label: string }>` 打印机列表
+- `selectedPrinter: string` 选中的打印机名称
+- `showPdf: boolean` 是否显示“导出 PDF”按钮，默认 `true`
+- `showImg: boolean` 是否显示“导出图片”按钮，默认 `true`
+- `showPrint2: boolean` 是否显示“直接打印”按钮，默认 `true`
+- `modalShow: boolean` 弹窗显隐（支持 `v-model:modalShow`）
+- `width: string | number` 弹窗宽度（默认 `'80%'`）
 
-- 入口与导出：`packages/index.ts`
-- 完整页面组件：`src/views/index.vue`
+### 事件（Emits）
 
-## 完整示例与头部定制
+- `update:modalShow` 双向绑定弹窗显隐
+- `update:selectedPrinter` 选中打印机变更
+- `close` 关闭弹窗
 
-`Header` 组件已完全内置于 `FullDesigner` 中。您**不需要**单独引入或编写 `<Header>` 标签，只需通过 `FullDesigner` 的属性和插槽即可实现对头部的完全控制。
+### 暴露方法（defineExpose）
 
-### 1. 基础定制：标题与 Logo (Props)
+- `show(template, data, width?)` 显示并渲染预览内容；可传入模板/数据与弹窗宽度
+- `hideModal()` 关闭弹窗
+- `init()` 初始化（内部使用）
+- `getTarget()` 获取预览容器 DOM
 
-最简单的用法，通过属性直接配置。
+### 使用示例（单独使用）
 
 ```vue
 <template>
-  <FullDesigner
-    :initial-template="tpl"
-    title="我的打印设计"
-    logo-html="<img src='https://example.com/logo.png' height='28px' />"
-    @save="onSave"
+  <el-button @click="openPreview">显示预览</el-button>
+  <Preview
+    ref="previewRef"
+    v-model:modalShow="visible"
+    :printerList="printers"
+    :selectedPrinter="printer"
+    @update:selectedPrinter="printer = $event"
   />
 </template>
-```
 
-### 2. 进阶定制：使用插槽 (Slots)
+<script setup>
+import { ref } from 'vue'
+import { Preview, createTemplate } from 'vg-print'
+import 'vg-print/style.css'
+
+const previewRef = ref(null)
+const visible = ref(false)
+const printers = ref([{ name: 'HP_001', label: 'HP 打印机' }])
+const printer = ref('')
+
+const tmplJson = { panels: [ /* ... */ ] }
+const data = { title: '病理图文报告', name: '东东' }
 
-通过插槽可以替换头部 specific 区域的内容。
+const openPreview = () => {
+  const tpl = createTemplate(tmplJson) // 也可传入 hiprint.PrintTemplate
+  previewRef.value.show(tpl, data, '80%')
+}
+</script>
+```
 
-#### 2.1 自定义左侧与中间区域
+### 使用示例（与 FullDesigner 搭配）
 
 ```vue
 <template>
-  <FullDesigner :initial-template="tpl">
-    <!-- #headerLeft: 替换默认的 Logo/标题 -->
-    <template #headerLeft>
-       <div class="my-brand">
-         <i class="el-icon-s-platform"></i> 
-         <strong>企业报表中心</strong>
-       </div>
-    </template>
-    
-    <!-- #headerCenter: 在中间空白区域添加内容 -->
-    <template #headerCenter>
-       <span class="status-badge">运行中</span>
-    </template>
-  </FullDesigner>
+  <FullDesigner ref="designer" default-lang="cn" />
+  <Preview ref="previewRef" v-model:modalShow="visible" />
+  <el-button @click="designer.value.preView()">直接使用 FullDesigner 的预览</el-button>
+  <el-button @click="showCustomPreview">用 Preview 展示当前模板</el-button>
 </template>
+
+<script setup>
+import { ref } from 'vue'
+const designer = ref(null)
+const previewRef = ref(null)
+const visible = ref(false)
+
+const showCustomPreview = () => {
+  const tpl = designer.value.getTemplate()      // 假设暴露了获取模板的方法
+  const data = designer.value.getPrintData()    // 假设暴露了获取数据的方法
+  previewRef.value.show(tpl, data, '80%')
+}
+</script>
 ```
 
-#### 2.2 自定义右侧工具栏（完全替换）
+### 注意
 
-使用 `#headerRight` 插槽将**完全替换**默认的工具栏按钮。适用于需要完全自定义操作按钮的场景。
+- 使用组件库时请引入 `vg-print/style.css`，其中包含自定义图标字体与预览/设计样式。
+- `Preview` 内部会根据 `printTemplate` 与 `printData` 自动渲染内容；也支持通过 `show(...)` 主动传入。
+
+
+样式引入（确保设计与打印样式生效）：
+
+```
+// 全局样式（组件库样式）
+import 'vg-print/style.css'
+
+// 打印锁样式（推荐；保证打印时样式稳定）
+// 在 `index.html` 中引入：
+<link rel="stylesheet" type="text/css" media="print" href="/css/print-lock.css" />
+```
+
+环境要求：Vue 3、Node >= 18.18。无需单独安装 `vue-plugin-hiprint`，本库已内置并导出 `hiprint` 能力。
+
+## 快速开始
+
+```js
+// 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')
+```
 
 ```vue
 <template>
-  <FullDesigner ref="designer">
-    <template #headerRight>
-       <!-- 自定义按钮组 -->
-       <el-button type="primary" size="small" @click="handlePrint">立即打印</el-button>
-       <el-button size="small" @click="handleSave">保存</el-button>
-    </template>
-  </FullDesigner>
+  <FullDesigner
+    ref="designer"
+    :hi-host="'http://127.0.0.1:17521'"
+    :hi-token="'your-token'"
+    :hi-auto-connect="true"
+  />
+
+  <el-button @click="preview">预览</el-button>
+  <el-button @click="printBrowser">浏览器打印</el-button>
+  <el-button @click="exportPdf">导出 PDF</el-button>
+  <el-button @click="exportImage">导出图片</el-button>
+  <el-button @click="directPrint">直接打印（需客户端）</el-button>
 </template>
 
 <script setup>
 import { ref } from 'vue'
 const designer = ref(null)
 
-const handlePrint = () => designer.value.printView() // 调用组件内部方法
-const handleSave = () => designer.value.save()       // 调用组件内部方法
+// 预览
+const preview = () => designer.value.preView()
+// 浏览器打印
+const printBrowser = () => designer.value.printView()
+// 直接打印（需客户端已连接）
+const exportPdf = () => designer.value.toPdf()
+// 导出图片
+const exportImage = () => designer.value.toImage()
+// 直接打印（需客户端已连接）
+const directPrint = () => designer.value.print()
+
+// 连接控制与参数设置
+const setHostToken = () => designer.value.setHiwebSocket('http://127.0.0.1:17521', 'token')
+// 主动连接客户端
+const connect = () => designer.value.connect()
+// 断开客户端
+const disconnect = () => designer.value.disconnect()
+// 关闭自动连接策略
+const disableAutoConnect = () => designer.value.disAutoConnect()
 </script>
 ```
 
-#### 2.3 完全替换头部组件 (Total Header Replacement)
+## API（FullDesigner）
+
+### 属性（Props，含描述）
+
+- `hi-host: string` 客户端服务地址；示例 `http://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`
+
+以上属性支持运行时动态修改；组件内部已监听并应用。
 
-使用 `#header` 插槽完全替换内置的 `Header` 组件。这对应于您可能看到的某些示例（如 `template #header` 包裹整个 Header 组件）。
+### 方法（通过组件 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` 保存模板与数据；回调参数结构：
+
+```js
+{
+  template,   // 模板 JSON
+  data,       // 当前打印数据（对象或数组）
+  templateId  // 模板标识（若存在）
+}
+```
+
+示例：
 
 ```vue
 <template>
-  <FullDesigner ref="designer">
-    <!-- #header: 完全自定义头部结构 -->
-    <template #header>
-      <div class="my-custom-header">
-        <h1>我的专属设计器</h1>
-        <div class="actions">
-           <button @click="designer.printView()">打印</button>
-        </div>
-      </div>
-    </template>
-  </FullDesigner>
+  <FullDesigner
+    :initial-template="tpl"
+    :initial-print-data="rows"
+    default-lang="cn"
+    @save="onSave"
+  />
 </template>
 
-<style scoped>
-.my-custom-header {
-  height: 60px;
-  background: #333;
-  color: #fff;
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  padding: 0 20px;
+<script setup>
+const onSave = ({ template, data, templateId }) => {
+  // 调用接口持久化到数据库
+  // await api.saveTemplate({ template, data, templateId })
 }
-</style>
+</script>
 ```
+### 语言与国际化
 
-### 3. 综合集成示例
+- 通过 `default-lang` 设置初始语言（`cn` 默认为中文）；内部会同步 `vue-i18n` 与 `hiprint` 的语言。
+- 运行时可在页面右上角语言切换菜单切换（无需刷新）。
 
-包含数据加载、连接客户端、自定义头部样式的完整代码。
+## 高级用法（hiprint）
 
-```vue
-<script setup>
-import { ref, onMounted } from 'vue'
-// import { FullDesigner } from 'vg-print' // 实际使用时引入
+本库导出 `hiprint`，可直接创建与操作模板对象（`hiprint.PrintTemplate`）：
 
-const tpl = ref({}) // 初始模板
-const token = ref('')
+```
+import { hiprint, defaultElementTypeProvider } from 'vg-print'
+// 全局配置
+hiprint.setConfig({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
+// 注册插件
+hiprint.register({ authKey: '', plugins: [] })
+// 初始化元素提供器 （默认元素提供器）
+hiprint.init({ 
+  providers: [new defaultElementTypeProvider()],
+  host: 'http://localhost:17521',
+  token: '',
+  lang: 'en'
+})
+// 创建模板对象
+   const tpl = new hiprint.PrintTemplate({ template: {} })
+// 设计模板
+   tpl.design('#hiprint-printTemplate', { grid: true })
+// 浏览器打印
+   tpl.print({ name: '示例' }, {}, {
+            callback: () => {
+                this.waitShowPrinter = false
+            },
+        })
+
+// 直接打印（需客户端已连接）
+   tpl.print2({ name: '示例' }, {
+                    printer: '',  // 打印机 名称
+                    title: '打印预览pdf'
+       });
+
+
+// 导出 PDF（内置示例参数）
+// 模式1: 小模版需要在一页中排列的话，增加增加页面宽高参数（想把多订单放在一页中排列）----小模板拼到大纸张（例如 A4）
+  tpl.toPdf([{ name: '示例1' },{ name: '示例2' },{ name: '示例3' }], '打印预览pdf', { 
+    paperWidth: 210, 
+    paperHeight: 297, 
+    scale: 2, 
+    perPage: 6, // 每页模板数
+    leftOffset:-1, // 对齐偏移
+    topOffset:-1, // 对齐偏移
+      onProgress: (cur, total) => { 
+      console.log('toPdf 进度', Math.floor((cur/total)*100))
+      }
+    })
+// 模式2:普通模板，导出预览全部页：
+  tpl.toPdf(this.printDataVar, '打印预览pdf',{
+  onProgress: (cur, total) => { 
+      console.log('toPdf 进度', Math.floor((cur/total)*100))
+      }
+  });
+
+// 导出图片（内置示例参数） 
+// 导出为多张图片，每张合成 6 页，自动下载 JPEG     
+  tpl.toImage({ name: '示例' }, { isDownload: true, name: '图片名称', limit: 1, type: 'image/jpeg', pixelRatio: 2, quality: 0.8, toType: 'url', onProgress: (cur, total) => console.log('toImage 进度', Math.floor((cur/total)*100)) })
+  //按 A4 纸张排版导出（把小模板排到 A4）：
+  tpl.toImage({ name: '示例' }, { paperWidth: 210, paperHeight: 297, limit: 6, isDownload: true, name: 'A4排版', type: 'image/jpeg', pixelRatio: 2 })
+
+```
+
+水印与授权行为说明：设计态与运行态分离。设计态不自动显示默认水印（由面板设置项决定）；运行态按授权和面板内容合并控制。
 
-const onSave = ({ template }) => {
-  console.log('Template JSON:', template)
-  ElMessage.success('保存成功')
+### 授权密钥（authKey）与默认水印
+
+- 行为说明：
+  - 设计态（FullDesigner 设计界面）：不自动注入默认水印；是否显示水印由面板中的“水印功能”设置项决定，与 `authKey` 无关。
+  - 运行态（预览、浏览器打印、导出 PDF/图片、直连打印）：
+    - 无授权（未注册 `authKey`）：
+      - 面板未填写内容 → 显示默认水印 `{ content: 'vg-print', timestamp: true }`
+      - 面板填写了内容 → 显示面板内容 + "试用版" 后缀
+    - 有授权（已注册有效 `authKey`）：
+      - 面板未填写内容 → 不显示水印（默认水印被移除）
+      - 面板填写了内容 → 显示面板内容（无后缀）
+
+- 注册授权密钥：
+  在项目入口（如 `main.js` 或 `App.vue`）尽早注册：
+
+  ```js
+  import { hiprint } from 'vg-print';
+
+  // 填入生成的 Key
+  hiprint.register({ authKey: 'eyJrIjoiZ21jNTc2MDMzNyJ9' });
+  ```
+
+  注册后，以下所有使用方式均会自动生效（移除默认水印）：
+  - 完整设计器组件 `FullDesigner`
+  - 核心类 `new hiprint.PrintTemplate(...)`
+  - 轻量运行时 helper `createTemplate(...)`
+
+- 示例：轻量运行时使用授权
+
+```js
+import { hiprint, createTemplate, printBrowser } from 'vg-print'
+
+hiprint.register({ authKey: 'eyJrIjoiZ21jNTc2MDMzNyJ9' })
+const tpl = createTemplate(tmplJson) // 不再自动注入默认水印
+printBrowser(tpl, data)
+```
+
+- 自定义或显式控制水印：
+
+```js
+// 无授权时，库会注入默认水印；如需自定义水印样式/内容
+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 } })
+```
+
+- 插件注册（可选）：
+
+```js
+import { hiprint } from 'vg-print'
+
+// 两种形式的插件均支持
+function pluginFn(h) { /* 扩展逻辑 */ }
+const pluginObj = { install(h) { /* 扩展逻辑 */ } }
+
+hiprint.register({
+  authKey: 'YOUR_AUTH_KEY',
+  plugins: [pluginFn, pluginObj]
+})
+```
+
+默认水印参数参考：
+
+```js
+{ content: 'vg-print', timestamp: true }
 }
-</script>
 
-<style scoped>
-.app-container { height: 100vh; }
-.info-bar { line-height: 40px; color: #999; font-size: 12px; }
-</style>
+ 
+
+
+## 轻量运行时 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('http://127.0.0.1:17521', 'your-token')
+connect()
+// 可选：查看打印机列表
+const printers = getPrinterList(tpl)
+// 使用模板对象直接发起直连打印
+tpl.print2(printData, { printer: printers?.[0]?.name || '' })
+
+// 7) 断开连接
+disconnect()
 ```
 
-## Preview 预览组件
+### 导出 PDF 两种模式
+
+- 普通导出（按模板自身纸张与分页设置）：
+
+```js
+// 不传纸张尺寸，使用模板的面板尺寸与分页配置
+exportPdf(tpl, printData, '打印预览pdf', {
+  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur/total)*100))
+})
+```
+
+- A4 排版导出（把小模板排到指定纸张）：
+
+```js
+// 传入纸张尺寸与排版参数，将多个模板排到一张 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))
+})
+```
+
+### 导出图片 两种模式
+
+- 普通导出（按模板自身纸张与分页设置）：
+
+```js
+// 不传纸张尺寸，按模板分页导出图片
+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 排版导出（把小模板排到指定纸张）：
+
+```js
+// 传入纸张尺寸以 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: [...] })`；默认已初始化内置提供器
 
-`Preview` 组件用于展示打印预览，支持多种导出格式（PDF、图片）及打印机选择。
+### 适用场景（含描述）
 
-### 组件参数 (Props)
+- 后台页面、弹窗、任务流：仅需“模板 + 数据”的预览/打印/导出能力
+- 脚本或批量任务：结合 `exportPdf`/`exportImage` 实现批量导出
 
-| 参数键名 | 数据类型 | 默认值 | 说明 | 备注 |
-| :--- | :--- | :--- | :--- | :--- |
-| printTemplate | Object/JSON | undefined | 模板对象 | |
-| printData | Object/JSON | undefined | 打印数据 | |
-| printerList | Array | [] | 打印机列表 | 显示时会自动刷新 |
-| selectedPrinter | String | '' | 默认选中打印机名称 | |
-| showPdf | Boolean | true | 是否显示导出 PDF 按钮 | |
-| showImg | Boolean | true | 是否显示导出图片按钮 | |
-| showPrint2 | Boolean | true | 是否显示直接打印按钮 | |
-| modalShow | Boolean | false | 是否显示弹窗 | 可使用 v-model:modalShow |
-| width | String/Number | '80%' | 弹窗宽度 | |
 
-### 方法 (Exposed Methods)
+## 注意事项
 
-| 方法名 | 参数 | 说明 |
-| :--- | :--- | :--- |
-| init | (template, data) | 初始化模板和数据 |
-| show | (template, data, width) | 显示预览弹窗（会自动调用 render） |
-| hideModal | - | 关闭弹窗 |
-| getTarget | - | 获取当前模板实例 |
+- 建议在 `index.html` 注入 `print-lock.css`，保证打印样式稳定
+- 直接打印需配套客户端（Electron 或服务端），跨域部署需启用 HTTPS
+- 若使用自定义 `host/token`，确保客户端配置一致且网络可达
+- SSR 兼容：插件安装仅在浏览器环境执行（`typeof window !== 'undefined'`），在 SSR 框架中引入不会因 `window` 未定义报错。
 
-### 使用示例
+## 完整示例
 
 ```vue
 <template>
-  <div>
-    <el-button @click="testPreview">显示预览组件</el-button>
-    <Preview ref="previewRef" v-model:modalShow="modalShow" />
+  <FullDesigner
+    :initial-template="tpl"
+    :initial-print-data="rows"
+    default-lang="cn"
+    :hi-host="host"
+    :hi-token="token"
+    :hi-auto-connect="true"
+    @save="onSave"
+  />
+
+  <div style="margin-top: 12px;">
+    <el-input v-model="host" placeholder="客户端地址，如 http://127.0.0.1:17521" style="width: 360px; margin-right: 8px;" />
+    <el-input v-model="token" placeholder="鉴权令牌" style="width: 200px; margin-right: 8px;" />
+    <el-button type="primary" @click="applyHostToken">应用连接参数</el-button>
+    <el-button style="margin-left:8px;" @click="preview">预览</el-button>
+    <el-button style="margin-left:8px;" @click="printBrowser">浏览器打印</el-button>
   </div>
 </template>
 
-<script setup lang="ts">
-import { ref } from "vue";
-import { Preview } from "vg-print"; // 假设这是您的包名
-
-// 假设 template 是已经创建好的 hiprint 模板实例
-// import { hiprint } from 'vg-print';
-// const template = new hiprint.PrintTemplate({...});
-
-const previewRef = ref(null);
-const modalShow = ref(false);
-
-const testPreview = () => {
-  // 方式1: 直接调用 show 并传入参数
-  // 假设 printData 是您的打印数据
-  previewRef.value.show(template, printData);
-  
-  // 方式2: 配合 Props 使用
-  // modalShow.value = true;
-};
+<script setup>
+import { ref } from 'vue'
+
+// 模板（示例）
+const tpl = {
+  panels: [
+    {
+      index: 0,
+      paperType: 'A4',
+      width: 210,
+      height: 297,
+      printElements: [
+        {
+          options: { left: 20, top: 20, title: '标题', field: 'title', fontSize: 18 },
+          printElementType: { type: 'text' }
+        },
+        {
+          options: { left: 20, top: 50, title: '姓名', field: 'name' },
+          printElementType: { type: 'text' }
+        }
+      ]
+    }
+  ]
+}
+
+// 数据（对象或数组均可）
+const rows = [{ title: '病理图文报告', name: '东东' }]
+
+// 连接参数
+const host = ref('http://127.0.0.1:17521')
+const token = ref('')
+
+// 组件引用
+const designer = ref(null)
+
+const applyHostToken = () => {
+  // 设置客户端地址与令牌，并尝试重连
+  designer.value?.setHiwebSocket(host.value, token.value)
+}
+
+// 预览与浏览器打印
+const preview = () => designer.value?.preView()
+const printBrowser = () => designer.value?.printView()
+
+// 保存事件：拿到模板与数据入库
+const onSave = ({ template, data, templateId }) => {
+  // 持久化示例
+  // await api.save({ template, data, templateId })
+  console.log('save payload:', { template, data, templateId })
+}
 </script>
 ```