跳转到内容

路由参考

Astro 中没有单独的路由配置。

位于特殊的 src/pages/ 目录中的每个受支持的页面文件都会创建一个路由。当文件名包含参数时，路由可以动态创建多个页面，否则它会创建一个单页面。

默认情况下，所有 Astro 页面路由和端点都在构建时生成和预渲染。按需服务器渲染可以为单个路由设置，也可以作为默认设置。

预渲染

“prerender”小节

类型： boolean
默认值：在静态模式下（默认）为 true；在配置了 output: 'server' 时为 false

添加于： astro@1.0.0

从每个单独的路由导出的一个值，用于确定它是否被预渲染。

默认情况下，所有页面和端点都会被预渲染，并在构建时静态生成。你可以在一个或多个路由上选择退出预渲染，并且你可以在同一个项目中同时拥有静态和按需渲染的路由。

逐页覆盖

“逐页覆盖”小节

你可以通过从文件中导出值为 false 的 prerender 来覆盖默认值，从而为单个路由启用按需渲染。

src/pages/rendered-on-demand.astro
---
export const prerender = false
---
<!-- server-rendered content -->
<!-- the rest of my site is static -->

切换到 server 模式

“切换到服务器模式”小节

你可以通过配置 output: 'server' 来为所有路由覆盖默认值。在此输出模式下，默认情况下，所有页面和端点都将在请求时在服务器上生成，而不是被预渲染。

在 server 模式下，通过从文件中导出值为 true 的 prerender 来为单个路由启用预渲染。

src/pages/static-about-page.astro
---
// with `output: 'server'` configured
export const prerender = true
---
<!-- My static about page -->
<!-- All other pages are rendered on demand -->

局部

“partial”小节

类型： boolean
默认值： false

新增于： astro@3.4.0

从单个路由导出的一个值，用于确定它是否应作为完整的 HTML 页面进行渲染。

默认情况下，位于保留的 src/pages/ 目录中的所有文件都会自动包含 <!DOCTYPE html> 声明和额外的 <head> 内容，例如 Astro 的作用域样式和脚本。

你可以通过从文件中导出 partial 的值来覆盖默认值，从而将内容指定为单个路由的页面局部。

src/pages/my-page-partial.astro
---
export const partial = true
---
<!-- Generated HTML available at a URL -->
<!-- Available to a rendering library -->

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

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

getStaticPaths()

“getStaticPaths()”小节

类型： (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult

添加于： astro@1.0.0

一个函数，用于从单个文件路径中包含一个或多个参数的 .astro 页面组件中生成多个预渲染的页面路由。此函数用于在构建时创建路由，也称为静态站点生成。

getStaticPaths() 函数必须返回一个对象数组，以确定 Astro 将预渲染哪些 URL 路径。每个对象必须包含一个 params 对象来指定路由路径。该对象可以选择性地包含一个 props 对象，其中包含要传递给每个页面模板的数据。

src/pages/blog/[post].astro
---
// In 'server' mode, opt in to prerendering:
// export const prerender = true


export async function getStaticPaths() {
  return [
    // { params: { /* required */ }, props: { /* optional */ } },
    { params: { post: '1' } }, // [post] is the parameter
    { params: { post: '2' } }, // must match the file name
    // ...
  ];
}
---
<!-- Your HTML template here. -->

getStaticPaths() 也可以在静态文件端点中用于动态路由。

params

“params”小节

getStaticPaths() 返回的数组中每个对象的 params 键告诉 Astro 要构建哪些路由。

params 中的键必须与组件文件路径中定义的参数匹配。每个 params 对象的值必须与页面名称中使用的参数匹配。params 被编码到 URL 中，因此只支持字符串作为值。

例如，src/pages/posts/[id].astro 的文件名中有一个 id 参数。这个 .astro 组件中的以下 getStaticPaths() 函数告诉 Astro 在构建时静态生成 posts/1、posts/2 和 posts/3。

src/pages/posts/[id].astro
---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}


const { id } = Astro.params;
---
<h1>{id}</h1>

使用 props 传递数据

“使用 props 传递数据”小节

