路由参考

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

¥There is no separate routing configuration in Astro.

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

¥Every supported page file located within the special src/pages/ directory creates a route. When the file name contains a parameter, a route can create multiple pages dynamically, otherwise it creates a single page.

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

¥By default, all Astro page routes and endpoints are generated and prerendered at build time. On-demand server rendering can be set for individual routes, or as the default.

`prerender`

类型：boolean
默认：true 处于静态模式（默认）；false 带有 output: 'server' 配置

¥Type: boolean
Default: true in static mode (default); false with output: 'server' configuration

Added in: astro@1.0.0

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

¥A value exported from each individual route to determine whether or not it is prerendered.

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

¥By default, all pages and endpoints are prerendered and will be statically generated at build time. You can opt out of prerendering on one or more routes, and you can have both static and on-demand rendered routes in the same project.

每页覆盖

¥Per-page override

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

¥You can override the default value to enable on demand rendering for an individual route by exporting prerender with the value false from that file:

---
export const prerender = false
---
<!-- server-rendered content -->
<!-- the rest of my site is static -->

切换到 `server` 模式

¥Switch to server mode

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

¥You can override the default value for all routes by configuring output: 'server'. In this output mode, all pages and endpoints will be generated on the server upon request by default instead of being prerendered.

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

¥In server mode, enable prerendering for an individual route by exporting prerender with the value true from that file:

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

`partial`

类型：boolean
默认：false

¥Type: boolean
Default: false

Added in: astro@3.4.0

从单个路由导出的值，以确定是否应将其渲染为完整的 HTML 页面。

¥A value exported from an individual route to determine whether or not it should be rendered as a full HTML page.

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

¥By default, all files located within the reserved src/pages/ directory automatically include the <!DOCTYPE html> declaration and additional <head> content such as Astro’s scoped styles and scripts.

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

¥You can override the default value to designate the content as a page partial for an individual route by exporting a value for partial from that file:

---
export const partial = true
---
<!-- Generated HTML available at a URL -->
<!-- Available to a rendering library -->

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。

`getStaticPaths()`

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

