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.

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

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

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

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

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)

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

`context.params`

`context.props`

`context.request`

`context.cookies`

`context.url`

`context.clientAddress`

`context.site`

`context.generator`

`context.redirect()`

`context.rewrite()`

`context.locals`

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

`type`

`schema`

`reference()`

`getCollection()`