Skip to content
Astro Astro

页面

页面 是位于 Astro 项目的 src/pages/ 子目录中的文件。 他们负责处理网站中每个页面的路由、数据加载和整体页面布局。

英Pages are files that live in the src/pages/ subdirectory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website.

支持的页面文件

Section titled 支持的页面文件

Astro 支持 src/pages/ 目录中的以下文件类型：

基于文件的路由

Section titled 基于文件的路由

Astro 利用名为 基于文件的路由 的路由策略。 src/pages/ 目录中的每个文件都会根据其文件路径成为站点上的端点。

英Astro leverages a routing strategy called file-based routing. Each file in your src/pages/ directory becomes an endpoint on your site based on its file path.

单个文件也可以使用 动态路由 生成多个页面。 即使你的内容位于特殊 /pages/ 目录之外（例如在 内容收集 或 CMS 中），这也允许你创建页面。

英A single file can also generate multiple pages using dynamic routing. This allows you to create pages even if your content lives outside of the special /pages/ directory, such as in a content collection or a CMS.

📚 了解有关 Astro 中的路由 的更多信息。

英📚 Read more about Routing in Astro.

页面之间的链接

Section titled 页面之间的链接

在你的 Astro 页面中编写标准 HTML <a> 元素 以链接到你网站上的其他页面。 使用 相对于你的根域的 URL 路径 作为链接，而不是相对文件路径。

英Write standard HTML <a> elements in your Astro pages to link to other pages on your site. Use a URL path relative to your root domain as your link, not a relative file path.

例如，要从 example.com 上的任何其他页面链接到 https://example.com/authors/sonali/：

英For example, to link to https://example.com/authors/sonali/ from any other page on example.com:

src/pages/index.astro
Read more <a href="/authors/sonali/">about Sonali</a>.

Astro 页面

Section titled Astro 页面

Astro 页面使用 .astro 文件扩展名并支持与 Astro 组件 相同的功能。

英Astro pages use the .astro file extension and support the same features as Astro components.

src/pages/index.astro
---
---
<html lang="en">
  <head>
    <title>My Homepage</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

页面必须生成完整的 HTML 文档。 如果没有明确包含，Astro 默认情况下会将必要的 <!DOCTYPE html> 声明和 <head> 内容添加到位于 src/pages/ 内的任何 .astro 组件中。 你可以通过将每个组件标记为 partial 页面来选择退出此行为。

英A page must produce a full HTML document. If not explicitly included, Astro will add the necessary <!DOCTYPE html> declaration and <head> content to any .astro component located within src/pages/ by default. You can opt-out of this behavior on a per-component basis by marking it as a partial page.

为了避免在每个页面上重复相同的 HTML 元素，你可以将常见的 <head> 和 <body> 元素移动到你自己的 布局组件 中。 你可以根据需要使用任意数量的布局组件。

英To avoid repeating the same HTML elements on every page, you can move common <head> and <body> elements into your own layout components. You can use as many or as few layout components as you’d like.

src/pages/index.astro
---
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout>
  <p>
  My page content, wrapped in a layout!
  </p>
</MySiteLayout>

📚 在 Astro 中阅读有关 布局组件 的更多信息。

英📚 Read more about layout components in Astro.

Markdown/MDX 页面

Section titled Markdown/MDX 页面

Astro 还将 src/pages/ 内的任何 Markdown (.md) 文件视为最终网站中的页面。 如果你有 已安装 MDX 集成，它也会以相同的方式处理 MDX (.mdx) 文件。 这些通常用于文本较多的页面，例如博客文章和文档。

英Astro also treats any Markdown (.md) files inside of src/pages/ as pages in your final website. If you have the MDX Integration installed, it also treats MDX (.mdx) files the same way. These are commonly used for text-heavy pages like blog posts and documentation.

src/content/ 中的 Markdown 或 MDX 页面内容的集合 可用于 动态生成页面。

英Collections of Markdown or MDX page content in src/content/ can be used to generate pages dynamically.

页面布局对于 Markdown 文件 特别有用。 Markdown 文件可以使用特殊的 layout frontmatter 属性来指定 布局组件，将其 Markdown 内容封装在完整的 <html>...</html> 页面文档中。

英Page layouts are especially useful for Markdown files. Markdown files can use the special layout frontmatter property to specify a layout component that will wrap their Markdown content in a full <html>...</html> page document.

src/pages/page.md
---
layout: '../layouts/MySiteLayout.astro'
title: 'My Markdown page'
---
# Title


