【亲测免费】Html Agility Pack (HAP) 项目教程

2026-01-15 17:44:11作者：凤尚柏Louis

Html Agility Pack (HAP) is a free and open-source HTML parser written in C# to read/write DOM and supports plain XPATH or XSLT. It is a .NET code library that allows you to parse "out of the web" HTML files.

项目地址：https://gitcode.com/gh_mirrors/ht/html-agility-pack

还在为HTML解析而烦恼吗？面对杂乱无章的HTML文档，传统的字符串处理方法往往力不从心。Html Agility Pack (HAP) 作为.NET生态中最强大的HTML解析库，能够轻松处理各种复杂的HTML文档，即使面对格式错误的HTML也能游刃有余。

读完本文，你将掌握：

HAP的核心功能与优势
完整的安装与配置指南
实战代码示例与最佳实践
XPath查询技巧与高级用法
常见问题解决方案

什么是Html Agility Pack？

Html Agility Pack是一个开源的.NET HTML解析库，它能够将HTML文档转换为可读写的DOM（Document Object Model）对象模型，支持XPath查询和XSLT转换。与System.Xml类似，但专门为HTML文档设计，具有极强的容错能力。

核心特性对比表

特性	传统字符串处理	Html Agility Pack
HTML容错性	差，需要完美格式	极强，能处理错误HTML
查询能力	正则表达式复杂	XPath简单强大
性能	低效，容易出错	高效，稳定可靠
维护性	代码难以维护	面向对象，易于维护
扩展性	有限	丰富的API和扩展

安装与配置

NuGet包安装

# Package Manager Console
Install-Package HtmlAgilityPack

# .NET CLI
dotnet add package HtmlAgilityPack

项目引用

using HtmlAgilityPack;

基础用法实战

1. 从字符串加载HTML

// 创建HtmlDocument实例
HtmlDocument doc = new HtmlDocument();

// 加载HTML字符串
string htmlContent = @"<html>
<head><title>测试页面</title></head>
<body>
    <div class='content'>
        <h1>欢迎使用HAP</h1>
        <p class='description'>这是一个示例段落</p>
        <ul>
            <li>项目1</li>
            <li>项目2</li>
            <li>项目3</li>
        </ul>
    </div>
</body>
</html>";

doc.LoadHtml(htmlContent);

2. 从文件加载HTML

// 从文件加载
HtmlDocument doc = new HtmlDocument();
doc.Load("example.html");

// 自动检测编码并加载
doc.DetectEncodingAndLoad("example.html");

// 指定编码加载
doc.Load("example.html", Encoding.UTF8);

3. 从URL加载网页内容

HtmlWeb web = new HtmlWeb();
HtmlDocument doc = web.Load("https://example.com");

// 异步加载
async Task LoadWebPageAsync()
{
    HtmlWeb web = new HtmlWeb();
    HtmlDocument doc = await web.LoadFromWebAsync("https://example.com");
}

XPath查询实战指南

XPath是HAP最强大的功能之一，让我们通过示例来掌握它：

常用XPath表达式

// 获取文档根节点
HtmlNode root = doc.DocumentNode;

// 1. 选择所有div元素
HtmlNodeCollection divs = root.SelectNodes("//div");

// 2. 选择特定class的元素
HtmlNodeCollection contentDivs = root.SelectNodes("//div[@class='content']");

// 3. 选择第一个匹配的元素
HtmlNode firstParagraph = root.SelectSingleNode("//p");

// 4. 选择特定id的元素
HtmlNode specificElement = root.SelectSingleNode("//*[@id='main']");

// 5. 选择子元素
HtmlNodeCollection listItems = root.SelectNodes("//ul/li");

// 6. 选择包含特定文本的元素
HtmlNodeCollection welcomeElements = root.SelectNodes("//*[contains(text(),'欢迎')]");

// 7. 选择属性值
HtmlNodeCollection links = root.SelectNodes("//a[@href]");

XPath查询示例表格

查询需求	XPath表达式	说明
所有段落	`//p`	选择所有p标签
特定class	`//div[@class='content']`	class为content的div
多个class	`//div[contains(@class,'btn')]`	class包含btn的div
特定id	`//*[@id='header']`	id为header的元素
子元素	`//ul/li`	ul下的直接li子元素
后代元素	`//div//p`	div下的所有p元素
属性存在	`//a[@href]`	包含href属性的a标签
文本包含	`//*[contains(text(),'搜索')]`	文本包含"搜索"的元素

高级功能与技巧

1. 处理编码问题

// 自动检测HTML编码
HtmlDocument doc = new HtmlDocument();
Encoding detectedEncoding = doc.DetectEncodingHtml(htmlContent);

// 手动指定编码
doc.Load("file.html", Encoding.GetEncoding("GB2312"));

2. 错误处理与调试

try
{
    HtmlDocument doc = new HtmlDocument();
    
    // 启用调试属性
    doc.OptionAddDebuggingAttributes = true;
    
    // 检查语法错误
    doc.OptionCheckSyntax = true;
    
    doc.LoadHtml(htmlContent);
    
    // 输出解析错误
    foreach (var error in doc.ParseErrors)
    {
        Console.WriteLine($"错误: {error.Reason} 在行 {error.Line} 位置 {error.LinePosition}");
    }
}
catch (Exception ex)
{
    Console.WriteLine($"解析错误: {ex.Message}");
}

