API 참조

`Astro` global

Astro global은 .astro 파일의 모든 컨텍스트에서 사용할 수 있습니다. 다음과 같은 기능이 있습니다:

`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()의 래퍼이기 때문입니다..

Astro 프로젝트에서 import.meta.glob() 자체를 사용할 수도 있습니다. 다음과 같은 경우에 이 작업을 수행할 수 있습니다.

API 경로와 같이 .astro가 아닌 파일에 이 기능이 필요합니다. 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: 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 파일에는 다음과 같은 인터페이스가 있습니다:

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.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" />

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 및 요청 본문을 가져오는 데 사용할 수 있습니다.

<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';
}
---

또는 헤더를 설정하려면:

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

`Astro.cookies`

타입: AstroCookies

Added in: astro@1.4.0

Astro.cookies에는 서버 측 렌더링 모드에서 쿠키를 읽고 조작하기 위한 유틸리티가 포함되어 있습니다.

`get`

타입: (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

쿠키를 문자열이 아닌 타입으로 변환하기 위한 value 및 유틸리티 함수가 포함된 AstroCookie 객체로 쿠키를 가져옵니다.

`has`

타입: (key: string, options?: AstroCookieGetOptions) => boolean

이 쿠키가 존재하는지 여부입니다. 쿠키가 Astro.cookies.set()을 통해 설정된 경우 true를 반환하고, 그렇지 않으면 Astro.request에서 쿠키를 확인합니다.

`set`

타입: (key: string, value: string | object, options?: AstroCookieSetOptions) => void

쿠키의 key를 주어진 값으로 설정합니다. 그러면 쿠키 값을 문자열로 변환하려고 시도합니다. 옵션은 maxAge 또는 httpOnly와 같은 쿠키 기능을 설정하는 방법을 제공합니다.

`delete`

타입: (key: string, options?: AstroCookieDeleteOptions) => void

만료 날짜를 과거 (Unix 시간에서는 0)로 설정하여 쿠키를 무효화합니다.

쿠키가 “제거되면” (만료되면) Astro.cookies.has()는 false를 반환하고 Astro.cookies.get()은 value가 undefined인 AstroCookie를 반환합니다. 쿠키를 삭제할 때 사용할 수 있는 옵션은 domain, path, httpOnly, sameSite 및 secure입니다.

`merge`

타입: (cookies: AstroCookies) => void

새 AstroCookies 인스턴스를 현재 인스턴스에 병합합니다. 새 쿠키가 현재 인스턴스에 추가되고 같은 이름의 쿠키가 존재하면 기존 값을 덮어씁니다.

`headers`

타입: () => Iterator<string>

응답과 함께 전송될 Set-Cookie에 대한 헤더 값을 가져옵니다.

`AstroCookie`

Astro.cookies.get()을 통해 쿠키를 가져오면 AstroCookie 타입이 반환됩니다. 다음과 같은 구조를 가지고 있습니다.

`value`

타입: string

쿠키의 원시 문자열 값입니다.

`json`

타입: () => Record<string, any>

JSON.parse()를 통해 쿠키 값을 구문 분석하여 객체를 반환합니다. 쿠키 값이 유효한 JSON이 아닌 경우 예외가 발생합니다.

`number`

타입: () => number

쿠키 값을 숫자로 구문 분석합니다. 유효한 숫자가 아닌 경우 NaN을 반환합니다.

`boolean`

타입: () => boolean

쿠키 값을 true 또는 false로 변환합니다.

`AstroCookieGetOptions`

Added in: astro@4.1.0

쿠키를 얻으면 AstroCookieGetOptions 인터페이스를 통해 옵션을 지정할 수도 있습니다.

`decode`

타입: (value: string) => string

쿠키가 값으로 역직렬화되는 방식을 사용자 정의할 수 있습니다.

`AstroCookieSetOptions`

Added in: astro@4.1.0

Astro.cookies.set()을 통해 쿠키를 설정하면 AstroCookieSetOptions를 전달하여 쿠키 직렬화 방법을 맞춤설정할 수 있습니다.

`domain`

타입: string

도메인을 지정합니다. 도메인이 설정되지 않은 경우 대부분의 클라이언트는 현재 도메인에 적용되도록 해석합니다.

`expires`

타입: Date

쿠키가 만료되는 날짜를 지정합니다.

`httpOnly`

타입: boolean

true인 경우 클라이언트 측에서 쿠키에 액세스할 수 없습니다.

`maxAge`

타입: number

쿠키가 유효한 시간 (초)을 지정합니다.

`path`

타입: string

쿠키가 적용되는 도메인의 하위 경로를 지정합니다.

`sameSite`

타입: boolean | 'lax' | 'none' | 'strict'

SameSite 쿠키 헤더의 값을 지정합니다.

`secure`

타입: boolean

true인 경우 쿠키는 https 사이트에만 설정됩니다.

`encode`

타입: (value: string) => string

쿠키가 직렬화되는 방식을 사용자 정의할 수 있습니다.

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

타입: (rewritePayload: string | URL | Request) => Promise<Response>

Added in: 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

Added in: 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`

타입: string

Added in: astro@1.0.0-rc

요청의 IP 주소를 지정합니다. 이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

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

<div>Your IP address is: <span class="address">{ ip }</span></div>

`Astro.site`

타입: URL | undefined

