English
资源说明： wkhtmltopdf-crystal 是一个基于 Crystal 语言的库，它是对 libwkhtmltox 库的封装，目的是为了让 Crystal 开发者能够方便地利用这个强大的工具进行网页转 PDF 的操作。libwkhtmltox 是一个开源项目，它内含了 WebKit 渲染引擎，能够将 HTML、CSS 和 JavaScript 完整地转换为 PDF 或图像格式。
wkhtmltopdf-crystal 的核心功能是提供了一个 Crystal 的接口，使得开发者可以调用 libwkhtmltox 的各种功能，如：
1. **HTML 转换**：你可以提供一个 HTML 文件或 URL，通过 wkhtmltopdf-crystal 将其转换为高质量的 PDF 文档。这在生成报告、文档或者需要将网页内容保存为离线阅读的场景下非常有用。
2. **样式与布局处理**：由于基于 WebKit，wkhtmltopdf-crystal 可以正确处理 CSS 样式，包括浮动元素、定位、响应式设计等，确保 PDF 输出与浏览器显示一致。
3. **JavaScript 支持**：在转换过程中， wkhtmltopdf-crystal 支持执行页面上的 JavaScript，这意味着动态内容也能正确转换，如图表、地图和其他交互式元素。
4. **选项定制**： wkhtmltopdf-crystal 提供了一系列参数，允许开发者调整输出的 PDF，比如设置页面大小、边距、方向、分辨率、加载时间限制、头部和尾部信息等。
5. **错误处理与日志**：库还包含了错误处理机制，当转换过程中出现错误时，会抛出异常并提供相应的错误信息，便于调试。同时，可以通过配置日志级别来记录转换过程中的详细信息。
要开始使用 wkhtmltopdf-crystal，你需要先安装 libwkhtmltox 库，这通常涉及下载二进制包或者编译源代码。然后，你可以在 Crystal 项目中添加 wkhtmltopdf-crystal 作为依赖，并通过以下步骤进行使用：
1. **引入库**：在 Crystal 项目中，添加 wkhtmltopdf-crystal 到 `shard.yml` 文件的依赖项。
2. **安装依赖**：运行 `crystal deps` 来安装 wkhtmltopdf-crystal。
3. **编写代码**：创建一个 `WkHtmlToPdf` 对象，调用 `convert` 方法传递 HTML 输入和输出 PDF 路径。
4. **处理结果**：根据返回值判断转换是否成功，如有错误，可以查看错误信息进行调试。
下面是一个简单的示例代码片段，展示了如何使用 wkhtmltopdf-crystal 转换一个网页：
```crystal
require "wkhtmltopdf-crystal"
pdf = WkHtmlToPdf.new
result = pdf.convert("https://example.com", "output.pdf")
if result.success?
puts "PDF generated successfully."
else
puts "Error generating PDF: #{result.error}"
end
```
需要注意的是，wkhtmltopdf-crystal 的性能受到 libwkhtmltox 库的性能限制，如果需要处理大量转换任务，可能需要考虑并发执行或多进程处理以提高效率。此外，由于 wkhtmltopdf 使用的是旧版 WebKit，对于某些现代 Web 标准支持可能有限，如果遇到问题，可能需要查找替代方案或更新 libwkhtmltox 到最新版本。
wkhtmltopdf-crystal 是 Crystal 社区的一个宝贵资源，它为开发者提供了方便、高效地将网页内容转化为 PDF 的能力，极大地扩展了 Crystal 在文档生成和静态内容转换领域的应用。
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
