vg-print 1.0.224 → 1.0.226

package/README.md

@@ -177,6 +177,154 @@ tpl.toPdf({ name: '示例' }, '打印预览pdf', { paperWidth: 210, paperHeight:
 tpl.toImage({ name: '示例' }, { isDownload: true, name: '图片', limit: 1, type: 'image/jpeg', pixelRatio: 2 })
 ```
 
+## 轻量运行时 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 html = getHtml(tpl, printData)
+document.querySelector('#preview').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()
+```
+
+### 导出 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）；通常用于小模板拼接到 A4。
+- `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: [...] })`；默认已初始化内置提供器。
+
+### 适用场景
+
+- 后台页面、弹窗、任务流等，只做“数据 + 模板”的快速预览/打印/导出
+- 服务端或脚本批量导出（结合 `exportPdf`/`exportImage`）
+
+
 ## 注意事项
 
 - 建议在 `index.html` 注入 `print-lock.css`，保证打印样式稳定