3. 修改和操作HTML

// 创建新元素
HtmlNode newDiv = doc.CreateElement("div");
newDiv.SetAttributeValue("class", "new-content");
newDiv.InnerHtml = "<p>新添加的内容</p>";

// 添加到文档
HtmlNode body = doc.DocumentNode.SelectSingleNode("//body");
body.AppendChild(newDiv);

// 修改属性
HtmlNode firstLink = doc.DocumentNode.SelectSingleNode("//a");
if (firstLink != null)
{
    firstLink.SetAttributeValue("target", "_blank");
}

// 删除元素
HtmlNode toRemove = doc.DocumentNode.SelectSingleNode("//div[@class='ads']");
toRemove?.Remove();

4. 保存修改后的HTML

// 保存到文件
doc.Save("modified.html");

// 保存为字符串
string modifiedHtml = doc.DocumentNode.OuterHtml;

// 保存时指定编码
doc.Save("output.html", Encoding.UTF8);

实战案例：网页数据提取

让我们通过一个完整的示例来演示如何从网页中提取结构化数据：

public class ProductInfo
{
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Description { get; set; }
    public string ImageUrl { get; set; }
}

public List<ProductInfo> ExtractProductsFromHtml(string htmlContent)
{
    List<ProductInfo> products = new List<ProductInfo>();
    
    HtmlDocument doc = new HtmlDocument();
    doc.LoadHtml(htmlContent);
    
    // 假设产品信息在具有特定class的div中
    HtmlNodeCollection productNodes = doc.DocumentNode.SelectNodes("//div[contains(@class,'product-item')]");
    
    if (productNodes != null)
    {
        foreach (HtmlNode productNode in productNodes)
        {
            ProductInfo product = new ProductInfo();
            
            // 提取产品名称
            HtmlNode nameNode = productNode.SelectSingleNode(".//h3[@class='product-name']");
            product.Name = nameNode?.InnerText.Trim();
            
            // 提取价格
            HtmlNode priceNode = productNode.SelectSingleNode(".//span[@class='price']");
            if (priceNode != null && decimal.TryParse(priceNode.InnerText.Trim().Replace("¥", ""), out decimal price))
            {
                product.Price = price;
            }
            
            // 提取描述
            HtmlNode descNode = productNode.SelectSingleNode(".//p[@class='description']");
            product.Description = descNode?.InnerText.Trim();
            
            // 提取图片URL
            HtmlNode imgNode = productNode.SelectSingleNode(".//img");
            product.ImageUrl = imgNode?.GetAttributeValue("src", "");
            
            products.Add(product);
        }
    }
    
    return products;
}

性能优化建议

1. 使用合适的加载选项

HtmlDocument doc = new HtmlDocument();

// 禁用语法检查提升性能
doc.OptionCheckSyntax = false;

// 不计算校验和
doc.OptionComputeChecksum = false;

// 对于大型文档，限制嵌套深度
doc.OptionMaxNestedChildNodes = 1000;

2. 高效的XPath查询

// 避免使用过于复杂的XPath
// 不佳: //div//p//span
// 推荐: //div/span

// 使用具体的选择器
// 不佳: //*[@class='btn']
// 推荐: //button[@class='btn'] 或 //a[@class='btn']

3. 内存管理

// 及时释放大型文档
using (HtmlDocument doc = new HtmlDocument())
{
    doc.LoadHtml(largeHtmlContent);
    // 处理文档...
} // 自动释放资源

// 分批处理大型HTML
public void ProcessLargeHtmlInChunks(string htmlContent)
{
    HtmlDocument doc = new HtmlDocument();
    doc.LoadHtml(htmlContent);
    
    // 分批处理节点
    HtmlNodeCollection nodes = doc.DocumentNode.SelectNodes("//div");
    if (nodes != null)
    {
        foreach (HtmlNode node in nodes)
        {
            ProcessNode(node);
        }
    }
}

常见问题与解决方案

1. 中文编码问题

// 处理中文编码
HtmlDocument doc = new HtmlDocument();

// 方法1: 自动检测
doc.DetectEncodingAndLoad("chinese-page.html");

// 方法2: 手动指定
doc.Load("chinese-page.html", Encoding.GetEncoding("GB2312"));

// 方法3: 从meta标签获取编码
var metaCharset = doc.DocumentNode.SelectSingleNode("//meta[@charset]");
if (metaCharset != null)
{
    string charset = metaCharset.GetAttributeValue("charset", "");
    Encoding encoding = Encoding.GetEncoding(charset);
}

2. 处理JavaScript生成的内容

// 使用浏览器渲染后的HTML
HtmlWeb web = new HtmlWeb();

// 设置用户代理模仿真实浏览器
web.UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36";

// 使用浏览器引擎渲染（需要额外配置）
try
{
    HtmlDocument doc = web.LoadFromBrowser("https://dynamic-page.com");
}
catch
{
    Console.WriteLine("需要安装浏览器驱动");
}