API 参考
Astro
global
段落标题 Astro globalAstro
global 在 .astro
文件的所有上下文中都可用。它具有以下功能:
Astro.glob()
段落标题 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 文件
段落标题 Markdown 文件Markdown 文件有以下接口:
export interface MarkdownInstance<T extends Record<string, any>> { /* 在此文件的 YAML frontmatter 中指定的任何数据 */ frontmatter: T; /* 该文件的文件路径 */ file: string; /* 该文件的渲染路径 */ url: string | undefined; /* 渲染此文件内容的 Astro 组件 */ Content: AstroComponent; /* 返回该文件中 h1...h6 元素数组的函数 */ getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;}
你可以选择使用 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 文件Astro 文件具有以下接口:
export interface AstroInstance { /* 此文件的文件路径 */ file: string; /* 此文件的 URL(如果它在 pages 目录中)*/ url: string | undefined; default: AstroComponent;}
其他文件
段落标题 其他文件其他文件可能有各种不同的接口,但如果你不知道文件类型包含什么,那么 Astro.glob()
可以接受 TypeScript 泛型。
---interface CustomDataFile { default: Record<string, any>;}const data = await Astro.glob<CustomDataFile>('../data/**/*.js');---
Astro.props
段落标题 Astro.propsAstro.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" />
Astro.params
段落标题 Astro.paramsAstro.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
段落标题 Astro.requestAstro.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
默认的 output: static
选项中,Astro.request.url
不包含搜索参数,如 ?foo=bar
,因为在静态构建中不可能提前确定这些参数。但是在 output: 'server'
模式下,Astro.request.url
可以包含搜索参数,因为它可以从服务器请求中确定。
Astro.response
段落标题 Astro.responseAstro.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
段落标题 Astro.cookies
添加于:
astro@1.4.0
Astro.cookies
包含用于在服务端渲染模式下读取和操作 cookie 的工具方法。
get
段落标题 get类型: (key: string, options?: CookieGetOptions) => AstroCookie
获取 AstroCookie
对象形式的 cookie,该对象包含value
和用于将 cookie 转换为非字符串类型的工具方法。
has
段落标题 has类型: (key: string) => boolean
用于判断 cookie 是否存在。如果这个 cookie 已经通过Astro.cookies.set()
设置,这将返回 true,否则它将检查 Astro.request
中的 cookies。
set
段落标题 set类型: (key: string, value: string | number | boolean | object, options?: CookieSetOptions) => void
将 cookie key
设置为给定的值。这将试图把 cookie 的值转换为一个字符串。选项提供了设置 cookie 功能的方法,例如 maxAge
或 httpOnly
。
delete
段落标题 delete类型: (key: string, options?: CookieDeleteOptions) => void
通过设置过去的到期日期(Unix 时间为 0)使 cookie 失效。
一旦 Cookie 被“删除”(过期),Astro.cookies.has()
将返回 false
,Astro.cookies.get()
将返回一个 value
为 undefined
的 AstroCookie
。删除 Cookie 时可用的选项包括:domain
、path
、httpOnly
、sameSite
和 secure
。
headers
段落标题 headers类型: () => Iterator<string>
获取将与响应一起发送的 Set-Cookie
的 header 的值。
AstroCookie
段落标题 AstroCookie通过 Astro.cookies.get()
获取 cookie 返回一个 AstroCookie
类型。它具有以下结构。
value
段落标题 value类型: string | undefined
cookie 的原始字符串值。
json
段落标题 json类型: () => Record<string, any>
通过 JSON.parse()
解析 cookie 值,返回一个对象。如果 cookie 值不是有效的 JSON,则抛出异常。
number
段落标题 number类型: () => number
将 cookie 值解析为数字。如果不是有效数字,则返回 NaN。
boolean
段落标题 boolean类型: () => boolean
转换 cookie 的值为 boolean 类型。
CookieGetOptions
段落标题 CookieGetOptions
添加于:
astro@4.1.0
获取 cookie 允许通过 CookieGetOptions
接口指定选项:
decode
段落标题 decode类型: (value: string) => string
允许自定义如何将 cookie 反序列化为值。
CookieSetOptions
段落标题 CookieSetOptions
添加于:
astro@4.1.0
通过 Astro.cookies.set()
设置 cookie,允许传入 CookieSetOptions
来自定义 cookie 如何被序列化。
domain
段落标题 domain类型: string
Specifies the domain. If no domain is set, most clients will interpret to apply to the current domain.
指定域。如果未设置域,则大多数客户端将解释为应用于当前域。
expires
段落标题 expires类型: Date
指定 cookie 过期日期。
httpOnly
段落标题 httpOnly类型: boolean
如果为 true,则客户端将无法访问该 Cookie。
maxAge
段落标题 maxAge类型: number
以秒为单位指定 cookie 有效的时间。
path
段落标题 path类型: string
指定应用 cookie 的域的子路径。
sameSite
段落标题 sameSite类型: boolean | 'lax' | 'none' | 'strict'
指定 SameSite cookie header 的值。
secure
段落标题 secure类型: boolean
如果为 true,则该 Cookie 仅在 https 网站上设置。
encode
段落标题 encode类型: (value: string) => string
允许自定义 cookie 序列化方式。
Astro.redirect()
段落标题 Astro.redirect()允许你重定向到另一个页面,并可选地提供一个 HTTP 响应状态码 作为第二个参数。
页面(而不是子组件)必须 return
Astro.redirect()
的结果,以便重定向发生。
以下示例将用户重定向到登录页面,使用默认的 HTTP 响应状态码 302:
---import { isLoggedIn } from '../utils';
const cookie = Astro.request.headers.get('cookie');
// 如果用户未登录,则将其重定向到登录页面if (!isLoggedIn(cookie)) { return Astro.redirect('/login');}---
Astro.canonicalURL
段落标题 Astro.canonicalURL使用 Astro.url
来构建你自己的标准链接。
当前页面的标准链接。
Astro.url
段落标题 Astro.url
添加于:
astro@1.0.0-rc
URL对象,由当前 Astro.request.url
的链接字符串值构成。对于与请求的链接的个别属性进行交互是有用的,如路径名和起源。
相当于做 new URL(Astro.request.url)
。
<h1>当前链接是:{Astro.url}</h1><h1>当前链接路径名是:{Astro.url.pathname}</h1><h1>当前链接源是:{Astro.url.origin}</h1>
你也可以使用 Astro.url
来创建新的链接,并把它作为参数传给 new URL()
。
---// 示例:使用你的生产域名构建一个规范的URLconst canonicalURL = new URL(Astro.url.pathname, Astro.site);// 示例:使用你目前的域名构建一个用于 SEO meta 标签的URLconst socialImageURL = new URL('/images/preview.png', Astro.url);---<link rel="canonical" href={canonicalURL} /><meta property="og:image" content={socialImageURL} />
Astro.clientAddress
段落标题 Astro.clientAddress
添加于:
astro@1.0.0-rc
指定请求的 IP 地址。这个属性只在为 SSR(服务器端渲染)构建时可用,不应该用于静态网站。
---const ip = Astro.clientAddress;---
<div>你的 IP 地址是:<span class="address">{ ip }</span></div>
Astro.site
段落标题 Astro.siteAstro.site
返回根据 Astro 配置中的 site
生成的 URL
。如果未定义 Astro 配置中的 site
,Astro.site
也不会被定义。
Astro.generator
段落标题 Astro.generator
添加于:
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>