템플릿 지시어 참조

템플릿 지시어는 Astro 컴포넌트 템플릿 (.astro 파일)에서 사용할 수 있는 특별한 종류의 HTML 속성이며, 일부는 .mdx 파일에서도 사용할 수 있습니다.

템플릿 지시어는 어떤 방식으로든 요소나 컴포넌트의 동작을 제어하는 ​​데 사용됩니다. 템플릿 지시어는 여러분의 삶을 더 쉽게 만들어주는 일부 컴파일러 기능을 활성화할 수 있습니다 (예: class 대신 class:list 사용). 또는 지시어는 Astro 컴파일러에게 해당 컴포넌트에 대해 특별한 작업을 수행하도록 지시할 수 있습니다 (예: client:load를 사용하여 수화).

이 페이지에서는 Astro에서 사용할 수 있는 모든 템플릿 지시어와 작동 방식을 설명합니다.

템플릿 지시어가 유효하려면 다음을 충족해야 합니다.

• X:Y 형식을 사용하여 이름에 콜론 :을 포함해야합니다 (예: client:load).
• 컴파일러에 표시되어야 합니다 (예: <X {...attr}>는 attr에 지시어가 포함된 경우 작동하지 않습니다).

전부는 아니지만 일부 템플릿 지시어는 사용자 정의 값을 가질 수 있습니다.

• <X client:load /> (값 없음)
• <X class:list={['some-css-class']} /> (배열 사용)

템플릿 지시어는 컴포넌트의 최종 HTML 출력에 직접 포함되지 않습니다.

class:list={...}는 클래스 값의 배열을 가져와 이를 클래스 문자열로 변환합니다. 이는 @lukeed의 인기 있는 clsx 도우미 라이브러리를 기반으로 합니다.

class:list는 여러 가지 가능한 값 종류의 배열을 취합니다.

• string: class 요소에 추가됨
• Object: 참의 값을 가진 모든 키가 class 요소에 추가됩니다.
• Array: 평탄화됩니다.
• false, null, undefined: 무시됩니다.

<!-- 이 코드는 -->
<span class:list={[ 'hello goodbye', { world: true }, [ 'friend' ] ]} />
<!-- 아래 코드로 변환됩니다. -->
<span class="hello goodbye world friend"></span>

set:html={string}은 el.innerHTML 설정과 유사하게 HTML 문자열을 요소에 삽입합니다.

값은 Astro에 의해 자동으로 이스케이프되지 않습니다! 값을 신뢰하는지, 아니면 템플릿에 전달하기 전에 수동으로 이스케이프했는지 확인하세요. 이 작업을 잊어버리면 교차 사이트 스크립팅 (XSS) 공격에 노출될 수 있습니다.

---
const rawHTMLString = "Hello <strong>World</strong>"
---
<h1>{rawHTMLString}</h1>
  <!-- 출력 결과: <h1>Hello &lt;strong&gt;World&lt;/strong&gt;</h1> -->
<h1 set:html={rawHTMLString} />
  <!-- 출력 결과: <h1>Hello <strong>World</strong></h1> -->

불필요한 래퍼 요소를 추가하지 않으려면 <Fragment>에 set:html을 사용할 수도 있습니다. 이는 CMS에서 HTML을 가져올 때 특히 유용할 수 있습니다.

---
const cmsContent = await fetchHTMLFromMyCMS();
---
<Fragment set:html={cmsContent}>

set:html={Promise<string>}은 Promise에 포함된 요소에 HTML 문자열을 삽입합니다.

이는 데이터베이스와 같이 외부에 저장된 HTML을 삽입하는 데 사용할 수 있습니다.

---
import api from '../db/api.js';
---
<article set:html={api.getArticle(Astro.props.id)}></article>

set:html={Promise<Response>}는 Response를 요소에 삽입합니다.

이는 fetch()를 사용할 때 가장 유용합니다. 예를 들어 이전 정적 사이트 생성기에서 이전 게시물을 가져오는 것입니다.

<article set:html={fetch('http://example/old-posts/making-soup.html')}></article>

set:html은 모든 태그에 사용할 수 있으며, HTML을 포함할 필요가 없습니다. 예를 들어 <script>에서 JSON.stringify()와 함께 사용합니다. 태그를 사용하여 페이지에 JSON-LD 스키마를 추가하세요.

<script type="application/ld+json" set:html={JSON.stringify({
  "@context": "https://schema.org/",
  "@type": "Person",
  name: "Houston",
  hasOccupation: {
    "@type": "Occupation",
    name: "Astronaut"
  }
})}/>

define:vars={...}는 컴포넌트 프런트매터의 서버 측 변수를 클라이언트 <script> 또는 <style> 태그로 전달할 수 있습니다. Astro.props를 통해 컴포넌트에 전달된 props를 포함하여 모든 JSON 직렬화 가능 프런트매터 변수가 지원됩니다. 값은 JSON.stringify()로 직렬화됩니다.

---
const foregroundColor = "rgb(221 243 228)";
const backgroundColor = "rgb(24 121 78)";
const message = "Astro is awesome!";
---
<style define:vars={{ textColor: foregroundColor, backgroundColor }}>
  h1 {
    background-color: var(--backgroundColor);
    color: var(--textColor);
  }
</style>

<script define:vars={{ message }}>
  alert(message);
</script>

is:raw는 Astro 컴파일러에게 해당 요소의 모든 하위 요소를 텍스트로 처리하도록 지시합니다. 이는 이 컴포넌트에서 모든 특수 Astro 템플릿 구문이 무시된다는 것을 의미합니다.

예를 들어 일부 텍스트를 HTML로 변환하는 사용자 정의 Katex 컴포넌트가 있는 경우, 사용자가 다음을 수행하도록 할 수 있습니다.

---
import Katex from '../components/Katex.astro';
---
<Katex is:raw>Some conflicting {syntax} here</Katex>