Astro.site는 Astro 구성의 site에서 만들어진 URL을 반환합니다. Astro 구성의 site가 정의되지 않은 경우 Astro.site가 정의되지 않습니다.

`Astro.generator`

타입: string

Added in: 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.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 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.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`

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`

타입: string | undefined

Added in: astro@3.5.0

Astro.preferredLocale은 사용자가 선호하는 언어를 나타내는 계산된 값입니다.

i18n.locales 배열에 구성된 언어와 Accept-Language 헤더를 통해 사용자 브라우저에서 지원하는 언어를 확인하여 계산됩니다. 일치하는 항목이 없으면 이 값은 undefined입니다.

이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

`Astro.preferredLocaleList`

타입: string[] | undefined

Added in: astro@3.5.0

Astro.preferredLocaleList는 브라우저에서 요청하고 웹사이트에서 지원하는 모든 언어의 배열을 나타냅니다. 그러면 여러분의 사이트와 방문자 간에 호환되는 모든 언어 목록이 생성됩니다.

브라우저에서 요청한 언어가 언어 배열에 없으면 값은 []입니다. 즉, 방문자가 선호하는 언어을 지원하지 않습니다.

브라우저가 선호하는 언어를 지정하지 않으면 이 값은 i18n.locales가 됩니다. 지원되는 모든 언어는 선호 사항이 없는 방문자가 동일하게 선호하는 것으로 간주됩니다.

이 속성은 SSR(서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

`Astro.currentLocale`

타입: string | undefined

Added in: astro@3.5.6

locales 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 언어입니다. URL에 /[locale]/ 접두사가 포함되어 있지 않으면 값은 기본적으로 i18n.defaultLocale이 됩니다.

`Astro.getActionResult()`

타입: (action: TAction) => ActionReturnType<TAction> | undefined

Added in: 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()`

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 객체를 받습니다. 이는 Astro global 속성의 많은 부분을 반영합니다.

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`

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`

타입: 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`

타입: AstroCookies

context.cookies에는 쿠키를 읽고 조작하는 유틸리티가 포함되어 있습니다.

함께 보기: Astro.cookies

`context.url`

타입: URL

Added in: astro@1.5.0

현재 context.request.url URL 문자열 값에서 생성된 URL 객체.

함께 보기: Astro.url

`context.clientAddress`

타입: string

Added in: 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

Added in: astro@1.5.0

context.site는 Astro 구성의 site에서 만들어진 URL을 반환합니다. 정의되지 않은 경우 localhost에서 생성된 URL이 반환됩니다.

함께 보기: Astro.site

`context.generator`

타입: string

Added in: 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

Added in: 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>

Added in: astro@4.13.0

브라우저를 새 페이지로 리디렉션하지 않고 다른 URL이나 경로에서 콘텐츠를 제공할 수 있습니다.

이 메서드는 경로 위치에 대한 문자열, URL, 또는 Request 중 하나를 허용합니다.

문자열을 사용하여 명시적인 경로를 제공합니다:

import type { APIContext } from 'astro';

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

import type { APIContext } from 'astro';

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

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`

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

타입: (action: TAction) => ActionReturnType<TAction> | undefined

Added in: astro@4.15.0

context.getActionResult()는 액션 제출의 결과를 반환하는 함수입니다. 이 함수는 액션 함수를 인수 (예: actions.logout)로 받고, 제출이 수신되면 data 또는 error 객체를 반환합니다. 그렇지 않으면 undefined를 반환합니다.

Astro.getActionResult()도 확인하세요.

`context.callAction()`

Added in: astro@4.15.0

context.callAction()은 Astro 컴포넌트에서 액션 핸들러를 직접 호출하는 데 사용되는 함수입니다. 이 함수는 액션 함수를 첫 번째 인수로 받고 (예: actions.logout), 액션이 수신하는 모든 입력을 두 번째 인수로 받습니다. 이 함수는 액션의 결과를 프로미스로 반환합니다.

Astro.callAction()도 확인하세요.

`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는 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 값을 설정할 수도 있습니다. 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()`

페이지네이션은 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<TData>

페이지네이션은 페이지 컬렉션의 단일 데이터 페이지를 나타내는 모든 렌더링된 페이지에 page prop을 전달합니다. 여기에는 페이지를 매긴 데이터 (page.data)와 페이지의 메타데이터 (page.url, page.start, page.end, page.total 등)가 포함됩니다. 이 메타데이터는 “다음 페이지” 버튼이나 “100개 중 1-10개 표시” 메시지 등을 표시하는데 유용합니다.

`page.data`

타입: Array<TData>

현재 페이지에 대해 paginate() 함수에서 반환된 데이터 배열입니다.

`page.start`

타입: number

현재 페이지의 첫 번째 항목 색인으로 0부터 시작합니다. (예: pageSize: 25인 경우 1페이지에서는 0, 2페이지에서는 25입니다.)

`page.end`

타입: number

현재 페이지의 마지막 항목 색인입니다.

`page.size`

타입: number
기본값: 10

페이지당 항목 수입니다.

`page.total`

타입: number

모든 페이지의 총 항목 수입니다.

`page.currentPage`

타입: number

1부터 시작하는 현재 페이지 번호입니다.

`page.lastPage`

타입: number

총 페이지 수입니다.

`page.url.current`

타입: string

현재 페이지의 URL을 가져옵니다 (표준 URL에 유용함).

`page.url.prev`

타입: string | undefined

이전 페이지의 URL을 가져옵니다 (1페이지인 경우 undefined). base에 값이 설정된 경우 기본 경로를 URL 앞에 추가하세요.

`page.url.next`

타입: string | undefined

다음 페이지의 URL을 가져옵니다 (더 이상 페이지가 없으면 undefined). base에 값이 설정된 경우 기본 경로를 URL 앞에 추가하세요.

`page.url.first`

타입: string | undefined

Added in: astro@4.12.0

첫 페이지의 URL을 가져옵니다 (1페이지에 있는 경우 undefined). base의 값이 설정된 경우 URL 앞에 기본 경로를 추가하세요.

`page.url.last`

타입: string | undefined

Added in: astro@4.12.0

마지막 페이지의 URL을 가져옵니다 (더이상의 페이지가 존재하지 않는 경우 undefined). base의 값이 설정된 경우 URL 앞에 기본 경로를 추가하세요.

`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 속성 (width, height, style 등) */
  attributes: Record<string, any>;
  /* 검증된 매개변수 전달 */
  options: ImageTransform;
  /* 원본 매개변수 전달 */
  rawOptions: ImageTransform;
  /* 생성된 이미지의 경로 */
  src: string;
  srcSet: {
    /* 생성된 srcset의 값, 각 항목에는 URL과 크기 설명자가 있습니다. */
    values: SrcSetValue[];
    /* `srcset` 속성에서 사용할 수 있는 값 */
    attribute: string;
  };
}

