@jcyao/print-sdk 1.0.0 → 1.0.1

package/README.md

@@ -5,6 +5,14 @@
 
 通用打印 SDK - 客户端打印解决方案
 
+**当前版本**: v1.0.1
+
+## 🆕 v1.0.1 新增功能
+
+- ⭐ **页码功能**：支持6种位置、3种格式、自定义样式（pageConfig.pageNumber）
+- ⭐ **批量打印预览**：支持多份文档一次性预览和打印
+- ⭐ **PageNumberRenderer**：新增页码渲染器插件
+
 ## ✨ 特性
 
 - 🎨 **可视化模板设计** - 拖拽式设计打印模板
@@ -24,13 +32,13 @@ npm install @jcyao/print-sdk
 ## 🚀 快速开始
 
 ```typescript
-import { init, print } from '@jcyao/print-sdk';
+import { createPrintSDK } from '@jcyao/print-sdk';
 
-// 初始化 SDK（全局执行一次）
-init();
+// 创建 SDK 实例（无需配置）
+const sdk = createPrintSDK();
 
 // 打印
-print({
+sdk.print({
   template: {
     pageConfig: {
       size: 'A4',
@@ -71,14 +79,6 @@ print({
 
 ## 📖 API 文档
 
-### `init()`
-
-初始化打印 SDK，全局执行一次。
-
-```typescript
-init();
-```
-
 ### `print(options: PrintOptions)`
 
 执行打印操作。
@@ -92,14 +92,31 @@ interface PrintOptions {
 }
 ```
 
-### `preview(options: PrintOptions): string`
+### `sdk.generateHTML(template, data)`
 
-生成预览 HTML。
+生成预览 HTML（不执行打印）。
 
 ```typescript
-const html = preview({
-  template: myTemplate,
-  data: myData
+const html = await sdk.generateHTML(myTemplate, myData);
+console.log(html);  // 完整的 HTML 字符串
+```
+
+### `sdk.printMultiple(template, dataList, options)`
+
+批量打印（同模板多数据）。
+
+```typescript
+const dataList = [
+  { orderNo: 'ORDER001', ... },
+  { orderNo: 'ORDER002', ... },
+  { orderNo: 'ORDER003', ... },
+];
+
+await sdk.printMultiple(myTemplate, dataList, {
+  preview: true,  // 预览所有
+  onProgress: (progress) => {
+    console.log(`进度: ${progress.completed}/${progress.total}`);
+  }
 });
 ```
 
