vg-print 1.0.410 → 1.0.412

package/README.md

@@ -3,7 +3,7 @@
 [中文](#chinese) | [English](#english)
 
 <span id="chinese"></span>
-[开源免费]一个开箱即用的打印设计器组件库（Vue 3）。现在聚焦于单一组件 `FullDesigner`，同时暴露底层 `hiprint` 能力与客户端直连（`hiwebSocket`）配置，便于快速集成模板设计、预览、浏览器打印、导出 PDF/图片、直- 接打印等功能。
+[开源免费]一个开箱即用的打印设计器组件库（Vue 3）。现在聚焦于单一组件 `FullDesigner`，同时暴露底层 `hiprint` 能力与客户端直连（`hiwebSocket`）配置，便于快速集成模板设计、预览、浏览器打印、导出 PDF/图片、直接打印等功能。
 - 您可以直接安装引入体验功能.功能在不断完善中，请及时更新使用，欢迎反馈与建议，共同成长
 - 没有域名限制,无网可用. 随时提供帮助和解决问题.
 - npm搜索vg-print.
@@ -88,12 +88,12 @@ hiprint.register({
 
 
 
-# 静默打印客户端工具安装包
+## 静默打印客户端工具安装包
 
 ![静默打印客户端工具](https://gitee.com/gao111/electron-vg-print/raw/master/electron-hiprint.png)
 
 客户端工具下载：
-```
+```text
 https://download.csdn.net/download/github_38400706/92538739
 ```
 ## 特性
@@ -103,12 +103,11 @@ https://download.csdn.net/download/github_38400706/92538739
 - 通过属性配置 `hiwebSocket` 的 `host`、`token` 与自动连接
 - 暴露实例方法：预览、打印、导出、连接控制等，外部可直接调用
 - 集成并导出 `hiprint`，可进行模板对象级的高级定制
-- 内置 `@sv-print/plugin-api-pdf3` 与 `@sv-print/plugin-api-image` 插件，提供更强大的导出功能
 
 
 ## 安装
 
-```
+```bash
 npm i vg-print
 ```
 
@@ -154,10 +153,11 @@ npm i vg-print
  假如你部署的网站是: https://www.abcd.com/index.html 
  那么确保 https://www.abcd.com/print-lock.css 
  能够正常访问在你项目的 index.html 入口 添加 print-lock.css 打印样式【名称 print-lock.css】注意: media="print"
- <!-- 可以调整成 相对链接/自有链接, 【重要】名称需要一致 【print-lock.css】-->
- ```
+可以调整成相对链接/自有链接，但【重要】名称需要一致（`print-lock.css`）：
+
+```html
 <link rel="stylesheet" type="text/css" media="print" href="/print-lock.css" />
- ```
+```
 
 ### 使用示例：与 FullDesigner 配合
 
@@ -282,7 +282,7 @@ const onSaveDirect = () => designer.value?.save()
 
 ```vue
 <template>
-  <el-button @click="openPreview">显示预览</el按钮>
+  <el-button @click="openPreview">显示预览</el-button>
   <Preview
     ref="previewRef"
     v-model:modalShow="visible"
@@ -346,12 +346,13 @@ const showCustomPreview = () => {
 
 样式引入（确保设计与打印样式生效）：
 
-```
+```js
 // 全局样式（组件库样式）
 import 'vg-print/style.css'
+```
 
-// 打印锁样式（推荐；保证打印时样式稳定）
-// 在 `index.html` 中引入：
+```html
+<!-- 打印锁样式（推荐；保证打印时样式稳定） -->
 <link rel="stylesheet" type="text/css" media="print" href="/css/print-lock.css" />
 ```
 
@@ -476,7 +477,7 @@ const onSave = ({ template, data, templateId }) => {
 
 本库导出 `hiprint`，可直接创建与操作模板对象（`hiprint.PrintTemplate`）：
 
-```
+```js
 import { hiprint, defaultElementTypeProvider } from 'vg-print'
 // 全局配置
 hiprint.setConfig({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
@@ -490,86 +491,86 @@ hiprint.init({
   lang: 'en'
 })
 // 创建模板对象
-   const tpl = new hiprint.PrintTemplate({ template: {} })
+const tpl = new hiprint.PrintTemplate({ template: {} })
 // 设计模板
-   tpl.design('#hiprint-printTemplate', { grid: true })
+tpl.design('#hiprint-printTemplate', { grid: true })
 // 浏览器打印
-   tpl.print({ name: '示例' }, {}, {
-            callback: () => {
-                this.waitShowPrinter = false
-            },
-        })
+tpl.print({ name: '示例' }, {}, {
+  callback: () => {
+    this.waitShowPrinter = false
+  },
+})
 
 // 直接打印（需客户端已连接）
-   tpl.print2({ name: '示例' }, {
-                    printer: '',  // 打印机 名称
-                    title: '打印预览pdf'
-       });
+tpl.print2({ name: '示例' }, {
+  printer: '', // 打印机名称
+  title: '打印预览pdf'
+});
 
 
 // 导出 PDF（内置示例参数）
-// 方式 1: 原生导出 (toPdf)
-// 模式1: 小模版需要在一页中排列的话...数据是数组格式
-  tpl.toPdf([...], '打印预览pdf', { 
-      isDownload: true, // 不自动下载
-      type: "blob", // 默认 blob  支持: blob、bloburl、pdfobjectnewwindow、dataurl  --> jspdf.output(type)
-      onProgress: (cur, total) => {
-        const percent = Math.floor((cur / total) * 100);
-        console.log("toPdf 进度", percent);
-        // 导出进度100%的时候关闭等待
-        if (cur === total) {
-          // 导出完成
-        }
-      },
-
-   })
+//模式1: 小模版需要在一页中排列的话，增加增加页面宽高参数（想把多订单放在一页中排列）----小模板拼到大纸张（例如 A4）
+tpl.toPdf(this.printDataVar, '打印预览pdf', { 
+  paperWidth: 210, 
+  paperHeight: 297, 
+  scale: 2, 
+  perPage: 6, // 每页模板数
+  leftOffset: -1, // 对齐偏移
+  topOffset: -1, // 对齐偏移
+  onProgress: (cur, total) => { 
+    // 导出进度100%的时候关闭等待
+    if (cur === total) {
+      this.loading = false
+    }
+    console.log('toPdf 进度', Math.floor((cur/total)*100))
+  }
+})
 
-// 方式 2: 插件导出 (toPdf2) - 推荐
-// 支持更多选项，如 isDownload, type (blob/url/...)
-  tpl.toPdf2(this.printDataVar, '文件名', {
-    paperWidth: 210, 
-    paperHeight: 297, 
-    scale: 2, 
-    perPage: 6, 
-    leftOffset:-1, 
-    topOffset:-1, 
-    onProgress: (cur: number, total: number) => { 
-      console.log('toPdf 进度', Math.floor((cur/total)*100))
-      if (cur === total) {
-        // 导出完成
-      }
+// 模式2:普通模板，导出预览全部页：
+tpl.toPdf(this.printDataVar, '打印预览pdf', {
+  onProgress: (cur, total) => { 
+    // 导出进度100%的时候关闭等待
+    if (cur === total) {
+      this.loading = false
     }
-  })
+  }
+});
 
 // 导出图片（内置示例参数） 
-// 方式 1: 原生导出 (toImage)
-  tpl.toImage({ name: '示例' }, { 
-    isDownload: true, // 不自动下载
-    name: "图片名称",
-    limit: 1, // 默认 10  多少页为一个 图片文件, 太多 图片文件就很长
-    type: "image/jpeg", // 默认 image/jpeg   --> canvas.toDataURL(type, quality)
-    pixelRatio: 2, // 图片像素比  2: 提高清晰度 默认 window.devicePixelRatio.
-    quality: 0.8, // 默认 0.92  图片质量 0-1
-    toType: "url", // 默认 url   支持: url、blob
-    onProgress: (cur, total) => {
-      const percent = Math.floor((cur / total) * 100);
-      console.log("toImage 进度", percent);
-      if (cur === total) {
-        // 导出完成
-      }
-    },
-   })
-
-// 方式 2: 插件导出 (toImage2) - 推荐
-// 支持跨域图片(useCORS), 更多格式控制
-  tpl.toImage2(this.printDataVar, {
-    isDownload: true,
-    name: '图片名称',
-    type: 'image/jpeg',
-    useCORS: true, // 开启跨域支持
-    onProgress: (cur, total) => { ... }
-  })
+  // 导出为多张图片，每张合成 6 页，自动下载 JPEG     
+tpl.toImage(this.printDataVar, { 
+  isDownload: true, 
+  name: '图片名称', 
+  limit: 0, 
+  type: 'image/jpeg', 
+  pixelRatio: 2, 
+  quality: 0.8, 
+  toType: 'url',
+  onProgress: (cur, total) => {
+    // 导出进度100%的时候关闭等待
+    if (cur === total) {
+      this.loading = false;
+    }
+  } 
+})
 
+//按 A4 纸张排版导出（把小模板排到 A4）：
+tpl.toImage(this.printDataVar, {
+  paperWidth: 210,
+  paperHeight: 297,
+  limit: 6,
+  isDownload: true,
+  name: 'A4排版',
+  type: 'image/jpeg',
+  pixelRatio: 2,
+  onProgress: (cur, total) => {
+    console.log('toImage 进度', Math.floor((cur/total)*100))
+    // 导出进度100%的时候关闭等待
+    if (cur === total) {
+      this.loading = false
+    }
+  }
+})
 ```
 
 水印与授权行为说明：设计态与运行态分离。设计态不自动显示默认水印（由面板设置项决定）；运行态按授权和面板内容合并控制。
@@ -584,9 +585,7 @@ import {
   getHtml,
   printBrowser,
   exportPdf,
-  exportPdf2, // 插件导出
   exportImage,
-  exportImage2, // 插件导出
   getPrinterList,
   refreshPrinterList,
   getAddress,
@@ -631,17 +630,8 @@ const preview = async () => {
 printBrowser(tpl, printData)
 
 // 4) 导出 PDF
-// 插件方法 (推荐)
-exportPdf(tpl, printData, '打印预览pdf', {
-  isDownload: true, // 不自动下载
-  type: "blob", // 默认 blob  支持: blob、bloburl、pdfobjectnewwindow、dataurl  --> jspdf.output(type)
-  onProgress: (cur, total) => {
-    const percent = Math.floor((cur / total) * 100);
-    console.log("toPdf 进度", percent);
-  },
-})
 // 原生方法
-exportPdf2(tpl, printData, '打印预览pdf', {
+exportPdf(tpl, printData, '打印预览pdf', {
     paperWidth: 210, 
     paperHeight: 297, 
     scale: 2, 
@@ -653,23 +643,8 @@ exportPdf2(tpl, printData, '打印预览pdf', {
     }
 })
 
-// 5) 导出图片
-// 插件方法 (推荐)
-await exportImage(tpl, printData, {
-  isDownload: true, // 不自动下载
-  name: "图片名称",
-  limit: 1, // 默认 10  多少页为一个 图片文件, 太多 图片文件就很长
-  type: "image/jpeg", // 默认 image/jpeg   --> canvas.toDataURL(type, quality)
-  pixelRatio: 2, // 图片像素比  2: 提高清晰度 默认 window.devicePixelRatio.
-  quality: 0.8, // 默认 0.92  图片质量 0-1
-  toType: "url", // 默认 url   支持: url、blob
-  onProgress: (cur, total) => {
-    const percent = Math.floor((cur / total) * 100);
-    console.log("toImage 进度", percent);
-  },
-})
 // 原生方法
-await exportImage2(tpl, printData, {
+await exportImage(tpl, printData, {
    isDownload: true, 
   name: '图片名称', 
   limit: 1, 
@@ -733,80 +708,133 @@ const { pdfPath, imgPath } = await clientGenerate(tpl, printData, {
 disconnect()
 ```
 
-### 导出 PDF 两种模式
+### 导出 PDF（toPdf / exportPdf）
 
-- 普通导出（按模板自身纸张与分页设置）：
+> `exportPdf(tpl, data, filename, options)` 本质调用的是模板实例的 `tpl.toPdf(data, filename, options)`；两者参数一致。
+
+#### 模式 A：普通导出（按模板自身纸张与分页）
+
+- 特点：不传纸张宽高，导出结果与预览分页一致（每个 `.hiprint-printPaper` 一页）。
+- 适用：报告类、A4/A5 正常分页模板。
 
 ```js
-// 不传纸张尺寸，使用模板的面板尺寸与分页配置
+// 不传 paperWidth/paperHeight，使用模板的面板尺寸与分页配置
 exportPdf(tpl, printData, '打印预览pdf', {
-  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur/total)*100))
+  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur / total) * 100))
 })
 ```
 
-- A4 排版导出（把小模板排到指定纸张）：
+#### 模式 B：排版导出（把小模板拼到大纸张，例如 A4）
+
+- 特点：传入 `paperWidth/paperHeight`（mm）后，会进入“平铺排版导出”。
+- 适用：小标签、小票、多订单合并到一张纸导出。
 
 ```js
-// 传入纸张尺寸与排版参数，将多个模板排到一张 A4
+// 传入纸张尺寸与排版参数，将多个“标签模板”平铺到一张 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))
+  perPage: 6,           // 每页放 6 个（不够的到下一页）
+  leftOffset: -1,       // -1 表示水平居中；>=0 表示左边距 mm
+  topOffset: -1,        // -1 表示垂直居中；>=0 表示上边距 mm
+  scale: 2,             // 清晰度/性能权衡（也可用 pixelRatio）
+  onProgress: (cur, total) => console.log('toPdf 进度', Math.floor((cur / total) * 100))
 })
 ```
 
-### 导出图片 两种模式
+#### 排版规则（重点：perPage=0/不传的行为）
+
+- 传入了纸张宽高（`paperWidth/paperHeight` 或 `usePaperType: true`）时：
+  - `perPage > 0`：强制“每页 N 个”，例如 `perPage: 6` 就会 6 个一页。
+  - `perPage = 0` 或不传 `perPage`：自动计算“一页能放几个放几个”（由纸张尺寸 + 标签尺寸 + 行列间距决定）。
+- 没有传纸张宽高时：
+  - 默认导出与预览一致（通常“一个模板一页”）。
+  - `perPage` 在该模式下不生效（因为不做平铺排版）。
+
+---
+
+### 导出图片（toImage / exportImage）
 
-- 普通导出（按模板自身纸张与分页设置）：
+> `exportImage(tpl, data, options)` 本质调用的是模板实例的 `tpl.toImage(data, options)`；两者参数一致。
+
+#### 模式 A：普通导出（按模板分页导出图片）
 
 ```js
-// 不传纸张尺寸，按模板分页导出图片
+// 不传 paperWidth/paperHeight：按模板分页导出
+// splitPages: true 表示“每页一张图片”（推荐：避免长图占用太大内存）
 await exportImage(tpl, printData, {
   isDownload: true,
   name: '图片',
-  limit: 1,              // 多少页合成一张图片；0 或不传则导出整图
-  type: 'image/jpeg',    // 或 'image/png'
-  pixelRatio: 2,         // 像素比例（清晰度）
+  splitPages: true,
+  type: 'image/png',     // 含二维码/条码建议 png；纯文字/照片可 jpeg
+  pixelRatio: 2,
   quality: 0.8,          // 仅 JPEG 有效（0-1）
-  toType: 'url',         // 不下载时返回类型：'url' 或 'blob'
-  onProgress: (cur, total) => console.log('toImage 进度', Math.floor((cur/total)*100))
+  toType: 'blob',        // 推荐 blob（避免大 dataURL 阻塞）
+  onProgress: (cur, total) => console.log('toImage 进度', Math.floor((cur / total) * 100))
+})
+```
+
+##### 合成长图（可选）
+
+```js
+// limit: N 表示每 N 页合成一张“长图”；limit<=0 表示全部页合成一张（可能很大，不推荐）
+await exportImage(tpl, printData, {
+  isDownload: true,
+  name: '长图',
+  limit: 6,
+  type: 'image/jpeg',
+  pixelRatio: 2,
+  quality: 0.85
 })
 ```
 
-- A4 排版导出（把小模板排到指定纸张）：
+#### 模式 B：排版导出（把小模板拼到大纸张，例如 A4）
 
 ```js
-// 传入纸张尺寸以 A4 方式排版导出
+// 传入纸张尺寸后，图片导出也会进入“平铺排版导出”
+// 注意：在排版模式下 limit 的语义等同于 perPage（每张纸放几个标签）
 await exportImage(tpl, printData, {
   paperWidth: 210,       // mm
   paperHeight: 297,      // mm
-  limit: 6,              // 每张合成 6 页
+  limit: 6,              // 每张“纸”放 6 个（不够的到下一张）
   isDownload: true,
   name: 'A4排版',
-  type: 'image/jpeg',
-  pixelRatio: 2,
-  quality: 0.8
+  splitPages: true,      // 每张纸输出一张图片（文件名自动追加 -1/-2/...）
+  type: 'image/png',
+  pixelRatio: 2
 })
 ```
 
+#### 排版规则（重点：limit=0/不传的行为）
+
+- 传入了纸张宽高（`paperWidth/paperHeight`）时：
+  - `limit > 0`：强制“每张纸 N 个”（等同于 PDF 的 `perPage`）。
+  - `limit = 0` 或不传 `limit`：自动计算“一张纸能放几个放几个”。
+- 没有传纸张宽高时：
+  - `splitPages: true`：每页一张图（推荐）。
+  - `splitPages: false` 且 `limit > 0`：每 N 页合成长图。
+  - `splitPages: false` 且 `limit <= 0`：所有页合成一张超长图（不推荐）。
+
+---
+
 ### 参数说明（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` 计算百分比
+- `paperWidth`、`paperHeight`：纸张尺寸（mm）；传入后启用“排版导出”（小模板拼到大纸张）。
+- `usePaperType`：PDF/图片可用；为 `true` 时按模板的 `paperType`（如 A4）设置页面尺寸。
+- `scale` / `pixelRatio`：渲染缩放；`pixelRatio` 优先级高于 `scale`。值越大越清晰，但越耗时/耗内存。
+- `perPage`：PDF 排版模式每页模板数量；`0/不传` 表示自动填充。
+- `limit`：图片普通模式下用于“每 N 页合成长图”；图片排版模式下等同于“每张纸 N 个”；`0/不传` 表示自动填充（排版模式）或全量合成（普通模式，谨慎）。
+- `splitPages`：图片每页/每张纸输出一张（推荐）。
+- `type`：图片格式；`'image/jpeg'` 或 `'image/png'`（二维码/条码建议 png）。
+- `quality`：图片质量（0-1，仅 JPEG 有效）。
+- `toType`：返回类型（不下载时）；`'url'` 或 `'blob'`。
+- `isDownload`：是否自动触发下载。
+- `name`：文件名（图片会自动追加页码后缀）。
+- `leftOffset`、`topOffset`：排版对齐偏移（mm）；`-1` 表示居中，`>=0` 表示边距。
+- `onProgress(cur, total)`：导出进度回调；以 `cur/total` 计算百分比。
+- `forcePng`（PDF）：强制使用 PNG 写入 PDF（条码/二维码建议开启）。
+- `maxCanvasPixels`：单页最大画布像素上限；导出卡顿/崩溃时可调小（例如 `2e7`）。
+- `debugPerf`：输出每页渲染耗时到控制台，便于定位慢点。
 
 ### 导入说明（含描述）
 
@@ -914,16 +942,16 @@ No domain restrictions, available offline. Provides one-on-one technical support
 Search `vg-print` on npm.
 Contact me: QQ 984239686 or use the WeChat group on the homepage to solve problems.
 
-# Silent Printing Client Tool Installer
+## Silent Printing Client Tool Installer
 
 ![Silent Printing Client Tool](https://gitee.com/gao111/electron-vg-print/raw/master/electron-hiprint.png)
 
 More info and download:
-```
+```text
 https://gitee.com/gao111/electron-vg-print
 ```
 Client tool download:
-```
+```text
 https://download.csdn.net/download/github_38400706/92538739
 ```
 
@@ -934,7 +962,6 @@ https://download.csdn.net/download/github_38400706/92538739
 - Configure `hiwebSocket` `host`, `token` and auto-connection via props
 - Exposes instance methods: preview, print, export, connection control, etc., for external calls
 - Integrates and exports `hiprint` for advanced customization at the template object level
-- Built-in `@sv-print/plugin-api-pdf3` and `@sv-print/plugin-api-image` plugins for more powerful export functions
 
 ## Installation
 
@@ -1288,7 +1315,106 @@ exportPdf(tpl, printData, 'filename')
 
 ### Export PDF / Image
 
-Support normal export and A4 layout export.
+`exportPdf` / `exportImage` are lightweight wrappers around the template instance methods:
+
+- `exportPdf(tpl, data, filename, options)` → `tpl.toPdf(data, filename, options)`
+- `exportImage(tpl, data, options)` → `tpl.toImage(data, options)`
+
+#### Export PDF
+
+**Mode A: Normal export (follow template paging)**
+
+```js
+// No paperWidth/paperHeight: export pages exactly like preview pagination
+exportPdf(tpl, printData, 'report', {
+  onProgress: (cur, total) => console.log('toPdf', Math.floor((cur / total) * 100))
+})
+```
+
+**Mode B: Layout export (tile small labels into a big paper, e.g. A4)**
+
+```js
+exportPdf(tpl, printData, 'labels', {
+  paperWidth: 210,     // mm
+  paperHeight: 297,    // mm
+  perPage: 6,          // put 6 labels per sheet (rest goes to next sheet)
+  leftOffset: -1,      // -1: center; >=0: left margin (mm)
+  topOffset: -1,       // -1: center; >=0: top margin (mm)
+  scale: 2,            // clarity vs performance (pixelRatio also supported)
+  onProgress: (cur, total) => console.log('toPdf', Math.floor((cur / total) * 100))
+})
+```
+
+**Layout rules**
+
+- With `paperWidth/paperHeight` (or `usePaperType: true`):
+  - `perPage > 0`: fixed “N per sheet”
+  - `perPage = 0` or omitted: auto-fill “as many as can fit per sheet”
+- Without paper size:
+  - Export follows template pagination; `perPage` does not apply in this mode.
+
+#### Export Image
+
+**Mode A: Normal export (follow template paging)**
+
+```js
+// Recommended: one image per page (avoid very long images)
+await exportImage(tpl, printData, {
+  isDownload: true,
+  name: 'page',
+  splitPages: true,
+  type: 'image/png',   // QR/barcode recommended
+  pixelRatio: 2,
+  toType: 'blob'
+})
+```
+
+**Optional: merge into long images**
+
+```js
+// limit: N pages per output image; limit<=0 merges all pages into one (can be huge)
+await exportImage(tpl, printData, {
+  isDownload: true,
+  name: 'merged',
+  limit: 6,
+  type: 'image/jpeg',
+  pixelRatio: 2,
+  quality: 0.85
+})
+```
+
+**Mode B: Layout export (tile small labels into a big paper, e.g. A4)**
+
+```js
+// In layout mode, `limit` works like “labels per sheet”
+await exportImage(tpl, printData, {
+  paperWidth: 210,
+  paperHeight: 297,
+  limit: 6,
+  isDownload: true,
+  name: 'A4-layout',
+  splitPages: true,
+  type: 'image/png',
+  pixelRatio: 2
+})
+```
+
+**Layout rules**
+
+- With `paperWidth/paperHeight`:
+  - `limit > 0`: fixed “N per sheet”
+  - `limit = 0` or omitted: auto-fill “as many as can fit per sheet”
+- Without paper size:
+  - `splitPages: true`: one image per page (recommended)
+  - `splitPages: false` + `limit > 0`: merge N pages per long image
+  - `splitPages: false` + `limit <= 0`: merge all pages into one long image (not recommended)
+
+#### Common options
+
+- `pixelRatio` / `scale`: render scale (higher = clearer but slower)
+- `forcePng` (PDF): force PNG for QR/barcode
+- `maxCanvasPixels`: cap per-page canvas pixels to reduce freezes
+- `debugPerf`: log per-page render time to console
 
 ### Notes