Hello, <%- name %>.
Hello, <%- 'the Most Honorable ' + name %>.
```
```json title="locals"
{
"name": "Rspack"
}
```
```html title="html"
Hello, Rspack<y>.
Hello, the Most Honorable Rspack<y>.
```
#### 非转义输出 `<%=`
直接插入未经转义的内容：
```html title="ejs"
Hello, <%- myHtml %>.
Hello, <%= myHtml %>.
Hello, <%- myMaliciousHtml %>.
Hello, <%= myMaliciousHtml %>.
```
```json title="locals"
{
"myHtml": "Rspack",
"myMaliciousHtml": ""
}
```
```html title="html"
Hello, <strong>Rspack</strong>.
Hello, Rspack.
Hello, </p><script>document.write()</script><p>.
Hello,
.
```
#### 控制语句
以下示例结合使用 `for in` 遍历和 `if` 条件判断：
```txt title="ejs"
<% for tag in htmlRspackPlugin.tags.headTags { %>
<% if tag.tagName=="script" { %>
<%= toHtml(tag) %>
<% } %>
<% } %>
```
## Hooks
HtmlRspackPlugin 提供了多个 hooks，可用于修改生成的标签和 HTML。通过 `rspack.HtmlRspackPlugin.getCompilationHooks` 可以获取这些 hooks：
传给插件构造函数的原始选项可通过 `data.plugin.options` 访问。额外的自定义字段也会保留在这里，供 hook 使用，但这些字段本身不会影响 HTML 的生成。
```js title="rspack.config.mjs"
const HtmlModifyPlugin = {
apply(compiler) {
compiler.hooks.compilation.tap('HtmlModifyPlugin', (compilation) => {
const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
// hooks.beforeAssetTagGeneration.tapPromise()
// hooks.alterAssetTags.tapPromise()
// hooks.alterAssetTagGroups.tapPromise()
// hooks.afterTemplateExecution.tapPromise()
// hooks.beforeEmit.tapPromise()
// hooks.afterEmit.tapPromise()
});
},
};
export default {
plugins: [new rspack.HtmlRspackPlugin(), HtmlModifyPlugin],
};
```
### beforeAssetTagGeneration
该 hook 会在插件从 `compilation` 中收集完产物 URL 后、生成标签前调用。
通过修改 `assets.js`、`assets.css` 或 `assets.favicon`，可以添加或替换用于生成标签的 URL。新增值会被直接使用：插件不会为其添加 `publicPath`，也不会输出对应文件。
- **类型：** `AsyncSeriesWaterfallHook<[BeforeAssetTagGenerationData]>`
- **参数：**
```ts
type BeforeAssetTagGenerationData = {
assets: {
publicPath: string;
js: Array;
css: Array;
favicon?: string;
jsIntegrity?: Array;
cssIntegrity?: Array;
};
outputName: string;
plugin: {
options: HtmlRspackPluginOptions;
};
};
```
:::warning 警告
只有对 `assets.js`、`assets.css` 和 `assets.favicon` 的修改会影响插件自动生成的标签。其他字段不会影响自动生成标签，但模板仍可通过 `htmlRspackPlugin.files` 读取这些字段。
:::
以下示例添加了 URL `extra-script.js`，最终 HTML 中会生成对应的 `` 标签。
```js title="rspack.config.mjs"
const AddScriptPlugin = {
apply(compiler) {
compiler.hooks.compilation.tap('AddScriptPlugin', (compilation) => {
const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
hooks.beforeAssetTagGeneration.tapPromise(
'AddScriptPlugin',
async (data) => {
data.assets.js.push('extra-script.js');
},
);
});
},
};
export default {
plugins: [new rspack.HtmlRspackPlugin(), AddScriptPlugin],
};
```
### alterAssetTags
该 hook 会在根据产物 URL 生成标签后、将标签分配到 `` 或 `` 前调用。通过修改 `assetTags`，可以添加、删除或更新标签。
- **类型：** `AsyncSeriesWaterfallHook<[AlterAssetTagsData]>`
- **参数：**
```ts
type HtmlTag = {
tagName: string;
attributes: Record;
voidTag: boolean;
innerHTML?: string;
asset?: string;
};
type AlterAssetTagsData = {
assetTags: {
scripts: Array;
styles: Array;
meta: Array;
};
publicPath: string;
outputName: string;
plugin: {
options: HtmlRspackPluginOptions;
};
};
```
:::warning 警告
只有对 `assetTags` 的修改会影响生成的 HTML；其他字段的变化会被忽略。
:::
属性名会统一转换为小写，属性值则按以下规则处理：
- **`true`：** 添加无值属性，例如 ``。
- **字符串：** 添加带有该值的属性，例如 ``。
- **`false`、`undefined` 或 `null`：** 移除该属性。
以下示例会为所有 ``：
```js title="rspack.config.mjs"
const InjectContentPlugin = {
apply(compiler) {
compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => {
const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
hooks.afterTemplateExecution.tapPromise(
'InjectContentPlugin',
async (data) => {
data.html = data.html.replace('', 'Injected by plugin');
},
);
});
},
};
export default {
plugins: [
new rspack.HtmlRspackPlugin({
inject: 'body',
}),
InjectContentPlugin,
],
};
```
### beforeEmit
该 hook 会在 HTML 产物输出前调用，也是修改产物内容的最后机会。
- **类型：** `AsyncSeriesWaterfallHook<[BeforeEmitData]>`
- **参数：**
```ts
type BeforeEmitData = {
html: string;
outputName: string;
plugin: {
options: HtmlRspackPluginOptions;
};
};
```
:::warning 警告
只有对 `html` 的修改会影响最终产物；其他字段的变化会被忽略。
:::
以下示例会在 `` 结尾添加 `Injected by plugin`，最终顺序为 `Injected by plugin`：
```js title="rspack.config.mjs"
const InjectContentPlugin = {
apply(compiler) {
compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => {
const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
hooks.beforeEmit.tapPromise('InjectContentPlugin', async (data) => {
data.html = data.html.replace('', 'Injected by plugin');
});
});
},
};
export default {
plugins: [
new rspack.HtmlRspackPlugin({
inject: 'body',
}),
InjectContentPlugin,
],
};
```
### afterEmit
该 hook 会在 HTML 产物输出后调用，仅用于通知产物已生成。
- **类型：** `AsyncSeriesWaterfallHook<[AfterEmitData]>`
- **参数：**
```ts
type AfterEmitData = {
outputName: string;
plugin: {
options: HtmlRspackPluginOptions;
};
};
```