API d'exécution d'Astro

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

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

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

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 { getPost } from '../api';

const post = await getPost(Astro.params.id);

// No posts found with this ID
if (!post) {
  Astro.redirect("/404")
}
---
<html>
  <h1>{post.name}</h1>
</html>

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

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

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

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

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() a les arguments suivants :

data - tableau contenant les données de la page transmises à la fonction paginate()
options - Objet facultatif avec les propriétés suivantes :
- 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 props supplémentaires pour qu’elles soient disponibles sur chaque page

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.

La propriété `page` de pagination

Type : Page<TData>

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

Tableau des données renvoyées par la fonction paginate() 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 />;
}

Contribuer

Communauté

API d'exécution d'Astro

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`