Référence API

`Astro` global

Le global Astro est disponible dans tous les contextes des fichiers .astro. Il a les fonctions suivantes :

`Astro.glob()`

Astro.glob() est un moyen de charger de nombreux fichiers locaux dans votre site statique.

---
const posts = await Astro.glob('../pages/post/*.md'); // renvoie un tableau de publications qui se trouvent à l'adresse ./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}>En savoir plus</a>
  </article>
))}
</div>

.glob() ne prend qu’un seul paramètre : une URL relative globale des fichiers locaux que vous souhaitez importer. Il est asynchrone et renvoie un tableau des exportations des fichiers correspondants.

.glob() ne peut pas prendre des variables ou des chaînes qui les interpolent, car elles ne sont pas statiquement analysables. (Voir le guide de dépannage pour une solution de contournement). Ceci est dû au fait que Astro.glob() est une enveloppe de import.meta.glob() de Vite.

Vous pouvez également utiliser import.meta.glob() dans votre projet Astro. Vous pouvez faire cela dans les cas suivants :

Vous avez besoin de cette fonctionnalité dans un fichier qui n’est pas .astro, comme une route d’API. Astro.glob() n’est disponible que dans les fichiers .astro, alors que import.meta.glob() est disponible n’importe où dans le projet.
Vous ne voulez pas charger chaque fichier immédiatement. import.meta.glob() peut retourner des fonctions qui importent le contenu du fichier, plutôt que de retourner le contenu lui-même. Notez que cette importation inclut tous les styles et les scripts pour tous les fichiers importés. Ceux-ci seront regroupés et ajoutés à la page, qu’un fichier soit réellement utilisé ou non, car c’est l’analyse statique qui en décide, et non l’exécution.
Vous voulez avoir accès au chemin de chaque fichier. import.meta.glob() renvoie une carte du chemin d’un fichier à son contenu, tandis que Astro.glob() renvoie une liste de contenu.
Vous voulez passer plusieurs motifs ; par exemple, vous voulez ajouter un “motif négatif” qui filtre certains fichiers. import.meta.glob() peut optionnellement prendre un tableau de chaînes globales, plutôt qu’une seule chaîne.

Pour en savoir plus, consultez la documentation de Vite.

Fichiers Markdown

Les fichiers Markdown chargés avec Astro.glob() renvoient l’interface MarkdownInstance suivante :

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Toutes les données spécifiées dans le frontmatter YAML de ce fichier. */
  frontmatter: T;
  /* Le chemin d'accès absolu de ce fichier */
  file: string;
  /* Le chemin affiché de ce fichier */
  url: string | undefined;
  /* Composant Astro qui affiche le contenu de ce fichier */
  Content: AstroComponentFactory;
  /** (Markdown uniquement) Contenu du fichier Markdown brut excepté la mise en page HTML et le frontmatter YAML */
  rawContent(): string;
  /** (Markdown uniquement) Fichier Markdown compilé en HTML excluant la mise en page HTML */
  compiledContent(): string;
  /* Fonction qui renvoie un tableau des éléments h1...h6 de ce fichier */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

Vous pouvez optionnellement fournir un type pour la variable frontmatter en utilisant un générique TypeScript.

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

Fichiers Astro

Les fichiers Astro ont l’interface suivante :