콘텐츠 컬렉션 (`astro:content`)

Added in: astro@2.0.0

콘텐츠 컬렉션은 src/content/에서 Markdown 또는 MDX 문서를 구성하고 쿼리하는 API를 제공합니다. 기능 및 사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`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(),
  }),
});

// 'collections' 내보내기를 통해 정의된 컬렉션을 Astro에 노출하세요.
export const collections = { blog };

이 함수는 다음 속성을 허용합니다.

`type`

타입: 'content' | 'data'
기본값: 'content'

Added in: astro@2.5.0

type은 컬렉션에 저장된 항목의 형식을 정의하는 문자열입니다.

'content' - Markdown (.md), MDX (.mdx), Markdoc (.mdoc)와 같은 콘텐츠 작성 형식
'data' - JSON (.json) 또는 YAML (.yaml)과 같은 데이터 전용 형식의 경우

`schema`

타입: ZodType | (context: SchemaContext) => ZodType

schema는 컬렉션에 대한 문서 프런트매터의 타입과 모양을 구성하는 선택적 Zod 객체입니다. 각 값은 Zod 유효성 검사기를 사용해야 합니다.

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`reference()`

타입: (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

Added in: astro@2.5.0

reference() 함수는 콘텐츠 구성에서 한 컬렉션에서 다른 컬렉션으로의 관계 또는 “reference”를 정의하는 데 사용됩니다. 이는 컬렉션 이름을 전달받고 콘텐츠 프런트매터 또는 데이터 파일에 지정된 항목 식별자의 유효성을 검사합니다.

이 예시에서는 authors 컬렉션에 대한 블로그 작성자의 참조와 동일한 blog 컬렉션에 대한 관련 게시물 배열을 정의합니다.

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // `id`로 `authors` 컬렉션에서 단일 저자 참조
    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<TCollectionName>) => boolean) => CollectionEntry<TCollectionName>[]

getCollection()은 컬렉션 이름별로 콘텐츠 컬렉션 항목 목록을 검색하는 함수입니다.

기본적으로 컬렉션의 모든 항목을 반환하고 항목 속성별로 범위를 좁힐 수 있는 선택적 filter 함수를 허용합니다. 이를 통해 data 객체를 통해 id, slug 또는 프런트매터 값을 기반으로 컬렉션의 일부 항목만 쿼리할 수 있습니다.

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

// Get all `src/content/blog/` entries
const allBlogPosts = await getCollection('blog');

// 프런트매터에 `draft: true`가 포함된 게시물만 반환합니다.
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`getEntry()`

Added in: astro@2.5.0

타입:

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

getEntry()는 컬렉션 이름과 항목 id (type: 'data' 컬렉션의 경우) 또는 항목 slug (type: 'content' 컬렉션의 경우)로 단일 컬렉션 항목을 검색하는 함수입니다. getEntry()는 data, body, render() 속성에 액세스하기 위해 참조된 항목을 가져오는 데에도 사용할 수 있습니다.

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

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

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

// `data.captain`이 참조하는 프로필 가져오기
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

컬렉션 항목 쿼리의 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`getEntries()`

Added in: astro@2.5.0

타입:

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

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) => Promise<CollectionEntry<TCollectionName>>

getEntryBySlug()는 컬렉션 이름과 항목 slug로 단일 컬렉션 항목을 검색하는 함수입니다.

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

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

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`getDataEntryById()`

타입: (collection: string, id: string) => Promise<CollectionEntry<TCollectionName>>

Added in: astro@2.5.0

getDataEntryById()는 컬렉션 이름과 항목 id로 단일 컬렉션 항목을 검색하는 함수입니다.

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

컬렉션 항목 타입

getCollection(), getEntry(), getEntries()를 포함한 쿼리 함수는 각각 CollectionEntry 타입의 항목을 반환합니다. 이 타입은 astro:content에서 유틸리티로 사용할 수 있습니다.

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

CollectionEntry<TCollectionName> 타입은 다음 값을 갖는 객체입니다. TCollectionName은 쿼리 중인 컬렉션의 이름입니다 (예: CollectionEntry<'blog'>).

`id`

사용 가능 대상: type: 'content' 및 type: 'data' 컬렉션
타입 예시:

콘텐츠 컬렉션: 'entry-1.md' | 'entry-2.md' | ...
데이터 컬렉션: 'author-1' | 'author-2' | ...

src/content/[collection]에 상대적인 파일 경로를 사용하는 고유 ID입니다. 컬렉션 항목 파일 경로를 기반으로 가능한 모든 문자열 값을 열거합니다. type: 'content'로 정의된 컬렉션은 ID에 파일 확장자를 포함하지만 type: 'data'로 정의된 컬렉션은 포함하지 않습니다.

`collection`

사용 가능 대상: type: 'content' 및 type: 'data' 컬렉션
타입 예시: 'blog' | 'authors' | ...

항목이 위치한 src/content/ 아래의 최상위 폴더 이름입니다. 이는 스키마 및 쿼리 함수에서 컬렉션을 참조하는 데 사용되는 이름입니다.

`data`

사용 가능 대상: type: 'content' 및 type: 'data' 컬렉션
타입: CollectionSchema<TCollectionName>

컬렉션 스키마에서 추론된 프런트매터 속성의 객체입니다 (defineCollection() 참조를 확인하세요). 스키마가 구성되지 않은 경우 기본값은 any입니다.

`slug`

사용 가능 대상: type: 'content' 컬렉션 전용
타입 예시: 'entry-1' | 'entry-2' | ...

Markdown 또는 MDX 문서용 URL 지원 슬러그입니다. 파일 확장자가 없는 id가 기본값이지만 파일의 프런트매터에서 slug 속성을 설정하여 재정의할 수 있습니다.

`body`

사용 가능 대상: type: 'content' 컬렉션 전용
타입: string

Markdown 또는 MDX 문서의 컴파일되지 않은 원시 본문을 포함하는 문자열입니다.

`render()`

사용 가능 대상: type: 'content' 컬렉션 전용
타입: () => Promise<RenderedEntry>

렌더링을 위해 지정된 Markdown 또는 MDX 문서를 컴파일하는 기능입니다. 그러면 다음 속성이 반환됩니다.

<Content /> - Astro 파일에서 문서의 내용을 렌더링하는 데 사용되는 컴포넌트입니다.
headings - Markdown 및 MDX 가져오기에 대해 생성된 제목 목록, Astro의 getHeadings() 유틸리티 미러링.
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`

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 모든 컬렉션 이름의 문자열 통합입니다. 이 타입은 모든 컬렉션 이름을 허용하는 일반 함수를 정의할 때 유용할 수 있습니다.

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

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

