在Python中将HTML转换为PDF

Q: 我如何在Python中将HTML字符串转换为PDF？

实例化 ChromePdfRenderer ，然后调用 renderer.RenderHtmlAsPdf(html_string) 。该方法接受任何有效的HTML，包括内联CSS和JavaScript。用 pdf.SaveAs("output.pdf") 保存返回的 PdfDocument 。

Q: 如何安装 IronPDF for Python？

从终端运行 pip install ironpdf 。IronPDF for Python需要.NET 6.0 SDK或更高版本，在首次使用前必须单独安装。

Q: IronPDF是否可以在Python中将实时URL转换为PDF？

可以。使用 renderer.RenderUrlAsPdf("https://example.com") 。IronPDF使用Chromium引擎获取页面，等待JavaScript完成执行，然后从完全渲染的DOM生成PDF。

Q: 我如何将本地HTML文件转换为PDF？

调用 renderer.RenderHtmlFileAsPdf("path/to/file.html") 。IronPDF自动将样式表、图像、脚本等所有相对资产路径解析为相对于HTML文件目录的路径。

Q: 如何移除IronPDF生成的PDF上的水印？

在任何PDF操作之前，使用 License.LicenseKey = "YOUR-KEY" 设置一个有效的许可证密钥。如果没有密钥，IronPDF将添加适合开发但不适合生产使用的平铺水印。

Q: IronPDF为Python提供了哪些渲染选项？

在 renderer.RenderingOptions 上设置的属性控制纸张大小（ PaperSize ）、方向（ PaperOrientation ）、边距（ MarginTop 、 MarginLeft 等）、自定义尺寸（ CustomPaperWidth 、 CustomPaperHeight ）、JavaScript执行（ EnableJavaScript ）等等。

Q: 如何在Python的IronPDF中为PDF添加页码？

将 TextHeaderFooter 分配给 renderer.RenderingOptions.TextFooter ，并在文本属性之一如 RightText 或 CenterText 中包含占位符 {page} 或 {total-pages} 。

Q: 我能否为生成的PDF的每页添加品牌标志页眉？

可以。使用带 <img> 标签的HTML片段创建 HtmlHeaderFooter 。分配给 renderer.RenderingOptions.HtmlHeader 并设置 BaseUrl 以正确解析图像路径。

Q: IronPDF在Python中是否支持自定义纸张尺寸？

可以。将 renderer.RenderingOptions.PaperSize 设置为 PdfPaperSize.Custom ，然后分配 CustomPaperWidth 和 CustomPaperHeight 以毫米为单位定义任意页面尺寸。

Curtis Chau

已更新:2026年6月28日

Translated

View the article in English

IronPDF为Python开发者提供了一条从HTML标记到生产就绪PDF文件的直接路径——不需要中间设计工具，没有专有布局引擎，没有单独的渲染管道。库的ChromePdfRenderer类在底层使用基于Chromium的引擎，因此在Chrome中正确显示的任何HTML将准确地转换为PDF。本教程演示了每种受支持的转换方法——HTML字符串、本地HTML文件和实时URL——然后涵盖了允许您控制页面大小、边距、页眉、页脚等的渲染选项。

如果您需要C#或VB.NET的工作流程，将HTML转换为PDF的.NET应用程序也有相关教程。

快速入门：在Python中将HTML转为PDF

如何在 Python 中将 HTML 转换为 PDF

通过pip安装IronPDF for Python
使用from ironpdf import *导入库
实例化ChromePdfRenderer
调用RenderHtmlAsPdf、RenderUrlAsPdf或RenderHtmlFileAsPdf
使用pdf.SaveAs("output.pdf")保存结果

入门

如何安装Python上的IronPDF？

IronPDF通过pip分发，这是Python的标准包管理器。在终端中运行以下命令以安装最新版本：

 pip install ironpdf

要固定特定版本——在CI管道或容器化环境中很有用——附上版本号：

pip install ironpdf==2024.x.x

请注意IronPDF for Python建立在IronPDF .NET库之上，需使用.NET 6.0 SDK或更高版本。在运行任何IronPDF Python代码之前安装SDK。)]

IronPDF首次初始化时，会下载兼容的Chromium二进制文件。在新机器上下载稍需片刻，但每个环境仅发生一次。随后的运行启动速度快得多，因为二进制文件被本地缓存。

操作指南和代码示例

您如何在转换之前配置IronPDF？

在首次转换调用之前完成两项设置任务：设置许可证密钥和——可选地——配置日志文件位置。

导入包

每个使用IronPDF的Python文件都需要这一行导入。将其放在文件顶部：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/import.py

from ironpdf import *

PYTHON

所有IronPDF类——Logger，以及其他类——通过此通配符导入变得可用。

