在 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能否將實時URL轉換為Python中的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: 我如何在使用IronPDF的Python中為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 進行工作流程，可以查看在 .NET 應用程式中將 HTML 轉換為 PDF 的教程。

快速入門：在 Python 中將 HTML 轉換為 PDF

如何在 Python 中將 HTML 轉換為 PDF

Install IronPDF for Python via pip
使用 from ironpdf import * 引入程式庫
實例化 ChromePdfRenderer
Call RenderHtmlAsPdf, RenderUrlAsPdf, or RenderHtmlFileAsPdf
使用 pdf.SaveAs("output.pdf") 保存結果

開始使用

如何安裝IronPDF for Python？

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？

在第一次轉換調用之前，值得完成兩個設置任務：設置授權密鑰和（可選）配置日誌檔位置。

導入包

using 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 字串轉換

實例化 ChromePdfRenderer，將 HTML 字串傳遞給 RenderHtmlAsPdf，並在返回的 PdfDocument 上調用 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 並在生成 PDF 之前渲染完整頁面——包括 JavaScript。

提示對於需要認證的頁面，在調用 RenderUrlAsPdf 之前，在 ChromePdfRenderer 實例上設置 Cookie 或 HTTP 請求頭。請參見HTTP 登錄憑據指南以獲取詳情。

當目標頁面載入異步內容時，IronPDF 會等到 Chromium 渲染引擎發出文件完全顯示的信號。對於具有繁重 JavaScript 或延遲網路請求的頁面，請考慮調整 WaitFor 屬性在 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 文件位置解析任何 <script> 和 <img> 標籤，因此連結的樣式表、嵌入的字形和圖像在 PDF 中顯示就像在瀏覽器中一樣。該過程模仿 RenderHtmlAsPdf 如何處理內聯資源，不同之處在於不需要提供顯式基礎路徑。

如何控制 PDF 渲染選項？

ChromePdfRenderOptions 是傳遞給 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

邊距以毫米表達。 PdfPaperSize 支援所有標準 ISO 大小——從 A0 到 A10、Letter、Legal、Tabloid——以及 Custom 用於由 CustomPaperWidth 和 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 中的標題和頁腳是通過附加至渲染器的 HtmlHeaderFooter 或 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

{page} 和 {total-pages} 佔位符在渲染時會被正確的值替換。其他可用的佔位符包括 {time} 和 {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 上設置 BaseUrl 為與文件主體使用的相同基礎路徑。這確保內部標題 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能否將實時URL轉換為Python中的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）等。