`ContentCollectionKey`

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 type: 'content' 컬렉션의 모든 이름에 대한 문자열 통합입니다.

`DataCollectionKey`

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 type: 'data' 컬렉션의 모든 이름에 대한 문자열 통합입니다.

`SchemaContext`

defineCollection이 schema의 함수 모양을 위해 사용하는 context 객체입니다. 이 타입은 여러 컬렉션에 대해 재사용 가능한 스키마를 구축할 때 유용할 수 있습니다.

여기에는 다음 속성이 포함됩니다.

image - 콘텐츠 컬렉션에서 로컬 이미지를 사용할 수 있게 해주는 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`)

Added in: astro@2.6.0

미들웨어를 사용하면 페이지나 엔드포인트가 렌더링될 때마다 요청과 응답을 가로채고 동작을 동적으로 주입할 수 있습니다. 기능 및 사용 예시는 미들웨어 안내서 참조를 확인하세요.

`onRequest()`

타입: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

모든 페이지 또는 API 경로를 렌더링하기 전에 호출되는 src/middleware.js에서 내보낸 필수 함수입니다. 두 개의 인수 context 및 next()를 전달받습니다. onRequest()는 Response를 직접 반환하거나 next()를 호출하여 반환해야 합니다.

export function onRequest (context, next) {
    // 요청의 응답 데이터 가로채기
    // 선택적으로 응답을 변환합니다.
    // 응답을 직접 반환하거나 `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

Added in: astro@2.8.0

Astro 미들웨어 onRequest() 함수에 전달될 APIContext를 생성하는 저수준 API입니다.

이 함수는 Astro 미들웨어를 프로그래밍 방식으로 실행하기 위해 통합/어댑터에서 사용할 수 있습니다.

`trySerializeLocals()`

타입: (value: unknown) => string

Added in: astro@2.8.0

모든 값을 받아들여 해당 값의 직렬화된 버전 (문자열)을 반환하려고 시도하는 저수준 API입니다. 값을 직렬화할 수 없으면 함수에서 런타임 오류가 발생합니다.

국제화 (`astro:i18n`)

Added in: astro@3.5.0

이 모듈은 프로젝트에 구성된 로케일을 사용하여 URL을 생성하는 데 도움이 되는 함수를 제공합니다.

i18n 라우터를 사용하여 프로젝트에 대한 경로를 생성하는 것은 페이지 경로에 영향을 주는 특정 구성 값에 따라 달라집니다. 이러한 함수를 사용하여 경로를 생성할 때 다음에 대한 개별 설정을 고려해야 합니다.

또한 defaultLocale에 대해 이러한 함수에서 반환된 URL은 i18n.routing 구성을 반영합니다.