¥Type: (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult

Added in: astro@1.0.0

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

¥A function to generate multiple, prerendered page routes from a single .astro page component with one or more parameters in its file path. Use this for routes that will be created at build time, also known as static site building.

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

¥The getStaticPaths() function must return an array of objects to determine which URL paths will be prerendered by Astro. Each object must include a params object, to specify route paths. The object may optionally contain a props object with data to be passed to each page template.

---
// 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() 也可用于动态路由的静态文件端点。

¥getStaticPaths() can also be used in static file endpoints for dynamic routing.

`params`

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

¥The params key of each object in the array returned by getStaticPaths() tells Astro what routes to build.

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

¥The keys in params must match the parameters defined in your component file path. The value for each params object must match the parameters used in the page name. params are encoded into the URL, so only strings are supported as values.

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

¥For example,src/pages/posts/[id].astrohas an id parameter in its file name. The following getStaticPaths() function in this .astro component tells Astro to statically generate posts/1, posts/2, and posts/3 at build time.

---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

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

使用 `props` 传递数据

¥Data passing with props

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

¥To pass additional data to each generated page, you can set a props value on each object in the array returned by getStaticPaths(). Unlike params, props are not encoded into the URL and so aren’t limited to only strings.

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

¥For example, if you generate pages with data fetched from a remote API, you can pass the full data object to the page component inside of getStaticPaths(). The page template can reference the data from each post using Astro.props.

---
export async function getStaticPaths() {
  const data = await fetch('...').then(response => 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()`

Added in: astro@1.0.0

可以从 getStaticPaths() 返回的函数，用于将内容项集合划分为单独的页面。

¥A function that can be returned from getStaticPaths() to divide a collection of content items into separate pages.

paginate() 将自动生成从 getStaticPaths() 返回的必要数组，以便为分页集合的每一页创建一个 URL。页码将作为 param 传递，页面数据将作为 page 属性传递。

¥paginate() will automatically generate the necessary array to return from getStaticPaths() to create one URL for every page of your paginated collection. The page number will be passed as a param, and the page data will be passed as a page prop.

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

¥The following example fetches and passes 150 items to the paginate function, and creates static, prerendered pages at build time that will display 10 items per page:

---
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() 有以下参数：

¥paginate() has the following arguments:

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

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

¥paginate() assumes a file name of [page].astro or [...page].astro. The page param becomes the page number in your URL:

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

分页 `page` 属性

¥The pagination page prop

类型：Page<TData>

¥Type: Page<TData>

分页会将 page 属性传递给每个渲染的页面，该页面表示分页集合中的单页数据。这包括你已分页的数据 (page.data) 以及页面的元数据（page.url、page.start、page.end、page.total 等）。此元数据对于 “下一页” 按钮或 “显示第 1-10 条，共 100 条” 消息等内容很有用。

¥Pagination will pass a page prop to every rendered page that represents a single page of data in the paginated collection. This includes the data that you’ve paginated (page.data) as well as metadata for the page (page.url, page.start, page.end, page.total, etc). This metadata is useful for things like a “Next Page” button or a “Showing 1-10 of 100” message.

`page.data`

类型：Array<TData>

¥Type: Array<TData>

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

¥Array of data returned from the paginate() function for the current page.

`page.start`

类型：number

¥Type: number

当前页面上第一项的索引，从 0 开始。（例如，如果是 pageSize: 25，则第 1 页上的 0、第 2 页上的 25 等）

¥Index of the first item on the current page, starting at 0. (e.g. if pageSize: 25, this would be 0 on page 1, 25 on page 2, etc.)

`page.end`

类型：number

¥Type: number

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

¥Index of the last item on the current page.

`page.size`

类型：number
默认：10

¥Type: number
Default: 10

每页的总项目数。

¥The total number of items per page.

`page.total`

类型：number

¥Type: number

所有页面的项目总数。

¥The total number of items across all pages.

`page.currentPage`

类型：number

¥Type: number

当前页码，从 1 开始。

¥The current page number, starting with 1.

`page.lastPage`

类型：number

¥Type: number

总页数。

¥The total number of pages.

`page.url.current`

类型：string

¥Type: string

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

¥Get the URL of the current page (useful for canonical URLs). If a value is set for base, the URL starts with that value.

`page.url.prev`

类型：string | undefined

¥Type: string | undefined

获取上一页的 URL（如果在第一页，则为 undefined）。如果为 base 设置了值，则 URL 以该值开头。

¥Get the URL of the previous page (will be undefined if on the first page). If a value is set for base, the URL starts with that value.

`page.url.next`

类型：string | undefined

¥Type: string | undefined

获取下一页的 URL（如果在最后一页，则为 undefined）。如果为 base 设置了值，则 URL 以该值开头。

¥Get the URL of the next page (will be undefined if on the last page). If a value is set for base, the URL starts with that value.

`page.url.first`

类型：string

¥Type: string

获取第一页的 URL（如果在第一页，则为 undefined）。如果为 base 设置了值，则 URL 以该值开头。

¥Get the URL of the first page (will be undefined if on the first page). If a value is set for base, the URL starts with that value.

`page.url.last`

类型：string

¥Type: string

获取最后一页的 URL（如果在最后一页，则为 undefined）。如果为 base 设置了值，则 URL 以该值开头。

¥Get the URL of the last page (will be undefined if on the last page). If a value is set for base, the URL starts with that value.

`page.url.first`

类型：string | undefined

¥Type: string | undefined

Added in: astro@4.12.0

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

¥Get the URL of the first page (will be undefined if on page 1). If a value is set for base, prepend the base path to the URL.

`page.url.last`

类型：string | undefined

¥Type: string | undefined

Added in: astro@4.12.0

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

¥Get the URL of the last page (will be undefined if no more pages). If a value is set for base, prepend the base path to the URL.

路由参考

prerender

每页覆盖

切换到 server 模式

partial

getStaticPaths()

params

使用 props 传递数据

paginate()

分页 page 属性

page.data

page.start

page.end

page.size

page.total

page.currentPage

page.lastPage

page.url.current

page.url.prev

page.url.next

page.url.first

page.url.last

page.url.first

page.url.last

`prerender`

切换到 `server` 模式

`partial`

`getStaticPaths()`

`params`

使用 `props` 传递数据

`paginate()`

分页 `page` 属性

`page.data`

`page.start`

`page.end`

`page.size`

`page.total`

`page.currentPage`

`page.lastPage`

`page.url.current`

`page.url.prev`

`page.url.next`

`page.url.first`

`page.url.last`

`page.url.first`

`page.url.last`