API 参考

`Astro` global

Astro global 在 .astro 文件的所有上下文中都可用。它具有以下功能：

`Astro.glob()`

Astro.glob() 可以在静态网站 setup 中加载本地文件：

---
const posts = await Astro.glob('../pages/post/*.md'); // 返回位于 ./src/pages/post/*.md 的数组并存储在常量 posts 中
---

<div>
{posts.slice(0, 3).map((post) => (
  <article>
    <h1>{post.frontmatter.title}</h1>
    <p>{post.frontmatter.description}</p>
    <a href={post.frontmatter.url}>Read more</a>
  </article>
))}
</div>

.glob() 只需要一个参数：你想导入的本地文件相对 glob URL。它是异步的并返回数组，这个数组包含匹配文件的导出内容。

.glob() 不接受使用变量或字符串进行插值，因为它们不是静态可分析的。(参见故障排查以了解解决方法)。这是因为 Astro.glob() 是 Vite 的 import.meta.glob() 的包装器。

你也可以在你的 Astro 项目中使用 import.meta.glob()。你可能想在以下情况下这样做：

你在一个不是 .astro 的文件中需要这个功能，比如一个 API 路由。Astro.glob() 只在 .astro 文件中可用，而 import.meta.glob() 在项目的任何地方都可用。
你不希望立即加载每个文件。import.meta.glob() 可以返回导入文件内容的函数，而不是返回内容本身。请注意，此导入包括任何导入文件的所有样式和脚本。无论文件是否被实际使用，这些样式和脚本都将被捆绑并添加到页面中，因为这是由静态分析决定的，而不是在运行时决定的。
你想访问每个文件的路径。import.meta.glob() 返回文件路径到其内容的映射，而 Astro.glob() 返回内容的列表。
你想传递多种模式；例如，你想添加一个“负模式”，过滤掉某些文件。import.meta.glob() 可以选择接受 glob 字符串数组，而不是单个字符串。

在 Vite 文档中阅读更多内容。

Markdown 文件

使用 Astro.glob() 加载的 Markdown 文件返回以下 MarkdownInstance 接口：

export interface MarkdownInstance<T extends Record<string, any>> {
  /* 在此文件的 YAML frontmatter 中指定的任何数据 */
 frontmatter: T;
  /* 该文件的文件绝对路径 */
 file: string;
  /* 该文件的渲染路径 */
 url: string | undefined;
  /* 渲染此文件内容的 Astro 组件 */
 Content: AstroComponentFactory;
 /** (仅限 Markdown) Markdown 文件的原始内容，不包括布局 HTML 和 YAML frontmatter */
 rawContent(): string;
 /* (仅限 Markdown) Markdown 文件编译后的 HTML，不包括布局 HTML */
 compiledContent(): string;
 /* 返回该文件中 h1...h6 元素数组的函数 */
 getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
 default: AstroComponentFactory;
}

你可以选择使用 TypeScript 泛型指定 frontmatter 变量类型：

---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Astro 文件

Astro 文件具有以下接口：

export interface AstroInstance {
  /* 此文件的文件路径 */
  file: string;
  /* 此文件的 URL（如果它在 pages 目录中）*/
  url: string | undefined;
  default: AstroComponentFactory;
}

其他文件

其他文件可能有各种不同的接口，但如果你不知道文件类型包含什么，那么 Astro.glob() 可以接受 TypeScript 泛型。

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
---

`Astro.props`

Astro.props 是一个包含任何作为组件属性传递的值的对象。.md 和 .mdx 文件的布局组件接收作为参数的 frontmatter 值。

---
const { title, date } = Astro.props;
---
<div>
    <h1>{title}</h1>
    <p>{date}</p>
</div>

---
import Heading from '../components/Heading.astro';
---
<Heading title="我的第一篇文章" date="09 Aug 2022" />

进一步了解关于 Markdown 和 MDX 布局如何处理 props 的内容。

了解如何为你的 props 添加 TypeScript 类型定义的内容。

`Astro.params`

Astro.params 是一个包含与此请求匹配的动态路由段的值的对象。

在静态构建中，这将是 getStaticPaths() 返回的params，用于预渲染动态路由.。

在 SSR 构建中，这可以是与动态路由模式中的路径段匹配的任何值。

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

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

另见：params

`Astro.request`

类型：Request

Astro.request 是标准的 Request 对象。它可以用来获取请求的 url、headers、method，甚至是 body。可以使用 new URL(Astro.request.url) 来获得链接对象。

<p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
<p>Received request headers: <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>

另见：Astro.url

`Astro.response`

类型：ResponseInit & { readonly headers: Headers }

Astro.response 是标准的 ResponseInit 对象，它具有以下结构：

status：响应的状态码，例如 200。
statusText：响应状态码与之相对应的状态信息，例如 OK。
headers：一个能让你为响应设置 HTTP 头部的 Headers 实例。

所以 Astro.response 也用于设置页面响应的 status、statusText 和 headers。

