@droid43/html-dom
v0.0.1-beta.1
Published
A lightweight HTML parsing utility with DOM-like query APIs and relative URL normalization.
Maintainers
droid4Readme
html-dom
一个基于 htmlparser2 的轻量 HTML 解析工具库，提供接近浏览器 DOM 的常用查询能力，并支持把相对资源地址自动补全为绝对地址。
安装
pnpm add html-dom如果你在当前仓库本地开发：
pnpm install快速开始
import { parseFromString } from 'html-dom';
const root = parseFromString(
`
<html>
<body>
<article class="card featured">
<h1 id="title">Hello html-dom</h1>
<a href="/docs/start">Read the docs</a>
</article>
</body>
</html>
`,
'https://example.com/posts/welcome',
);
console.log(root.innerText);
console.log(root.getElementById('title')?.innerText);
console.log(root.getElementsByClassName('card')[0]?.innerHtml);
console.log(root.getElementsByTagName('a')[0]?.href);
console.log(root.getElementsByTagName('a')[0]?.getAttribute('href'));API
parseFromString(html, baseUrl?)
把 HTML 字符串解析为一个 DomNode 根节点。
参数说明：
html: string要解析的 HTML 字符串。baseUrl?: string可选的基础链接。传入后，节点上的src、href、data-src、poster等相对地址会被自动转成绝对地址。
返回值：
DomNode对应输入 HTML 中的根<html>节点。
异常说明：
- 当输入内容中不存在
<html>根节点时，会抛出错误。
DomNode
DomNode 是当前库的核心节点对象，代表一个 HTML 标签节点，同时暴露常用查询和内容读取能力。
常用属性
baseUrl: string当前节点使用的基础链接。children: DomNode[]当前节点的子节点列表。lastChild: DomNode | undefined当前节点最后一个子节点。innerText: string当前节点及其子树的纯文本内容。innerHtml: string当前节点子树重新拼接后的 HTML 字符串。tagName?: string当前节点的标签名，例如div、a、img。rawElement: Element原始的domhandler节点对象。attributes: Record<string, string | undefined>当前节点的全部属性映射。id?: string当前节点的id属性值。name?: string当前节点的name属性值。class?: string当前节点的class属性值。
说明：
- 常见属性可以直接通过实例访问，比如
node.href、node.src、node.id。 - 如果你需要读取任意属性，推荐使用
node.attributes或node.getAttribute(name)。 - 如果传入了
baseUrl，这些资源类属性可能已经被转换为绝对地址。
getAttribute(name)
读取任意属性值。
返回值：
string | undefined
查询方法
getElementById(id)
按 id 查找第一个匹配节点。
返回值：
DomNode | undefined
getElementsByName(name)
按 name 属性查找全部匹配节点。
返回值：
DomNode[]
getElementsByTagName(name)
按标签名查找全部匹配节点。
返回值：
DomNode[]
getElementsByClassName(name)
按 class 名查找全部匹配节点，支持传入多个 class，多个 class 之间使用空格分隔。
示例：
root.getElementsByClassName('card');
root.getElementsByClassName('card featured');返回值：
DomNode[]
相对地址自动补全
当你传入 baseUrl 时，以下属性会自动尝试转成绝对地址：
srchrefdata-srcposter
以下前缀会被视为已经是完整地址，不会重复处理：
http://https://data:mailto:tel:
示例：
const root = parseFromString(
`
<html>
<body>
<img src="/images/cover.png" />
</body>
</html>
`,
'https://example.com/posts/welcome',
);
const image = root.getElementsByTagName('img')[0];
console.log(image?.src);
// https://example.com/images/cover.png适用场景
- 服务端抓取后的 HTML 内容解析
- Node.js 环境下提取标题、链接、图片等内容
- 对静态 HTML 做轻量规则查询
- 对资源相对路径做快速绝对化处理
本地开发
运行调试页
启动本地示例页面：
pnpm dev示例页支持：
- 切换多组预置 HTML 场景
- 手动输入
baseUrl - 查看
innerText - 查看
innerHtml - 查看常见查询结果
生成发布产物
构建库产物：
pnpm build当前会输出三类文件：
dist/esmdist/cjsdist/types
说明：
- 本地调试页面来自
src/demo.ts - 发布产物只包含库入口
src/index.ts demo不会被打进最终库包中