设置许可证密钥

没有许可证密钥，IronPDF会在每个生成的PDF上添加平铺水印。水印适合开发和测试，但生产部署需要有效密钥。

无许可证密钥生成的PDF包含平铺水印。访问许可页面以获取密钥。

在任何其他IronPDF调用之前设置密钥：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/set-license.py

from ironpdf import *

# Set the license key before any PDF operations
License.LicenseKey = "IRONPDF-MYLICENSE-KEY-1EF01"

PYTHON

开始免费试用以接收临时密钥，或购买许可证以供无限制的生产使用。

配置日志输出

IronPDF将诊断输出写入名为Default.log的文件中，该文件位于脚本的工作目录中。要将日志记录重定向到不同路径或捕获更多细节以进行调试，在第一次转换前设置Logger属性：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/configure-logging.py

from ironpdf import *

# Configure logging before running any conversions
Logger.EnableDebugging = True
Logger.LogFilePath = "ironpdf-debug.log"
Logger.LoggingMode = Logger.LoggingModes.All

PYTHON

请注意Logger.LogFilePath必须在第一次PDF转换调用之前设置。之后做出的更改对当前会话不起作用。

详细日志在诊断特定HTML页面未按预期渲染时最有用——它们捕获网络请求、CSS加载事件和JavaScript执行时间。

如何将HTML字符串转换为PDF？

转换内存中的HTML字符串是最直接的方法，并且在HTML是通过编程生成时效果良好——例如，从Jinja2模板或数据库驱动的报告生成。

基本HTML字符串转换

实例化SaveAs：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/html-string-basic.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Convert an HTML string to a PDF document
pdf = renderer.RenderHtmlAsPdf("<h1>Hello from IronPDF!</h1><p>Generated in Python.</p>")

pdf.SaveAs("hello.pdf")

PYTHON

RenderHtmlAsPdf精确处理HTML，就像Chrome会做的，包括CSS和JavaScript。

ChromePdfRenderer以现代浏览器的方式处理HTML、CSS和JavaScript。在Chrome中正确渲染的任何内容将生成准确的PDF。

具有外部资产的HTML字符串

当HTML字符串引用本地资源（样式表、图像、脚本）时，将目录路径作为第二个参数传递给RenderHtmlAsPdf。 IronPDF将此路径用作基础URL，以解析相对引用：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/html-string-assets.py

from ironpdf import *

html_content = """
<html>
  <head>
    <title>Styled Report</title>
    <link rel='stylesheet' href='assets/style.css'>
  </head>
  <body>
    <h1>Monthly Report</h1>
    <img src='assets/logo.png' alt='Company logo'>
    <p>Data as of Q1 2024.</p>
  </body>
</html>
"""

renderer = ChromePdfRenderer()

# The second argument sets the base path for resolving relative asset URLs
pdf = renderer.RenderHtmlAsPdf(html_content, "./")

pdf.SaveAs("styled-report.pdf")

PYTHON

当您提供基路径给RenderHtmlAsPdf时，外部CSS和图像正确加载。

基路径可以指向任何本地目录或网络共享。子目录中的资产相对于它解析。有关复杂HTML字符串的更多模式，请参见HTML字符串到PDF代码示例。

如何将URL转换为PDF？

RenderUrlAsPdf方法获取一个实时URL，等待页面完全加载（包括任何JavaScript驱动的内容），并将渲染结果转换为PDF。这使其适用于捕捉仪表板、报告或任何视觉状态取决于JavaScript执行的页面。

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/url-to-pdf.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Fetch and convert a live web page to PDF
pdf = renderer.RenderUrlAsPdf("https://en.wikipedia.org/wiki/Portable_Document_Format")

pdf.SaveAs("wikipedia-pdf.pdf")

PYTHON

IronPDF获取实时URL并渲染整页——包括JavaScript——再生成PDF。

提示对于需要身份验证的页面，在调用ChromePdfRenderer实例上设置cookie或HTTP请求头。详情请参见HTTP登录凭据指南。

当目标页面加载异步内容时，IronPDF会等待Chromium渲染引擎发出文档完全绘制的信号。对于具有大量JavaScript或延迟网络请求的页面，可以考虑调整ChromePdfRenderOptions上的属性（在下面的渲染选项部分有介绍）。 URL到PDF代码示例显示了其他配置模式。

您如何将HTML文件转换为PDF？

RenderHtmlFileAsPdf接受本地HTML文件的路径并直接转换。 HTML中的相对路径——到CSS文件、图像或JavaScript——会根据HTML文件的目录自动解析，因此不需要基路径参数。

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/html-file-to-pdf.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Convert a local HTML file (and its linked CSS/JS) to PDF
pdf = renderer.RenderHtmlFileAsPdf("invoices/TestInvoice1.html")