export interface AstroInstance {
  /* Le chemin d'accès à ce fichier */
  file: string;
  /* L'URL de ce fichier (s'il se trouve dans le répertoire des pages) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Autres fichiers

D’autres fichiers peuvent avoir des interfaces différentes, mais Astro.glob() accepte un générique TypeScript si vous savez exactement ce que contient un type de fichier non reconnu.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
---

`Astro.props`

Astro.props est un objet contenant toutes les valeurs qui ont été transmises en tant qu’attributs de composant. Les composants de mise en page pour les fichiers .md et .mdx reçoivent les valeurs de frontmatter comme props.

---
const { title, date } = Astro.props;
---
<div>
  <h1>{title}</h1>
  <p>{date}</p>
</div>

---
import Heading from '../components/Heading.astro';
---
<Heading title="Mon tout premier article" date="09 Août 2022" />

En savoir plus sur la façon dont les Mises en page Markdown et MDX gèrent les propriétés.

Apprenez à ajouter des définitions de type TypeScript pour vos props.

`Astro.params`

Astro.params est un objet contenant les valeurs des segments de routes dynamiques correspondant à cette requête.

Dans les versions statiques, il s’agira des params renvoyés par getStaticPaths() utilisés pour le pré-rendu des routes dynamiques.

Dans les versions SSR, il peut s’agir de n’importe quelle valeur correspondant aux segments de chemin dans le modèle de route dynamique.

---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

Voir aussi : params

`Astro.request`

Type : Request

Astro.request est un objet Request standard. Il peut être utilisé pour obtenir les propriétés url, headers, method, et même le corps de la requête.

<p>Réception d'une requête {Astro.request.method} depuis "{Astro.request.url}".</p>
<p>En-têtes de requête reçus : <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>

Voir aussi : Astro.url

`Astro.response`

Type : ResponseInit & { readonly headers: Headers }

Astro.response est un objet ResponseInit standard. Il a la structure suivante.

status : Le code de statut numérique de la réponse, par exemple 200.
statusText : Le message de statut associé au code de statut, par exemple 'OK'.
headers : Une instance Headers que vous pouvez utiliser pour définir les en-têtes HTTP de la réponse.

Astro.response est utilisé pour définir le status, le statusText et les headers de la réponse d’une page.

---
if(condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Non trouvé';
}
---

Ou de définir un en-tête :

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

`Astro.cookies`

Type : AstroCookies

Ajouté à la version : astro@1.4.0

Astro.cookies contient des utilitaires pour lire et manipuler les cookies en mode rendu à la demande.

`get`

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

Obtient le cookie sous la forme d’un objet AstroCookie, qui contient la value et des fonctions utilitaires pour convertir le cookie en types autres que des chaînes de caractères.

`has`

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

Détermine si ce cookie existe. Si le cookie a été défini via Astro.cookies.set() cela retournera true, sinon cela vérifiera les cookies dans Astro.request.

`set`

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

Fixe le cookie key à la valeur donnée. Ceci tentera de convertir la valeur du cookie en une chaîne de caractères. Les options permettent de définir les caractéristiques du cookie, comme maxAge ou httpOnly.

`delete`

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

Invalide un cookie en fixant la date d’expiration dans le passé (0 en temps Unix).

Une fois qu’un cookie est “supprimé” (expiré), Astro.cookies.has() retournera false et Astro.cookies.get() retournera un AstroCookie avec une valeur de undefined. Les options disponibles lors de la suppression d’un cookie sont : domain, path, httpOnly, sameSite, et secure.

`merge`

Type : (cookies: AstroCookies) => void

Fusionne une nouvelle instance AstroCookies dans l’instance actuelle. Tous les nouveaux cookies seront ajoutés à l’instance actuelle et tous les cookies portant le même nom remplaceront les valeurs existantes.

`headers`

Type : () => Iterator<string>

Obtient les valeurs de l’en-tête Set-Cookie qui seront envoyées avec la réponse.

`AstroCookie`

L’obtention d’un cookie via Astro.cookies.get() renvoie un type AstroCookie. Il a la structure suivante.

`value`

Type : string

La valeur brute de la chaîne du cookie.

`json`

Type : () => Record<string, any>

Analyse la valeur du cookie via JSON.parse(), retournant un objet. Génère une erreur si la valeur du cookie n’est pas un JSON valide.

`number`

Type : () => number

Analyse la valeur du cookie en tant que nombre. Renvoie NaN s’il ne s’agit pas d’un nombre valide.

`boolean`

Type : () => boolean

Convertit la valeur du cookie en un booléen.

`AstroCookieGetOptions`

Ajouté à la version : astro@4.1.0

L’obtention d’un cookie permet également de spécifier des options via l’interface AstroCookieGetOptions :

`decode`

Type : (value: string) => string

Permet de personnaliser la manière dont un cookie est désérialisé en une valeur.

`AstroCookieSetOptions`

Ajouté à la version : astro@4.1.0

La définition d’un cookie via Astro.cookies.set() permet de passer un AstroCookieSetOptions pour personnaliser la façon dont le cookie est sérialisé.

`domain`

Type : string

Spécifie le domaine. Si aucun domaine n’est défini, la plupart des clients interpréteront l’application au domaine actuel.

`expires`

Type : Date

Spécifie la date d’expiration du cookie.

`httpOnly`

Type : boolean

Si la valeur est true, le cookie ne sera pas accessible côté client.

`maxAge`

Type : number

Spécifie un nombre, en secondes, pour lequel le cookie est valide.

`path`

Type : string

Spécifie un sous-chemin du domaine dans lequel le cookie est appliqué.

`sameSite`

Type : boolean | 'lax' | 'none' | 'strict'

Spécifie la valeur de l’en-tête du cookie SameSite.

`secure`

Type : boolean

Si c’est vrai, le cookie n’est défini que sur les sites https.

`encode`

Type : (value: string) => string

Permet de personnaliser la façon dont le cookie est sérialisé.

`Astro.redirect()`

Type : (path: string, status?: number) => Response

Permet de rediriger vers une autre page, et optionnellement de fournir un code de réponse avec un statut HTTP comme second paramètre.

Une page (et non un composant enfant) doit retourner le résultat de Astro.redirect() pour que la redirection ait lieu.

Pour les sites générés statiquement, cela produira une redirection client utilisant une balise <meta http-equiv="refresh"> et ne prend pas en charge les codes d’état.

Lors de l’utilisation d’un mode d’affichage à la demande, les codes d’état sont pris en charge. Astro servira les requêtes redirigées avec un statut de réponse HTTP par défaut de 302 à moins qu’un autre code ne soit spécifié.

L’exemple suivant redirige un utilisateur vers une page de connexion :

---
import { isLoggedIn } from '../utils';

const cookie = Astro.request.headers.get('cookie');

// Si l'utilisateur n'est pas connecté, le rediriger vers la page de connexion.
if (!isLoggedIn(cookie)) {
  return Astro.redirect('/login');
}
---

`Astro.rewrite()`

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

Ajouté à la version : astro@4.13.0

Permet de servir du contenu à partir d’une URL ou d’un chemin différent sans rediriger le navigateur vers une nouvelle page.

La méthode accepte soit une chaîne de caractères, soit une URL, soit une Request pour l’emplacement du chemin.

Utilisez une chaîne de caractères pour fournir un chemin explicite :

---
return Astro.rewrite("/login")
---

Utilisez un type URL lorsque vous devez construire le chemin de l’URL pour la réécriture. L’exemple suivant affiche le chemin parent d’une page en créant une nouvelle URL à partir du chemin relatif "../" :

---
return Astro.rewrite(new URL("../", Astro.url))
---

Utilisez un type Request pour un contrôle complet de la Request envoyée au serveur pour le nouveau chemin. L’exemple suivant envoie une requête pour afficher la page parent tout en fournissant des en-têtes :

---
return Astro.rewrite(new Request(new URL("../", Astro.url), {
  headers: {
    "x-custom-header": JSON.stringify(Astro.locals.someValue)
  }
}))
---

`Astro.url`

Type : URL

Ajouté à la version : astro@1.0.0-rc

Un objet URL construit à partir de la chaîne d’URL courante Astro.request.url. Utile pour interagir avec les propriétés individuelles de l’URL de la requête, comme le chemin et l’origine.

Equivalent à new URL(Astro.request.url).

Astro.url aura pour valeur localhost en mode dev pour les sites statiques quand site n’est pas configuré et pour les sites rendus à la demande utilisant la sortie server ou hybrid.

<h1>L'URL actuelle est : {Astro.url}</h1>
<h1>Le chemin d'accès à l'URL actuelle est : {Astro.url.pathname}</h1>
<h1>L'origine de l'URL actuelle est : {Astro.url.origin}</h1>

Vous pouvez également utiliser Astro.url pour créer de nouvelles URL en le passant comme argument à [new URL()] (https://developer.mozilla.org/fr/docs/Web/API/URL).

---
// Exemple : Construire une URL canonique en utilisant votre domaine de production
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// Exemple : Construire une URL pour les méta-tags SEO en utilisant votre domaine actuel
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />

`Astro.clientAddress`

Type : string

Ajouté à la version : astro@1.0.0-rc

Spécifie l’adresse IP de la requête. Cette propriété n’est disponible que lors de la construction pour SSR (server-side rendering) et ne doit pas être utilisée pour les sites statiques.

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

<div>Votre adresse IP est : <span class="address">{ ip }</span></div>

`Astro.site`

Type : URL | undefined

Astro.site retourne une URL faite à partir de site dans votre configuration Astro. Si site n’est pas défini dans votre configuration Astro, Astro.site ne sera pas défini.

`Astro.generator`

Type : string

Ajouté à la version : astro@1.0.0

Astro.generator est un moyen pratique d’ajouter une balise <meta name="generator"> avec votre version actuelle d’Astro. Elle suit le format "Astro v1.x.x".

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>Généré avec <a href="https://astro.build">{Astro.generator}</a></p>
    </footer>
  </body>
</html>

`Astro.slots`

Astro.slots contient des fonctions utilitaires pour modifier les enfants d’un composant Astro.

`Astro.slots.has()`

Type : (slotName: string) => boolean

Vous pouvez vérifier si le contenu d’un slot spécifique existe avec Astro.slots.has(). Cela peut être utile lorsque vous voulez envelopper le contenu d’un slot, mais que vous ne voulez afficher les éléments de l’enveloppe que lorsque le slot est utilisé.

---
---
<slot />

{Astro.slots.has('more') && (
  <aside>
    <h2>Plus d'informations</h2>
    <slot name="more" />
  </aside>
)}

`Astro.slots.render()`

Type : (slotName: string, args?: any[]) => Promise<string>

Vous pouvez afficher de manière asynchrone le contenu d’un slot en une chaîne de caractères HTML en utilisant Astro.slots.render().

---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />

Astro.slots.render() accepte optionnellement un second argument : un tableau de paramètres qui sera transmis à tous les enfants de la fonction. Cela peut être utile pour les composants utilitaires personnalisés.

Par exemple, ce composant <Shout /> convertit sa propriété message en majuscules et le transmet au slot par défaut :

---
const message = Astro.props.message.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [message]);
}
---
<Fragment set:html={html} />

Une fonction de callback passée comme un enfant de <Shout /> recevra le paramètre message tout en majuscules :

---
import Shout from "../components/Shout.astro";
---
<Shout message="slots!">
  {(message) => <div>{message}</div>}
</Shout>

<!-- s'affiche comme <div>SLOTS!</div> -->

Les fonctions de rappel peuvent être transmises à des emplacements nommés à l’intérieur d’une balise d’élément HTML enveloppante avec un attribut slot. Cet élément est uniquement utilisé pour transférer la fonction de rappel à un emplacement nommé et ne sera pas rendu sur la page.

<Shout message="slots!">
  <fragment slot="message">
    {(message) => <div>{message}</div>}
  </fragment>
</Shout>

Utilisez un élément HTML standard pour la balise d’encapsulation ou toute balise en minuscules (par exemple <fragment> au lieu de <Fragment />) qui ne sera pas interprété comme un composant. N’utilisez pas l’élément HTML <slot> car il sera interprété comme un slot Astro.

`Astro.self`

Astro.self permet aux composants Astro d’être appelés de manière récursive. Ce comportement vous permet d’afficher un composant Astro à partir de lui-même en utilisant <Astro.self> dans le modèle du composant. Cela peut être utile pour itérer sur de grands magasins de données et des structures de données imbriquées.

---
const { items } = Astro.props;
---
<ul class="nested-list">
  {items.map((item) => (
    <li>
      <!-- S'il y a une structure de données imbriquée, nous affichons `<Astro.self>` -->
      <!-- et pouvons passer des props avec l'appel récursif -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>

Ce composant pourrait alors être utilisé comme suit :

---
import NestedList from './NestedList.astro';
---
<NestedList items={['A', ['B', 'C'], 'D']} />

Et afficherait le code HTML comme suit :

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

Ajouté à la version : astro@2.4.0

Astro.locals est un objet contenant toutes les valeurs de l’objet context.locals d’un middleware. Utilisez-le pour accéder aux données retournées par le middleware dans vos fichiers .astro.

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<ul>
    {orders.map(order => {
        return <li>{/* fait quelque chose avec chaque `order` */}</li>
    })}
</ul>

`Astro.preferredLocale`

Type : string | undefined

Ajouté à la version : astro@3.5.0

Astro.preferredLocale est une valeur calculée qui représente la locale préférée de l’utilisateur.

Elle est calculée en vérifiant les locales configurées dans votre tableau i18n.locales et les locales supportées par le navigateur de l’utilisateur via l’en-tête Accept-Language. Cette valeur est undefined si aucune correspondance n’existe.