기능 및 사용 예시는 i18n 라우팅 가이드를 참조하세요.

`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"); // 구성된 첫 번째 code이기 때문에 "fr"을 반환합니다.
---

`redirectToDefaultLocale()`

타입: (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

Added in: astro@4.6.0

구성된 defaultLocale로 리디렉션되는 Response를 반환하는 함수입니다. 유효한 리디렉션 상태 코드를 선택적으로 허용합니다.

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>

Added in: 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

Added in: 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

Added in: 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

Added in: 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 });
})

View Transitions 클라이언트 API (`astro:transitions/client`)

Added in: astro@3.2.0

이 모듈은 View Transitions API 및 클라이언트 측 라우터를 제어하고 상호 작용하는 함수를 제공합니다.

기능 및 사용 예시는 View Transitions 가이드를 참조하세요.

`navigate()`

타입: (href: string, options?: Options) => void

Added in: astro@3.2.0

View Transitions API를 사용하여 지정된 href로 탐색을 실행하는 함수입니다.

이 함수 시그니처는 브라우저 Navigation API의 navigate 함수를 기반으로 합니다. 이 함수는 Navigation API를 기반으로 하지만, 페이지를 다시 로드하지 않고 탐색할 수 있도록 History API 위에 구현되어 있습니다.

`history` 옵션

타입: 'auto' | 'push' | 'replace'
기본값: 'auto'

Added in: astro@3.2.0

이 탐색을 브라우저 기록에 추가하는 방법을 정의합니다.

'push': 라우터는 history.pushState를 사용하여 브라우저 기록에 새 항목을 생성합니다.
'replace': 라우터는 history.replaceState를 사용하여 탐색에 새 항목을 추가하지 않고 URL을 업데이트합니다.
'auto' (기본값): 라우터는 history.pushState를 시도하지만, URL을 전환할 수 없는 경우 현재 URL은 브라우저 기록을 변경하지 않고 그대로 유지됩니다.

이 옵션은 브라우저 Navigation API의 history 옵션을 따르지만, Astro 프로젝트에서 발생할 수 있는 경우를 위해 단순화되었습니다.

`formData` 옵션

타입: FormData

Added in: astro@3.5.0

POST 요청을 위한 FormData 객체입니다.

이 옵션을 제공하면 탐색 대상 페이지에 대한 요청이 양식 데이터 객체를 콘텐츠로 하는 POST 요청으로 전송됩니다.

view transitions가 활성화된 HTML 양식을 제출하면 페이지 새로 고침이 있는 기본 탐색 대신 이 메서드가 사용됩니다. 이 메서드를 호출하면 프로그래밍 방식으로 동일한 동작을 트리거할 수 있습니다.

`info` 옵션

타입: any

Added in: astro@3.6.0

이 탐색으로 인해 발생하는 astro:before-preparation 및 astro:before-swap 이벤트에 포함될 임의의 데이터입니다.

이 옵션은 브라우저 Navigation API의 info 옵션을 모방합니다.

`state` 옵션

타입: any

Added in: astro@3.6.0

이 탐색에서 생성된 NavitationHistoryEntry 객체에 연결할 임의의 데이터입니다. 이 데이터는 History API의 history.getState 함수를 사용하여 검색할 수 있습니다.

이 옵션은 브라우저 Navigation API의 state 옵션을 모방합니다.

`sourceElement` 옵션

타입: Element

Added in: astro@3.6.0

이 탐색을 트리거한 요소 (있는 경우)입니다. 이 요소는 다음 이벤트에서 사용할 수 있습니다:

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

타입: boolean

Added in: astro@3.2.0

현재 브라우저에서 view transitions가 지원되고 활성화되어 있는지 여부입니다.

`transitionEnabledOnThisPage`

타입: boolean

Added in: astro@3.2.0

현재 페이지에 클라이언트 측 탐색을 위한 view transitions가 활성화되어 있는지 여부입니다. view transitions가 있는 페이지에서 사용할 때 다르게 동작하는 컴포넌트를 만드는 데 사용할 수 있습니다.

`getFallback`

타입: () => 'none' | 'animate' | 'swap'

Added in: astro@3.6.0

view transitions를 지원하지 않는 브라우저에서 사용할 대체 전략을 반환합니다.

대체 동작을 선택하고 구성하는 방법은 대체 제어 가이드를 참조하세요.

`astro:before-preparation` 이벤트

View Transitions를 사용하여 탐색을 시작할 때 전송되는 이벤트입니다. 이 이벤트는 요청이 이루어지고 브라우저 상태가 변경되기 전에 발생합니다.

이 이벤트에는 속성이 있습니다:

info
sourceElement
navigationType
direction
from
to
formData
loader

이 이벤트의 사용 방법에 대한 자세한 내용은 View Transitions 가이드에서 확인하세요.

`astro:after-preparation` 이벤트

View Transitions를 사용하는 탐색에서 다음 페이지가 로드된 후에 전송되는 이벤트입니다.

이 이벤트에는 속성이 없습니다.

이 이벤트의 사용 방법에 대한 자세한 내용은 View Transitions 가이드에서 확인하세요.

`astro:before-swap` 이벤트

다음 페이지가 구문 분석되고, 준비되고, 트랜지션을 준비하면서 문서에 링크된 후, 문서 간 콘텐츠가 교환되기 전에 전송되는 이벤트입니다.

이 이벤트는 취소할 수 없습니다. preventDefault()를 호출하는 것은 아무 작업도 하지 않습니다.

이 이벤트에는 속성이 있습니다:

info
sourceElement
navigationType
direction
from
to
viewTransition
swap

이 이벤트의 사용 방법에 대한 자세한 내용은 View Transitions 가이드에서 확인하세요.

`astro:after-swap` 이벤트

페이지의 콘텐츠가 교체된 후, view transition이 끝나기 전에 전달되는 이벤트입니다.

이 이벤트가 트리거될 때는, 이미 기록 항목과 스크롤 위치가 업데이트된 후입니다.

`astro:page-load` 이벤트

view transitions을 사용한 탐색이나 브라우저의 기본 기능으로 페이지 로드가 완료된 후 전달되는 이벤트입니다.

페이지에서 view transitions가 활성화되면 일반적으로 DOMContentLoaded에서 실행되는 코드가 이 이벤트에서 실행되도록 변경되어야 합니다.

View Transitions 이벤트 속성

Added in: astro@3.6.0

`info`

타입: URL

탐색 중에 정의된 임의의 데이터입니다.

이는 navigate() 함수의 info 옵션에 전달된 리터럴 값입니다.

`sourceElement`

타입: Element | undefined

탐색을 트리거한 요소입니다. 예를 들어 클릭된 <a> 요소가 될 수 있습니다.

navigate() 함수를 사용할 때, 이는 호출에서 지정된 요소가 됩니다.

`newDocument`

타입: Document

탐색의 다음 페이지에 대한 문서입니다. 이 문서의 내용은 현재 문서의 내용 대신 교체됩니다.

`navigationType`

타입: 'push' | 'replace' | 'traverse'

어떤 종류의 기록 탐색이 일어나고 있나요.

push: 새 페이지에 대한 새 NavigationHistoryEntry가 만들어지고 있습니다.
replace: 현재 NavigationHistoryEntry가 새 페이지의 항목으로 대체됩니다.
traverse: NavigationHistoryEntry이 생성되지 않습니다. 히스토리 내 위치가 변경됩니다. 순회 방향은 direction 속성에 지정됩니다.

`direction`

타입: Direction

트랜지션 방향입니다.

forward: 기록의 다음 페이지 또는 새 페이지로 이동합니다.
back: 기록의 이전 페이지로 이동합니다.
다른 리스너가 설정했을 수 있는 기타 모든 항목.

`from`

타입: URL

탐색을 시작하는 페이지의 URL입니다.

`to`

타입: URL

탐색 중인 페이지의 URL입니다. 이 속성은 수정할 수 있으며, 라이프사이클이 끝날 때의 값이 다음 페이지의 NavigationHistoryEntry에 사용됩니다.

`formData`

타입: FormData | undefined

POST 요청을 위한 FormData 객체입니다.

이 속성을 설정하면 일반적인 GET 요청 대신 지정된 양식 데이터 객체를 콘텐츠로 하는 POST 요청이 to URL로 전송됩니다.

view transitions가 활성화된 HTML 양식을 제출할 때 이 필드는 양식의 데이터로 자동 설정됩니다. navigate() 함수를 사용하는 경우 이 값은 옵션에 지정된 것과 동일합니다.

`loader`

타입: () => Promise<void>

탐색에서 다음 단계 (다음 페이지 로딩)를 구현합니다. 이 구현을 재정의하여 동작을 추가할 수 있습니다.

`viewTransition`

타입: ViewTransition

이 탐색에 사용된 view transition 객체입니다. View Transitions API를 지원하지 않는 브라우저에서는 편의를 위해 동일한 API를 구현하지만 DOM 통합이 없는 객체입니다.

`swap`

타입: () => void

문서 스왑 로직 구현.

나만의 사용자 지정 스왑 함수를 구축하는 방법에 대한 자세한 내용은 View Transitions 가이드를 참조하세요.

기본적으로 이 구현은 다음 함수를 순서대로 호출합니다:

`deselectScripts()`

타입: (newDocument: Document) => void

새 문서에서 실행해서는 안 되는 스크립트를 표시합니다. 이러한 스크립트는 이미 현재 문서에 있으며 data-astro-rerun을 사용하여 다시 실행하도록 플래그가 지정되지 않습니다.

`swapRootAttributes()`

타입: (newDocument: Document) => void

lang 속성과 같은 문서 루트 간 속성을 스왑합니다. 여기에는 data-astro-transition과 같은 Astro에서 삽입한 내부 속성도 포함되어 있어, 트랜지션 방향을 Astro에서 생성된 CSS 규칙에 사용할 수 있습니다.

사용자 지정 스왑 함수를 만들 때, view transition의 애니메이션이 깨지지 않도록 이 함수를 호출하는 것이 중요합니다.

`swapHeadElements()`

타입: (newDocument: Document) => void

현재 문서의 <head>에서 새 문서에 유지되지 않는 모든 요소를 제거합니다. 그런 다음 새 문서의 <head>에 있는 모든 새 요소를 현재 문서의 <head>에 추가합니다.

`saveFocus()`

타입: () => () => void

현재 페이지에서 초점이 맞춰진 요소를 저장하고 호출 시 초점이 맞춰진 요소가 유지된 경우 해당 요소에 초점을 반환하는 함수를 반환합니다.

`swapBodyElements()`

타입: (newBody: Element, oldBody: Element) => void

이전 body를 새 body로 교체합니다. 그런 다음 이전 body에서 유지되어야 하는 모든 요소를 검토하고 새 body에서 일치하는 요소를 찾아 이전 요소를 다시 제자리로 바꿉니다.

액션 (`astro:actions`)

Added in: astro@4.15.0

액션을 사용하면 클라이언트 코드 및 HTML 양식에서 호출할 수 있는 타입 안정성을 갖춘 백엔드를 구축할 수 있습니다. 액션을 정의하고 호출하는 모든 유틸리티는 astro:actions 모듈에 의해 노출됩니다. 예시 및 사용 지침은 액션 가이드를 참조하세요.

`defineAction()`

Added in: astro@4.15.0

defineAction() 유틸리티는 src/actions/index.ts 파일에서 새 액션을 정의하는 데 사용됩니다. 이 함수는 실행할 서버 로직이 포함된 handler() 함수와 런타임에 입력 매개변수를 검사하는 선택적인 input 속성을 받습니다.

export const server = {
  getGreeting: defineAction({
    input: z.object({
      name: z.string(),
    }),
    handler: async (input, context) => {
      return `Hello, ${input.name}!`
    }
  })
}

`handler()` 속성

타입: (input, context) => any

defineAction()에는 액션이 호출될 때 실행할 서버 로직이 포함된 handler() 함수가 필요합니다. 핸들러에서 반환된 데이터는 자동으로 직렬화되어 호출자에게 전송됩니다.

handler()는 사용자 입력을 첫 번째 인수로 받아 호출됩니다. input 유효성 검사기가 설정되어 있으면 사용자 입력은 핸들러로 전달되기 전에 유효성이 검사됩니다. 두 번째 인수는 getActionResult(), callAction() 및 redirect()를 제외한 대부분의 Astro 표준 엔드포인트 컨텍스트를 포함하는 context 객체입니다.

반환 값은 devalue 라이브러리를 사용하여 구문 분석됩니다. 이 라이브러리는 Date(), Map(), Set() 및 URL()의 인스턴스와 JSON 값을 지원합니다.

`input` 유효성 검사기

타입: ZodType | undefined

선택적 input 속성은 런타임에 핸들러 입력의 유효성을 검사하기 위해 Zod 유효성 검사기를 전달받습니다. 액션이 유효성 검사에 실패하면 BAD_REQUEST 오류가 반환되고 handler가 호출되지 않습니다.

input을 생략하면 handler는 JSON 요청의 경우 unknown 타입의 입력을, 양식 요청의 경우 FormData 타입의 입력을 받습니다.

`accept: 'form'`과 함께 사용

액션이 양식 입력을 전달받는 경우 z.object() 유효성 검사기를 사용하여 양식 데이터를 타입이 정해진 객체로 자동 구문 분석합니다. 양식 데이터 필드에 지원되는 유효성 검사기는 다음과 같습니다:

number 유형의 입력은 z.number()를 사용하여 검증할 수 있습니다.
checkbox 유형의 입력은 z.boolean()을 사용하여 검증할 수 있습니다.
file 유형의 입력은 z.instanceof(File)을 사용하여 검증할 수 있습니다.
동일한 name의 여러 입력은 z.array(/* validator */)를 사용하여 검증할 수 있습니다.
다른 모든 입력은 z.string()을 사용하여 검증할 수 있습니다.

.refine(), .transform(), .pipe()를 포함한 확장 함수도 z.object() 유효성 검사기에서 지원됩니다.

서로 다른 유효성 검사기의 조합을 적용하려면 z.discriminatedUnion() 래퍼를 사용하여 특정 양식 필드를 기준으로 타입을 좁히세요. 이 예시는 사용자 “생성” 또는 “업데이트” 중 하나로 양식 제출을 처리하며, type이라는 이름의 양식 필드를 사용하여 어떤 객체에 대해 유효성 검사를 수행할지 결정합니다.

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  changeUser: defineAction({
    accept: 'form',
    input: z.discriminatedUnion('type', [
      z.object({
        // `type` 필드에 `create` 값이 있을 때 일치합니다.
        type: z.literal('create'),
        name: z.string(),
        email: z.string().email(),
      }),
      z.object({
        // `type` 필드에 `update` 값이 있을 때 일치합니다.
        type: z.literal('update'),
        id: z.number(),
        name: z.string(),
        email: z.string().email(),
      }),
    ]),
    async handler(input) {
      if (input.type === 'create') {
        // input은 { type: 'create', name: string, email: string }
      } else {
        // input은 { type: 'update', id: number, name: string, email: string }
      }
    },
  }),
};

`isInputError()`

타입: (error?: unknown | ActionError) => boolean

Added in: astro@4.15.0

isInputError() 유틸리티는 ActionError가 입력 유효성 검사 오류인지 확인하는 데 사용됩니다. input 유효성 검사기가 z.object()인 경우 입력 오류에는 이름별로 그룹화된 오류 메시지가 있는 fields 객체가 포함됩니다.

양식 입력 오류 가이드에서 isInputError() 사용에 대한 자세한 내용을 참조하세요.

`ActionError`

Added in: astro@4.15.0

액션 handler가 던지는 오류를 생성하는 데 ActionError() 생성자가 사용됩니다. 이는 발생한 오류 (예: "UNAUTHORIZED")를 설명하는 code 속성과 추가 세부정보가 포함된 선택적 message 속성을 허용합니다.

`code`

Added in: astro@4.15.0

code 속성은 모든 HTTP 상태 코드의 사람이 읽을 수 있는 버전을 허용합니다. 지원되는 코드는 다음과 같습니다:

BAD_REQUEST (400): 클라이언트가 잘못된 입력을 보냈습니다. 이 오류는 액션 input 유효성 검사기가 유효성 검사에 실패할 때 발생합니다.
UNAUTHORIZED (401): 클라이언트에 유효한 인증 자격 증명이 없습니다.
FORBIDDEN (403): 클라이언트가 리소스에 액세스할 수 있는 권한이 없습니다.
NOT_FOUND (404): 서버가 요청된 리소스를 찾을 수 없습니다.
METHOD_NOT_SUPPORTED (405): 서버가 요청된 메서드를 지원하지 않습니다.
TIMEOUT (408): 서버가 요청을 처리하는 동안 시간 초과가 발생했습니다.
CONFLICT (409): 충돌로 인해 서버에서 리소스를 업데이트할 수 없습니다.
PRECONDITION_FAILED (412): 서버가 요청의 전제 조건을 충족하지 않습니다.
PAYLOAD_TOO_LARGE (413): 페이로드가 너무 커서 서버가 요청을 처리할 수 없습니다.
UNSUPPORTED_MEDIA_TYPE (415): 서버가 요청의 미디어 유형을 지원하지 않습니다. 참고: 액션은 이미 JSON 및 양식 요청에 대해 Content-Type 헤더를 확인하므로 이 코드를 수동으로 사용할 필요가 없을 것입니다.
UNPROCESSABLE_CONTENT (422): 시멘틱 오류로 인해 서버가 요청을 처리할 수 없습니다.
TOO_MANY_REQUESTS (429): 서버가 지정된 속도 제한을 초과했습니다.
CLIENT_CLOSED_REQUEST (499): 서버가 응답하기 전에 클라이언트가 요청을 종료했습니다.
INTERNAL_SERVER_ERROR (500): 서버가 예기치 않게 실패했습니다.
NOT_IMPLEMENTED (501): 서버가 요청된 기능을 지원하지 않습니다.
BAD_GATEWAY (502): 서버가 업스트림 서버로부터 잘못된 응답을 받았습니다.
SERVICE_UNAVAILABLE (503): 서버를 일시적으로 사용할 수 없습니다.
GATEWAY_TIMEOUT (504): 서버가 업스트림 서버로부터 시간 초과를 받았습니다.

`message`

Added in: astro@4.15.0

message 속성은 문자열을 받습니다. (예: “사용자는 로그인해야 합니다.“)

내장 컴포넌트

Astro에는 프로젝트에 사용할 수 있는 여러 내장 컴포넌트가 포함되어 있습니다. 모든 내장 컴포넌트는 import {} from 'astro:components';를 통해 .astro 파일에서 사용할 수 있습니다.

ComponentProp 타입 유틸리티를 사용하여 이 컴포넌트의 Props를 참조할 수 있습니다.

`<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에 의해 내부적으로 구동되며 모든 인기 있는 테마 및 언어를 지원합니다. 또한 사용자 정의 테마, 언어, transformers 및 기본 색상을 각각 theme, lang, transformers, defaultColor 속성에 전달하여 추가할 수 있습니다.

