template-designer 0.5.0 → 0.5.2

package/README.md

@@ -262,7 +262,89 @@ const config = {
 
 ### 1、控件中的字段（FieldName）只选中一个值为字符串，如果选中多个则为字符串数组，使用时注意兼容
 
-### 2、当前模板中控件的旋转中心为控件的中心，每个组件的数据都包含x1，y1，为左上角旋转之后的实时坐标
+### 2、当前模板中控件的旋转中心为控件的中心，每个组件的数据都包含x1，y1，为左上角旋转之后的实时坐标，旋转角度为顺时针
+
+## 渲染导出工具：renderTemplateToPdfBase64
+
+提供一个独立工具，将“模板数据 + 打印数据”渲染为 PDF 或 PNG，并返回 base64 或 dataURL
+
+### 导入
+
+```js
+import { renderTemplateToPdfBase64 } from 'template-designer'
+```
+
+### 函数签名
+
+```ts
+async function renderTemplateToPdfBase64(
+  template: object,            // 模板数据（同设计器使用的数据结构）
+  printData: Record<string, any>, // 打印数据（key -> value）
+  options?: {
+    page?: { widthMm?: number; heightMm?: number; marginMm?: number } // （可选）默认打印宽高
+    returnType?: 'base64' | 'dataUrl' // （可选）默认 'base64'
+    format?: 'pdf' | 'png'            // （可选）默认 'pdf'；png 可保留透明背景
+    pdf?: {
+      orientation?: 'portrait' | 'landscape' // （可选）默认自动
+      transparent?: boolean                  // （可选）是否保留透明背景（仅对 pdf 内嵌图像生效）
+      quality?: number                       // （可选）0~1（jpeg质量，透明=false 时生效，默认 0.85）
+      scale?: number                         // （可选）html2canvas 放大倍数，建议 1.5~2.5
+      compress?: boolean                     // （可选）jsPDF 压缩，默认 true
+    }
+  }
+): Promise<string>
+```
+
+### 字段替换规则
+
+- 适用组件：text、barcode、qrcode。
+- FieldName 支持 string 或数组：
+  - string：从 `printData[key]` 取值
+  - array：从 `printData` 逐个取值，使用组件 `FieldConnector` 连接（默认空格）
+- 覆盖策略：导出前始终用打印数据覆盖组件测试值：
+  - text → 覆盖 `Text`（并拼接 `Title`）
+  - barcode → 覆盖 `BarcodeValue`
+  - qrcode → 覆盖 `QRCodeValue`
+
+### 基础用法（导出 PDF，返回 base64）
+
+```js
+const pdfBase64 = await renderTemplateToPdfBase64(template, printData, {
+  page: { widthMm: 103, heightMm: 40 },
+  returnType: 'base64',
+  pdf: {
+    orientation: 'landscape',
+    transparent: false, // 若不需要透明，可关闭以减小体积
+    quality: 0.8,       // 仅非透明时生效（jpeg质量）
+    scale: 2,           // 1.5~2.5 间调节清晰度与体积
+    compress: true
+  }
+})
+```
+
+### 在浏览器中预览与下载 PDF
+
+```js
+// 预览（推荐使用 blob URL，兼容性更好）
+const dataUrl = await renderTemplateToPdfBase64(template, printData, { returnType: 'baseUrl' })
+const base64 = dataUrl.split(',')[1]
+const blob = new Blob([Uint8Array.from(atob(base64), c => c.charCodeAt(0))], { type: 'application/pdf' })
+const blobUrl = URL.createObjectURL(blob)
+window.open(blobUrl)
+
+// 下载
+const a = document.createElement('a')
+a.href = blobUrl
+a.download = 'template.pdf'
+document.body.appendChild(a)
+a.click()
+document.body.removeChild(a)
+```
+
+### 体积优化建议
+
+- 不需要透明背景时，`transparent=false` + `quality≈0.8` + `scale≈2`，可显著减小体积仍保持清晰。
+- 需要极致清晰时提高 `scale`；若体积过大，适当降低 `quality`。
 
 ## 开发