---
if(condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---

或者设置 header：

---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---

`Astro.cookies`

类型：AstroCookies

添加于： astro@1.4.0

Astro.cookies 包含用于在服务端渲染模式下读取和操作 cookie 的工具方法。

`get`

类型：(key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

获取 AstroCookie 对象形式的 cookie，该对象包含value和用于将 cookie 转换为非字符串类型的工具方法。

`has`

类型：(key: string, options?: AstroCookieGetOptions) => boolean

用于判断 cookie 是否存在。如果这个 cookie 已经通过Astro.cookies.set()设置，这将返回 true，否则它将检查 Astro.request 中的 cookies。

`set`

类型：(key: string, value: string | object, options?: AstroCookieSetOptions) => void

将 cookie key 设置为给定的值。这将试图把 cookie 的值转换为一个字符串。选项提供了设置 cookie 功能的方法，例如 maxAge 或 httpOnly。

`delete`

类型：(key: string, options?: AstroCookieDeleteOptions) => void

通过设置过去的到期日期（Unix 时间为 0）使 cookie 失效。

一旦 Cookie 被“删除”（过期），Astro.cookies.has() 将返回 false，Astro.cookies.get() 将返回一个 value 为 undefined 的 AstroCookie。删除 Cookie 时可用的选项包括：domain、path、httpOnly、sameSite 和 secure。

`merge`

类型：(cookies: AstroCookies) => void

将新的 AstroCookies 实例合并到当前实例中。任何新的 cookie 将被添加到当前实例中，任何具有相同名称的 cookie 将覆盖现有值。

`headers`

类型：() => Iterator<string>

获取将与响应一起发送的 Set-Cookie 的 header 的值。

`AstroCookie`

通过 Astro.cookies.get() 获取 cookie 返回一个 AstroCookie 类型。它具有以下结构。

`value`

类型：string

cookie 的原始字符串值。

`json`

类型：() => Record<string, any>

通过 JSON.parse() 解析 cookie 值，返回一个对象。如果 cookie 值不是有效的 JSON，则抛出异常。

`number`

类型：() => number

将 cookie 值解析为数字。如果不是有效数字，则返回 NaN。

`boolean`

类型：() => boolean

转换 cookie 的值为 boolean 类型。

`AstroCookieGetOptions`

添加于： astro@4.1.0

获取 cookie 允许通过 AstroCookieGetOptions 接口指定选项：

`decode`

类型：(value: string) => string

允许自定义如何将 cookie 反序列化为值。

`AstroCookieSetOptions`

添加于： astro@4.1.0

通过 Astro.cookies.set() 设置 cookie，允许传入 AstroCookieSetOptions 来自定义 cookie 如何被序列化。

`domain`

类型：string

指定域。如果未设置域，则大多数客户端将解释为应用于当前域。

`expires`

类型：Date

指定 cookie 过期日期。

`httpOnly`

类型：boolean

如果为 true，则客户端将无法访问该 Cookie。

`maxAge`

类型：number

以秒为单位指定 cookie 有效的时间。

`path`

类型：string

指定应用 cookie 的域的子路径。

`sameSite`

类型：boolean | 'lax' | 'none' | 'strict'

指定 SameSite cookie header 的值。

`secure`

类型：boolean

如果为 true，则该 Cookie 仅在 https 网站上设置。

`encode`

类型：(value: string) => string

允许自定义 cookie 序列化方式。

`Astro.redirect()`

类型：(path: string, status?: number) => Response

允许你重定向到另一个页面，并可选地提供一个 HTTP 响应状态码作为第二个参数。

页面（而不是子组件）必须 return Astro.redirect() 的结果，以便重定向发生。

对于静态生成的网站，这将使用 <meta http-equiv="refresh"> 标签实现客户端重定向，并且不支持状态码。

使用按需渲染模式时，支持状态码。除非指定其他代码，否则 Astro 将以默认的 HTTP 302 响应状态码实现重定向请求。

以下示例将用户重定向到登录页面：

---
import { isLoggedIn } from '../utils';

const cookie = Astro.request.headers.get('cookie');

// 如果用户未登录，则将其重定向到登录页面
if (!isLoggedIn(cookie)) {
  return Astro.redirect('/login');
}
---

`Astro.rewrite()`

类型：(rewritePayload: string | URL | Request) => Promise<Response>

添加于： astro@4.13.0

允许你从不同的 URL 或路径提供内容，而不会将浏览器重定向到新页面。

该方法接受字符串、URL 或 Request 作为路径的位置。

使用字符串提供一个明确的路径：

---
return Astro.rewrite("/login")
---

当你需要构造重写的 URL 路径时，使用 URL 类型。以下示例通过从相对路径 "../" 创建一个新的 URL 来呈现页面的父路径：

---
return Astro.rewrite(new URL("../", Astro.url))
---

使用 Request 类型完全控制发送到新路径的 Request。以下示例发送一个请求来渲染父页面，同时提供标头：

---
return Astro.rewrite(new Request(new URL("../", Astro.url), {
  headers: {
    "x-custom-header": JSON.stringify(Astro.locals.someValue)
  }
}))
---

`Astro.url`

类型：URL

添加于： astro@1.0.0-rc

由当前 Astro.request.url 的链接字符串值构造的 URL对象。对于与请求链接的某些属性进行交互很有用，例如 pathname 和 origin。

相当于 new URL(Astro.request.url)。

如果 site 未配置为静态站点或者使用 server 或 hybrid 输出的按需渲染站点，Astro.url 在开发模式下将是 localhost。

<h1>当前链接是：{Astro.url}</h1>
<h1>当前链接路径名是：{Astro.url.pathname}</h1>
<h1>当前链接源是：{Astro.url.origin}</h1>

你也可以使用 Astro.url 来创建新的链接，并把它作为参数传给 new URL()。

---
// 示例：使用你的生产域名构建一个规范的URL
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// 示例：使用你目前的域名构建一个用于 SEO meta 标签的URL
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />

`Astro.clientAddress`

类型：string

添加于： astro@1.0.0-rc

指定请求的 IP 地址。这个属性只在为 SSR（服务器端渲染）构建时可用，不应该用于静态网站。

---
const ip = Astro.clientAddress;
---

<div>你的 IP 地址是：<span class="address">{ ip }</span></div>

`Astro.site`

类型：URL | undefined

Astro.site 返回根据 Astro 配置中的 site 生成的 URL。如果未定义 Astro 配置中的 site，Astro.site 也不会被定义。

`Astro.generator`

类型：string

添加于： astro@1.0.0

Astro.generator 是个便捷方法，它可以添加与你当前 Astro 版本一致的 <meta name="generator"> 标签。它遵循的格式是 "Astro v1.x.x"。

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>由 <a href="https://astro.build">{Astro.generator}</a> 构建</p>
    </footer>
  </body>
</html>

`Astro.slots`

Astro.slots 包含修改 Astro 组件插槽的工具函数。

`Astro.slots.has()`

类型：(slotName: string) => boolean

你可以使用 Astro.slots.has() 检查特定插槽名称的内容是否存在。当你想要包装插槽内容，但只想在使用插槽时呈现包装器元素时，这会很有用。

---
---
<slot />

{Astro.slots.has('more') && (
  <aside>
    <h2>More</h2>
    <slot name="more" />
  </aside>
)}

`Astro.slots.render()`

类型：(slotName: string, args?: any[]) => Promise<string>

你可以使用 Astro.slots.render() 将插槽的内容异步渲染为 HTML 字符串。

---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />

Astro.slots.render() 还可以接受第二个参数：一个参数数组，该参数数组将被转发给任何函数子组件。这对于自定义实用程序组件很有用。

举个例子，这个 <Shout /> 组件将它的 message 属性转换为大写，并将其传递给默认插槽：

---
const message = Astro.props.message.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [message]);
}
---
<Fragment set:html={html} />

