> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# HTMLRewriter
> 使用 Bun 的 HTMLRewriter 通过 CSS 选择器转换 HTML 文档
HTMLRewriter 通过 CSS 选择器转换 HTML 文档。它适用于 `Response`、`string` 和 `ArrayBuffer` 输入。Bun 的实现基于 Cloudflare 的 [lol-html](https://github.com/cloudflare/lol-html)。
***
## 用法
一个常见的用例是重写 HTML 内容中的 URL：
```ts theme={null}
// 将所有图片替换为 rickroll
const rewriter = new HTMLRewriter().on("img", {
element(img) {
// 著名的 rickroll 视频缩略图
img.setAttribute("src", "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg");
// 将图片包装在视频链接中
img.before('', {
html: true,
});
img.after("", { html: true });
// 添加一些有趣的替代文本
img.setAttribute("alt", "Definitely not a rickroll");
},
});
// 一个示例 HTML 文档
const html = `
`;
const result = rewriter.transform(html);
console.log(result);
```
重写器将每个图片替换为 Rick Astley 的缩略图，并将每个 `![]()
` 包装在链接中，产生如下差异：
```html theme={null}
```
点击任何图片现在都会链接到[一个非常著名的视频](https://www.youtube.com/watch?v=dQw4w9WgXcQ)。
### 输入类型
HTMLRewriter 可以从多种输入类型转换 HTML：
```ts theme={null}
// 从 Response
rewriter.transform(new Response("content
"));
// 从字符串
rewriter.transform("content
");
// 从 ArrayBuffer
rewriter.transform(new TextEncoder().encode("content
").buffer);
// 从 Blob（包装在 Response 中）
rewriter.transform(new Response(new Blob(["content
"])));
// 从 File（包装在 Response 中）
rewriter.transform(new Response(Bun.file("index.html")));
```
Cloudflare Workers 的 HTMLRewriter 实现仅支持 `Response` 对象。
### 元素处理器
`on(selector, handlers)` 方法注册用于匹配 CSS 选择器的 HTML 元素的处理器。处理器会在解析期间为每个匹配的元素运行：
```ts theme={null}
rewriter.on("div.content", {
// 处理元素
element(element) {
element.setAttribute("class", "new-content");
element.append("New content
", { html: true });
},
// 处理文本节点
text(text) {
text.replace("new text");
},
// 处理注释
comments(comment) {
comment.remove();
},
});
```
处理器可以是异步的并返回 Promise。异步操作会阻塞转换直到它们完成：
```ts theme={null}
rewriter.on("div", {
async element(element) {
await Bun.sleep(1000);
element.setInnerContent("replace", { html: true });
},
});
```
### CSS 选择器支持
`on()` 方法支持广泛的 CSS 选择器：
```ts theme={null}
// 标签选择器
rewriter.on("p", handler);
// 类选择器
rewriter.on("p.red", handler);
// ID 选择器
rewriter.on("h1#header", handler);
// 属性选择器
rewriter.on("p[data-test]", handler); // 拥有属性
rewriter.on('p[data-test="one"]', handler); // 精确匹配
rewriter.on('p[data-test="one" i]', handler); // 不区分大小写
rewriter.on('p[data-test="one" s]', handler); // 区分大小写
rewriter.on('p[data-test~="two"]', handler); // 单词匹配
rewriter.on('p[data-test^="a"]', handler); // 以...开头
rewriter.on('p[data-test$="1"]', handler); // 以...结尾
rewriter.on('p[data-test*="b"]', handler); // 包含
rewriter.on('p[data-test|="a"]', handler); // 破折号分隔
// 组合器
rewriter.on("div span", handler); // 后代
rewriter.on("div > span", handler); // 直接子代
// 伪类
rewriter.on("p:nth-child(2)", handler);
rewriter.on("p:first-child", handler);
rewriter.on("p:nth-of-type(2)", handler);
rewriter.on("p:first-of-type", handler);
rewriter.on("p:not(:first-child)", handler);
// 通用选择器
rewriter.on("*", handler);
```
### 元素操作
所有元素修改方法都返回元素实例，因此调用可以被链式连接：
```ts theme={null}
rewriter.on("div", {
element(el) {
// 属性
el.setAttribute("class", "new-class").setAttribute("data-id", "123");
const classAttr = el.getAttribute("class"); // "new-class"
const hasId = el.hasAttribute("id"); // boolean
el.removeAttribute("class");
// 内容操作
el.setInnerContent("New content"); // 默认转义 HTML
el.setInnerContent("HTML content
", { html: true }); // 解析 HTML
el.setInnerContent(""); // 清除内容
// 位置操作
el.before("Content before").after("Content after").prepend("First child").append("Last child");
// HTML 内容插入
el.before("before", { html: true })
.after("after", { html: true })
.prepend("first", { html: true })
.append("last", { html: true });
// 移除
el.remove(); // 移除元素及其内容
el.removeAndKeepContent(); // 仅移除元素标签
// 属性
console.log(el.tagName); // 小写标签名
console.log(el.namespaceURI); // 元素的命名空间 URI
console.log(el.selfClosing); // 元素是否自闭合（例如 ）
console.log(el.canHaveContent); // 元素是否可以包含内容（void 元素如
为 false）
console.log(el.removed); // 元素是否已被移除
// 属性迭代
for (const [name, value] of el.attributes) {
console.log(name, value);
}
// 结束标签处理
el.onEndTag(endTag => {
endTag.before("Before end tag");
endTag.after("After end tag");
endTag.remove(); // 移除结束标签
console.log(endTag.name); // 小写的标签名
});
},
});
```
### 文本操作
文本块代表文本内容的一部分，并报告它们在其文本节点中的位置：
```ts theme={null}
rewriter.on("p", {
text(text) {
// 内容
console.log(text.text); // 文本内容
console.log(text.lastInTextNode); // 是否是最后一个块
console.log(text.removed); // 文本是否已被移除
// 操作
text.before("Before text").after("After text").replace("New text").remove();
// HTML 内容插入
text
.before("before", { html: true })
.after("after", { html: true })
.replace("replace", { html: true });
},
});
```
### 注释操作
注释支持类似于文本节点的方法：
```ts theme={null}
rewriter.on("*", {
comments(comment) {
// 内容
console.log(comment.text); // 注释文本
comment.text = "New comment text"; // 设置注释文本
console.log(comment.removed); // 注释是否已被移除
// 操作
comment.before("Before comment").after("After comment").replace("New comment").remove();
// HTML 内容插入
comment
.before("before", { html: true })
.after("after", { html: true })
.replace("replace", { html: true });
},
});
```
### 文档处理器
`onDocument(handlers)` 方法用于在文档级别注册处理器，而不是在特定元素内：
```ts theme={null}
rewriter.onDocument({
// 处理文档类型
doctype(doctype) {
console.log(doctype.name); // "html"
console.log(doctype.publicId); // 公有的标识符（如果存在）
console.log(doctype.systemId); // 系统的标识符（如果存在）
},
// 处理文本节点
text(text) {
console.log(text.text);
},
// 处理注释
comments(comment) {
console.log(comment.text);
},
// 处理文档结束
end(end) {
end.append("", { html: true });
},
});
```
### Response 处理
当转换 Response 时：
* 状态码、头部和其他响应属性被保留
* 主体在被转换的同时保持流式处理能力
* 内容编码（如 gzip）被自动处理
* 原始响应主体在转换后被标记为已使用
* 头部被克隆到新响应
## 错误处理
HTMLRewriter 操作在以下情况下可能会抛出错误：
* `on()` 方法中的选择器语法无效
* 转换方法中的 HTML 内容无效
* 处理 Response 主体时的流错误
* 内存分配失败
* 无效的输入类型（例如，传递 Symbol）
* 主体已使用错误
捕获并处理这些错误：
```ts theme={null}
try {
const result = rewriter.transform(input);
// 处理结果
} catch (error) {
console.error("HTMLRewriter error:", error);
}
```
***
## 另请参阅
您还可以阅读 [Cloudflare 文档](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/)，此 API 旨在与其兼容。