Referência de Diretivas de Template

Diretivas de template são um tipo especial de atributo HTML disponível dentro do template de qualquer componente Astro (arquivos .astro), com alguns podendo ser utilizados em arquivos .mdx.

Diretivas de template são utilizadas para controlar o comportamento de um elemento ou componente de alguma forma. Uma diretiva de template pode habilitar alguma funcionalidade do compilador que facilitaria sua vida (como utilizar class:list ao invés de class). Ou então, uma diretiva pode dizer para o compilador do Astro fazer algo especial com aquele componente (como hidratá-lo com client:load).

Esta página descreve todas as diretivas de template disponíveis para você no Astro e como elas funcionam.

Regras

Seção intitulada Regras

Para uma diretiva de template ser válida, ela deve:

• Incluir um dois-pontos : em seu nome, utilizando o padrão X:Y (ex: client:load).
• Ser visível ao compilador (ex.:X {...atributo} não funcionaria se atributo contivesse uma diretiva).

Algumas diretivas de template, mas não todas, podem receber um valor customizado:

• <X client:load /> (recebe nenhum valor)
• <X class:list={['alguma-classe-css']} /> (recebe um array)

Uma diretiva de template nunca é inclusa diretamente no HTML final resultante de um componente.

Diretivas Comuns

Seção intitulada Diretivas Comuns

class:list

Seção intitulada class:list

class:list={...} recebe um array de valores de classes e as converte em uma string de classes. Isso é fornecido pela famosa biblioteca utilitária clsx feita por @lukeed.

class:list recebe um array de vários diferentes tipos de valores:

• string: Adicionadas ao elemento class
• Object: Todas as chaves com valor truthy são adicionadas ao elemento class
• Array: Inserido como uma string dos valores
• Set: Inserido como uma string dos valores
• false, null ou undefined: pulado

<!-- Isso -->
<span class:list={[ 'ola tchau', { mundo: true }, [ 'amigo' ] ]} />
<!-- Se torna -->
<span class="olá tchau mundo amigo"></span>

set:html

Seção intitulada set:html

set:html={string} injeta uma string HTML em um elemento, similar a se utilizar el.innerHTML.

O valor não é automaticamente sanitizado pelo Astro! Tenha certeza de que o valor inserido é seguro, ou que você o sanitizou manualmente antes de passá-lo ao template. Esquecer disto vai te deixar exposto a ataques de Cross Site Scripting.

---
const stringHtmlBruta = "Olá <strong>Mundo</strong>"
---
<h1>{stringHtmlBruta}</h1>
  <!-- Resultado final: <h1>Olá &lt;strong&gt;Mundo&lt;/strong&gt;</h1> -->
<h1 set:html={stringHtmlBruta} />
  <!-- Resultado final: <h1>Olá <strong>Mundo</strong></h1> -->

Você também pode utilizar set:html em um <Fragment> para evitar adicionar um elemento wrapper desnecessário. Isso pode ser especialmente útil ao se buscar HTML de um CMS.

---
const conteudoCMS = await buscarHtmlCMS();
---
<Fragment set:html={conteudoCMS}>

set:html={Promise<string>} injeta uma string HTML em um elemento que é envolvido em uma Promise.

Isso pode ser usado para injetar HTML armazenado externamente, como de um banco de dados.

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

set:html={Promise<Response>} injeta uma Response em um elemento.

Isso é mais útil quando estiver utilizando fetch(). Por exemplo, ao buscar postagens antigas de um gerador de sites estáticos anterior.

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

set:html pode ser utilizado em qualquer tag e não tem que incluir HTML. Por exemplo, utilize com JSON.stringify() em uma tag <script> para adicionar um esquema JSON-LD em sua página.

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

📚 Veja como scripts no lado do cliente funcionam em componentes Astro.

define:vars

Seção intitulada define:vars

define:vars={...} pode passar variáveis do frontmatter do seu componente no lado do servidor para tags <script> ou <style> do cliente. Qualquer variável frontmatter serializável como JSON é suportada, incluindo props passadas ao seu componente através de Astro.props. Valores são serializados com JSON.stringify().

---
const corPrimeiroPlano = "rgb(221 243 228)";
const corPlanoDeFundo = "rgb(24 121 78)";
const mensagem = "Astro é incrível!";
---
<style define:vars={{ corTexto: corPrimeiroPlano, corPlanoDeFundo }}>
  h1 {
    background-color: var(--corPlanoDeFundo);
    color: var(--corTexto);
  }
</style>

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

Cuidado

Utilizar define:vars em uma tag <script> implica na diretiva is:inline, o que significa que seus scripts não passarão por bundle e serão inseridos diretamente no seu HTML.

Isso é porque quando o Astro faz bundle de um script, ele inclui e executa o script uma vez mesmo que você inclua o componente contendo o script múltiplas vezes em uma página. define:vars requer um script para ser executado novamente com cada par de valores, então Astro cria um script inline no lugar.

Para scripts, tente passar variáveis para scripts manualmente no lugar.

Diretivas Avançadas

Seção intitulada Diretivas Avançadas

is:raw

Seção intitulada is:raw

is:raw instrui o compilador do Astro a tratar qualquer elemento-filho do elemento como texto. Isso significa que toda a sintaxe de template especial do Astro será ignorada dentro desse componente.

Por exemplo, se você tivesse um componente Katex customizado que converte algum texto para HTML, usuários poderiam fazer isso:

---
import Katex from '../components/Katex.astro';
---
<Katex is:raw>Alguma {sintaxe} conflitante aqui</Katex>