作为 <Shout /> 的子级传递的回调函数将会接收到大写的 message 参数：

---
import Shout from "../components/Shout.astro";
---
<Shout message="slots!">
  {(message) => <div>{message}</div>}
</Shout>

<!-- 渲染成 <div>SLOTS!</div> -->

回调函数可以传递给带有 slot 属性并包装着 HTML 元素标签的具名插槽。这个元素仅用于将回调传递给具名插槽，而不会被渲染到页面上。

<Shout message="slots!">
  <fragment slot="message">
    {(message) => <div>{message}</div>}
  </fragment>
</Shout>

使用标准的 HTML 元素作为包装标签，或者使用任何小写标签（例如 <fragment> 而不是 <Fragment />），这些标签不会被解释为组件。不要使用 HTML 的 <slot> 元素，因为它会被解释为 Astro 插槽。

`Astro.self`

Astro.self 允许 Astro 组件被递归调用。这使得你可以通过在组件模板中使用 <Astro.self> 从自身内部渲染 Astro 组件。这对遍历大型数据存储和嵌套数据结构很有帮助。

---
const { items } = Astro.props;
---
<ul class="nested-list">
  {items.map((item) => (
    <li>
      <!-- 如果有嵌套的数据结构，将渲染 `<Astro.self>` -->
      <!-- 并可以通过递归调用来传递参数 -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>

然后，这个组件可以这样用：

---
import NestedList from './NestedList.astro';
---
<NestedList items={['A', ['B', 'C'], 'D']} />

之后将会渲染这样的 HTML：

<ul class="nested-list">
  <li>A</li>
  <li>
    <ul class="nested-list">
      <li>B</li>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

`Astro.locals`

添加于： astro@2.4.0

Astro.locals 是一个对象，包含来自中间件的 context.locals对象的任何值。使用该对象可访问中间件在你的 .astro 文件中返回的数据。

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<ul>
    {orders.map(order => {
        return <li>{ /* 每单都有收获 */ }</li>
    })}
</ul>

`Astro.preferredLocale`

类型：string | undefined

添加于： astro@3.5.0

Astro.preferredLocale 是一个代表当前用户的首选语言环境的计算出的值。

它是通过检查 i18n.locales 数组中配置的语言环境和用户浏览器通过头部 Accept-Language 指定的语言环境来计算的。如果不存在匹配项则该值为 undefined。

这个属性只在为 SSR（服务器端渲染）构建时可用，不应该用于静态网站。

`Astro.preferredLocaleList`

类型：string[] | undefined

添加于： astro@3.5.0

Astro.preferredLocaleList 是一个同时被浏览器请求并且你的网站也支持的语言环境的数组。它是一个由你的网站和你的访客共同支持的语言环境的列表。

如果浏览器请求的语言环境没有在你的网站中被支持，那么该值为 []：你不支持你的访客的任何首选语言环境。

如果浏览器没有指定任何首选语言环境，那么该值将是 i18n.locales：你支持的所有语言环境都将被同等视为访客倾向的语言环境。

这个属性只在为 SSR（服务器端渲染）构建时可用，不应该用于静态网站。

`Astro.currentLocale`

类型：string | undefined

添加于： astro@3.5.6

从当前 URL 使用你的 locales 配置中指定的语法计算出的语言环境。如果 URL 不包含 /[locale]/ 前缀，则该值将默认为 i18n.defaultLocale。

端点上下文

端点函数接收一个上下文对象作为第一个参数。它与许多 Astro 全局属性相似。

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

`context.params`

context.params 是一个对象，其中包含与此请求匹配的动态路由段的值。

在静态构建中，这将是用于预渲染动态路由的 getStaticPaths() 返回的 params。

在 SSR 构建中，这可以是与动态路由模式中的路径段匹配的任何值。

import type { APIContext } from 'astro';

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

export function GET({ params }: APIContext) {
  return new Response(
    JSON.stringify({ id: params.id }),
  );
}

另见：params

`context.props`

添加于： astro@1.5.0

context.props 是一个对象，其中包含从 getStaticPaths() 传递的任何 props。由于在为 SSR 构建时不使用 getStaticPaths()，因此 context.props 仅在静态构建中可用。

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' }, props: { author: 'Blu' } },
    { params: { id: '2' }, props: { author: 'Erika' } },
    { params: { id: '3' }, props: { author: 'Matthew' } }
  ];
}

export function GET({ props }: APIContext) {
  return new Response(
    JSON.stringify({ author: props.author }),
  );
}

另见：通过props传递数据

`context.request`

类型：Request

一个标准的 Request 对象。它可以用来获取请求的 url、headers、method 甚至是 body。

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Hello ${request.url}`);
}

另见：Astro.request

`context.cookies`

类型：AstroCookies

context.cookies 包含用于读取和操作 cookie 的工具。

另见：Astro.cookies

`context.url`

类型：URL

添加于： astro@1.5.0

context.url 是一个 URL 对象，它是从当前 context.request.url URL 字符串值构造的。

另见：Astro.url

`context.clientAddress`

类型：string

添加于： astro@1.5.0

指定请求的 IP 地址。此属性仅在构建 SSR（服务器端渲染）时可用，不应用于静态站点。

import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Your IP address is: ${clientAddress}`);
}

另见：Astro.clientAddress

