> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # HTML 模板 Modern.js 提供了 **JSX 语法**和 **HTML(EJS) 语法**两种方式用于自定义 HTML 模板。 ## JSX 语法 Modern.js 约定，在 `src/` 或入口目录下，可以创建 `Document.tsx` 文件并默认导出组件，该组件的渲染结果可以作为入口的 HTML 模板。例如以下目录结构： ```bash . └── src ├── Document.tsx ├── entry-a │ ├── Document.tsx │ └── routes └── entry-b └── routes ``` `entry-a` 会优先使用当前入口下的 `Document.tsx` 文件。如果当前入口没有 `Document.tsx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.tsx` 文件。如果未找到，将会使用 Modern.js 的默认模板。 :::tip `Document.tsx` 会在构建时由 Modern.js 的 Document 插件创建 Rspack 子编译器流程，编译为面向 Node.js 的产物，并在编译时以 `renderToStaticMarkup` 渲染为字符串作为 HTML 模板内容，其行为类似[静态站点生成](/zh/guides/basic-features/render/ssg.md)。HTML 模板模块不会经过页面 Bundler 的常规编译打包，因此组件中的 React Hooks 不会在浏览器运行时被执行，也不支持导入 JavaScript 以外的图片等资源模块。 ::: ### HTML 组件 Modern.js 提供了一系列渲染页面的组件，用来帮助开发者生成模板，可以从 `@modern-js/runtime/document` 中使用这些组件： ```tsx import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document'; ``` 这些组件分别用于渲染： - `Html`：提供原生 HTML Element 的能力，并能默认渲染开发者未添加的必须的组件。`` 和 `` 是必须要存在的，其它组件可以按需选择合适的组件进行组装。 - `Body`：提供原生 Body Element 的能力，内部需要包含 `` 组件，也支持其它元素同时作为子元素，例如添加页脚。 - `Root`：渲染的根节点 `

`。默认根节点的 `id = 'root'`。可以设置 `props.rootId` 来更改 id 属性。可以添加子组件，也会被渲染到 HTML 模板中，当 React 渲染完成后会被覆盖，一般用来实现全局 Loading。 - `Head`：提供原生 Head Element 的能力，并会自动填充 ``，以及 `` 组件。 - `Scripts`：用于控制构建生成的 `

以下为构建时传过来的参数：

entryName: sub

title:

rootId: root

bottom

``` ### Scripts 组件示例你可以使用 `` 组件，将构建生成的 ` ``` :::info 自定义 HTML 片段的实现方式是将片段与框架内置的模板进行合并，由于框架的默认模板中已经存在 ``，因此自定义 HTML 模板中的 title 标签无法生效，请通过 [html.title](/zh/configure/app/html/title.md) 来修改页面标题。 ::: ### 完全自定义 HTML 模板某些情况下，HTML 片段无法满足自定义需求，Modern.js 提供了完全自定义方式。 :::caution 注意通常不建议直接覆盖默认的 HTML 模板，可能会失去一部分功能选项。即使需要替换，建议以内置模板为基础，按需修改。 ::: 在 `config/html/` 目录下，创建 `index.html` 文件,该文件将替代默认的 HTML 模板。 :::info 内部默认 HTML 模板可以在 `node_modules/.modern-js/${entryName}/index.html` 中查看。 ::: ### 模板参数模板中使用的参数可以通过 [html.templateParameters](/zh/configure/app/html/template-parameters.md) 配置项来定义。 ### 按入口设置 `config/html/` 目录中的 HTML 片段对应用中的所有入口都生效。如果希望按入口自定义 HTML 片段，可以在 `config/html/` 目录下新建一个以**入口名**命名的目录，然后在这个目录中自定义 HTML 片段。例如，如下设置的 HTML 片段仅对入口 `entry1` 生效： ```bash . ├── config/ │ └── html/ │ └── entry1 │ ├── head.html │ └── body.html └── src/ ├── entry1/ │ └── routes └── entry2/ └── routes ```