Cette propriété n’est disponible que lors de la construction pour SSR (server-side rendering) et ne devrait pas être utilisée pour les sites statiques.

`Astro.preferredLocaleList`

Type : string[] | undefined

Ajouté à la version : astro@3.5.0

Astro.preferredLocaleList représente le tableau de toutes les locales qui sont à la fois demandées par le navigateur et supportées par votre site web. Cela produit une liste de toutes les langues compatibles entre votre site et votre visiteur.

Si aucune des langues demandées par le navigateur n’est trouvée dans votre tableau de langues, la valeur est [] : vous ne supportez aucune des langues préférées de votre visiteur.

Si le navigateur ne spécifie aucune langue préférée, alors cette valeur sera i18n.locales : toutes les langues supportées seront considérées comme préférées par un visiteur qui n’a pas de préférences.

Cette propriété n’est disponible que pour l’affichage côté serveur (SSR) et ne doit pas être utilisée pour les sites statiques.

`Astro.currentLocale`

Type : string | undefined

Ajouté à la version : astro@3.5.6

La locale calculée à partir de l’URL courante, en utilisant la syntaxe spécifiée dans votre configuration locales. Si l’URL ne contient pas de préfixe /[locale]/, alors la valeur sera par défaut i18n.defaultLocale.

`Astro.getActionResult()`

Type : (action: TAction) => ActionReturnType<TAction> | undefined

Ajouté à la version : astro@4.15.0 Nouveau

Astro.getActionResult() est une fonction qui renvoie le résultat d’une soumission d’Action. Celle-ci accepte une fonction d’action comme argument (par exemple, actions.logout) et renvoie un objet data ou error lorsqu’une soumission est reçue. Sinon, elle renverra undefined.

---
import { actions } from 'astro:actions';

const result = Astro.getActionResult(actions.logout);
---

<form action={actions.logout}>
  <button type="submit">Se déconnecter</button>
</form>
{result?.error && <p>Échec de la déconnexion. Veuillez réessayer.</p>}

`Astro.callAction()`

Ajouté à la version : astro@4.15.0 Nouveau

Astro.callAction() est une fonction utilisée pour appeler un gestionnaire d’Action directement depuis votre composant Astro. Celle-ci accepte une fonction Action comme premier argument (par exemple actions.logout) et toute entrée que l’action reçoit comme deuxième argument. Elle renvoie le résultat de l’action sous forme de promesse.

---
import { actions } from 'astro:actions';

const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---

Contexte du point de terminaison

Les fonctions de points de terminaisons reçoivent un objet contextuel comme premier paramètre. Il reflète la plupart des propriétés globales de Astro.

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

`context.params`

context.params est un objet contenant les valeurs des segments de routes dynamiques correspondant à cette requête.

Dans les versions statiques, il s’agira des params retournés par getStaticPaths() utilisés pour le pré-rendement des routes dynamiques.

Dans les versions SSR, il peut s’agir de n’importe quelle valeur correspondant aux segments de chemin dans le modèle de route dynamique.

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

Voir aussi : params

`context.props`

Ajouté à la version : astro@1.5.0

context.props est un objet contenant toutes les propriétés (props) transmises par getStaticPaths(). Comme getStaticPaths() n’est pas utilisé lors de la construction pour SSR (rendu côté serveur), context.props n’est disponible que dans les constructions statiques.

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

Voir aussi : Transfert de données avec props

`context.request`

Type : Request

Un objet Request standard. Il peut être utilisé pour obtenir les propriétés url, headers, method, et même le corps de la requête.

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Hello ${request.url}`);
}

Voir aussi : Astro.request

`context.cookies`

Type : AstroCookies

context.cookies contient des utilitaires pour lire et manipuler les cookies.

Voir aussi : Astro.cookies

`context.url`

Type : URL

Ajouté à la version : astro@1.5.0

Un objet URL construit à partir de la valeur de la chaîne URL context.request.url actuelle.

Voir aussi : Astro.url

`context.clientAddress`

Type : string

Ajouté à la version : astro@1.5.0

Spécifie l’adresse IP de la requête. Cette propriété n’est disponible que lors de la construction pour SSR (rendu côté serveur) et ne doit pas être utilisée pour les sites statiques.

import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Votre adresse IP est : ${clientAddress}`);
}

Voir aussi : Astro.clientAddress

`context.site`

Type : URL | undefined

Ajouté à la version : astro@1.5.0

context.site renvoie une URL générée à partir de site dans votre configuration Astro. Si elle n’est pas définie, elle retournera une URL générée à partir de localhost.

Voir aussi : Astro.site

`context.generator`

Type : string

Ajouté à la version : astro@1.5.0

context.generator est un moyen pratique d’indiquer la version d’Astro que votre projet utilise. Il suit le format "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);
}

Voir aussi : Astro.generator

`context.redirect()`

Type : (path: string, status?: number) => Response

Ajouté à la version : astro@1.5.0

context.redirect() renvoie un objet Response qui vous permet de rediriger vers une autre page. Cette fonction n’est disponible que lors de la construction pour SSR (rendu côté serveur) et ne doit pas être utilisée pour les sites statiques.

import type { APIContext } from 'astro';

export function GET({ redirect }: APIContext) {
  return redirect('/login', 302);
}

Voir aussi : Astro.redirect()

`context.rewrite()`

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

Ajouté à la version : astro@4.13.0

Permet de servir du contenu à partir d’une URL ou d’un chemin différent sans rediriger le navigateur vers une nouvelle page.

La méthode accepte soit une chaîne de caractères, soit une URL, soit une Request pour l’emplacement du chemin.

Utilisez une chaîne de caractères pour fournir un chemin explicite :

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

Voir aussi : Astro.rewrite()

`context.locals`

Ajouté à la version : astro@2.4.0

context.locals est un objet utilisé pour stocker et accéder à des informations arbitraires pendant le cycle de vie d’une requête.

Les fonctions du middleware peuvent lire et écrire les valeurs de context.locals :

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Titre par défaut";
  }
  return next();
}

Les points de terminaison de l’API ne peuvent lire que des informations provenant de context.locals :

import type { APIContext } from 'astro';

export function GET({ locals }: APIContext) {
  return new Response(locals.title); // "Titre par défaut"
}

Voir aussi : Astro.locals

`context.getActionResult()`

Type : (action: TAction) => ActionReturnType<TAction> | undefined

Ajouté à la version : astro@4.15.0 Nouveau

context.getActionResult() est une fonction qui renvoie le résultat d’une soumission d’Action. Celle-ci accepte une fonction d’action comme argument (par exemple actions.logout) et renvoie un objet data ou error lorsqu’une soumission est reçue. Sinon, elle renverra undefined.

Voir aussi Astro.getActionResult()

`context.callAction()`

Ajouté à la version : astro@4.15.0 Nouveau

context.callAction() est une fonction utilisée pour appeler un gestionnaire d’action directement depuis votre composant Astro. Celle-ci accepte une fonction Action comme premier argument (par exemple actions.logout) et toute entrée reçue par l’action comme deuxième argument. Elle renvoie le résultat de l’action sous forme de promesse.

Voir aussi Astro.callAction()

`getStaticPaths()`