pdf.SaveAs("invoice.pdf")

PYTHON

此方法特别适用于服务器端文档生成，其中HTML模板已被写入磁盘——在使用Django或Flask将Jinja2模板渲染为文件，再转换为PDF以便下载时常见的模式。

IronPDF相对于HTML文件位置解析任何<img>标签，因此链接的样式表、嵌入的字体和图像在PDF中显示与在浏览器中一样。该过程反映了RenderHtmlAsPdf如何处理内联资源，区别在于不需要提供显式的基路径。

您如何控制PDF渲染选项？

ChromePdfRenderer（或直接传递给任何渲染方法）的配置对象，用于控制页面布局、边距、纸张尺寸和其他输出特性。在转换之前设置选项是定制PDF输出的标准方式。

纸张尺寸和方向

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/render-options-paper.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Configure page layout before rendering
renderer.RenderingOptions.PaperSize = PdfPaperSize.A4
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape
renderer.RenderingOptions.MarginTop = 20
renderer.RenderingOptions.MarginBottom = 20
renderer.RenderingOptions.MarginLeft = 15
renderer.RenderingOptions.MarginRight = 15

pdf = renderer.RenderHtmlAsPdf("<h1>Landscape Report</h1><p>Content here.</p>")
pdf.SaveAs("landscape-a4.pdf")

PYTHON

边距以毫米表示。 CustomPaperHeight定义的任意尺寸。

自定义纸张尺寸

当标准纸张尺寸不符合输出要求时——例如，收据或标签打印格式——明确定义宽度和高度：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/render-options-custom-size.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Set a custom paper size (in millimetres)
renderer.RenderingOptions.PaperSize = PdfPaperSize.Custom
renderer.RenderingOptions.CustomPaperWidth = 80   # 80 mm receipt roll width
renderer.RenderingOptions.CustomPaperHeight = 200

pdf = renderer.RenderHtmlAsPdf("<h2>Receipt</h2><p>Total: $12.50</p>")
pdf.SaveAs("receipt.pdf")

PYTHON

重要自定义纸张尺寸对于热敏收据打印机和标签格式（如4×6英寸的运输标签）特别有用。

启用JavaScript执行

默认情况下，IronPDF在渲染期间执行JavaScript。如果页面依赖于JavaScript生成可见内容——图表、数据表、动态表单值——这种行为意味着渲染的PDF反映了最终的DOM状态。要在不必要的页面上禁用JavaScript：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/render-options-javascript.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Disable JavaScript for static HTML pages
renderer.RenderingOptions.EnableJavaScript = False

pdf = renderer.RenderHtmlAsPdf("<p>Static content only.</p>")
pdf.SaveAs("static.pdf")

PYTHON

禁用JavaScript可减少简单、静态HTML文档的渲染时间。

有关更多渲染配置详情，请参见PDF生成设置和自定义纸张尺寸示例。

如何添加自定义页眉和页脚？

IronPDF中的页眉和页脚通过附加到渲染器的TextHeaderFooter对象应用。 HtmlHeaderFooter为您提供完整的HTML和CSS控制——非常适合带有徽标的品牌信头。 TextHeaderFooter更简单，并涵盖大多数基于文本的需求，包括动态页码。

基于文本的页眉和页脚

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/headers-footers-text.py

from ironpdf import *

renderer = ChromePdfRenderer()

# Add a text header with the document title
renderer.RenderingOptions.TextHeader = TextHeaderFooter()
renderer.RenderingOptions.TextHeader.CenterText = "Quarterly Report — Q1 2024"
renderer.RenderingOptions.TextHeader.DrawDividerLine = True
renderer.RenderingOptions.TextHeader.FontSize = 10

# Add a footer with page numbers
renderer.RenderingOptions.TextFooter = TextHeaderFooter()
renderer.RenderingOptions.TextFooter.RightText = "Page {page} of {total-pages}"
renderer.RenderingOptions.TextFooter.FontSize = 9
renderer.RenderingOptions.TextFooter.DrawDividerLine = True

html = "<h1>Executive Summary</h1><p>Revenue increased 12% year-over-year.</p>"
pdf = renderer.RenderHtmlAsPdf(html)
pdf.SaveAs("report-with-footer.pdf")

PYTHON

{total-pages}占位符在渲染时替换为正确的值。其他可用占位符包括{url}。

带有徽标的HTML页眉

当需要带有公司徽标、彩色条带或格式化地址块的品牌页眉时，使用HtmlHeaderFooter代替：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/headers-footers-html.py

from ironpdf import *

renderer = ChromePdfRenderer()

