html4cj DOM操作实战手册：1分钟获取节点的文本、属性与标签内容

html4cj DOM操作实战手册：1分钟获取节点的文本、属性与标签内容

【免费下载链接】html4cj一个HTML格式解析库项目地址: https://gitcode.com/Cangjie-TPC/html4cj

html4cj 是一个简洁好用的 HTML 解析库，它能把 HTML 字符串解析成 DOM 树，让你在代码中像操作对象一样取出节点的文本、属性和标签内容，特别适合网页数据处理和爬虫场景。本文带你用最短时间掌握 html4cj 的 DOM 操作核心 API。

上图展示了 html4cj 的解析器工作流程：HTML 文本经过字符读取、构建 Token、构建 DOM 树，最终生成可供操作的 Document 对象。

🚀 3步快速上手：解析出你的第一个DOM对象

使用 html4cj 只需三步：导入库 → 调用 parse → 操作节点。

import html4cj.* main(): Int64 { // 第2步：把HTML解析成Document（DOM对象） var doc: Document = Html4cj.parse("<a href=/foo>Hello</a>", "http://127.0.0.1/") // 第3步：用CSS选择器定位节点 var a: Element = doc.select("a").first().getOrThrow() println(a.text()) // Hello println(a.attr("href")) // /foo return 0 }

核心入口是Html4cj.parse静态方法，定义在 html4cj.cj：

💡小贴士：解析网页时务必传入baseUri（页面真实 URL），这样href="/foo"这类相对路径才能正确还原成绝对地址。

📝 1分钟获取节点文本：text()方法全解

获取节点文本是 DOM 操作最高频的动作，html4cj 提供了几个层次分明的方法：

let p: Element = doc.select("p").first().getOrThrow() p.text() // 元素及其所有子元素的组合文本（已规范化空白） p.ownText() // 仅该元素自身的文本，不含子元素 p.wholeText() // 保留原始空白和换行符的文本 p.hasText() // 判断是否有非空白文本，返回Bool

• text()定义在 element.cj，最常用，返回解码后的干净文本
• 批量场景用eachText()一次拿到所有匹配元素的文本列表，定义在 elements.cj

let items: ArrayList<String> = doc.select("li").eachText() // 逐个获取多个列表项的文本，一个方法搞定

⚠️ 注意：text()返回的是纯文本，会剥掉所有标签；如果子元素为空，返回空字符串而非 None。

🎯 精准获取节点属性：attr()与hasAttr()两大招式

属性获取的 API 集中在 Node 基类上，所有节点类型通用：

a.attr("href") // 获取属性值，不存在时返回空字符串 a.hasAttr("href") // 先判断属性是否存在，避免空值歧义 a.id() // 快捷方法：获取id属性 a.className() // 快捷方法：获取class属性文本 a.hasClass("logo") // 判断是否有某个class

• attr读取实现见 node.cj
• 判断属性存在用 node.cj 的hasAttr
• 类名相关快捷方法在 element.cj 起

🔑 进阶：一键把相对URL变绝对地址

这是 html4cj 最实用的功能之一——在属性键前加abs:前缀，自动把相对 URL 转成绝对 URL：

a.attr("abs:href") // 输出 http://127.0.0.1/foo

底层对应absUrl方法，定义在 node.cj，原理是结合解析时传入的baseUri做地址拼接。爬链接时这个技巧能省去大量手工处理。

🏷️ 提取标签内容：html()与outerHtml()一文看懂

"文本"和"标签内容"是两回事：前者是纯文字，后者保留 HTML 结构。

let div: Element = doc.select("div").first().getOrThrow() div.html() // 内部HTML：不含div自身的开始/结束标签 div.outerHtml() // 外部HTML：包含div自身标签的完整片段

• html()在 element.cj
• outerHtml()批量版本在 elements.cj

💡 记忆口诀："text 要文字，html 要里子，outerHtml 要整体"。

✅ 避坑指南：3个常见坑一次说清

坑1：属性不存在时拿到空字符串。attr对不存在的属性返回""而不是报错，建议重要字段先用hasAttr判断，见 elements.cj。

坑2：忘记传 baseUri 导致绝对 URL 失效。abs:href依赖解析时的基准地址，若调用parse(html)时没传 baseUri，abs:前缀拿到的可能还是相对路径。

坑3：选择器没匹配到节点。select("a").first()可能返回 None，记得用.getOrThrow()或直接判空，别裸调方法。

📚 延伸阅读：完整API与源码路径

想深入某个 API 时，直接对照文档和源码效率最高：

• 完整接口文档（含全部方法签名与示例）：doc/feature_api.md
• 核心解析入口类 Html4cj：html4cj.cj
• Element 元素节点（文本、类名、选择器）：element.cj
• Elements 批量操作（eachText、outerHtml）：elements.cj
• Node 节点基类（attr、absUrl）：node.cj
• 选择器查询实现：selector.cj

掌握本文的parse→select→text/attr/html这条主线，你就能覆盖 90% 的日常 DOM 操作需求，剩下的特殊场景再查完整 API 文档即可。

【免费下载链接】html4cj一个HTML格式解析库项目地址: https://gitcode.com/Cangjie-TPC/html4cj