`context.site`

类型：URL | undefined

添加于： astro@1.5.0

context.site 返回一个由 Astro 配置中的 site 生成的 URL。如果未定义，则将返回从 localhost 生成的 URL。

另见：Astro.site

`context.generator`

类型：string

添加于： astro@1.5.0

context.generator 是一个方便的方法，用于指示项目正在运行的 Astro 版本。它遵循 "Astro v1.x.x" 的格式。

import type { APIContext } from 'astro';

export function GET({ generator, site }: APIContext) {
  const body = JSON.stringify({ generator, site });
  return new Response(body);
}

另见：Astro.generator

`context.redirect()`

类型：(path: string, status?: number) => Response

添加于： astro@1.5.0

context.redirect() 返回一个 Response 对象，允许你重定向到另一个页面。此函数仅在构建 SSR（服务器端渲染）时可用，不应用于静态站点。

import type { APIContext } from 'astro';

export function GET({ redirect }: APIContext) {
  return redirect('/login', 302);
}

另见：Astro.redirect()

`context.rewrite()`

类型：(rewritePayload: string | URL | Request) => Promise<Response>

添加于： astro@4.13.0

允许你从不同的 URL 或路径提供内容，而不会将浏览器重定向到新页面。

该方法接受字符串、URL 或 Request 作为路径的位置。

使用字符串提供一个明确的路径：

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite('/login');
}

当你需要构造重写的 URL 路径时，使用 URL 类型。以下示例通过从相对路径 "../" 创建一个新的 URL 来呈现页面的父路径：

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new URL("../", Astro.url));
}

使用 Request 类型完全控制发送到新路径的 Request。以下示例发送一个请求来渲染父页面，同时提供标头：

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new Request(new URL("../", Astro.url), {
   headers: {
     "x-custom-header": JSON.stringify(Astro.locals.someValue)
   }
 }));
}

另见：Astro.rewrite()

`context.locals`

添加于： astro@2.4.0

context.locals 是一个对象，用于在请求的生命周期内存储和访问任意信息。

中间件函数可以读写context.locals的值：

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Default Title";
  }
  return next();
}

API 端点只能从 context.locals中读取信息：

import type { APIContext } from 'astro';

export function get({ locals }: APIContext) {
  return new Response(locals.title); // "默认标题"
}

另见：Astro.locals

`getStaticPaths()`

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

如果页面在文件名中使用动态参数，该组件将需要导出一个 getStaticPaths() 函数。

必须要有该函数，因为 Astro 是静态站点生成器。这意味着整个网站是预构建的。如果 Astro 不知道在构建时生成什么页面，你的用户在访问你的网站时就看不到它。