@@ -111,8 +128,7 @@ const html = preview({
 - **二维码组件** - 自动生成二维码
 - **条形码组件** - 多种条形码格式
 - **线条组件** - 实线/虚线装饰
-- **矩形组件** - 边框装饰
-- **页码组件** - 自动分页页码
+- **矩形组件** - 边框装饰、背景色块
 
 ## 🔄 数据管道
 
@@ -184,19 +200,173 @@ const html = preview({
 }
 ```
 
+## 🔢 页码功能配置 ⭐ **v1.0.1 新增**
+
+页码功能通过页面配置实现，而非作为组件添加：
+
+### 基础配置
+
+```typescript
+{
+  pageConfig: {
+    size: 'A4',
+    orientation: 'portrait',
+    marginMm: { top: 10, right: 10, bottom: 10, left: 10 },
+    
+    // 页码配置
+    pageNumber: {
+      enabled: true,
+      position: 'bottom-center',  // 6种位置
+      format: 'slash',            // 3种格式
+      offsetX: 0,                 // 横向偏移 (mm)
+      offsetY: 0,                 // 纵向偏移 (mm)
+      prefix: '',                 // 前缀
+      suffix: '',                 // 后缀
+      style: {
+        fontSize: 12,
+        color: '#666',
+        fontWeight: 'normal'
+      }
+    }
+  },
+  components: [...]
+}
+```
+
+### 位置选项 (position)
+
+- `top-left` - 左上角
+- `top-center` - 上中
+- `top-right` - 右上角
+- `bottom-left` - 左下角
+- `bottom-center` - 下中 (默认)
+- `bottom-right` - 右下角
+
+### 格式选项 (format)
+
+1. **`simple`** - 简单格式
+   ```
+   显示：1  2  3
+   ```
+
+2. **`slash`** - 斜线格式 (默认)
+   ```
+   显示：1/3  2/3  3/3
+   ```
+
+3. **`text`** - 文字格式
+   ```
+   显示：第1页 共3页  第2页 共3页
+   ```
+
+### 完整示例
+
+```typescript
+const template = {
+  pageConfig: {
+    size: 'A4',
+    orientation: 'portrait',
+    marginMm: { top: 10, right: 10, bottom: 10, left: 10 },
+    pageNumber: {
+      enabled: true,
+      position: 'bottom-right',
+      format: 'text',
+      offsetX: -5,              // 向左偏移 5mm
+      offsetY: -3,              // 向上偏移 3mm
+      prefix: '页码：',
+      suffix: '',
+      style: {
+        fontSize: 10,
+        color: '#999',
+        fontWeight: 'bold'
+      }
+    }
+  },
+  components: [...]
+};
+
+await sdk.print({ template, data });
+// 打印输出：右下角显示 "页码：第1页 共3页"
+```
+
 ## 🔧 类型定义
 
 完整的 TypeScript 类型定义：
 
 ```typescript
 import type {
-  Template,
+  PrintTemplate,
   ComponentNode,
   TableColumn,
   PipeConfig
 } from '@jcyao/print-sdk';
 ```
 
+## 💻 使用示例
+
+### 示例 1：基本打印
+
+```typescript
+import { createPrintSDK } from '@jcyao/print-sdk';
+
+const sdk = createPrintSDK();
+
+// 准备模板和数据
+const template = {
+  pageConfig: {
+    size: 'A4',
+    orientation: 'portrait',
+    marginMm: { top: 10, right: 10, bottom: 10, left: 10 }
+  },
+  components: [
+    {
+      id: 'text-1',
+      type: 'text',
+      layout: { xMm: 20, yMm: 20, widthMm: 170, heightMm: 10 },
+      binding: { path: 'orderNo' },
+      props: { label: '订单号：' }
+    }
+  ]
+};
+
+const data = { orderNo: 'SR202401', customerName: '张三' };
+
+// 直接打印
+await sdk.printDirect(template, data);
+```
+
+### 示例 2：预览后打印
+
+```typescript
+import { createPrintSDK } from '@jcyao/print-sdk';
+
+const sdk = createPrintSDK();
+
+// 预览后打印
+await sdk.printWithPreview(template, data);
+```
+
+### 示例 3：批量打印
+
+```typescript
+import { createPrintSDK } from '@jcyao/print-sdk';
+
+const sdk = createPrintSDK();
+
+const orders = [
+  { orderNo: 'ORDER001', amount: 1000 },
+  { orderNo: 'ORDER002', amount: 2000 },
+  { orderNo: 'ORDER003', amount: 3000 },
+];
+
+await sdk.printMultiple(template, orders, {
+  preview: true,
+  onProgress: (progress) => {
+    console.log(`打印进度: ${progress.completed}/${progress.total}`);
+  }
+});
+```
+
 ## 📝 License
 
 MIT © joke_yao

package/dist/index.d.ts

@@ -9,3 +9,4 @@
  */
 export * from './sdk';
 export * from './pipes';
+export { waitForImagesLoaded, waitForPrintResourcesReady } from './utils/resourceLoader';

package/dist/index.esm.js

@@ -546,7 +546,7 @@ function buildPositionStyle(xMm, yMm, widthMm, heightMm, mmToPx = 3.78) {
         styles.width = `${widthMm * mmToPx}px`;
     }
     if (heightMm !== undefined) {
-        styles.minHeight = `${heightMm * mmToPx}px`;
+        styles.height = `${heightMm * mmToPx}px`;
     }
     return styles;
 }
@@ -820,13 +820,13 @@ class ImageRenderer {
         const imageSrc = value || (props === null || props === void 0 ? void 0 : props.src) || '';
         // 容器定位样式
         const positionStyles = buildPositionStyle(layout.xMm || 0, layout.yMm || 0, layout.widthMm || COMPONENT_DEFAULT_SIZE.IMAGE_WIDTH, layout.heightMm || COMPONENT_DEFAULT_SIZE.IMAGE_HEIGHT, context.mmToPx);
-        const containerStyles = Object.assign(Object.assign({}, positionStyles), { display: 'flex', alignItems: 'center', justifyContent: 'center', overflow: 'hidden' });
+        const containerStyles = Object.assign(Object.assign({}, positionStyles), { overflow: 'hidden' });
         const containerStyleStr = buildStyleString(containerStyles);
-        // 图片样式
+        // 图片样式：严格按模板尺寸渲染，避免自适应导致排版错乱
         const imageStyle = `
-      max-width: 100%;
-      max-height: 100%;
-      object-fit: ${(style === null || style === void 0 ? void 0 : style.objectFit) || 'contain'};
+      width: 100%;
+      height: 100%;
+      object-fit: ${(style === null || style === void 0 ? void 0 : style.objectFit) || 'fill'};
     `;
         if (imageSrc) {
             return `<div style="${containerStyleStr}"><img src="${imageSrc}" style="${imageStyle}" alt="" /></div>`;
@@ -1197,14 +1197,108 @@ class PrintEngine {
         // 使用 MIN_ROW_HEIGHT * ROW_HEIGHT_FACTOR 作为行高
         return TABLE_DEFAULT.MIN_ROW_HEIGHT * TABLE_DEFAULT.ROW_HEIGHT_FACTOR;
     }
+    /**
+     * 渲染页码（根据页面配置）
+     */
+    renderPageNumber(pageNumber, totalPages) {
+        var _a, _b, _c, _d;
+        const { page } = this.template;
+        const pageNumberConfig = page.pageNumber;
+        // 如果未启用页码或缺少页码信息，返回空
+        if (!(pageNumberConfig === null || pageNumberConfig === void 0 ? void 0 : pageNumberConfig.enabled) || pageNumber === undefined || totalPages === undefined) {
+            return '';
+        }
+        console.log(`[PrintEngine] 渲染页码: pageNumber=${pageNumber}, totalPages=${totalPages}`, pageNumberConfig);
+        // 格式化页码文本
+        const format = pageNumberConfig.format || 'slash';
+        const prefix = pageNumberConfig.prefix || '';
+        const suffix = pageNumberConfig.suffix || '';
+        const separator = pageNumberConfig.separator || '/';
+        let pageText = '';
+        if (format === 'simple') {
+            pageText = `${pageNumber}`;
+        }
+        else if (format === 'text') {
+            pageText = `第${pageNumber}页 共${totalPages}页`;
+        }
+        else {
+            pageText = `${pageNumber}${separator}${totalPages}`;
+        }
+        pageText = `${prefix}${pageText}${suffix}`;
+        // 计算位置
+        const { widthMm, heightMm } = this.getPageSize();
+        const { position, offsetX = 0, offsetY = 0, style = {} } = pageNumberConfig;
+        const fontSize = style.fontSize || 12;
+        const color = style.color || '#666';
+        const fontWeight = style.fontWeight || 'normal';
+        // 根据 position 计算 x, y 坐标
+        let xMm = 0;
+        let yMm = 0;
+        const pageNumberWidth = 20; // 页码宽度 mm
+        const pageNumberHeight = 6; // 页码高度 mm
+        const marginTop = ((_a = page.marginMm) === null || _a === void 0 ? void 0 : _a.top) || 0;
+        const marginRight = ((_b = page.marginMm) === null || _b === void 0 ? void 0 : _b.right) || 0;
+        const marginBottom = ((_c = page.marginMm) === null || _c === void 0 ? void 0 : _c.bottom) || 0;
+        const marginLeft = ((_d = page.marginMm) === null || _d === void 0 ? void 0 : _d.left) || 0;
+        switch (position) {
+            case 'top-left':
+                xMm = marginLeft;
+                yMm = marginTop;
+                break;
+            case 'top-center':
+                xMm = (widthMm - pageNumberWidth) / 2;
+                yMm = marginTop;
+                break;
+            case 'top-right':
+                xMm = widthMm - marginRight - pageNumberWidth;
+                yMm = marginTop;
+                break;
+            case 'bottom-left':
+                xMm = marginLeft;
+                yMm = heightMm - marginBottom - pageNumberHeight;
+                break;
+            case 'bottom-center':
+                xMm = (widthMm - pageNumberWidth) / 2;
+                yMm = heightMm - marginBottom - pageNumberHeight;
+                break;
+            case 'bottom-right':
+            default:
+                xMm = widthMm - marginRight - pageNumberWidth;
+                yMm = heightMm - marginBottom - pageNumberHeight;
+                break;
+        }
+        // 应用偏移
+        xMm += offsetX;
+        yMm += offsetY;
+        // 转换为 px
+        const xPx = xMm * this.mmToPx;
+        const yPx = yMm * this.mmToPx;
+        const widthPx = pageNumberWidth * this.mmToPx;
+        const heightPx = pageNumberHeight * this.mmToPx;
+        // 生成 HTML
+        const alignStyle = position.includes('left') ? 'left' : position.includes('right') ? 'right' : 'center';
+        const justifyContent = alignStyle === 'left' ? 'flex-start' : alignStyle === 'right' ? 'flex-end' : 'center';
+        return `<div style="position: absolute; left: ${xPx}px; top: ${yPx}px; width: ${widthPx}px; height: ${heightPx}px; font-size: ${fontSize}px; color: ${color}; font-weight: ${fontWeight}; display: flex; align-items: center; justify-content: ${justifyContent};">${this.escapeHtml(pageText)}</div>`;
+    }
+    /**
+     * HTML 转义
+     */
+    escapeHtml(text) {
+        return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#039;');
+    }
     /**
      * 渲染单个页面（直接渲染，不做智能布局）
+     * @param components 组件列表
+     * @param pageNumber 当前页码（可选）
+     * @param totalPages 总页数（可选）
      */
-    renderSinglePage(components) {
-        const componentsHTML = components.map((comp) => {
-            return this.renderComponent(comp);
-        }).join('');
-        return componentsHTML;
+    renderSinglePage(components, pageNumber, totalPages) {
+        console.log(`[PrintEngine] renderSinglePage: 页码=${pageNumber}, 总页数=${totalPages}, 组件数=${components.length}`);
+        // 渲染所有组件
+        const componentsHTML = components.map(comp => this.renderComponent(comp)).join('');
+        // 如果页面配置启用了页码，在固定位置渲染页码
+        const pageNumberHTML = this.renderPageNumber(pageNumber, totalPages);
+        return componentsHTML + pageNumberHTML;
     }
     /**
      * 虚拟分页：基于相对间距的流式布局
@@ -1437,10 +1531,12 @@ class PrintEngine {
         }
         // 标准页面模式：虚拟分页，生成多个独立的页面
         const pages = this.calculatePages(components);
+        const totalPages = pages.length;
         // 渲染每个页面
         const pagesHTML = pages.map((pageComponents, index) => {
-            const pageContent = this.renderSinglePage(pageComponents);
-            return `<div class="print-page" data-page="${index + 1}">${pageContent}</div>`;
+            const pageNumber = index + 1;
+            const pageContent = this.renderSinglePage(pageComponents, pageNumber, totalPages);
+            return `<div class="print-page" data-page="${pageNumber}">${pageContent}</div>`;
         }).join('');
         const styles = generatePrintPageStyles({
             pageWidthMm: widthMm,
@@ -1485,6 +1581,83 @@ function createPrintEngine(template, data) {
     };
 }
 
+/**
+ * 资源加载工具
+ * 用于等待图片、二维码、条形码等异步资源加载完成
+ */
+/**
+ * 等待文档中所有图片加载完成
+ * @param doc 文档对象（可以是 window.document 或 iframe.contentDocument）
+ * @param timeout 超时时间（毫秒），默认 10000ms
+ * @returns Promise<void>
+ */
+async function waitForImagesLoaded(doc, timeout = 10000) {
+    const images = Array.from(doc.querySelectorAll('img'));
+    if (images.length === 0) {
+        // 没有图片，直接返回
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        let loadedCount = 0;
+        let errorCount = 0;
+        const totalImages = images.length;
+        // 超时处理
+        const timeoutId = setTimeout(() => {
+            console.warn(`图片加载超时，已加载 ${loadedCount}/${totalImages}，失败 ${errorCount} 张`);
+            resolve(); // 超时也算完成，避免无限等待
+        }, timeout);
+        // 检查是否所有图片都已完成
+        const checkComplete = () => {
+            if (loadedCount + errorCount >= totalImages) {
+                clearTimeout(timeoutId);
+                if (errorCount > 0) {
+                    console.warn(`有 ${errorCount} 张图片加载失败`);
+                }
+                resolve();
+            }
+        };
+        // 为每个图片添加加载监听
+        images.forEach((img) => {
+            // 如果图片已经加载完成（cached）
+            if (img.complete) {
+                if (img.naturalHeight !== 0) {
+                    loadedCount++;
+                }
+                else {
+                    errorCount++;
+                }
+                checkComplete();
+            }
+            else {
+                // 监听 load 和 error 事件
+                img.addEventListener('load', () => {
+                    loadedCount++;
+                    checkComplete();
+                });
+                img.addEventListener('error', (e) => {
+                    errorCount++;
+                    console.error('图片加载失败:', img.src, e);
+                    checkComplete();
+                });
+            }
+        });
+        // 立即检查一次（可能所有图片都已缓存）
+        checkComplete();
+    });
+}
+/**
+ * 等待所有打印资源加载完成
+ * 包括：图片、二维码（已转base64）、条形码（已转base64）
+ * 注意：二维码和条形码在渲染时已同步生成为 base64，所以主要等待外部图片
+ * @param doc 文档对象
+ * @param timeout 超时时间（毫秒），默认 10000ms
+ */
+async function waitForPrintResourcesReady(doc, timeout = 10000) {
+    // 目前只需要等待图片加载
+    // 二维码和条形码在 QRCodeRenderer 和 BarcodeRenderer 中已同步生成为 base64
+    return waitForImagesLoaded(doc, timeout);
+}
+
 /**
  * 打印 SDK 核心类
  * 提供完整的打印功能封装
@@ -1512,6 +1685,8 @@ class PrintSDK {
             const html = engine.generatePrintHTML();
             printWindow.document.write(html);
             printWindow.document.close();
+            // 等待所有图片加载完成后再打印
+            await waitForImagesLoaded(printWindow.document);
             printWindow.print();
         }
         else {
@@ -1528,7 +1703,9 @@ class PrintSDK {
             }
             iframeDoc.write(html);
             iframeDoc.close();
-            // 二维码和条形码已同步生成为base64图片，无需等待，直接打印
+            // 等待所有图片加载完成后再打印
+            // 注意：二维码和条形码已同步生成为base64，主要等待外部图片资源
+            await waitForImagesLoaded(iframeDoc);
             (_b = iframe.contentWindow) === null || _b === void 0 ? void 0 : _b.print();
             // 打印完成后移除 iframe
             setTimeout(() => {
@@ -1631,7 +1808,8 @@ class PrintSDK {
             }
             printWindow.document.write(fullHTML);
             printWindow.document.close();
-            // 二维码和条形码已同步生成为base64图片，无需等待，直接打印
+            // 等待所有图片加载完成后再打印
+            await waitForImagesLoaded(printWindow.document);
             printWindow.print();
         }
         else {
@@ -1647,7 +1825,8 @@ class PrintSDK {
             }
             iframeDoc.write(fullHTML);
             iframeDoc.close();
-            // 二维码和条形码已同步生成为base64图片，无需等待，直接打印
+            // 等待所有图片加载完成后再打印
+            await waitForImagesLoaded(iframeDoc);
             (_b = iframe.contentWindow) === null || _b === void 0 ? void 0 : _b.print();
             // 打印完成后移除 iframe
             setTimeout(() => {
@@ -1664,5 +1843,5 @@ function createPrintSDK() {
     return new PrintSDK();
 }
 
-export { BARCODE_CONFIG, BarcodeRenderer, COMPONENT_DEFAULT_SIZE, CurrencyPipe, DatePipe, DefaultPipe, ImageRenderer, LineRenderer, LowercasePipe, MM_TO_PX, MoneyPipe, PrintEngine, PrintSDK, QRCODE_CONFIG, QRCodeRenderer, RectRenderer, STYLE_DEFAULT, SlicePipe, TABLE_DEFAULT, TABLE_STYLE_DEFAULT, TableRenderer, TextRenderer, UppercasePipe, createPrintEngine, createPrintSDK, executePipe, generateBatchPrintStyles, generatePrintHTML, generatePrintPageStyles, getAllPipes, getExecutor, getPageSizeFromConfig, registerExecutor };
+export { BARCODE_CONFIG, BarcodeRenderer, COMPONENT_DEFAULT_SIZE, CurrencyPipe, DatePipe, DefaultPipe, ImageRenderer, LineRenderer, LowercasePipe, MM_TO_PX, MoneyPipe, PrintEngine, PrintSDK, QRCODE_CONFIG, QRCodeRenderer, RectRenderer, STYLE_DEFAULT, SlicePipe, TABLE_DEFAULT, TABLE_STYLE_DEFAULT, TableRenderer, TextRenderer, UppercasePipe, createPrintEngine, createPrintSDK, executePipe, generateBatchPrintStyles, generatePrintHTML, generatePrintPageStyles, getAllPipes, getExecutor, getPageSizeFromConfig, registerExecutor, waitForImagesLoaded, waitForPrintResourcesReady };
 //# sourceMappingURL=index.esm.js.map