页面
页面是位于 Astro 项目的 src/pages/
子目录中的文件。它们负责处理路由、数据加载以及网站中每个页面的整体页面布局。
支持的页面文件
段落标题 支持的页面文件Astro 支持 src/pages/
目录中的以下文件类型:
基于文件的路由
段落标题 基于文件的路由Astro 使用一种名为 基于文件的路由 的路由策略。src/pages/
目录中的每个文件都会根据其文件路径成为网站上的一个端点。
一个文件也可以使用动态路由来生成多个页面。这允许你即使内容不在特殊的 /pages/
目录中,也可以创建页面,例如在内容集合或内容管理系统中。
页面之间的链接
段落标题 页面之间的链接在你的 Astro 页面中,使用标准的 HTML <a>
元素来链接到网站上的其他页面。这需要使用 相对于根域名的 URL 路径 作为你的链接,而不是相对文件路径。
例如,要从 example.com
上的任何其他页面链接到 https://example.com/authors/sonali/
,你可以像这样:
Astro 页面
段落标题 Astro 页面Astro 页面使用 .astro
文件扩展名,并支持与 Astro 组件相同的功能。
一个页面必须生成完整的 HTML 文档。如果没有显式包含,Astro 将会自动为位于 src/pages/
目录下的任何 .astro
组件默认添加必要的 <!DOCTYPE html>
声明和 <head>
内容。你可以通过将组件标记为局部页面来为每个组件避免这种行为。
为了避免在每个页面上重复相同的 HTML 元素,你可以将常见的 <head>
和 <body>
元素移动到自己的 布局组件 中。你可以使用任意多的布局组件。
Markdown/MDX 页面
段落标题 Markdown/MDX 页面Astro 还将 src/pages/
目录中的任何 Markdown (.md
) 文件视为网站中的页面。如果你安装了 MDX 集成,它也会将 MDX (.mdx
) 文件视为相同的页面。
当内容为博客文章或者产品项目这类共享相似结构的相关 Markdown 文件时,请考虑创建 内容集合 而不是页面。
Markdown 文件可以使用特殊的 layout
前置属性来指定一个 布局组件,它将包装其 Markdown 内容在一个完整的 <html>...</html>
页面文档中。
HTML 页面
段落标题 HTML 页面.html
文件扩展名的文件可以放在 src/pages/
中,并直接用作网站上的页面。请注意,某些关键的 Astro 功能在 HTML 组件 中不受支持。
自定义 404 错误页面
段落标题 自定义 404 错误页面想要自定义 404 错误页面,你可以在 src/pages
中创建 404.astro
或 404.md
文件。
它将生成 404.html
页面。大多数部署服务都自动找到并使用它。
自定义 500 错误页面
段落标题 自定义 500 错误页面要为按需渲染的页面 (EN)创建自定义的 500 错误页面,可以创建一个 src/pages/500.astro
文件。但这个自定义页面不适用于预渲染的页面,也不能被预渲染。
如果在渲染此页面时发生错误,将显示主机默认的 500 错误页面给访问者。
添加于:
astro@4.10.3
在开发过程中,如果你有一个 500.astro
文件,运行时抛出的错误将被记录在终端中,而不是显示在错误覆盖层中。
error
段落标题 error
添加于:
astro@4.11.0
src/pages/500.astro
是一个特殊页面,它会在渲染过程中对抛出的任何错误都会自动传递一个 error
属性。这允许你向访客展示详细的错误信息(例如来自页面、中间件等)。
错误属性的数据类型可以是任何类型,这可能会影响你在代码中的定义或使用值的方式:
为了避免在展示内容时从 error
属性中显示敏感信息,请首先考虑评估错误,并根据抛出的错误返回适当的内容。例如,应避免显示错误的堆栈,因为它包含有关服务器上代码结构的信息。
局部页面
段落标题 局部页面
添加于:
astro@3.4.0
局部页面是位于 src/pages/
目录中的页面组件,但不会作为完整页面进行渲染。
与位于此文件夹之外的组件一样,这些文件不会自动包含 <!DOCTYPE html>
声明,也不会包含任何作用域样式和脚本的 <head>
内容。
不过,由于它们位于特殊的 src/pages/
目录中,所以生成的 HTML 可以通过与文件路径相对应的 URL 来访问。这允许渲染库(如 htmx、Stimulus、jQuery 等)在客户端访问它,并在页面上动态加载 HTML 的部分,而无需刷新浏览器或进行页面导航。
局部页面与渲染库结合时,局部页面提供了一种可以代替 Astro 岛屿和 <script>
标签方式用于在 Astro 中构建动态内容的方法。
可以导出值(例如.astro
,.mdx
)的页面文件将被标记为局部页面。
通过添加以下导出项来将 src/pages/
目录中的文件配置为局部页面:
export const partial
必须是静态标识。它可以是以下值之一:
- 布尔值
true
。 - 使用
import.meta.env
的环境变量,如import.meta.env.USE_PARTIALS
。
和库搭配使用
段落标题 和库搭配使用局部页面用于使用诸如 htmx 的库动态更新页面的某个部分。
下面的示例展示了将 hx-post
属性设置为局部页面的 URL。局部页面的内容将用于更新此页面上目标 HTML 元素的内容。
.astro
局部页面必须在相应的文件路径中存在,并且包含一个导出定义将页面定义为局部页面:
参见 htmx 文档以了解更多关于使用 htmx 的细节。
Learn