c-htmlpdf/CHANGELOG.md

A tool script for converting HTML elements to PDF with TypeScript support, modified based on k-htmlpdf

# 更新日志

## [1.4.1] - 2025-01-24

### 🚀 重大功能更新 - 对象配置支持 + 样式处理优化

#### 🔧 重要修复 - 样式处理策略优化
- **🎯 精准样式控制**: 只修改 `overflow` 相关属性，不再影响元素的 `width`、`height`、`maxWidth`、`maxHeight`
- **📐 保持布局稳定**: 避免因修改尺寸属性导致的布局变化和意外的样式副作用
- **⚡ 更好的兼容性**: 减少与现有 CSS 样式的冲突，提高渲染准确性

#### ✨ 新增功能
- **🆕 对象配置方式**: 支持通过配置对象传入参数，提高代码可读性和维护性
- **📝 PdfLoaderOptions 接口**: 新增完整的 TypeScript 配置接口定义
- **🔄 构造函数重载**: 支持两种调用方式，完全向后兼容

#### 📈 使用体验提升
- **✅ 参数清晰化**: 不再需要记住参数顺序，通过对象属性名明确参数含义
- **🎯 按需配置**: 只需指定需要的参数，其他参数自动使用默认值
- **🛡️ 类型安全**: TypeScript 提供完整的类型检查和智能提示

#### 使用示例
```javascript
// 🆕 推荐方式：对象配置
const pdf = new PdfLoader(element, {
  pdfFileName: '我的文档',
  orientation: 'landscape',
  processChildScrollable: true
});

// ✅ 传统方式：仍然支持
const pdf = new PdfLoader(element, '我的文档', 595, 842, 'l');
```

#### 📚 文档更新
- 完全重写使用文档，突出对象配置方式
- 添加配置方式对比示例
- 更新所有使用示例为推荐的对象配置方式
- 增强 TypeScript 类型定义文档

**向后兼容**: 现有代码无需修改，传统参数方式继续完全支持

## [1.3.1] - 2025-01-24

### 🐛 重要修复 - Promise 处理优化
- **修复 `getPDF` 方法**: 正确返回 Promise 而不是接受 resolve/reject 参数
- **改进错误处理**: 为 `genPDf` 方法添加完整的 try-catch 错误处理
- **修复 `outPutPdfFn` 调用**: 正确处理 `getPDF` 返回的 Promise
- **增强滚动元素处理**: 为滚动元素查找和处理添加错误捕获
- **同步错误处理**: 为 setTimeout 内部的同步代码添加 try-catch

### 📚 文档更新
- 更新 TypeScript 声明文件中的 `@throws` 注释
- 改进 Promise 相关方法的文档说明
- 添加错误处理的使用示例

### 🔧 技术改进
- 所有异步方法现在都有完整的错误恢复机制
- 确保滚动元素状态在任何情况下都能正确恢复
- 改进错误信息的可读性和调试性

**这是一个重要的稳定性更新，强烈建议所有用户升级！**

## [1.3.0] - 2024-12-XX

### 重大改进
- 🚀 **递归子元素滚动处理**: 现在可以自动检测并处理所有子元素的滚动状态
- 🔍 **智能滚动检测**: 自动识别具有 `overflow: auto/scroll` 且内容溢出的元素
- 🎛️ **可配置的处理选项**: 新增 `processChildScrollable` 参数控制是否处理子元素滚动
- 🛡️ **完善的状态恢复**: 支持多层嵌套滚动元素的状态保存和恢复

### 新增功能
- ✨ **深度递归扫描**: 遍历整个 DOM 树，发现所有可滚动容器
- 📏 **精确尺寸控制**: 处理 `max-width`、`max-height` 等限制性样式
- 🔄 **批量状态管理**: 统一管理所有滚动元素的原始状态

### 使用场景
- 父容器不滚动，子元素有滚动条的复杂布局
- 多层嵌套的滚动容器
- 表格、列表等数据展示组件
- 侧边栏、内容区域等分区滚动

### 示例
```javascript
// 自动处理所有子元素滚动（默认行为）
const pdf = new PdfLoader(container, 'file', 595, 842, 'p', 'itemClass', 'break_page', true);

// 禁用子元素滚动处理（仅处理根元素）
const pdf = new PdfLoader(container, 'file', 595, 842, 'p', 'itemClass', 'break_page', false);
```

## [1.2.0] - 2024-12-XX

### 新增功能
- ✨ **支持可滚动元素完整渲染**: 现在可以正确渲染有滚动条的容器的完整内容
- 🔧 **智能样式处理**: 自动临时调整元素的 overflow 样式以确保完整内容可见
- 🛡️ **错误恢复机制**: 在生成过程中发生错误时自动恢复原始样式和滚动状态

### 改进
- 📈 **更高的渲染质量**: 优化了 html2canvas 配置参数
- 🎯 **更精确的尺寸控制**: 明确指定渲染区域的宽度和高度
- ⚡ **更好的性能**: 添加样式变更等待时间，确保渲染的准确性

### 修复
- 🐛 修复了可滚动容器内容被截断的问题
- 🐛 修复了滚动元素位置偏移的问题
- 🐛 改进了错误处理，确保样式状态正确恢复

### 使用说明

对于有滚动条的元素，新版本会：

1. **保存原始状态**: 记录元素的滚动位置和样式
2. **临时调整样式**: 设置 `overflow: visible` 使完整内容可见
3. **完整渲染**: 捕获包括滚动区域在内的所有内容
4. **恢复状态**: 完成后恢复原始样式和滚动位置

```javascript
// 示例：处理可滚动的表格容器
const scrollableTable = document.querySelector('#scrollable-table');
const pdf = new PdfLoader(scrollableTable, '完整表格数据');

// 现在可以正确渲染滚动区域的所有内容
await pdf.outPutPdfFn('完整数据表格');
```

## [1.1.0] - 2024-12-XX

### 新增功能
- 🎯 **完整的 TypeScript 支持**: 添加了完整的类型声明文件
- 📚 **TypeScript 使用文档**: 提供详细的 TypeScript 使用指南
- 🏷️ **类型安全**: 所有方法和属性都有完整的类型定义

### 改进
- 📦 **更好的包配置**: 添加了 `types` 字段指向声明文件
- 🔖 **更丰富的关键词**: 添加了 `typescript` 和 `types` 关键词
- 📝 **完善的文档**: 更新了使用说明和示例

## [1.0.0] - 2024-04-XX

### 初始版本
- 🎉 基于 k-htmlpdf 的改进版本
- 📄 HTML 到 PDF 转换功能
- 🔄 分页处理和防截断机制
- 📏 自定义分页符支持