---
export async function getStaticPaths() {
  return [
    { params: { /* 必需 */ }, props: { /* 可选 */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---
<!-- 你的 HTML 模板在这里 -->

getStaticPaths() 函数应该返回对象数组，以确定哪些路径会被 Astro 预渲染。

`params`

每个返回对象的 params 键都会告诉 Astro 要构建什么路由。返回参数必须映射到你的组件文件路径中定义的动态参数和其余参数。

params 被编码到链接中，所以只能由字符串作为值。每个 params 对象的值必须与页面名称中使用的参数一致。

比如说有 src/pages/posts/[id].astro 页面。如果你从这个页面导出 getStaticPaths 并返回以下的路由：

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

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

然后 Astro 会在构建时静态地生成 posts/1、posts/2 和 posts/3。

通过 `props` 传递数据

为了给每个生成的页面传递额外的数据，你也可以在每个返回的路径对象上设置 props 值。与 params 不同的是，props 没有被编码到链接中，所以并不局限于字符串。

例如，假设你根据从远程 API 获取的数据来生成页面。你可以将完整的数据对象传递给 getStaticPaths 中的页面组件。

---
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>

你也可以传递普通数组，这在生成或缓存已知路径列表时可能会有帮助。

---
export async function getStaticPaths() {
  const posts = [
    {id: '1', category: "astro", title: "API Reference"},
    {id: '2', category: "react", title: "Creating a React Counter!"}
  ];
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { post }
    };
  });
}
const {id} = Astro.params;
const {post} = Astro.props;
---
<body>
  <h1>{id}: {post.title}</h1>
  <h2>Category: {post.category}</h2>
</body>

然后 Astro 将在构建时使用 pages/posts/[id].astro 中的页面组件静态地生成 posts/1 和 posts/2。页面可以使用 Astro.props 引用这些数据。

`paginate()`

分页是 Astro 通过 paginate() 函数原生支持网站的常见用例。paginate() 将自动生成数组，从getStaticPaths()返回，为分页集合的每个页面创建一个 URL。页面编号将作为参数传递，而页面数据将作为page道具传递。

export async function getStaticPaths({ paginate }) {
  // 用 fetch()、Astro.glob() 等加载你的数据
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;

  // 返回包含分页的所有帖子的路由集合
  return paginate(allPokemon, { pageSize: 10 });
}

// 如果设置正确，现在页面已经具备了渲染单页所需的一切参数（见下一节）。
const { page } = Astro.props;

paginate()：假定文件名为 [page].astro 或 [...page].astro。page 参数将是链接中的页数。

/posts/[page].astro：会产生 /posts/1、/posts/2、/posts/3 等链接。
/posts/[...page].astro：将产生 /posts、/posts/2 /posts/3 等链接。

paginate() 函数具有以下参数：

pageSize - 每页显示的项目数（默认为 10）
params - 用于创建动态路由的附加参数
props - 在每个页面上可用的附加属性

`page` 分页参数

分页会给每个渲染的页面传递 page 参数，代表分页集合中的单页数据。这包括你分页的数据（page.data）以及该页的元数据（page.url、page.start、page.end、page.total 等）。这些元数据对诸如“下一页”按钮或“显示 100 个中前十个”的信息很有用。

`page.data`

类型：Array

从 data() 中返回当前页面数据数组。

`page.start`

类型：number

当前页第一个项目的索引，从 0 开始（例如，如果 pageSize: 25，第一页该值未 0，第二页为25，以此类推）。

`page.end`

类型：number

当前页面最后一条数据的索引。

`page.size`

类型：number 默认值：10

每个页面有多少条数据。

`page.total`

类型：number

所有数据的总数量。

`page.currentPage`

类型：number

当前页码，从 1 开始。

`page.lastPage`

类型：number

总页数。

`page.url.current`

类型：string

获取当前页面的链接（对规范链接很有用）。

`page.url.prev`

类型：string | undefined

获取上一页链接（如果在首页，将是undefined）。如果为 base 设置了值，那么需要将 base 路径拼接到链接前面。

`page.url.next`

类型：string | undefined

获取下一页链接（如果没有更多的页面，将是undefined）。如果为 base 设置了值，那么需要将 base 路径拼接到链接前面。

`page.url.first`

类型：string | undefined

添加于： astro@4.12.0

获取第一页链接（如果在首页，将是undefined）。如果为 base 设置了值，那么需要将 base 路径拼接到链接前面。

`page.url.last`

类型：string | undefined

添加于： astro@4.12.0

获取最后一页链接（如果在最后一页，将是undefined）。如果为 base 设置了值，那么需要将 base 路径拼接到链接前面。

`import.meta`

所有 ESM 模块都包含 import.meta 属性。Astro 基于 Vite 增加了 import.meta.env。

import.meta.env.SSR 可以用来了解何时在服务器渲染。有时你可能想要不同的逻辑，例如，某个组件应该只在客户端渲染：

export default function () {
  return import.meta.env.SSR ? <div class="spinner"></div> : <FancyComponent />;
}

图像（`astro:assets`）

`getImage()`

类型：(options: UnresolvedImageTransform) => Promise<GetImageResult>

getImage()函数旨在生成用于在 HTML 之外的其他地方所使用的图像，例如在 API 路由中。它还允许你创建自定义的 <Image /> 组件。

getImage() 函数接受一个选项对象，其中包含与 Image 组件相同的属性（除了 alt）。

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"
const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---
<div style={`background-image: url(${optimizedBackground.src});`}></div>

它返回了一个具有以下类型的对象：

type GetImageResult = {
  /* 渲染图像所需的附加 HTML 属性（宽度、高度、样式等） */
  attributes: Record<string, any>;
  /* 已通过校验的参数 */
  options: ImageTransform;
  /* 传递的原始参数 */
  rawOptions: ImageTransform;
  /* 生成图像的路径 */
  src: string;
  srcSet: {
    /* 为 srcset 生成值，每个条目都有一个 url 和一个 size */
    values: SrcSetValue[];
    /* 准备在`srcset`属性中使用的值 */
    attribute: string;
  };
}

内容集合（`astro:content`）

添加于： astro@2.0.0

内容集合提供了 API 来配置和查询 src/content/ 中的 Markdown 或 MDX 文档。有关功能和用法示例，请参考内容集合指南。

`defineCollection()`

类型：(input: CollectionConfig) => CollectionConfig

defineCollection() 是一个用于在 src/content/config.* 文件中配置集合的工具函数。

import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// 将定义的集合公开给 Astro
// 通过 `collections` 导出
export const collections = { blog };

这个函数接受以下属性：

`type`

类型：'content' | 'data'
默认：'content'

添加于： astro@2.5.0

type 是一个字符串，用于定义存储在集合中的条目的类型：

'content' - 用于内容创作格式，如 Markdown (.md)、MDX (.mdx) 或 Markdoc (.mdoc)
'data' - 用于 JSON (.json) 或 YAML (.yaml) 等纯数据格式

`schema`

类型：ZodType | (context: SchemaContext) => ZodType

schema 是一个可选的 Zod 对象，用于配置集合的文档 frontmatter 的类型和形状。每个值必须使用 Zod 验证器

有关示例请参考 内容集合指南

`reference()`

类型：(collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

添加于： astro@2.5.0

在内容配置中使用 reference() 函数来定义从一个集合到另一个集合的关系或 “引用”。该函数接受一个集合名称，并验证内容前置事项或数据文件中指定的条目标识符。

此示例定义了从博客作者到 “作者 “集合的引用，以及到同一 “博客 “集合的相关文章数组的引用：

import { defineCollection, reference, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // 通过 "id "从 "作者 "集合中引用单个作者
    author: reference('authors'),
    // 按 "slug "从 "blog "集合中引用相关帖子数组
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

有关示例请参考 内容集合指南.

`getCollection()`

类型：(collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

getCollection() 是一个函数，用于通过集合名称检索内容集合条目列表。

默认情况下，它返回集合中的所有项目，并接受可选的 filter 函数来缩小条目属性。这允许你根据 id、slug 或 frontmatter 值（通过 data 对象）查询集合中的某些项目。

---
import { getCollection } from 'astro:content';

// 获取 `src/content/blog/` 中的所有条目
const allBlogPosts = await getCollection('blog');

// 仅返回 frontmatter 中 `draft: true` 的条目
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

有关示例请参考 内容集合指南以获取示例用法。

`getEntry()`

添加于： astro@2.5.0

类型：

(collection: string, contentSlugOrDataId: string) => CollectionEntry<collection>
({ collection: string, id: string }) => CollectionEntry<collection>
({ collection: string, slug: string }) => CollectionEntry<collection>

getEntry() 是一个函数，可通过集合名称和条目 id （对于 type: 'data' 集合）或条目 slug （对于 type: 'content' 集合）检索单个集合条目。getEntry()也可用于获取引用条目，以访问data、body或render()属性：

---
import { getEntry } from 'astro:content';

// 得到 `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// 得到 `src/content/captains/picard.yaml`
const picardProfile = await getEntry('captains', 'picard');

// 得到 the profile referenced by `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

有关内容集合的示例，请参考查询集合条目.

`getEntries()`

添加于： astro@2.5.0

类型：

(Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>
(Array<{ collection: string, slug: string }>) => Array<CollectionEntry<collection>>

getEntries() 是一个从同一集合中检索多个集合条目的函数。这对于返回引用条目的数组访问其关联的data、body和render()属性非常有用。

---
import { getEntries } from 'astro:content';

const enterprisePost = await getEntry('blog', 'enterprise');

// 获取由 `data.relatedPosts` 引用的相关帖子
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`getEntryBySlug()`

类型：(collection: string, slug: string) => CollectionEntry<collection>

getEntryBySlug() 是一个函数，用于通过集合名称和条目 slug 检索单个集合条目。

---
import { getEntryBySlug } from 'astro:content';

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

有关示例请参考 内容集合指南以获取示例用法。

`getDataEntryById()`

类型：(collection: string, id: string) => Promise<CollectionEntry<collection>>

添加于： astro@2.5.0

getDataEntryById() 是一个用于通过集合名称和条目 id 检索单个集合条目的函数。

---
import { getDataEntryById } from 'astro:content';
const picardProfile = await getDataEntryById('captains', 'picard');
---

集合条目类型

getCollection()和 getEntryBySlug() 函数都会返回 CollectionEntry 类型的条目。这个类型可以从 astro:content 中获取：

import type { CollectionEntry } from 'astro:content';

CollectionEntry<TCollectionName> 类型是一个对象，具有以下值。 TCollectionName 是你正在查询的集合的名称（例如 CollectionEntry<'blog'>）。

`id`

适用于： type: 'content' and type: 'data' 集合

示例类型：

内容集合: 'entry-1.md' | 'entry-2.md' | ...
数据集合: 'author-1' | 'author-2' | ...

一个使用相对于 src/content/[collection] 的文件路径的唯一 ID。根据集合条目文件路径枚举所有可能的字符串值。请注意，类型: 'content' 的集合在其 ID 中包含文件扩展名，而定义为 type: 'data' 的集合则不包含。

`collection`

适用于： type: 'content' and type: 'data' 集合

示例类型： 'blog' | 'authors' | ...

src/content/ 下顶级文件夹的名称，条目位于该文件夹中。该名称用于在模式和查询函数中引用集合。

`data`

适用于： type: 'content' and type: 'data' 集合

类型：CollectionSchema<TCollectionName>

一个从集合模式推断出的 frontmatter 属性对象（参考 defineCollection()）。如果没有配置模式，则默认为 any。

`slug`

适用于： 仅仅 type: 'content' 集合

示例类型： 'entry-1' | 'entry-2' | ...

可用于 Markdown 或 MDX 文档的 URL 标头。默认为不含文件扩展名的 “id”，但可以通过在文件的 frontmatter 中设置slug属性来覆盖。

`body`

适用于： 仅 type: 'content' 集合

类型：string

一个包含 Markdown 或 MDX 文档原始未编译的 body 的字符串。

`render()`

适用于： 仅 type: 'content' 集合

类型：() => Promise<RenderedEntry>

一个用于编译给定的 Markdown 或 MDX 文档以进行渲染的函数。它返回以下属性：

<Content /> - 用于在 Astro 文件中渲染文档内容的组件。
headings - 生成的标题列表，与 Astro 的 getHeadings() 工具函数相同在 Markdown 和 MDX 导入中。
remarkPluginFrontmatter - 在应用 remark 或 rehype 插件后修改后的 frontmatter 对象。设置为类型 any。

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

有关示例请参考 内容集合指南以获取示例用法。

其他内容集合类型

astro:content 模块也导出了以下类型，供你在 Astro 项目中使用：

`CollectionKey`

添加于： astro@3.1.0

这是一个在 src/content/config.* 文件中定义的所有集合名称的字符串联合类型。当定义一个可以接受任何集合名称的通用函数时，这个类型很有用。

import type { CollectionKey, getCollection } from 'astro:content';

async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

`ContentCollectionKey`

添加于： astro@3.1.0

一个在 src/content/config.* 文件中定义的所有 type: 'content' 集合名称的字符串联合类型。

`DataCollectionKey`

添加于： astro@3.1.0

一个在 src/content/config.* 文件中定义的所有 type: 'data' 集合名称的字符串联合类型。

`SchemaContext`

即 defineCollection 在 schema 函数形状中所使用的 context 对象。当为多个集合构建可重用的模式时，这个类型很有用。

它包括了以下属性：

image() 模式辅助工具允许你在内容集合中使用本地图片。

import type { SchemaContext } from 'astro:content';

export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });

const blog = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});

中间件（`astro:middleware`）

添加于： astro@2.6.0

中间件使你能拦截请求和响应，并在每次渲染页面或端点时动态注入行为。有关功能和用法示例，请参考中间件指南。

`onRequest()`

类型：(context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

一个在 src/middleware.js 里的必须导出的函数，它将在每次渲染页面或端点时被调用。它接受两个参数：context 和 next()。onRequest() 必须返回一个 Response：要么直接返回，要么通过调用 next() 返回。

export function onRequest (context, next) {
    // 拦截一个请求的响应数据
    // 可选修改响应
    // 直接返回一个 Response 对象，或者调用 `next()` 的结果
    return next();
};

`context`

类型：APIContext

onRequest() 的第一个参数是一个上下文对象。它反映了许多 Astro 全局属性。

有关更多信息，请参阅端点上下文。

`next()`

类型：(rewritePayload?: string | URL | Request) => Promise<Response>

onRequest() 的第二个参数是一个调用链中的所有后续中间件，并返回一个 Response 的函数。例如，其他中间件可以修改响应的 HTML 主体，等待 next() 的结果将允许你的中间件响应这些更改。

自从 Astro v4.13.0，next() 接受一个可选的 URL 路径参数，形式为字符串、URL 或 Request，用于重写当前请求而不重新触发新的渲染阶段。

`sequence()`

类型：(...handlers: MiddlewareHandler[]) => MiddlewareHandler

一个接受中间件函数作为参数的函数，它将按照它们传递的顺序执行它们。

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

export const onRequest = sequence(validation, auth, greeting);

`createContext()`

类型：(context: CreateContext) => APIContext

添加于： astro@2.8.0

一个底层 API，用于创建一个 APIContext 以传递给 Astro 中间件的 onRequest() 函数。

此函数可以由集成/适配器用于执行 Astro 中间件。

`trySerializeLocals()`

类型：(value: unknown) => string

添加于： astro@2.8.0

一个底层 API，它接受任何值并尝试返回它的序列化版本（一个字符串）。如果该值无法序列化，该函数将抛出一个运行时错误。

国际化（`astro:i18n`）

添加于： astro@3.5.0

此模块提供了一些函数，帮助你使用项目配置的语言环境设置创建 URL。

使用 i18n 路由为你的项目创建路由将依赖于你设置的某些配置值，这些值会影响你的页面路由。使用这些函数创建路由时，请确保考虑到你的个人设置，包括：

另外，请注意，这些函数为你的 defaultLocale 创建的返回 URL 将反映你的 i18n.routing 配置。

有关功能和使用示例，请参阅我们的 i18n 路由指南。

`getRelativeLocaleUrl()`

类型：(locale: string, path?: string, options?: GetLocaleOptions) => string

getRelativeLocaleUrl(locale: string, path?: string, options?: GetLocaleOptions): string

使用此函数来检索一个语言环境的相对路径。如果该语言环境不存在，Astro 会抛出一个错误。

---
getRelativeLocaleUrl("fr");
// 返回 /fr
getRelativeLocaleUrl("fr", "");
// 返回 /fr
getRelativeLocaleUrl("fr", "getting-started");
// 返回 /fr/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// 返回 /blog/fr-ca/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// 返回 /blog/fr_CA/getting-started
---

`getAbsoluteLocaleUrl()`

类型：(locale: string, path: string, options?: GetLocaleOptions) => string

当 [site] 配置了值时，使用这个函数来检索一个语言环境的绝对路径。如果 [site] 没有被配置，该函数将返回一个相对 URL。如果语言环境不存在，Astro 会抛出一个错误。

---
// 如果 `site` 被设置为 `https://example.com`
getAbsoluteLocaleUrl("fr");
// 返回 https://example.com/fr
getAbsoluteLocaleUrl("fr", "");
// 返回 https://example.com/fr
getAbsoluteLocaleUrl("fr", "getting-started");
// 返回 https://example.com/fr/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// 返回 https://example.com/blog/fr-ca/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// 返回 https://example.com/blog/fr_CA/getting-started
---

`getRelativeLocaleUrlList()`

类型：(path?: string, options?: GetLocaleOptions) => string[]

像使用 getRelativeLocaleUrl 那样使用此函数，返回所有语言环境的相对路径列表。

`getAbsoluteLocaleUrlList()`

类型：(path?: string, options?: GetLocaleOptions) => string[]

像使用 getAbsoluteLocaleUrl 那样使用此函数，返回所有语言环境的绝对路径列表。

`getPathByLocale()`

类型：(locale: string) => string

当配置了自定义语言环境路径时，此函数返回与一个或多个 codes 关联的 path。

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getPathByLocale("fr"); // 返回 "french"
getPathByLocale("fr-CA"); // 返回 "french"
---

`getLocaleByPath()`

类型：(path: string) => string

此函数返回与语言环境 path 关联的 code。

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getLocaleByPath("french"); // 返回 "fr"，因为这是首个配置的代码
---

`redirectToDefaultLocale()`

类型：(context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

添加于： astro@4.6.0

此函数返回一个 Response，将重定向到配置的 defaultLocale。它接受一个可选的有效重定向状态码。

import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  if (context.url.pathname.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(context, 302);
  }
})

`redirectToFallback()`

类型：(context: APIContext, response: Response) => Promise<Response>

添加于： astro@4.6.0

此函数允许你在自己的中间件中使用你的 i18n.fallback 配置。

import { defineMiddleware } from "astro:middleware";
import { redirectToFallback } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next();
  if (response.status >= 300) {
    return redirectToFallback(context, response)
  }
  return response;
})