要将额外的数据传递给每个生成的页面，你可以在 getStaticPaths() 返回的数组中的每个对象上设置一个 props 值。与 params 不同，props 不会被编码到 URL 中，因此不限于只能是字符串。

例如，如果你使用从远程 API 获取的数据生成页面，你可以在 getStaticPaths() 内部将完整的数据对象传递给页面组件。页面模板可以使用 Astro.props 引用每篇文章的数据。

src/pages/posts/[id].astro
---
export async function getStaticPaths() {
  const response = await fetch('...');
  const data = await response.json();


  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post },
    };
  });
}


const { id } = Astro.params;
const { post } = Astro.props;
---
<h1>{id}: {post.name}</h1>

paginate()

“paginate()”小节

添加于： astro@1.0.0

一个可以从 getStaticPaths() 返回的函数，用于将内容项集合分割成多个单独的页面。

paginate() 将自动生成从 getStaticPaths() 返回所需的数组，为你的分页集合的每个页面创建一个 URL。页码将作为 param 传递，页面数据将作为 page prop 传递。

下面的例子获取并传递 150 个项目给 paginate 函数，并在构建时创建静态、预渲染的页面，每页将显示 10 个项目。

src/pages/pokemon/[page].astro
---
export async function getStaticPaths({ paginate }) {
  // Load your data with fetch(), getCollection(), etc.
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;


  // Return a paginated collection of paths for all items
  return paginate(allPokemon, { pageSize: 10 });
}


const { page } = Astro.props;
---

paginate() 有以下参数：

  • data - 包含传递给 paginate() 函数的页面数据的数组
  • options - 可选对象，具有以下属性：
    • pageSize - 每页显示的项目数（默认为 10）
    • params - 发送用于创建动态路由的附加参数
    • props - 发送可在每个页面上使用的附加 props

paginate() 假定文件名为 [page].astro 或 [...page].astro。page 参数成为你 URL 中的页码：

  • /posts/[page].astro 会生成 /posts/1、/posts/2、/posts/3 等 URL。
  • /posts/[...page].astro 会生成 /posts、/posts/2、/posts/3 等 URL。

分页 page prop

“分页页面 prop”小节

类型： Page<TData>

分页功能会向每个渲染的页面传递一个 page prop，它代表了分页集合中单个页面的数据。这包括你已分页的数据 (page.data) 以及页面的元数据 (page.url, page.start, page.end, page.total 等)。这些元数据对于像“下一页”按钮或“显示 100 条中的 1-10 条”这样的信息很有用。

page.data
“page.data”小节

类型： Array<TData>

从 paginate() 函数返回的当前页面的数据数组。

page.start
“page.start”小节

类型： number

当前页面上第一项的索引，从 0 开始。（例如，如果 pageSize: 25，则在第 1 页为 0，第 2 页为 25，以此类推。）

page.end
“page.end”小节

类型： number

当前页面最后一项的索引。

page.size
“page.size”小节

类型： number
默认值： 10

每页的项目总数。

page.total
“page.total”小节

类型： number

所有页面上的项目总数。

page.currentPage
“page.currentPage”小节

类型： number

当前页码，从 1 开始。

page.lastPage
“page.lastPage”小节

类型： number

页面总数。

page.url.current
“page.url.current”小节

类型： string

获取当前页面的 URL（对规范 URL 很有用）。如果为 base 设置了值，URL 将以该值开头。

page.url.prev
“page.url.prev”小节

类型： string | undefined

获取上一页的 URL（如果在第 1 页，则为 undefined）。如果为 base 设置了值，则在 URL 前添加基本路径。

page.url.next
“page.url.next”小节

类型： string | undefined

获取下一页的 URL（如果没有更多页面，则为 undefined）。如果为 base 设置了值，则在 URL 前添加基本路径。

page.url.first
“page.url.first”小节

类型： string | undefined

添加于： astro@4.12.0

获取第一页的 URL（如果在第 1 页，则为 undefined）。如果为 base 设置了值，则在 URL 前添加基本路径。

page.url.last
“page.url.last”小节

类型： string | undefined

添加于： astro@4.12.0

获取最后一页的 URL（如果没有更多页面，则为 undefined）。如果为 base 设置了值，则在 URL 前添加基本路径。

贡献 社区 赞助