如何使用基础 URL 和资产编码

This article was translated from English: Does it need improvement?
Translated
View the article in English

IronPDF是一个用于在.NET项目中生成PDF文档的有用工具。

这个库的一个常见用途是“HTML 转 PDF”渲染——使用 HTML 作为渲染 PDF 文档的设计语言。 一个合乎逻辑的问题是 我们如何在 HTML 到 PDF 的转换中使用 CSS 样式表和图像文件?


使用图像和 CSS 资产从 HTML 字符串渲染 PDF

在将HTML字符串转换为PDF时,设置BaseUrlOrPath参数以包含CSS、JavaScript文件和图像等资产是非常重要的。 BaseUrlOrPath指定了将相对于其加载所有资产的基本URL。

这可以是以“http”开头的网页URL,用于加载远程资产,或者是本地文件路径,用于访问磁盘上的资产。 正确设置 BaseUrlOrPath 可确保在转换过程中正确加载资产。

:path=/static-assets/pdf/content-code-examples/how-to/base-urls-baseurl.cs
using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

string baseUrl = @"C:\site\assets\";
string html = "<img src='icons/iron.png'>";

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html, baseUrl);

// Export PDF
pdf.SaveAs("html-with-assets.pdf");
Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

Private baseUrl As String = "C:\site\assets\"
Private html As String = "<img src='icons/iron.png'>"

' Render HTML to PDF
Private pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, baseUrl)

' Export PDF
pdf.SaveAs("html-with-assets.pdf")
VB   C#

MVC 应用程序

在MVC应用程序中,指定图像的文件路径可能会有挑战性。 为确保图像能被 IronPDF 找到并在网站上正确显示,需要正确配置 IronPDF 的 baseUrl 和 HTML 字符串上的 src="" 属性。

如下所示的文件层级设置

  • baseUrlOrPath 设置为 @"wwwroot/image"
  • src属性为"../image/Sample.jpg"
wwwroot
└── image
    ├── Sample.jpg
    └── Sample.png

例如:

:path=/static-assets/pdf/content-code-examples/how-to/base-mvc.cs
// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("html.Result", @"wwwroot/image");
' Instantiate ChromePdfRenderer
Dim renderer As New ChromePdfRenderer()

' Render HTML to PDF
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("html.Result", "wwwroot/image")
VB   C#
<img src="../image/Sample.jpg"/>
<img src="../image/Sample.png"/>
<img src="../image/Sample.jpg"/>
<img src="../image/Sample.png"/>
HTML

在继续之前

无效的文件路径格式

以下格式在 Chrome 浏览器上查看时效果良好,但在 MVC 应用程序中使用时指向错误的文件夹目录。如果在 RenderHtmlAsPdf 方法中提供了 baseUrlOrPath,这些格式仍然可以与 IronPDF 一起使用:

<img src="image/footer.png"/>  
<img src="./image/footer.png"/>  
<img src="image/footer.png"/>  
<img src="./image/footer.png"/>  
HTML

另一方面,这些格式在 MVC 应用程序中运行良好,但在文件路径方面,这些格式在 IronPDF 中运行不佳:

<img src="/image/footer.png"/>  
<img src="~/image/footer.png"/>
<img src="/image/footer.png"/>  
<img src="~/image/footer.png"/>
HTML

HTML标题和页脚中的图片和资源

当我们将 HTML 页眉和页脚呈现到新的或现有的 PDF 时,它们会被视为独立的 HTML 文档,而不会继承 PDF 本身的 BaseURL。

我们应该设置一个BaseURL,用于加载资源:

:path=/static-assets/pdf/content-code-examples/how-to/base-header-footer.cs
using IronPdf;
using System;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Add header
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    MaxHeight = 20,
    HtmlFragment = "<img src='logo.png'>",
    BaseUrl = new Uri(@"C:\assets\images\").AbsoluteUri
};
Imports IronPdf
Imports System

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Add header
renderer.RenderingOptions.HtmlHeader = New HtmlHeaderFooter() With {
	.MaxHeight = 20,
	.HtmlFragment = "<img src='logo.png'>",
	.BaseUrl = (New Uri("C:\assets\images\")).AbsoluteUri
}
VB   C#

使用 CSS、JS 和图像资产将 HTML 文件转换为 PDF

在将HTML文件渲染为PDF时,所有资源都将被假定为该文件的本地资源。

:path=/static-assets/pdf/content-code-examples/how-to/base-html-file.cs
using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlFileAsPdf("C:\\Assets\\TestInvoice1.html");

// Export PDF
pdf.SaveAs("Invoice.pdf");
Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Render HTML file to PDF
Private pdf As PdfDocument = renderer.RenderHtmlFileAsPdf("C:\Assets\TestInvoice1.html")

' Export PDF
pdf.SaveAs("Invoice.pdf")
VB   C#

在上述示例中,所有 JS、CSS 和图片文件都将从磁盘上的 C:\Assets 文件夹加载--这与 HTML 文件所在的目录相同。

为方便起见,您可以使用用于附加样式表的 ChromePdfRenderOptions 中的 CustomCssUrl如果您需要,还可以指定一个仅用于 .NET PDF 渲染的附加样式表。例如

:path=/static-assets/pdf/content-code-examples/how-to/base-html-file-baseurl.cs
using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css";

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export PDF
pdf.SaveAs("tryCss.pdf");
Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css"

' Render HTML file to PDF
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")

' Export PDF
pdf.SaveAs("tryCss.pdf")
VB   C#

请注意
ChromePdfRenderOptions.CustomCssUrl 属性目前仅在使用 RenderHtmlAsPdf 方法将 HTML 字符串渲染为 PDF 文档时有效。

图像资产编码

图像资源可以直接编码到HTML文件或字符串中,这有助于避免找不到图像的一些令人沮丧的问题。 为此,我们可以利用 base64 的使用:

  1. 首先通过读取图像文件或通过网络请求接收图像,获取图像的二进制数据。

  2. 在 Microsoft .NET 中使用 Convert.ToBase64String 方法将二进制数据转换为 base64。

  3. 在HTML中使用“data:image/svg+xml;base64,”来构建图像标签,然后加上base64数据。 您可能已经注意到,在base64数据之前已指定了图像类型。 访问关于图像类型和格式的 MDN 网络文档了解更多图像格式类型的信息。
:path=/static-assets/pdf/content-code-examples/how-to/add-images-to-pdfs-base64-image.cs
using IronPdf;
using System;
using System.IO;

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Import image file binary data
byte[] binaryData = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg");

// Convert the binary data to base 64
string imgDataUri = Convert.ToBase64String(binaryData);

// Embed in HTML
string html = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>";

// Convert HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html);

// Export the PDF
pdf.SaveAs("embedImageBase64.pdf");
Imports IronPdf
Imports System
Imports System.IO

Private renderer As New ChromePdfRenderer()

' Import image file binary data
Private binaryData() As Byte = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg")

' Convert the binary data to base 64
Private imgDataUri As String = Convert.ToBase64String(binaryData)

' Embed in HTML
Private html As String = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>"

' Convert HTML to PDF
Private pdf As PdfDocument = renderer.RenderHtmlAsPdf(html)

' Export the PDF
pdf.SaveAs("embedImageBase64.pdf")
VB   C#