This is my page, written in **Markdown.**

📚 在 Astro 中阅读有关 Markdown 的更多信息。

英📚 Read more about Markdown in Astro.

HTML 页面

Section titled HTML 页面

具有 .html 文件扩展名的文件可以放置在 src/pages/ 目录中并直接用作站点上的页面。 请注意，HTML 组件 不支持某些关键的 Astro 功能。

英Files with the .html file extension can be placed in the src/pages/ directory and used directly as pages on your site. Note that some key Astro features are not supported in HTML Components.

自定义 404 错误页面

Section titled 自定义 404 错误页面

对于自定义 404 错误页面，你可以在 /src/pages 中创建 404.astro 或 404.md 文件。

英For a custom 404 error page, you can create a 404.astro or 404.md file in /src/pages.

这将构建 404.html 页面。 大多数 部署服务 都会找到并使用它。

英This will build to a 404.html page. Most deploy services will find and use it.

页面部分

Section titled 页面部分
Added in: astro@3.4.0

:::caution 提醒 页面部分旨在与前端库结合使用，例如 htmx 或 安聚。 如果你擅长编写底层前端 JavaScript，也可以使用它们。 因此，它们是一项高级功能。

英Page partials are intended to be used in conjunction with a front-end library, such as htmx or Unpoly. You can also use them if you are comfortable writing low-level front-end JavaScript. For this reason they are an advanced feature.

此外，如果组件包含作用域样式或脚本，则不应使用部分元素，因为这些元素将从 HTML 输出中删除。 如果你需要范围样式，最好使用常规的非部分页面以及知道如何将内容合并到头部的前端库。 :::

部分页面组件位于 src/pages/ 内，不打算渲染为完整页面。

英Partials are page components located within src/pages/ that are not intended to render as full pages.

与位于此文件夹外部的组件一样，这些文件不会自动包含 <!DOCTYPE html> 声明，也不会自动包含任何 <head> 内容，例如作用域样式和脚本。

英Like components located outside of this folder, these files do not automatically include the <!DOCTYPE html> declaration, nor any <head> content such as scoped styles and scripts.

但是，由于它们位于特殊的 src/pages/ 目录中，因此生成的 HTML 可以通过与其文件路径对应的 URL 获得。 这允许渲染库（例如 htmx、Stimulus、jQuery）在客户端上访问它并在页面上动态加载 HTML 部分，而无需浏览器刷新或页面导航。

英However, because they are located in the special src/pages/ directory, the generated HTML is available at a URL corresponding to its file path. This allows a rendering library (e.g. htmx, Stimulus, jQuery) to access it on the client and load sections of HTML dynamically on a page without a browser refresh or page navigation.

当与渲染库结合使用时，Partials 提供了 Astro 群岛 和 <script> 标签 的替代方案，用于在 Astro 中构建动态内容。

英Partials, when combined with a rendering library, provide an alternative to Astro islands and <script> tags for building dynamic content in Astro.

可以导出值（例如 .astro 、 .mdx ）的页面文件可以标记为部分文件。

英Page files that can export a value (e.g. .astro , .mdx) can be marked as partials.

通过添加以下导出将 src/pages/ 目录中的文件配置为部分文件：

英Configure a file within the src/pages/ directory to be a partial by adding the following export:

src/pages/partial.astro
---
export const partial = true;
---


<li>I'm a partial!</li>

export const partial 必须可静态识别。 它可以具有以下值：

英The export const partial must be identifiable statically. It can have the value of:

  • 布尔值 true。
  • 使用 import.meta.env 的环境变量，例如 import.meta.env.USE_PARTIALS。

与库一起使用

Section titled 与库一起使用

部分用于使用 htmx 等库动态更新页面的一部分。

以下示例显示了设置为部分 URL 的 hx-post 属性。 部分页面的内容将用于更新该页面上的目标 HTML 元素。

src/pages/index.astro
<html>
  <head>
    <title>My page</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
</html>
<section>
  <div id="parent-div">Target here</div>


  <button hx-post="/partials/clicked/"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="innerHTML"
  >
      Click Me!
  </button>
</section>

.astro 部分必须存在于相应的文件路径中，并且包含将页面定义为部分的导出：

英The .astro partial must exist at the corresponding file path, and include an export defining the page as a partial:

src/pages/partials/clicked.astro
---
export const partial = true;
---
<div>I was clicked!</div>

有关使用 htmx 的更多详细信息，请参阅 htmx 文档。

英See the htmx documentation for more details on using htmx.