Transformers

Added in: astro@4.11.0

Shiki transformers는 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 />`

추가 래핑 요소 없이 HTML 콘텐츠를 렌더링하기 위해 set:* 지시어와 함께 사용되는 컴포넌트:

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

Astro 구문의 프래그먼트 사용에 대해 자세히 알아보세요.

`<Prism />`

Prism 구문 강조 컴포넌트를 사용하려면 먼저 @astrojs/prism 패키지를 설치하세요.

npm install @astrojs/prism

pnpm add @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 />`

---
// Image 컴포넌트 및 이미지 가져오기
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 1600x900의 이미지
---

<!-- Image 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="A description of my 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 />`

Added in: astro@3.3.0

다양한 형식 및/또는 크기로 반응형 이미지를 표시하려면 내장된 <Picture /> Astro 컴포넌트를 사용하세요.

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 1600x900의 이미지
---

<!-- Picture 컴포넌트에서는 '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() 함수는 .astro 파일 템플릿에 사용할 <Content /> 컴포넌트를 반환할 수 있습니다.

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

Added in: astro@2.9.0

원하는 모든 페이지의 <head>에 <ViewTransitions /> 라우팅 컴포넌트를 가져오고 추가하여 개별 페이지에서 view transitions를 사용하도록 선택합니다.

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

Astro.getActionResult()

Astro.callAction()

엔드포인트 Context

context.params

context.props

context.request

context.cookies

context.url

context.clientAddress

context.site

context.generator

context.redirect()

context.rewrite()

context.locals

context.getActionResult()

context.callAction()

getStaticPaths()

params

props를 사용한 데이터 전달

paginate()

페이지네이션의 page prop

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

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

`Astro.getActionResult()`

`Astro.callAction()`

`context.params`

`context.props`

`context.request`

`context.cookies`

`context.url`

`context.clientAddress`

`context.site`

`context.generator`

`context.redirect()`

`context.rewrite()`

`context.locals`

`context.getActionResult()`

`context.callAction()`

`getStaticPaths()`

`params`

`props`를 사용한 데이터 전달

`paginate()`

페이지네이션의 `page` prop

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