`notFound()`

类型：(context: APIContext, response?: Response) => Promise<Response> | undefined

添加于： astro@4.6.0

当以下情况发生时，在你的路由中间件中使用此函数来返回一个 404 错误：

当前路径不是根路径。例如：/ 或 /<base>
URL 中不包含语言环境代码

当传递了一个 Response，由此函数发出的新 Response 将包含原始响应的相同头信息。

import { defineMiddleware } from "astro:middleware";
import { notFound } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  const pathNotFound = notFound(context);
  if (pathNotFound) {
    return pathNotFound;
  }
  return next();
})

`middleware()`

类型：(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

添加于： astro@4.6.0

此函数允许你以编程方式创建 Astro i18n 中间件。

当你仍然想要使用默认的 i18n 逻辑，但只在你的网站添加少数例外时，这个功能非常有用。

import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();
  // 在这里解析响应后的自定义逻辑。
  // 可以捕获来自 Astro i18n 中间件的响应。

  return response;
});

export const onRequest = sequence(customLogic, middleware({
  prefixDefaultLocale: true,
  redirectToDefaultLocale: false
}))

`requestHasLocale()`

类型：(context: APIContext) => boolean

添加于： astro@4.6.0

检查当前 URL 是否包含已配置的语言环境代码。在内部，此函数将使用 APIContext#url.pathname。

