Astro 런타임 API
Astro global
섹션 제목: Astro globalAstro global은 .astro 파일의 모든 컨텍스트에서 사용할 수 있습니다. 다음과 같은 기능이 있습니다:
Astro.glob()
섹션 제목: Astro.glob()Astro.glob()은 정적 사이트 설정에 많은 로컬 파일을 로드하는 방법입니다.
---const posts = await Astro.glob('../pages/post/*.md'); // ./src/pages/post/*.md 파일에 있는 게시물 배열을 반환합니다.---
<div>{posts.slice(0, 3).map((post) => ( <article> <h2>{post.frontmatter.title}</h2> <p>{post.frontmatter.description}</p> <a href={post.url}>Read more</a> </article>))}</div>.glob()은 하나의 매개변수, 즉 가져오려는 로컬 파일의 상대 URL glob만 사용합니다. 비동기식이며 일치하는 파일에서 내보내기 배열을 반환합니다.
.glob()은 정적으로 분석할 수 없기 때문에 이를 보간하는 변수나 문자열을 사용할 수 없습니다. (해결 방법은 문제 해결 안내서를 참조하세요.) 이는 Astro.glob()이 Vite의 import.meta.glob()의 래퍼이기 때문입니다..
Markdown 파일
섹션 제목: Markdown 파일Astro.glob()으로 로드된 Markdown 파일은 다음과 같은 MarkdownInstance 인터페이스를 반환합니다:
export interface MarkdownInstance<T extends Record<string, any>> { /* 이 파일의 YAML 프런트매터에 지정된 모든 데이터 */ frontmatter: T; /* 이 파일의 절대 파일 경로 */ file: string; /* 이 파일의 렌더링된 경로 */ url: string | undefined; /* 이 파일의 내용을 렌더링하는 Astro 컴포넌트 */ Content: AstroComponentFactory; /** (Markdown 전용) 레이아웃 HTML 및 YAML 프런트매터를 제외한 원시 Markdown 파일 콘텐츠 */ rawContent(): string; /** (Markdown 전용) 레이아웃 HTML을 제외한 HTML로 컴파일된 Markdown 파일 */ 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 파일Astro 파일에는 다음과 같은 인터페이스가 있습니다:
export interface AstroInstance { /* 이 파일의 파일 경로 */ file: string; /* 이 파일의 URL (page 디렉터리에 있는 경우) */ 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.propsAstro.props는 컴포넌트 속성으로 전달된 모든 값을 포함하는 객체입니다. .md 및 .mdx 파일의 레이아웃 컴포넌트는 프런트매터 값을 props로 받습니다.
---const { title, date } = Astro.props;---<div> <h1>{title}</h1> <p>{date}</p></div>---import Heading from '../components/Heading.astro';---<Heading title="My First Post" date="09 Aug 2022" />Astro.params
섹션 제목: Astro.paramsAstro.params는 이 요청과 일치하는 동적 경로 세그먼트의 값을 포함하는 객체입니다.
정적 빌드에서 이 객체는 동적 경로 사전 렌더링에 사용되는 getStaticPaths()에서 반환하는 params입니다.
---export function getStaticPaths() { return [ { params: { id: '1' } }, { params: { id: '2' } }, { params: { id: '3' } } ];}
const { id } = Astro.params;---<h1>{id}</h1>SSR 빌드에서는 동적 경로 패턴의 경로 세그먼트와 일치하는 모든 값이 될 수 있습니다.
---import { getPost } from '../api';
const post = await getPost(Astro.params.id);
// 이 ID로 게시물을 찾을 수 없습니다.if (!post) { Astro.redirect("/404")}---<html> <h1>{post.name}</h1></html>함께 보기: params
Astro.request
섹션 제목: Astro.request타입: Request
Astro.request는 표준 Request 객체입니다. url, headers, method 및 요청 본문을 가져오는 데 사용할 수 있습니다.
<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
섹션 제목: 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';}---또는 헤더를 설정하려면:
---Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');---Astro.cookies
섹션 제목: Astro.cookies타입: AstroCookies
astro@1.4.0
Astro.cookies에는 서버 측 렌더링 모드에서 쿠키를 읽고 조작하기 위한 유틸리티가 포함되어 있습니다.
get
섹션 제목: get타입: (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined
쿠키를 문자열이 아닌 타입으로 변환하기 위한 value 및 유틸리티 함수가 포함된 AstroCookie 객체로 쿠키를 가져옵니다.
has
섹션 제목: has타입: (key: string, options?: AstroCookieGetOptions) => boolean
이 쿠키가 존재하는지 여부입니다. 쿠키가 Astro.cookies.set()을 통해 설정된 경우 true를 반환하고, 그렇지 않으면 Astro.request에서 쿠키를 확인합니다.
set
섹션 제목: set타입: (key: string, value: string | object, options?: AstroCookieSetOptions) => void
쿠키의 key를 주어진 값으로 설정합니다. 그러면 쿠키 값을 문자열로 변환하려고 시도합니다. 옵션은 maxAge 또는 httpOnly와 같은 쿠키 기능을 설정하는 방법을 제공합니다.
delete
섹션 제목: delete타입: (key: string, options?: AstroCookieDeleteOptions) => void
만료 날짜를 과거 (Unix 시간에서는 0)로 설정하여 쿠키를 무효화합니다.
쿠키가 “제거되면” (만료되면) Astro.cookies.has()는 false를 반환하고 Astro.cookies.get()은 value가 undefined인 AstroCookie를 반환합니다. 쿠키를 삭제할 때 사용할 수 있는 옵션은 domain, path, httpOnly, sameSite 및 secure입니다.
merge
섹션 제목: merge타입: (cookies: AstroCookies) => void
새 AstroCookies 인스턴스를 현재 인스턴스에 병합합니다. 새 쿠키가 현재 인스턴스에 추가되고 같은 이름의 쿠키가 존재하면 기존 값을 덮어씁니다.
headers
섹션 제목: headers타입: () => Iterator<string>
응답과 함께 전송될 Set-Cookie에 대한 헤더 값을 가져옵니다.
AstroCookie
섹션 제목: AstroCookieAstro.cookies.get()을 통해 쿠키를 가져오면 AstroCookie 타입이 반환됩니다. 다음과 같은 구조를 가지고 있습니다.
value
섹션 제목: value타입: string
쿠키의 원시 문자열 값입니다.
json
섹션 제목: json타입: () => Record<string, any>
JSON.parse()를 통해 쿠키 값을 구문 분석하여 객체를 반환합니다. 쿠키 값이 유효한 JSON이 아닌 경우 예외가 발생합니다.
number
섹션 제목: number타입: () => number
쿠키 값을 숫자로 구문 분석합니다. 유효한 숫자가 아닌 경우 NaN을 반환합니다.
boolean
섹션 제목: boolean타입: () => boolean
쿠키 값을 true 또는 false로 변환합니다.
AstroCookieGetOptions
섹션 제목: AstroCookieGetOptions
Added in:
astro@4.1.0
쿠키를 얻으면 AstroCookieGetOptions 인터페이스를 통해 옵션을 지정할 수도 있습니다.
decode
섹션 제목: decode타입: (value: string) => string
쿠키가 값으로 역직렬화되는 방식을 사용자 정의할 수 있습니다.
AstroCookieSetOptions
섹션 제목: AstroCookieSetOptions
Added in:
astro@4.1.0
Astro.cookies.set()을 통해 쿠키를 설정하면 AstroCookieSetOptions를 전달하여 쿠키 직렬화 방법을 맞춤설정할 수 있습니다.
domain
섹션 제목: domain타입: string
도메인을 지정합니다. 도메인이 설정되지 않은 경우 대부분의 클라이언트는 현재 도메인에 적용되도록 해석합니다.
expires
섹션 제목: expires타입: Date
쿠키가 만료되는 날짜를 지정합니다.
httpOnly
섹션 제목: httpOnly타입: boolean
true인 경우 클라이언트 측에서 쿠키에 액세스할 수 없습니다.
maxAge
섹션 제목: maxAge타입: number
쿠키가 유효한 시간 (초)을 지정합니다.
path
섹션 제목: path타입: string
쿠키가 적용되는 도메인의 하위 경로를 지정합니다.
sameSite
섹션 제목: sameSite타입: boolean | 'lax' | 'none' | 'strict'
SameSite 쿠키 헤더의 값을 지정합니다.
secure
섹션 제목: secure타입: boolean
true인 경우 쿠키는 https 사이트에만 설정됩니다.
encode
섹션 제목: encode타입: (value: string) => string
쿠키가 직렬화되는 방식을 사용자 정의할 수 있습니다.
Astro.redirect()
섹션 제목: Astro.redirect()타입: (path: string, status?: number) => Response
다른 페이지로 리디렉션할 수 있으며, 선택적으로 HTTP 응답 상태 코드를 두 번째 매개변수로 제공할 수 있습니다.
페이지 (하위 컴포넌트는 아님)에 리디렉션이 발생하려면 Astro.redirect() 결과를 return해야 합니다.
정적으로 생성된 사이트의 경우 <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()
섹션 제목: 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
섹션 제목: Astro.url타입: URL
astro@1.0.0-rc
현재 Astro.request.url URL 문자열 값에서 생성된 URL 객체입니다. pathname 및 origin과 같은 요청 URL의 개별 속성과 상호 작용하는 데 유용합니다.
new URL(Astro.request.url)을 수행하는 것과 동일합니다.
정적 사이트 및 server 또는 hybrid 출력을 사용하는 주문형 렌더링 사이트에서 site가 구성되지 않은 경우 개발 모드에서 Astro.url은 localhost가 됩니다.
<h1>The current URL is: {Astro.url}</h1><h1>The current URL pathname is: {Astro.url.pathname}</h1><h1>The current URL origin is: {Astro.url.origin}</h1>Astro.url을 new URL()에 인수로 전달하여 새 URL을 생성하는 데 사용할 수도 있습니다.
---// 예: 프로덕션 도메인을 사용하여 canonical URL 구성const canonicalURL = new URL(Astro.url.pathname, Astro.site);// Example: 현재 도메인을 사용하여 SEO 메타 태그용 URL을 구성const socialImageURL = new URL('/images/preview.png', Astro.url);---<link rel="canonical" href={canonicalURL} /><meta property="og:image" content={socialImageURL} />Astro.clientAddress
섹션 제목: Astro.clientAddress타입: string
astro@1.0.0-rc
요청의 IP 주소를 지정합니다. 이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.
---const ip = Astro.clientAddress;---
<div>Your IP address is: <span class="address">{ ip }</span></div>Astro.site
섹션 제목: Astro.site타입: URL | undefined
Astro.site는 Astro 구성의 site에서 만들어진 URL을 반환합니다. Astro 구성의 site가 정의되지 않은 경우 Astro.site가 정의되지 않습니다.
Astro.generator
섹션 제목: Astro.generator타입: string
astro@1.0.0
Astro.generator는 <meta name="generator"> 태그에 현재 버전의 Astro를 추가하는 편리한 방법입니다. "Astro v1.x.x" 형식을 따릅니다.
<html> <head> <meta name="generator" content={Astro.generator} /> </head> <body> <footer> <p>Built with <a href="https://astro.build">{Astro.generator}</a></p> </footer> </body></html>Astro.slots
섹션 제목: Astro.slotsAstro.slots에는 Astro 컴포넌트의 슬롯 하위 항목을 수정하기 위한 유틸리티 함수가 포함되어 있습니다.
Astro.slots.has()
섹션 제목: 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()
섹션 제목: 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 prop을 대문자로 변환하고 이를 기본 슬롯에 전달합니다.
---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.selfAstro.self를 사용하면 Astro 컴포넌트를 재귀적으로 호출할 수 있습니다. 이 동작을 사용하면 컴포넌트 템플릿의 <Astro.self>를 사용하여 Astro 컴포넌트 자체에서 Astro 컴포넌트를 렌더링할 수 있습니다. 이는 대규모 데이터 저장소와 중첩된 데이터 구조를 반복하는 데 도움이 될 수 있습니다.
---const { items } = Astro.props;---<ul class="nested-list"> {items.map((item) => ( <li> <!-- If there is a nested data-structure we render `<Astro.self>` --> <!-- and can pass props through with the recursive call --> {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.locals
Added in:
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>{/* 각 order마다 작업 수행 */}</li> })}</ul>Astro.preferredLocale
섹션 제목: Astro.preferredLocale타입: string | undefined
astro@3.5.0
Astro.preferredLocale은 사용자가 선호하는 언어를 나타내는 계산된 값입니다.
i18n.locales 배열에 구성된 언어와 Accept-Language 헤더를 통해 사용자 브라우저에서 지원하는 언어를 확인하여 계산됩니다. 일치하는 항목이 없으면 이 값은 undefined입니다.
이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.
Astro.preferredLocaleList
섹션 제목: Astro.preferredLocaleList타입: string[] | undefined
astro@3.5.0
Astro.preferredLocaleList는 브라우저에서 요청하고 웹사이트에서 지원하는 모든 언어의 배열을 나타냅니다. 그러면 여러분의 사이트와 방문자 간에 호환되는 모든 언어 목록이 생성됩니다.
브라우저에서 요청한 언어가 언어 배열에 없으면 값은 []입니다. 즉, 방문자가 선호하는 언어을 지원하지 않습니다.
브라우저가 선호하는 언어를 지정하지 않으면 이 값은 i18n.locales가 됩니다. 지원되는 모든 언어는 선호 사항이 없는 방문자가 동일하게 선호하는 것으로 간주됩니다.
이 속성은 SSR(서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.
Astro.currentLocale
섹션 제목: Astro.currentLocale타입: string | undefined
astro@3.5.6
locales 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 언어입니다. URL에 /[locale]/ 접두사가 포함되어 있지 않으면 값은 기본적으로 i18n.defaultLocale이 됩니다.
Astro.getActionResult()
섹션 제목: Astro.getActionResult()타입: (action: TAction) => ActionReturnType<TAction> | undefined
astro@4.15.0
Astro.getActionResult()는 액션 제출의 결과를 반환하는 함수입니다. 이 함수는 액션 함수를 인수로 받아 (예: actions.logout) 제출이 수신되면 data 또는 error 객체를 반환합니다. 그렇지 않으면 undefined를 반환합니다.
---import { actions } from 'astro:actions';
const result = Astro.getActionResult(actions.logout);---
<form action={actions.logout}> <button type="submit">Log out</button></form>{result?.error && <p>Failed to log out. Please try again.</p>}Astro.callAction()
섹션 제목: Astro.callAction()
Added in:
astro@4.15.0
Astro.callAction()은 Astro 컴포넌트에서 액션 핸들러를 직접 호출하는 데 사용되는 함수입니다. 이 함수는 액션 함수를 첫 번째 인수 (예: actions.logout)로 받고 액션이 수신하는 모든 입력을 두 번째 인수로 받습니다. 이 함수는 액션의 결과를 프로미스로 반환합니다.
---import { actions } from 'astro:actions';
const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });---엔드포인트 Context
섹션 제목: 엔드포인트 Context엔드포인트 함수는 첫 번째 매개변수로 context 객체를 받습니다. 이는 Astro global 속성의 많은 부분을 반영합니다.
import type { APIContext } from 'astro';
export function GET(context: APIContext) { // ...}context.params
섹션 제목: context.paramscontext.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
섹션 제목: context.props
Added in:
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
섹션 제목: context.request타입: Request
표준 Request 객체입니다. url, headers, method 및 요청 본문을 가져오는 데 사용할 수 있습니다.
import type { APIContext } from 'astro';
export function GET({ request }: APIContext) { return new Response(`Hello ${request.url}`);}함께 보기: Astro.request
context.cookies
섹션 제목: context.cookies타입: AstroCookies
context.cookies에는 쿠키를 읽고 조작하는 유틸리티가 포함되어 있습니다.
함께 보기: Astro.cookies
context.url
섹션 제목: context.url타입: URL
astro@1.5.0
현재 context.request.url URL 문자열 값에서 생성된 URL 객체.
함께 보기: Astro.url
context.clientAddress
섹션 제목: 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
섹션 제목: context.site타입: URL | undefined
astro@1.5.0
context.site는 Astro 구성의 site에서 만들어진 URL을 반환합니다. 정의되지 않은 경우 localhost에서 생성된 URL이 반환됩니다.
함께 보기: Astro.site
context.generator
섹션 제목: 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()
섹션 제목: 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()
섹션 제목: 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
섹션 제목: context.locals
Added in:
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); // "Default Title"}함께 보기: Astro.locals
context.getActionResult()
섹션 제목: context.getActionResult()타입: (action: TAction) => ActionReturnType<TAction> | undefined
astro@4.15.0
context.getActionResult()는 액션 제출의 결과를 반환하는 함수입니다. 이 함수는 액션 함수를 인수 (예: actions.logout)로 받고, 제출이 수신되면 data 또는 error 객체를 반환합니다. 그렇지 않으면 undefined를 반환합니다.
Astro.getActionResult()도 확인하세요.
context.callAction()
섹션 제목: context.callAction()
Added in:
astro@4.15.0
context.callAction()은 Astro 컴포넌트에서 액션 핸들러를 직접 호출하는 데 사용되는 함수입니다. 이 함수는 액션 함수를 첫 번째 인수로 받고 (예: actions.logout), 액션이 수신하는 모든 입력을 두 번째 인수로 받습니다. 이 함수는 액션의 결과를 프로미스로 반환합니다.
Astro.callAction()도 확인하세요.
getStaticPaths()
섹션 제목: getStaticPaths()타입: (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult
페이지가 파일 이름에 동적 매개변수를 사용하는 경우 해당 컴포넌트는 getStaticPaths() 함수를 내보내야 합니다.
Astro는 정적 사이트 빌더이기 때문에 이 기능이 필요합니다. 이는 전체 사이트가 미리 빌드되었음을 의미합니다. Astro가 빌드 시 페이지를 생성하는 방법을 모른다면 사용자가 사이트를 방문할 때 해당 페이지를 볼 수 없습니다.
---export async function getStaticPaths() { return [ { params: { /* 필수 */ }, props: { /* 선택사항 */ } }, { params: { ... } }, { params: { ... } }, // ... ];}---<!-- HTML 템플릿 작성 -->getStaticPaths() 함수는 Astro가 어떤 경로를 미리 렌더링할지 결정하기 위해 객체 배열을 반환해야 합니다.
동적 라우팅을 위한 정적 파일 엔드포인트에서도 사용할 수 있습니다.
params
섹션 제목: params반환된 모든 객체의 params 키는 Astro에게 어떤 경로를 빌드할지 알려줍니다. 반환된 매개변수는 컴포넌트 파일 경로에 정의된 동적 매개변수 및 나머지 매개변수에 다시 매핑되어야 합니다.
params는 URL로 인코딩되므로 문자열만 값으로 지원됩니다. 각 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를 사용한 데이터 전달생성된 각 페이지에 추가 데이터를 전달하려면 반환된 모든 경로 객체에 props 값을 설정할 수도 있습니다. params와 달리 props는 URL로 인코딩되지 않으므로 문자열로만 제한되지 않습니다.
예를 들어, 원격 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()
섹션 제목: paginate()페이지네이션은 Astro가 paginate() 함수를 통해 기본적으로 지원하는 웹사이트의 일반적인 사용 사례입니다. paginate()는 페이지가 매겨진 컬렉션의 모든 페이지에 대해 하나의 URL을 생성하는 getStaticPaths()에서 반환할 배열을 자동으로 생성합니다. 페이지 번호는 매개변수로 전달되고, 페이지 데이터는 page prop으로 전달됩니다.
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 });}
// 올바르게 설정되면 이제 page prop에 단일 페이지를 렌더링하는 데 필요한 모든 것이 포함됩니다 (다음 섹션 참조).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
섹션 제목: 페이지네이션의 page 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에 유용함).
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 앞에 기본 경로를 추가하세요.
import.meta
섹션 제목: 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 />;}