使用iText7与C# .NET MAUI将HTML转PDF时遇URI格式异常求助

问题根源 #

iText7的HtmlConverter.ConvertToPdf默认会尝试解析HTML内容中的所有资源引用（如图片、样式表的相对路径），如果HTML里包含不规范的URI，或者没有指定正确的BaseUri供iText解析相对路径，就会触发UriFormatException。纯文本PDF生成不需要处理资源引用，所以不会出现这个问题。

解决方案 #

1. 规范HTML内容（无外部资源时） #

如果测试用的HTML没有外部资源，确保内容里没有无效的URI引用，比如避免<img src="">、<link href="invalid-path">这类不合法的资源标签。

2. 正确调用ConvertToPdf并设置ConverterProperties #

使用带ConverterProperties参数的重载方法，明确指定BaseUri（即使没有外部资源，也可以设置为空字符串或缓存目录路径，避免iText使用默认的无效BaseUri）。

完整代码示例 #

using iText.Html2pdf;
using iText.Kernel.Pdf;
using System.IO;

// 1. 准备测试用的HTML字符串
var htmlContent = @"
<!DOCTYPE html>
<html>
<head>
    <title>Test PDF</title>
    <style>
        h1 { color: #2c3e50; }
        p { font-size: 14px; }
    </style>
</head>
<body>
    <h1>Hello from HTML to PDF</h1>
    <p>This is a test PDF generated from HTML in .NET MAUI</p>
</body>
</html>";

// 2. 获取Android缓存目录路径
var cachePath = FileSystem.CacheDirectory;
var pdfFilePath = Path.Combine(cachePath, "test_html.pdf");

// 3. 使用HtmlConverter转换HTML到PDF
using (var fs = new FileStream(pdfFilePath, FileMode.Create))
{
    var converterProperties = new ConverterProperties();
    // 设置BaseUri为缓存目录（如果有相对路径资源，iText会从这里查找）
    converterProperties.SetBaseUri(cachePath);
    
    // 转换HTML字符串到PDF
    HtmlConverter.ConvertToPdf(htmlContent, new PdfWriter(fs), converterProperties);
}

// 4. 打开生成的PDF文件（Android平台）
var pdfFile = new FileInfo(pdfFilePath);
if (pdfFile.Exists)
{
    var uri = Android.Net.Uri.FromFile(pdfFile);
    var intent = new Android.Content.Intent(Android.Content.Intent.ActionView);
    intent.SetDataAndType(uri, "application/pdf");
    intent.AddFlags(Android.Content.ActivityFlags.GrantReadUriPermission);
    intent.AddFlags(Android.Content.ActivityFlags.NewTask);
    Android.App.Application.Context.StartActivity(intent);
}

处理大型HTML内容的注意事项 #

当后续处理服务器返回的大型HTML时，建议使用流读取HTML内容，避免一次性加载整个字符串到内存：

// 从Http响应流读取HTML示例
using (var htmlStream = await response.Content.ReadAsStreamAsync())
using (var fs = new FileStream(pdfFilePath, FileMode.Create))
{
    var converterProperties = new ConverterProperties();
    converterProperties.SetBaseUri(cachePath);
    HtmlConverter.ConvertToPdf(htmlStream, new PdfWriter(fs), converterProperties);
}

额外排查点 #

• 如果HTML里确实需要引用外部资源（如图片），确保BaseUri设置为资源所在的正确路径（比如服务器基础地址或本地资源目录）。
• 检查HTML中的所有URI是否符合标准格式，避免出现空格、特殊字符未转义的情况。

内容的提问来源于stack exchange，提问作者Reyneer Leon