header_html = """
<div style="font-family: Arial, sans-serif; border-bottom: 2px solid #003366; padding: 8px 0;">
  <img src='assets/logo.png' style='height: 40px; float: left;' alt='Company logo'>
  <span style='float: right; font-size: 11px; color: #666;'>Confidential</span>
  <div style='clear:both;'></div>
</div>
"""

renderer.RenderingOptions.HtmlHeader = HtmlHeaderFooter()
renderer.RenderingOptions.HtmlHeader.HtmlFragment = header_html
renderer.RenderingOptions.HtmlHeader.BaseUrl = "./"

html_body = "<h1>Project Status Update</h1><p>All milestones on track.</p>"
pdf = renderer.RenderHtmlAsPdf(html_body, "./")
pdf.SaveAs("branded-report.pdf")

PYTHON

请注意将HtmlHeaderFooter上，与文档主体使用的基路径相同。这确保了页眉HTML中引用的图片和样式表可以正确解析。

页眉和页脚出现在生成的PDF的每一页上，包括多页文档。有关在页脚中包含页面级元数据的工作示例，请参见HTML页眉和页脚代码示例。

页眉和页脚的边距调整

添加页眉或页脚时，请增加相应的边距以防内容与页面主体重叠：

:path=/static-assets/pdf/content-code-examples/tutorials/html-to-pdf/headers-footers-margins.py

from ironpdf import *

renderer = ChromePdfRenderer()

renderer.RenderingOptions.MarginTop = 30     # Make room for header
renderer.RenderingOptions.MarginBottom = 20  # Make room for footer

renderer.RenderingOptions.TextHeader = TextHeaderFooter()
renderer.RenderingOptions.TextHeader.CenterText = "Internal Use Only"

renderer.RenderingOptions.TextFooter = TextHeaderFooter()
renderer.RenderingOptions.TextFooter.CenterText = "Page {page} of {total-pages}"

pdf = renderer.RenderHtmlAsPdf("<h1>Internal Document</h1><p>Body content.</p>")
pdf.SaveAs("margined-report.pdf")

PYTHON

对于布局关键文档，将边距调整与PaperSize设置结合，以使输出完全符合打印规范。附加的布局控件——如IronSoftwareSystemDrawingColor背景填充和CSS @page规则——在自定义边距示例中详细介绍。

下一步是什么？

本教程涵盖了三个核心HTML到PDF的转换方法及其输出控制的渲染选项。以下指南是在此基础上构建的，并涵盖更专业的任务：

PDF生成设置——深入探讨ChromePdfRenderOptions：DPI、背景渲染、CSS媒体类型、JavaScript等待策略，打印模式和屏幕模式。
HTML页眉和页脚——带有徽标、页码、日期和多栏布局的品牌页眉和页脚模板。
自定义边距和纸张尺寸——微调页面几何形状，以获得打印就绪的输出和非标准格式。
向PDF添加水印——将文本或图像水印印在现有或新生成的PDF上。
从PDF中提取文本——以编程方式读取生成或现有PDF的文本内容。

开始免费的30天试用，在评估期间生成无限制、无水印的PDF。准备好生产时，请查看许可选项以进行团队和企业部署。

常见问题解答

我如何在Python中将HTML字符串转换为PDF？

实例化ChromePdfRenderer，然后调用renderer.RenderHtmlAsPdf(html_string)。该方法接受任何有效的HTML，包括内联CSS和JavaScript。用pdf.SaveAs("output.pdf")保存返回的PdfDocument。

如何安装 IronPDF for Python？

从终端运行pip install ironpdf。IronPDF for Python需要.NET 6.0 SDK或更高版本，在首次使用前必须单独安装。

IronPDF是否可以在Python中将实时URL转换为PDF？

可以。使用renderer.RenderUrlAsPdf("https://example.com")。IronPDF使用Chromium引擎获取页面，等待JavaScript完成执行，然后从完全渲染的DOM生成PDF。

我如何将本地HTML文件转换为PDF？

调用renderer.RenderHtmlFileAsPdf("path/to/file.html")。IronPDF自动将样式表、图像、脚本等所有相对资产路径解析为相对于HTML文件目录的路径。

如何移除IronPDF生成的PDF上的水印？

在任何PDF操作之前，使用License.LicenseKey = "YOUR-KEY"设置一个有效的许可证密钥。如果没有密钥，IronPDF将添加适合开发但不适合生产使用的平铺水印。

IronPDF为Python提供了哪些渲染选项？

在renderer.RenderingOptions上设置的属性控制纸张大小（PaperSize）、方向（PaperOrientation）、边距（MarginTop、MarginLeft等）、自定义尺寸（CustomPaperWidth、CustomPaperHeight）、JavaScript执行（EnableJavaScript）等等。