Référence des directives de modèle

Les directives de modèle sont un type spécial d’attribut HTML disponible dans n’importe quel modèle de composant Astro (fichiers .astro). Certains peuvent également être utilisés dans les fichiers .mdx.

Les directives de modèle sont utilisées pour contrôler le comportement d’un élément ou d’un composant d’une certaine manière. Une directive de modèle peut activer certaines fonctionnalités du compilateur qui vous facilitent la vie (comme l’utilisation de class:list au lieu de class). Ou, une directive pourrait dire au compilateur d’Astro de faire quelque chose de spécial avec un composant (comme l’hydratation avec client:load).

Cette page décrit toutes les directives de modèle disponibles dans Astro et leur fonctionnement.

Règles

Titre de la section Règles

Pour qu’une directive de modèle soit valide, il faut :

• Inclure un deux-points : dans son nom, en utilisant la forme X:Y (ex : client:load).
• Être visible pour le compilateur (ex : <X {...attr}> ne fonctionnerait pas si attr contenait une directive).

Certaines directives de modèle, mais pas toutes, peuvent prendre une valeur personnalisée :

• <X client:load /> (ne prend aucune valeur)
• <X class:list={['une-class-css']} /> (prend un tableau)

Une directive de modèle n’est jamais incluse directement dans la sortie HTML finale d’un composant.

Directives Communes

Titre de la section Directives Communes

class:list

Titre de la section class:list

class:list={...} prend un tableau de classe et les convertit en une chaîne de caractères contenant les classes. Ceci est inspiré de la populaire bibliothèque d’assistance clsx de @lukeed, mais intégrée directement dans Astro lui-même.

class:list prend un tableau de plusieurs types de valeurs possibles :

• string : ajouté à l’élément class
• Object : toutes les clés truthy sont ajoutées à l’élément class
• Array : aplati
• false, null, ou undefined: ignoré

<!-- Ceci -->
<span class:list={[ 'bonjour salut', { bonjour: true, monde: true }, new Set([ 'bonjour', 'ami' ]) ]} />
<!-- Devient -->
<span class="bonjour salut monde ami"></span>

set:html

Titre de la section set:html

set:html={string} injecte une chaîne de caractères HTML dans un élément, similaire à la propriété el.innerHTML.

La valeur n’est pas automatiquement échappée par Astro ! Assurez-vous que vous faites confiance à la valeur ou que vous l’avez échappée manuellement avant de la transmettre au modèle. Oublier de le faire vous exposera aux attaques de type Cross Site Scripting (XSS).

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

Vous pouvez également utiliser set:html sur un <Fragment> pour éviter d’ajouter un élément d’enveloppe inutile. Cela peut être particulièrement utile lors de la récupération de code HTML à partir d’un CMS.

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

set:html={Promise<string>} injecte une chaîne de caractères HTML dans un élément qui est enveloppé dans une Promise.

Cela peut être utilisé pour injecter du HTML stocké en externe, comme dans une base de données.

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

set:html={Promise<Response>} injecte une Response dans un élément.

Ceci est particulièrement utile lors de l’utilisation de fetch(). Par exemple, récupérer d’anciens posts à partir d’un précédent générateur de site statique.

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

set:html peut être utilisé sur n’importe quelle balise et n’a pas besoin d’inclure de HTML. Par exemple, vous pouvez l’utiliser avec JSON.stringify() sur une balise <script> pour ajouter un schéma JSON-LD à votre page.

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

Découvrez comment les scripts côté client fonctionnent dans les composants Astro.

define:vars

Titre de la section define:vars

define:vars={...} peut passer des variables côté serveur du frontmatter de votre composant dans les balises client <script> ou <style>. Toute variable du frontmatter sérialisable en JSON est supportée, y compris les “props” transmis à votre composant via Astro.props. Les valeurs sont sérialisées avec JSON.stringify().

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

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

Attention

L’utilisation de define:vars sur une balise <script> implique la directive is:inline, ce qui signifie que vos scripts ne seront pas regroupés et seront intégrés directement dans le code HTML.

En effet, lorsque Astro regroupe un script, il inclut et exécute le script une seule fois même si vous incluez le composant contenant le script plusieurs fois sur une même page. define:vars nécessite qu’un script soit réexécuté avec chaque ensemble de valeurs, donc Astro crée un script en ligne à la place.

Pour les scripts, essayez plutôt de transmettre les variables aux scripts manuellement.

Directives Avancées

Titre de la section Directives Avancées

is:raw

Titre de la section is:raw

is:raw indique au compilateur d’Astro de traiter tous les enfants de cet élément comme du texte. Cela signifie que toute syntaxe spéciale de template Astro sera ignorée à l’intérieur de ce composant.

Par exemple, si vous aviez un composant Katex personnalisé qui convertit du texte en HTML, vous pourriez demander aux utilisateurs de faire ceci :

---
import Katex from '../components/Katex.astro' ;
---
<Katex is:raw>Certaines {syntaxes} contradictoires ici</Katex>