@jcyao/print-sdk 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+所有版本的变更记录都列在这里，遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 规范。
+
+## [1.1.0] - 2026-04-15
+
+### 🎯 重大改进
+
+#### 表格分页精度革命性提升
+- **渲染后测量方案**：将表格真实渲染到隐藏 DOM 中，测量每行实际高度
+- **彻底解决长文本换行问题**：不再依赖估算行高，避免分页截断
+- **表头高度真实测量**：支持表头换行场景
+- **合计行高度真实测量**：避免合计行间距不一致
+
+#### 组件定位逻辑优化
+- **支持负 gap（组件重叠）**：完全保留设计时的相对位置关系
+- **表格跨页后精确定位**：后续组件定位到表格实际底部
+- **新页面组件间距处理**：正确处理与页面顶部的间距
+
+#### 表格渲染改进
+- **列宽均分方案**：按列数百分比均分，避免宽度溢出
+- **单元格垂直居中**：文字垂直居中对齐
+- **min-height 替代固定高度**：允许内容自然撑开
+
+### 🔧 工程改进
+
+- **iframe 生命周期优化**：使用 `afterprint` 事件 + 5秒兜底，确保可靠清理
+- **DOMParser 替代正则**：批量打印时更健壮地提取 body 内容
+- **Decimal.js 错误处理**：添加友好的"计算错误"提示
+- **表格宽度溢出检测**：`xMm` 越界时输出明确错误提示
+- **异步架构改造**：核心方法改为 `async/await`，支持渲染后测量
+
+### 🐛 问题修复
+
+| 问题 | 修复内容 |
+|------|----------|
+| 分页计算精度丢失 | 使用真实渲染高度代替估算高度 |
+| 表格高度计算不一致 | 渲染后测量 + min-height |
+| 组件间距为负数 | 保留设计意图，支持组件重叠 |
+| iframe 移除时机 | afterprint 事件 + 兜底定时器 |
+| 表格宽度溢出 | 添加 xMm 越界检测 |
+| 正则提取 body | 使用 DOMParser |
+| Decimal.js 错误 | 添加错误处理和友好提示 |
+
+### ⚠️ 已知限制
+
+- 页码宽高固定（20mm x 6mm），大字体时可能溢出
+- 连续纸模式高度为 Infinity（设计如此，适配连续纸打印）
+
+---
+
+## [1.0.1] - 2026-01-22
+
+### ✨ 新增功能
+
+- **页码功能**：支持6种位置、3种格式、自定义样式
+  - 位置：上左/上中/上右/下左/下中/下右
+  - 格式：simple、slash、text
+  - 支持偏移量、前后缀、样式自定义
+  
+- **批量打印预览**：支持多份文档一次性预览和打印
+  - 自动合并 HTML
+  - 显示文档分割线和序号
+  - 支持进度回调
+
+- **PageNumberRenderer**：新增页码渲染器插件
+
+### 🎨 体验优化
+
+- 组件库和数据资产支持双击快速添加
+- 组件库和数据资产支持拖拽精确定位
+- 智能计算画布中心位置
+
+### 🔧 架构优化
+
+- 页码功能从组件模式重构为页面配置模式
+- SDK 增加 PageNumberRenderer 支持
+
+---
+
+## [1.0.0] - 2026-01-20
+
+### 🎉 初始发布
+
+**核心功能**
+- 可视化模板设计器（拖拽 + 对齐 + 网格吸附）
+- 7种基础组件：文本、图片、表格、二维码、条形码、矩形、线条
+- Schema 字典管理 + Mock 数据管理
+- 数据绑定 + Pipes 格式化
+- SDK 打印引擎 + 表格分页渲染
+
+**技术特性**
+- 插件化架构（渲染器、管道）
+- TypeScript 完整类型定义
+- 客户端渲染，零服务端压力
+- 使用 decimal.js 保证数值精度
+
+---
+
+## 版本号说明
+
+遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/)：
+
+- **主版本号**：不兼容的 API 修改
+- **次版本号**：向下兼容的功能新增
+- **修订号**：向下兼容的问题修复

package/README.md

@@ -5,6 +5,22 @@
 
 通用打印 SDK - 客户端打印解决方案
 
+**当前版本**: v1.1.0
+
+## 🆕 v1.1.0 重大改进
+
+- ⭐ **表格分页精度大幅提升**：引入「渲染后测量」方案，彻底解决长文本换行导致的分页截断问题
+- ⭐ **组件定位优化**：支持负 gap（组件重叠），表格跨页后后续组件精确定位
+- ⭐ **表格渲染改进**：列宽均分、单元格垂直居中、使用 min-height 替代固定高度
+- 🔧 **错误处理增强**：iframe 使用 afterprint 事件、DOMParser 替代正则、Decimal.js 错误友好提示
+
+## 📋 历史版本
+
+### v1.0.1
+- 页码功能：支持6种位置、3种格式、自定义样式
+- 批量打印预览：支持多份文档一次性预览和打印
+- PageNumberRenderer：新增页码渲染器插件
+
 ## ✨ 特性
 
 - 🎨 **可视化模板设计** - 拖拽式设计打印模板
@@ -24,13 +40,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 +87,6 @@ print({
 
 ## 📖 API 文档
 
-### `init()`
-
-初始化打印 SDK，全局执行一次。
-
-```typescript
-init();
-```
-
 ### `print(options: PrintOptions)`
 
 执行打印操作。
@@ -92,14 +100,31 @@ interface PrintOptions {
 }
 ```
 
-### `preview(options: PrintOptions): string`
+### `sdk.generateHTML(template, data)`
+
+生成预览 HTML（不执行打印）。
+
+```typescript
+const html = await sdk.generateHTML(myTemplate, myData);
+console.log(html);  // 完整的 HTML 字符串
+```
+
+### `sdk.printMultiple(template, dataList, options)`
 
-生成预览 HTML。
+批量打印（同模板多数据）。
 
 ```typescript
-const html = preview({
-  template: myTemplate,
-  data: myData
+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 +136,7 @@ const html = preview({
 - **二维码组件** - 自动生成二维码
 - **条形码组件** - 多种条形码格式
 - **线条组件** - 实线/虚线装饰
-- **矩形组件** - 边框装饰
-- **页码组件** - 自动分页页码
+- **矩形组件** - 边框装饰、背景色块
 
 ## 🔄 数据管道
 
@@ -184,19 +208,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';