Type : (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult

Si une page utilise des paramètres dynamiques dans le nom de fichier, ce composant devra exporter une fonction getStaticPaths().

Cette fonction est nécessaire car Astro est un constructeur de sites statiques. Cela signifie que l’ensemble de votre site est construit à l’avance. Si Astro ne sait pas générer une page au moment de la construction, vos utilisateurs ne la verront pas lorsqu’ils visiteront votre site.

---
export async function getStaticPaths() {
  return [
    { params: { /* requis */ }, props: { /* optionnel */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---
<!-- Votre modèle HTML ici. -->

La fonction getStaticPaths() doit renvoyer un tableau d’objets pour déterminer les chemins qui seront pré-rendus par Astro.

Elle peut également être utilisée dans les points de terminaison de fichiers statiques pour le routage dynamique.

`params`

La clé params de chaque objet retourné indique à Astro les routes à construire. Les paramètres retournés doivent correspondre aux paramètres dynamiques et aux paramètres de repos définis dans le chemin de fichier de votre composant.

Les params sont encodés dans l’URL, donc seules les chaînes de caractères sont supportées comme valeurs. La valeur de chaque objet params doit correspondre aux paramètres utilisés dans le nom de la page.

Par exemple, supposons que vous ayez une page à src/pages/posts/[id].astro. Si vous exportez getStaticPaths depuis cette page et que vous renvoyez les chemins suivants :

---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

Astro générera alors statiquement posts/1, posts/2, et posts/3 au moment de la construction.

Transfert de données avec `props`

Pour passer des données supplémentaires à chaque page générée, vous pouvez également définir une valeur props sur chaque objet path retourné. Contrairement à params, props n’est pas encodé dans l’URL et n’est donc pas limité à des chaînes de caractères.

Par exemple, supposons que vous génériez des pages basées sur des données récupérées à partir d’une API distante. Vous pouvez passer l’objet de données complet au composant page à l’intérieur de 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>

Vous pouvez également passer un tableau régulier, ce qui peut être utile pour générer ou créer une liste connue d’itinéraires.

---
export async function getStaticPaths() {
  const posts = [
    {id: '1', category: "astro", title: "Référence API"},
    {id: '2', category: "react", title: "Créer un compteur React !"}
  ];
  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>Catégorie : {post.category}</h2>
</body>

Astro va alors générer statiquement posts/1 et posts/2 au moment de la construction en utilisant le composant page dans pages/posts/[id].astro. La page peut référencer ces données en utilisant Astro.props :

`paginate()`

La pagination est un cas d’utilisation courant pour les sites web qu’Astro supporte nativement via la fonction paginate(). La fonction paginate() génère automatiquement le tableau à renvoyer par getStaticPaths() qui crée une URL pour chaque page de la collection paginée. Le numéro de page sera passé en tant que paramètre, et les données de la page seront passées en tant que propriété page.

export async function getStaticPaths({ paginate }) {
  // Chargez vos données avec fetch(), Astro.glob(), etc.
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;

  // Retourne une collection indexée de chemins d'accès pour tous les articles.
  return paginate(allPokemon, { pageSize: 10 });
}

// Si la configuration est correcte, la propriété page contient maintenant tout ce dont
// vous avez besoin pour afficher une seule page (voir la section suivante).
const { page } = Astro.props;

paginate() suppose un nom de fichier [page].astro ou [...page].astro. Le paramètre page devient le numéro de page dans votre URL :

/posts/[page].astro générerait les URL suivants /posts/1, /posts/2, /posts/3, etc.
/posts/[...page].astro générerait les URL suivants /posts, /posts/2, /posts/3, etc.

paginate() a les arguments suivants :

pageSize - Nombre d’éléments affichés par page (10 par défaut)
params - Envoi de paramètres supplémentaires pour la création de routes dynamiques
props - Envoi de propriétés supplémentaires pour qu’elles soient disponibles sur chaque page

La propriété `page` de pagination

La pagination va passer une propriété page à chaque page affichée qui représente une seule page de données dans la collection paginée. Cela inclut les données que vous avez paginées (page.data) ainsi que les métadonnées de la page (page.url, page.start, page.end, page.total, etc). Ces métadonnées sont utiles pour des choses comme un bouton « Page suivante » ou un message « Pages 1-10 sur 100 ».

`page.data`

Type : Array

Tableau des données renvoyées par data() pour la page en cours.

`page.start`

Type : number

Index du premier élément de la page courante, en commençant par 0. (par exemple, si pageSize : 25, ce sera 0 sur la page 1, 25 sur la page 2, etc.)

`page.end`

Type : number

Index du dernier élément de la page en cours.

`page.size`

Type : number
Par défaut : 10

Nombre d’éléments par page.

`page.total`

Type : number

Le nombre total d’éléments sur toutes les pages.

`page.currentPage`

Type : number

Le numéro de la page actuelle, en commençant par 1.

`page.lastPage`

Type : number

Le nombre total de pages.

`page.url.current`

Type : string

Obtenir l’URL de la page actuelle (utile pour les URL canoniques).

`page.url.prev`

Type : string | undefined

Récupère l’URL de la page précédente (sera undefined si à la page 1). Si une valeur est définie pour base, le chemin de la base est ajouté à l’URL.

`page.url.next`

Type : string | undefined

Récupère l’URL de la page suivante (sera undefined s’il n’y a plus de pages). Si une valeur est définie pour base, le chemin de la base est ajouté à l’URL.

`page.url.first`

Type : string | undefined

Ajouté à la version : astro@4.12.0

Récupère l’URL de la première page (sera undefined si c’est la page 1). Si une valeur est définie pour base, le chemin de la base est ajouté à l’URL.

`page.url.last`

Type : string | undefined

Ajouté à la version : astro@4.12.0

Récupère l’URL de la dernière page (sera undefined s’il n’y a plus de pages). Si une valeur est définie pour base, le chemin de la base est ajouté à l’URL.

`import.meta`

Tous les modules ESM incluent une propriété import.meta. Astro ajoute import.meta.env via Vite.

import.meta.env.SSR peut être utilisée pour identifier si le rendu se fait côté serveur. Parfois, vous souhaiterez peut-être une logique différente, comme un composant qui ne doit être restitué que dans le client :

export default function () {
  return import.meta.env.SSR ? <div class="spinner"></div> : <FancyComponent />;
}

Images (`astro:assets`)

`getImage()`

Type : (options: UnresolvedImageTransform) => Promise<GetImageResult>

La fonction getImage() est prévue pour générer des images destinées à être utilisées ailleurs que directement en HTML, par exemple dans une route d’API. Elle vous permet également de créer votre propre composant <Image /> personnalisé.

getImage() prend un objet d’options avec les mêmes propriétés que le composant Image (à l’exception de 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>

Il renvoie un objet avec le type suivant :

type GetImageResult = {
  /* Attributs HTML supplémentaires nécessaires au rendu de l'image (largeur, hauteur, style, etc.) */
  attributes: Record<string, any>;
  /* Paramètres passés validés */
  options: ImageTransform;
  /* Paramètres d'origine transmis */
  rawOptions: ImageTransform;
  /* Chemin d'accès à l'image générée */
  src: string;
  srcSet: {
    /* Valeurs générées pour srcset, chaque entrée a une URL et un descripteur de taille */
    values: SrcSetValue[];
    /* Une valeur prête à être utilisée dans l'attribut `srcset` */
    attribute: string;
  };
}

Collections de contenu (`astro:content`)

Ajouté à la version : astro@2.0.0

Les collections de contenu proposent des API pour configurer et interroger vos documents Markdown ou MDX dans src/content/. Pour connaître les fonctionnalités et les exemples d’utilisation, consultez notre guide sur les collections de contenu.

`defineCollection()`

Type : (input: CollectionConfig) => CollectionConfig

defineCollection() est un utilitaire pour configurer une collection dans un fichier src/content/config.*.

import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// Exposez votre collection définie à Astro
// avec l'exportation `collections`
export const collections = { blog };

Cette fonction accepte les propriétés suivantes :

`type`

Type : 'content' | 'data'
Par défaut : 'content'

Ajouté à la version : astro@2.5.0

type est une chaîne de caractères qui définit le type d’entrées stockées dans une collection :

'content' - pour les formats de création de contenu comme Markdown (.md), MDX (.mdx) ou Markdoc (.mdoc)
'data' - pour les formats de données uniquement comme JSON (.json) ou YAML (.yaml)

`schema`

Type : ZodType | (context: SchemaContext) => ZodType

schema est un objet Zod facultatif pour configurer le type et la forme du document pour une collection. Chaque valeur doit utiliser un validateur Zod.

Consultez le guide Collections de contenu pour un exemple d’utilisation.

`reference()`

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

Ajouté à la version : astro@2.5.0

La fonction reference() est utilisée dans la configuration du contenu pour définir une relation, ou une « référence », entre une collection et une autre. Elle accepte un nom de collection et valide le ou les identifiants d’entrée spécifiés dans le frontmatter de votre contenu ou dans votre fichier de données.

Cet exemple définit les références d’un auteur de blog à la collection authors et un tableau d’articles associés à la même collection blog :

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // Référencer un seul auteur de la collection `authors` par `id`
    author: reference('authors'),
    // Référencer un tableau d'articles connexes de la collection `blog` par `slug`
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

Consultez le guide Collections de contenu pour un exemple d’utilisation.

`getCollection()`

Type : (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

getCollection() est une fonction qui récupère une liste d’entrées de collection de contenu par nom de collection.

Il renvoie tous les éléments de la collection par défaut et accepte une fonction facultative filter pour affiner les propriétés d’entrée. Cela vous permet d’interroger uniquement certains éléments d’une collection en fonction de id, slug ou des valeurs du frontmatter via l’objet data.

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

// Obtenez toutes les entrées dans `src/content/blog/`
const allBlogPosts = await getCollection('blog');

// Ne renvoyez que les messages avec `draft: true` dans le frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

Consultez le guide Collections de contenu pour un exemple d’utilisation.

`getEntry()`

Ajouté à la version : astro@2.5.0

Types :

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

getEntry() est une fonction qui récupère une seule entrée de collection en utilisant le nom de la collection et soit l’entrée id (pour les collections utilisant type: 'data') soit l’entrée slug (pour les collections utilisant type: 'content'). getEntry() peut également être utilisée pour obtenir des entrées référencées pour accéder aux propriétés data, body ou render() :

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

// Récupère `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Récupère `src/content/captains/picard.yaml`
const picardProfile = await getEntry('captains', 'picard');

// Récupère le profil référencé par `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

Consultez le guide Collections de contenu pour des exemples d’interrogation des entrées de collection.

`getEntries()`

Ajouté à la version : astro@2.5.0

Types :

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

getEntries() est une fonction qui récupère plusieurs entrées dans une même collection. Ceci est utile pour renvoyer un tableau d’entrées référencées pour accéder à leurs propriétés data, body et render() associées.

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

const enterprisePost = await getEntry('blog', 'enterprise');

// Obtenir les articles associés référencés par `data.relatedPosts`
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`getEntryBySlug()`

Type : (collection: string, slug: string) => Promise<CollectionEntry<collection>>

getEntryBySlug() est une fonction qui récupère une seule entrée de collection en utilisant le nom de la collection et le slug d’une entrée.

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

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

Consultez le guide Collections de contenu pour un exemple d’utilisation.

`getDataEntryById()`

Type : (collection: string, id: string) => Promise<CollectionEntry<collection>>

Ajouté à la version : astro@2.5.0

getDataEntryById() est une fonction qui récupère une seule entrée de collection par nom de collection et par id d’entrée.

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

const picardProfile = await getDataEntryById('captains', 'picard');
---

Type des entrées de collection

Les fonctions de requête, notamment getCollection(), getEntry() et getEntries() renvoient chacune des entrées avec le type CollectionEntry. Ce type est disponible en tant qu’utilitaire depuis astro:content :

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

Le type CollectionEntry<TCollectionName> est un objet avec les valeurs suivantes. TCollectionName est le nom de la collection que vous interrogez (par exemple CollectionEntry<'blog'>).

`id`

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Exemple de types :

collections de contenu : 'entry-1.md' | 'entry-2.md' | ...
collections de données : 'author-1' | 'author-2' | ...

Un identifiant unique utilisant le chemin du fichier relatif à src/content/[collection]. Énumère toutes les valeurs de chaîne de caractères possibles en fonction des chemins d’accès au fichier d’entrée de collection. Notez que les collections définies comme type: 'content' incluent l’extension de fichier dans leur ID, contrairement aux collections définies comme type: 'data'.

`collection`

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Exemple de type : 'blog' | 'authors' | ...

Le nom d’un dossier placé à la racine de src/content/ et dans lequel se trouvent les entrées. Il s’agit du nom utilisé pour référencer la collection dans votre schéma et dans les fonctions de requête.

`data`

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Type : CollectionSchema<TCollectionName>

Un objet de propriétés provenant du frontmatter et déduit de votre schéma de collection (voir la référence defineCollection()). La valeur par défaut est any si aucun schéma n’est configuré.

`slug`

Disponible pour : les collections utilisant type: 'content' seulement
Exemple de type : 'entry-1' | 'entry-2' | ...

Un slug d’URL préparé pour les documents Markdown ou MDX. La valeur par défaut est id sans l’extension de fichier, mais peut être remplacée en définissant la propriété slug dans le frontmatter d’un fichier.

`body`

Disponible pour : les collections utilisant type: 'content' seulement
Type : string

Une chaîne de caractères contenant le corps brut et non compilé du document Markdown ou MDX.

`render()`

Disponible pour : les collections utilisant type: 'content' seulement
Type : () => Promise<RenderedEntry>

Une fonction pour compiler un document Markdown ou MDX donné à afficher. Cela renvoie les propriétés suivantes :

<Content /> - Un composant utilisé pour restituer le contenu du document dans un fichier Astro.
headings - Une liste générée de titres, reflétant l’utilitaire getHeadings() d’Astro sur les importations Markdown et MDX.
remarkPluginFrontmatter - L’objet frontmatter modifié après l’application de plugins Remark or Rehype. Définit sur le type any.

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

Consultez le guide Collections de contenu pour un exemple d’utilisation.

Autres types associés aux collections de contenu

Le module astro:content exporte également les types suivants pour les utiliser dans votre projet Astro :

`CollectionKey`

Ajouté à la version : astro@3.1.0

Une union de chaînes de caractères de tous les noms de collections définis dans votre fichier src/content/config.*. Ce type peut être utile lors de la définition d’une fonction générique qui accepte n’importe quel nom de collection.

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

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

`ContentCollectionKey`

Ajouté à la version : astro@3.1.0

Une union de chaînes de caractères de tous les noms des collections type: 'content' définies dans votre fichier src/content/config.*.

`DataCollectionKey`

Ajouté à la version : astro@3.1.0

Une union de chaînes de caractères de tous les noms de la collection type: 'data' définie dans votre fichier src/content/config.*.

`SchemaContext`

L’objet context que defineCollection utilise pour la forme de fonction du schema. Ce type peut être utile lors de la création de schémas réutilisables pour plusieurs collections.

Cela inclut la propriété suivante :

image - L’assistant de schéma image() qui vous permet d’utiliser des images locales dans les collections de contenu

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

Middleware (`astro:middleware`)

Ajouté à la version : astro@2.6.0

Le middleware vous permet d’intercepter les requêtes et les réponses et d’injecter des comportements de manière dynamique chaque fois qu’une page ou un point de terminaison est sur le point d’être rendu. Pour les fonctionnalités et les exemples d’utilisation, consultez notre guide Middleware.

`onRequest()`

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

Une fonction exportée requise depuis src/middleware.js qui sera appelée avant le rendu de chaque page ou route API. Elle reçoit deux arguments : context et next(). onRequest() doit renvoyer une réponse (Response) : soit directement, soit en appelant next().

export function onRequest (context, next) {
    // intercepte les données de réponse d'une requête
    // éventuellement, transforme la réponse
    // renvoie directement une réponse, ou le résultat de l'appel de `next()`
    return next();
};

`context`

Type : APIContext

Le premier argument de onRequest() est un objet de contexte. Il reflète de nombreuses propriétés globales d’Astro.

Consultez Contextes de point de terminaison pour plus d’informations sur l’objet de contexte.

`next()`

Type : (rewritePayload?: string | URL | Request) => Promise<Response>

Le deuxième argument de onRequest() est une fonction qui appelle tous les middlewares suivants de la chaîne et renvoie une Response. Par exemple, un autre middleware pourrait modifier le corps HTML d’une réponse et attendre le résultat de next() permettrait à votre middleware de répondre à ces modifications.

Depuis Astro v4.13.0, next() accepte un paramètre de chemin d’URL facultatif sous la forme d’une chaîne de caractères, d’une URL ou d’un objet Request pour réécrire la requête actuelle sans déclencher une nouvelle phase de rendu.

`sequence()`

Type : (...handlers: MiddlewareHandler[]) => MiddlewareHandler

Une fonction qui accepte les fonctions middleware comme arguments et les exécutera dans l’ordre dans lequel elles sont transmises.

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

Type : (context: CreateContext) => APIContext

Ajouté à la version : astro@2.8.0

Une API de bas niveau pour créer un objet APIContext à transmettre à une fonction onRequest() du middleware Astro.

Cette fonction peut être utilisée par les intégrations/adaptateurs pour exécuter par programmation le middleware Astro.

`trySerializeLocals()`

Type : (value: unknown) => string

Ajouté à la version : astro@2.8.0

Une API de bas niveau qui prend n’importe quelle valeur et tente d’en renvoyer une version sérialisée (une chaîne de caractères). Si la valeur ne peut pas être sérialisée, la fonction générera une erreur d’exécution.

Internationalisation (`astro:i18n`)

Ajouté à la version : astro@3.5.0

Ce module fournit des fonctions pour vous aider à créer des URL à l’aide des paramètres régionaux configurés de votre projet.

La création de routes pour votre projet avec le routeur i18n dépendra de certaines valeurs de configuration que vous avez définies et qui affectent les routes de vos pages. Lorsque vous créez des routes avec ces fonctions, veillez à prendre en compte vos paramètres individuels pour :

Notez également que les URL renvoyées créées par ces fonctions pour votre defaultLocale refléteront votre configuration i18n.routing.

Pour les fonctionnalités et les exemples d’utilisation, consultez notre guide de routage i18n.

`getRelativeLocaleUrl()`

Type : (locale: string, path?: string, options?: GetLocaleOptions) => string

Utilisez cette fonction pour récupérer un chemin relatif pour des paramètres régionaux. Si les paramètres régionaux n’existent pas, Astro renvoie une erreur.

---
getRelativeLocaleUrl("fr");
// renvoie /fr

getRelativeLocaleUrl("fr", "");
// renvoie /fr

getRelativeLocaleUrl("fr", "getting-started");
// renvoie /fr/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// renvoie /blog/fr-ca/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// renvoie /blog/fr_CA/getting-started
---

`getAbsoluteLocaleUrl()`

Type : (locale: string, path: string, options?: GetLocaleOptions) => string

Utilisez cette fonction pour récupérer un chemin absolu pour des paramètres régionaux lorsque [site] a une valeur. Si [site] n’est pas configuré, la fonction renvoie une URL relative. Si les paramètres régionaux n’existent pas, Astro renvoie une erreur.

---
// Si `site` est défini sur `https://example.com`

getAbsoluteLocaleUrl("fr");
// renvoie https://example.com/fr

getAbsoluteLocaleUrl("fr", "");
// renvoie https://example.com/fr

getAbsoluteLocaleUrl("fr", "getting-started");
// renvoie https://example.com/fr/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// renvoie https://example.com/blog/fr-ca/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// renvoie https://example.com/blog/fr_CA/getting-started
---

`getRelativeLocaleUrlList()`

Type : (path?: string, options?: GetLocaleOptions) => string[]

Utilisez cette fonction de la même manière que getRelativeLocaleUrl pour renvoyer une liste de chemins relatifs pour tous les paramètres régionaux.

`getAbsoluteLocaleUrlList()`

Type : (path?: string, options?: GetLocaleOptions) => string[]

Utilisez cette fonction de la même manière que getAbsoluteLocaleUrl pour renvoyer une liste de chemins absolus pour tous les paramètres régionaux.

`getPathByLocale()`

Type : (locale: string) => string

Une fonction qui renvoie le chemin (path) associé à un ou plusieurs codes lorsque les chemins de paramètres régionaux personnalisés sont configurés.

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getPathByLocale("fr"); // renvoie "french"
getPathByLocale("fr-CA"); // renvoie "french"
---

`getLocaleByPath()`

Type : (path: string) => string

Une fonction qui renvoie le code associé à un chemin (path) de paramètres régionaux.

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getLocaleByPath("french"); // renvoie "fr" car c'est le premier code configuré
---

`redirectToDefaultLocale()`

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

Ajouté à la version : astro@4.6.0

Une fonction qui renvoie une Response qui redirige vers les paramètres régionaux utilisés par défaut (defaultLocale). Il accepte un code d’état de redirection valide facultatif.

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

Type : (context: APIContext, response: Response) => Promise<Response>

Ajouté à la version : astro@4.6.0

Une fonction qui vous permet d’utiliser votre configuration i18n.fallback dans votre propre middleware.

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

Type : (context: APIContext, response?: Response) => Promise<Response> | undefined

Ajouté à la version : astro@4.6.0

Utilisez cette fonction dans votre middleware de routage pour renvoyer une 404 lorsque :

le chemin actuel n’est pas une racine, par exemple / ou /<base>
l’URL ne contient pas de paramètres régionaux

Lorsqu’une Response est transmise, la nouvelle Response émise par cette fonction contiendra les mêmes en-têtes que la réponse d’origine.

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

Type : (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

Ajouté à la version : astro@4.6.0

Une fonction qui vous permet de créer par programmation le middleware i18n d’Astro.

Ceci est utile lorsque vous souhaitez utiliser la logique i18n par défaut tout en ajoutant quelques exceptions pour votre site.

import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();

  // Logique personnalisée après résolution de la réponse.
  // Il est possible de capter la réponse provenant du middleware i18n d'Astro.

  return response;
});

export const onRequest = sequence(customLogic, middleware({
  prefixDefaultLocale: true,
  redirectToDefaultLocale: false
}))

`requestHasLocale()`

Type : (context: APIContext) => boolean

Ajouté à la version : astro@4.6.0

Vérifie si l’URL actuelle contient des paramètres régionaux configurés. En interne, cette fonction utilisera 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 });
})

API client de Transitions de Vue (`astro:transitions/client`)

Ajouté à la version : astro@3.2.0

Ce module fournit des fonctions pour contrôler et interagir avec l’API Transitions de Vue et le routeur côté client.

Pour des fonctionnalités et des exemples d’utilisation, consultez notre guide sur les Transitions de Vue.

`navigate()`

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

Ajouté à la version : astro@3.2.0

Une fonction qui exécute une navigation vers le href donné à l’aide de l’API Transitions de Vue.

Cette signature de fonction est basée sur la fonction navigate de l’API Navigation du navigateur. Bien que basée sur l’API Navigation, cette fonction est implémentée sur l’API History pour permettre la navigation sans recharger la page.

Option `history`

Type : 'auto' | 'push' | 'replace'
Par défaut : 'auto'

Ajouté à la version : astro@3.2.0

Définit la manière dont cette navigation doit être ajoutée à l’historique du navigateur.

'push' : le routeur utilisera history.pushState pour créer une nouvelle entrée dans l’historique du navigateur.
'replace' : le routeur utilisera history.replaceState pour mettre à jour l’URL sans ajouter de nouvelle entrée dans la navigation.
'auto' (par défaut) : le routeur tentera history.pushState, mais si l’URL ne peut pas être transférée, l’URL actuelle restera sans modification de l’historique du navigateur.

Cette option suit l’option history de l’API Navigation du navigateur mais simplifiée pour les cas qui peuvent survenir sur un projet Astro.

Option `formData`

Type : FormData

Ajouté à la version : astro@3.5.0

Un objet FormData pour les requêtes POST.

Lorsque cette option est fournie, les requêtes vers la page cible de navigation seront envoyées sous forme de requête POST avec l’objet de données du formulaire comme contenu.

L’envoi d’un formulaire HTML avec les transitions de vue activées utilisera cette méthode au lieu de la navigation par défaut avec rechargement de page. L’appel de cette méthode permet de déclencher le même comportement par programmation.

Option `info`

Type : any

Ajouté à la version : astro@3.6.0

Données arbitraires à inclure dans les événements astro:before-preparation et astro:before-swap provoqués par cette navigation.

Cette option imite l’option info de l’API Navigation du navigateur.

Option `state`

Type : any

Ajouté à la version : astro@3.6.0

Données arbitraires à associer à l’objet NavitationHistoryEntry créé par cette navigation. Ces données peuvent ensuite être récupérées à l’aide de la fonction history.getState de l’API History.

Cette option imite l’option state de l’API Navigation du navigateur.

Option `sourceElement`

Type : Element

Ajouté à la version : astro@3.6.0

L’élément qui a déclenché cette navigation, le cas échéant. Cet élément sera disponible dans les événements suivants :

astro:before-preparation
astro:before-swap

`supportsViewTransitions`

Type : boolean

Ajouté à la version : astro@3.2.0

Indique si les transitions de vue sont prises en charge et activées dans le navigateur actuel.

`transitionEnabledOnThisPage`

Type : boolean

Ajouté à la version : astro@3.2.0

Indique si la page actuelle comporte ou non des transitions d’affichage activées pour la navigation côté client. Cela peut être utilisé pour créer des composants qui se comportent différemment lorsqu’ils sont utilisés sur des pages avec des transitions de vue.

`getFallback`

Type : () => 'none' | 'animate' | 'swap'

Ajouté à la version : astro@3.6.0

Renvoie la stratégie de secours à utiliser dans les navigateurs qui ne prennent pas en charge les transitions de vue.

Voir le guide sur la Gestion de solution de secours pour savoir comment choisir et configurer le comportement de repli.

Événement `astro:before-preparation`

Un événement déclenché au début d’une navigation à l’aide de Transitions de Vue. Cet événement se produit avant toute demande et tout changement d’état du navigateur.

Cet événement possède les attributs suivants :

info
sourceElement
navigationType
direction
from
to
formData
loader

Pour en savoir plus sur l’utilisation de cet événement, consultez le Guide des Transitions de Vue.

Événement `astro:after-preparation`

Un événement envoyé après le chargement de la page suivante dans une navigation utilisant des Transitions de Vue.

Cet événement n’a aucun attribut.

Pour en savoir plus sur l’utilisation de cet événement, consultez le Guide des Transitions de Vue.

Événement `astro:before-swap`

Un événement envoyé après que la page suivante est analysée, préparée et liée à un document en prévision de la transition, mais avant que tout contenu ne soit échangé entre les documents.

Cet événement ne peut pas être annulé. L’appel de preventDefault() est une opération interdite.

Cet événement possède les attributs suivants :

info
sourceElement
navigationType
direction
from
to
viewTransition
swap

Pour en savoir plus sur l’utilisation de cet événement, consultez le Guide des Transitions de Vue.

Événement `astro:after-swap`

Un événement envoyé après que le contenu de la page a été échangé mais avant la fin de la transition de vue.

L’entrée de l’historique et la position de défilement ont déjà été mises à jour lorsque cet événement est déclenché.

Événement `astro:page-load`

Un événement envoyé une fois le chargement d’une page terminé, qu’il s’agisse d’une navigation utilisant des transitions de vue ou native du navigateur.

Lorsque les transitions de vue sont activées sur la page, le code qui s’exécuterait normalement sur DOMContentLoaded doit être modifié pour s’exécuter sur cet événement.

Attributs des événements de Transitions de Vue

Ajouté à la version : astro@3.6.0

`info`

Type : URL

Données arbitraires définies lors de la navigation.

Il s’agit de la valeur littérale transmise à l’option info de la fonction navigate().

`sourceElement`

Type : Element | undefined

L’élément qui a déclenché la navigation. Il peut s’agir, par exemple, d’un élément <a> sur lequel on a cliqué.

Lors de l’utilisation de la fonction navigate(), ce sera l’élément spécifié dans l’appel.

`newDocument`

Type : Document

Le document de la page suivante dans la navigation. Le contenu de ce document sera échangé à la place du contenu du document actuel.

`navigationType`

Type : 'push' | 'replace' | 'traverse'

Quel type de navigation dans l’historique est en cours.

push: une nouvelle NavigationHistoryEntry est en cours de création pour la nouvelle page.
replace: l’actuelle NavigationHistoryEntry est remplacée par une entrée pour la nouvelle page.
traverse: aucune NavigationHistoryEntry n’est créée. La position dans l’historique change. La direction du parcours est donnée sur l’attribut direction

`direction`

Type : Direction

La direction de la transition.

forward : naviguer vers la page suivante de l’historique ou vers une nouvelle page.
back : naviguer vers la page précédente de l’historique.
Tout ce qu’un autre écouteur d’événement aurait pu définir.

`from`

Type : URL

L’URL de la page initiant la navigation.

`to`

Type : URL

L’URL de la page vers laquelle on navigue. Cette propriété peut être modifiée, la valeur à la fin du cycle de vie sera utilisée dans le NavigationHistoryEntry pour la page suivante.

`formData`

Type : FormData | undefined

Un objet FormData pour les requêtes POST.

Lorsque cet attribut est défini, une requête POST sera envoyée à l’URLto avec l’objet de données de formulaire donné comme contenu au lieu de la requête GET normale.

Lors de la soumission d’un formulaire HTML avec les transitions de vue activées, ce champ est automatiquement défini sur les données du formulaire. Lorsque vous utilisez la fonction navigate(), cette valeur est la même que celle donnée dans les options.

`loader`

Type : () => Promise<void>

Implémentation de la phase suivante dans la navigation (chargement de la page suivante). Cette implémentation peut être surchargée pour ajouter un comportement supplémentaire.

`viewTransition`

Type : ViewTransition

L’objet de transition de vue utilisé dans cette navigation. Sur les navigateurs qui ne prennent pas en charge l’API de Transitions de Vue, il s’agit d’un objet implémentant la même API pour plus de commodité, mais sans l’intégration DOM.

`swap`

Type : () => void

Mise en place de la logique d’échange de documents.

Apprenez-en davantage sur la façon de créer votre propre fonction d’échange personnalisée dans le guide Transitions de Vue.

Par défaut, cette implémentation appellera les fonctions suivantes dans l’ordre :

`deselectScripts()`

Type : (newDocument: Document) => void

Marque les scripts du nouveau document qui ne doivent pas être exécutés. Ces scripts sont déjà présents dans le document actuel et ne sont pas signalés pour une réexécution à l’aide de data-astro-rerun.

`swapRootAttributes()`

Type : (newDocument: Document) => void

Échange les attributs entre les racines du document, comme l’attribut lang. Cela inclut également les attributs internes injectés par Astro comme data-astro-transition, qui rendent la direction de transition disponible pour les règles CSS générées par Astro.

Lors de la création d’une fonction d’échange personnalisée, il est important d’appeler cette fonction afin de ne pas interrompre les animations de transition de vue.

`swapHeadElements()`

Type : (newDocument: Document) => void

Supprime tous les éléments présents dans la balise <head> du document actuel qui ne sont pas conservés dans le nouveau document. Ajoute ensuite tous les nouveaux éléments présents dans la balise <head> du nouveau document dans celle du document courant.

`saveFocus()`

Type : () => () => void

Stocke l’élément focalisé sur la page actuelle et renvoie une fonction qui, lorsqu’elle est appelée, si l’élément focalisé a été conservé, renvoie le focus sur celui-ci.

`swapBodyElements()`

Type : (newBody: Element, oldBody: Element) => void

Remplace l’ancien corps par le nouveau. Ensuite, il passe en revue chaque élément de l’ancien corps qui doit être conservé et qui possède un élément correspondant dans le nouveau corps avant de remplacer l’ancien élément en place.

Actions (`astro:actions`)

Ajouté à la version : astro@4.15.0 Nouveau

Les actions vous aident à créer un backend avec sécurité de types que vous pouvez appeler à partir du code client et des formulaires HTML. Tous les utilitaires permettant de définir et d’appeler des actions sont exposés par le module astro:actions. Pour des exemples et des instructions d’utilisation, consultez le guide Actions.

`defineAction()`

Ajouté à la version : astro@4.15.0 Nouveau

L’utilitaire defineAction() est utilisé pour définir de nouvelles actions à partir du fichier src/actions/index.ts. Il accepte une fonction handler() contenant la logique du serveur à exécuter et une propriété facultative input pour valider les paramètres d’entrée lors de l’exécution.

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

Propriété `handler()`

Ajouté à la version : astro@4.15.0 Nouveau

defineAction() accepte une fonction handler() contenant la logique du serveur à exécuter lorsque l’action est appelée. Cette fonction peut renvoyer des données qui sont automatiquement sérialisées et envoyées à l’appelant.

Les valeurs de retour sont analysées à l’aide de la bibliothèque devalue. Celle-ci prend en charge les valeurs JSON, ainsi que les instances de Date(), Map(), Set() ou URL().

Validateur de saisie (`input`)

Ajouté à la version : astro@4.15.0 Nouveau

La propriété facultative input accepte un validateur Zod pour vérifier les entrées du gestionnaire lors de l’exécution. Si l’action échoue à la validation, une erreur BAD_REQUEST est renvoyée et la fonction handler n’est pas appelée.

S’il est utilisé avec accept: 'form', input doit utiliser le validateur z.object().

Les fonctions d’extension, notamment .refine(), .transform() et .pipe(), sont également prises en charge sur cet objet. Les validateurs suivants sont pris en charge pour les champs de données de formulaire :

Les entrées de type number peuvent être validées à l’aide de z.number()
Les entrées de type checkbox peuvent être validées à l’aide de z.boolean()
Les entrées de type file peuvent être validées à l’aide de z.instanceof(File)
Plusieurs entrées du même nom (name) peuvent être validées à l’aide de z.array(/* validateur */)
Toutes les autres entrées peuvent être validées à l’aide de z.string()

`isInputError()`

Type : (error?: unknown | ActionError) => boolean

Ajouté à la version : astro@4.15.0 Nouveau

L’utilitaire isInputError() permet de vérifier si une ActionError est une erreur de validation d’entrée. Lorsque le validateur utilisé pour input correspond à z.object(), les erreurs d’entrée incluent un objet fields avec des messages d’erreur regroupés par nom.

Consultez le guide des erreurs de saisie de formulaire pour en savoir plus sur l’utilisation de isInputError().

`ActionError`

Ajouté à la version : astro@4.15.0 Nouveau

Le constructeur ActionError() est utilisé pour créer des erreurs générées par un gestionnaire d’action (handler). Il accepte une propriété code décrivant l’erreur qui s’est produite (exemple : "UNAUTHORIZED"), et une propriété facultative message contenant plus de détails.

`code`

Ajouté à la version : astro@4.15.0 Nouveau

La propriété code accepte les versions lisibles par l’homme de tous les codes d’état HTTP. Les codes suivants sont pris en charge :

BAD_REQUEST (400) : Le client a envoyé une entrée non valide. Cette erreur est générée lorsqu’un validateur d’entrée d’action (input) ne parvient pas à valider.
UNAUTHORIZED (401) : Le client ne dispose pas d’informations d’authentification valides.
FORBIDDEN (403) : Le client n’est pas autorisé à accéder à une ressource.
NOT_FOUND (404) : Le serveur ne trouve pas la ressource demandée.
METHOD_NOT_SUPPORTED (405) : Le serveur ne prend pas en charge la méthode demandée.
TIMEOUT (408) : Le serveur a expiré lors du traitement de la demande.
CONFLICT (409) : Le serveur ne peut pas mettre à jour une ressource en raison d’un conflit.
PRECONDITION_FAILED (412) : Le serveur ne répond pas à une condition préalable de la requête.
PAYLOAD_TOO_LARGE (413) : Le serveur ne peut pas traiter la demande car la charge utile est trop importante.
UNSUPPORTED_MEDIA_TYPE (415) : Le serveur ne prend pas en charge le type de média de la requête. Remarque : les actions vérifient déjà l’en-tête Content-Type pour les requêtes JSON et de formulaire. Vous n’aurez donc probablement pas besoin de générer ce code manuellement.
UNPROCESSABLE_CONTENT (422) : Le serveur ne peut pas traiter la demande en raison d’erreurs sémantiques.
TOO_MANY_REQUESTS (429) : Le serveur a dépassé une limite de débit spécifiée.
CLIENT_CLOSED_REQUEST (499) : Le client a fermé la demande avant que le serveur puisse répondre.
INTERNAL_SERVER_ERROR (500) : Le serveur est tombé en panne de manière inattendue.
NOT_IMPLEMENTED (501) : Le serveur ne prend pas en charge la fonctionnalité demandée.
BAD_GATEWAY (502) : Le serveur a reçu une réponse non valide d’un serveur en amont.
SERVICE_UNAVAILABLE (503) : Le serveur est temporairement indisponible.
GATEWAY_TIMEOUT (504) : Le serveur a reçu un délai d’attente d’un serveur en amont.

`message`

Ajouté à la version : astro@4.15.0 Nouveau

La propriété message accepte une chaîne de caractères. (par exemple, « L’utilisateur doit être connecté. »)

Composants intégrés

Astro comprend plusieurs composants intégrés que vous pouvez utiliser dans vos projets. Tous les composants intégrés sont disponibles dans les fichiers .astro via import {} from 'astro:components';.

Vous pouvez référencer les Props de ces composants à l’aide de l’utilitaire ComponentProp.

`<Code />`

---
import { Code } from 'astro:components';
---
<!-- Ajouter la coloration syntaxique à du code JavaScript. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- Facultatif : Personnaliser votre thème. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- Facultatif : Activer le retour à la ligne. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- Facultatif : Générer du code en ligne. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  sera généré en ligne.
</p>
<!-- Facultatif : defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

Ce composant fournit une coloration syntaxique pour les blocs de code au moment de la construction (aucun JavaScript côté client n’est inclus). Le composant est alimenté en interne par Shiki et prend en charge tous les thèmes et langues populaires. De plus, vous pouvez ajouter vos thèmes, langues, transformateurs et couleurs par défaut personnalisés en les transmettant respectivement aux attributs theme, lang, transformers et defaultColor.

Transformateurs

Ajouté à la version : astro@4.11.0

Les Transformateurs de Shiki peuvent éventuellement être appliqués au code en les transmettant via la propriété transformers sous forme de tableau. Depuis Astro v4.14.0, vous pouvez également fournir une chaîne de caractères à l’attribut meta de Shiki pour transmettre des options aux transformateurs.

Notez que transformers n’applique que les classes et vous devez fournir vos propres règles CSS pour cibler les éléments de votre bloc de code.

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

Un composant utilisé avec les directives set:* pour restituer le contenu HTML sans aucun élément d’habillage supplémentaire :

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

En savoir plus sur l’utilisation de fragments dans la syntaxe Astro.

`<Prism />`

Pour utiliser le composant de coloration Prism, installez d’abord le package @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';`} />

Ce composant fournit une coloration syntaxique spécifique au langage pour les blocs de code en appliquant les classes CSS de Prism. Notez que vous devez fournir une feuille de style CSS Prism (ou apporter la vôtre) pour que la coloration syntaxique apparaisse ! Consultez la section Configuration de Prism pour plus de détails.

Consultez la liste des langues supportées par Prism où vous pouvez trouver l’alias correspondant à une langue. Et vous pouvez également afficher vos blocs de code Astro avec lang="astro" !

`<Image />`

---
// importation du composant Image et de l'image
import { Image } from 'astro:assets';
import myImage from "../assets/mon_image.png"; // La résolution de l'image est de 1600x900
---

<!-- `alt` est obligatoire sur le composant Image -->
<Image src={myImage} alt="Une description de mon image." />

<!-- Sortie -->
<!-- L'image est optimisée, les attributs appropriés sont appliqués -->
<img
  src="/_astro/mon_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Une description de mon image."
/>

Propriétés

src (requis)
alt (requis)
width et height (requis pour les images dans public/ et celles distantes)
format
quality
densities
widths

En plus des propriétés ci-dessus, le composant <Image /> accepte toutes les propriétés acceptées par la balise HTML <img>.

Pour en savoir plus, consultez le Guide des images.

`<Picture />`

Ajouté à la version : astro@3.3.0

Utilisez le composant Astro intégré <Picture /> pour afficher une image réactive avec plusieurs formats et/ou tailles.

---
import { Picture } from 'astro:assets';
import monImage from "../assets/mon_image.png"; // La résolution de l'image est de 1600x900
---

<!-- `alt` est obligatoire sur le composant Image -->
<Picture src={monImage} formats={['avif', 'webp']} alt="Une description de mon image." />

<!-- Sortie -->
<picture>
  <source srcset="/_astro/mon_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/mon_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/mon_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Une description de mon image."
  />
</picture>

Pour en savoir plus, consultez le Guide des images.

Propriétés

<Picture /> accepte toutes les propriétés du composant <Image /> en plus des suivantes :

`formats`

Un tableau de formats d’image à utiliser pour les balises <source>. Par défaut, ceci est défini sur ['webp'].

`fallbackFormat`

Format à utiliser comme valeur de repli pour la balise <img>. La valeur par défaut est .png pour les images statiques, .gif pour les images animées et .svg pour les fichiers SVG.

`pictureAttributes`

Un objet d’attributs à ajouter à la balise <picture>. Utilisez cette propriété pour appliquer des attributs à l’élément externe <picture> lui-même. Les attributs appliqués directement au composant <Picture /> s’appliqueront à l’élément interne <img>, à l’exception de ceux utilisés pour la transformation d’image.

`<Content />`

Un composant générique utilisé pour restituer le contenu d’une entrée de collection de contenu.

Tout d’abord, interrogez une ou plusieurs entrées en utilisant getCollection() ou getEntry(). Ensuite, la fonction entry.render() peut renvoyer le composant <Content /> à utiliser dans un modèle de fichier .astro.

---
import { getEntry } from 'astro:content';
const entry = await getEntry('blog', 'article-1');
const { Content } = await entry.render();
---
<p>Publié le : {entry.data.published.toDateString()}</p>
<Content />

`<ViewTransitions />`

Ajouté à la version : astro@2.9.0

Choisissez d’utiliser les transitions de vue sur des pages individuelles en important et en ajoutant le composant de routage <ViewTransitions /> à la balise <head> sur chaque page souhaitée.

---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="fr">
  <head>
    <title>Ma page d'accueil</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Bienvenue sur mon site web !</h1>
  </body>
</html>

Découvrez comment contrôler le routeur et ajouter des directives de transition aux éléments et composants de la page.

`<Debug />`

---
import { Debug } from 'astro:components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

Ce composant fournit un moyen d’inspecter les valeurs côté client, sans aucun JavaScript.

Contribuer

Communauté

Référence API

Astro global

Astro.glob()

Fichiers Markdown

Fichiers Astro

Autres fichiers

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

Contexte du point de terminaison

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

Transfert de données avec props

paginate()

La propriété page de pagination

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`

Transfert de données avec `props`

`paginate()`

La propriété `page` de pagination

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

Images (`astro:assets`)

`getImage()`

Collections de contenu (`astro:content`)

`defineCollection()`