import { defineMiddleware } from "astro:middleware";
import { requestHasLocale } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  if (requestHasLocale(context)) {
    return next();
  }
  return new Response("Not found", { status: 404 });
})

内置组件

Astro 包括几个内置的组件供你在你的项目中使用。在 .astro 文件中可以通过 import {} from 'astro:components'; 引用所有的内置组件。

`<Code />`

---
import { Code } from 'astro:components';
---
<!-- 使用语法凸显部分 JavaScript 代码-->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- 可选：定制你的主题 -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- 可选：启用文字包装 -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- 可选：输出内联代码 -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- 可选: defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

该组件在构建时为代码块提供语法高亮（不包括客户端 JavaScript）。该组件由 Shiki 内部驱动，它支持所有流行的主题和语言。另外，你可以通过将自定义主题、语言、转换器和默认配色分别传递给 theme、lang、transformers 和 defaultColor 属性以添加它们。

转换器

添加于： astro@4.11.0

Shiki 转换器可以通过将其作为数组传递到 transformers 属性中，来选择性地应用于代码。从 Astro v4.14.0 开始，你还可以为 Shiki 的 meta 属性提供一个字符串，以将选项传递给转换器。

注意，transformers 只能用于类，同时你必须提供自己的 CSS 规则来针对代码块的元素。

---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}" />

  <style is:global>
    pre.has-focused .line:not(.focused) {
      filter: blur(1px);
    }
  </style>

`<Fragment />`

一个与 set:* 指令一起使用的组件，用于渲染 HTML 内容而不添加任何额外的包裹元素。

---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

请参见在 Astro 语法中使用片段的更多信息。

`<Prism />`

要安装 Prism 高亮器组件，需要先安装 @astrojs/prism 包：

npm i @astrojs/prism

pnpm i @astrojs/prism

yarn add @astrojs/prism

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

这个组件通过应用 Prism 的 CSS 类为代码块提供特定语言的语法高亮。注意，你需要提供 Prism 的 CSS 样式表（或用自己的），以启用语法高亮！参见 Prism 配置部分了解更多细节。

参见 Prism 支持的语言列表，在那里你可以找到一种语言的对应别名。而且，你也可以用 lang="astro" 来展示 Astro 代码块！

`<Image />`

---
// 导入图像组件和图片
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---
<!-- `alt` 在 Image 组件中是必需的属性 -->
<Image src={myImage} alt="A description of my image." />

<!-- 输出 -->
<!-- Image 组件已经过优化，并且对应的属性也被强制使用。 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

属性

src（必需的）
alt（必需的）
width 和 height（对 public/ 和远程图像而言是必需的）
format
quality
densities
widths

除了上述属性之外，<Image /> 组件还接受 HTML <img> 标签接受的所有属性。

详见图像指南。

`<Picture />`

添加于： astro@3.3.0

使用内置的 <Picture /> Astro 组件来展示具有多种格式和（或）尺寸的响应式图像。

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 图像的分辨率为 1600x900
---
<!-- 在图片组件上 `alt` 属性是必需的 -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

<!-- 输出 -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>

详见图像指南。

属性

<Picture /> 接受 <Image /> 组件的所有属性，以及以下属性：

`formats`

一个图像格式的数组，用于 <source> 标签。默认情况下，它被设置为 ['webp']。

`fallbackFormat`

用于作为 <img> 标签的回退值的格式。对于静态图像，默认为 .png；对于动画图像，默认为 .gif；对于 SVG 文件，默认为 .svg。

`pictureAttributes`

一个被添加到 <picture> 标签的属性对象。使用该属性可将属性应用于外部的 <picture> 元素本身。除了用于图像转换的属性外，直接应用于 <Picture /> 组件的属性将应用于内部的 <img> 元素。

`<Content />`

一个通用组件，用于呈现内容集合条目的内容。

首先，使用 getCollection() 或 getEntry() 查询一个或多个条目。然后，entry.render() 函数可以返回 <Content /> 组件，以供在 .astro 文件模板中使用。

---
import { getEntry } from 'astro:content';
const entry = await getEntry('blog', 'post-1');
const { Content } = await entry.render();
---
<p>Published on: {entry.data.published.toDateString()}</p>
<Content />

`<ViewTransitions />`

添加于： astro@2.9.0

在每个希望应用视图过渡动画的页面上，通过导入并将 <ViewTransitions /> 路由组件添加到 <head> 中，来选择使用单个页面上的视图过渡动画。

---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

查看更多关于如何控制路由器和向页面元素和组件添加过渡动画指令的信息。

`<Debug />`

---
import { Debug } from 'astro:components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

这个组件提供了无需 JavaScript 在客户端检查数值的方法。

贡献

社区

API 参考

Astro global

Astro.glob()

Markdown 文件

Astro 文件

其他文件

Astro.props

Astro.params

Astro.request

Astro.response

Astro.cookies

get

has

set

delete

merge

headers

AstroCookie

value

json

number

boolean

AstroCookieGetOptions

decode

AstroCookieSetOptions

domain

expires

httpOnly

maxAge

path

sameSite

secure

encode

Astro.redirect()

Astro.rewrite()

Astro.url

Astro.clientAddress

Astro.site

Astro.generator

Astro.slots

Astro.slots.has()

Astro.slots.render()

Astro.self

Astro.locals

Astro.preferredLocale

Astro.preferredLocaleList

Astro.currentLocale

端点上下文

context.params

context.props

context.request

context.cookies

context.url

context.clientAddress

context.site

context.generator

context.redirect()

context.rewrite()

context.locals

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

import.meta

图像（astro:assets）

getImage()

内容集合（astro:content）

`Astro` global

`Astro.glob()`

`Astro.props`

`Astro.params`

`Astro.request`

`Astro.response`

`Astro.cookies`

`get`

`has`

`set`

`delete`

`merge`

`headers`

`AstroCookie`

`value`

`json`

`number`

`boolean`

`AstroCookieGetOptions`

`decode`

`AstroCookieSetOptions`

`domain`

`expires`

`httpOnly`

`maxAge`

`path`

`sameSite`

`secure`

`encode`

`Astro.redirect()`

`Astro.rewrite()`

`Astro.url`

`Astro.clientAddress`

`Astro.site`

`Astro.generator`

`Astro.slots`

`Astro.slots.has()`

`Astro.slots.render()`

`Astro.self`

`Astro.locals`

`Astro.preferredLocale`

`Astro.preferredLocaleList`

`Astro.currentLocale`

`context.params`

`context.props`

`context.request`

`context.cookies`

`context.url`

`context.clientAddress`

`context.site`

`context.generator`

`context.redirect()`

`context.rewrite()`

`context.locals`

`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`

`import.meta`

图像（`astro:assets`）

`getImage()`

内容集合（`astro:content`）

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`