API d'exécution d'Astro
Astro global
Titre de la section Astro globalLe global Astro est disponible dans tous les contextes des fichiers .astro. Il a les fonctions suivantes :
Astro.glob()
Titre de la section 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.
Fichiers Markdown
Titre de la section Fichiers MarkdownLes 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
Titre de la section Fichiers AstroLes 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
Titre de la section Autres fichiersD’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
Titre de la section Astro.propsAstro.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" />Astro.params
Titre de la section Astro.paramsAstro.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 IDif (!post) { Astro.redirect("/404")}---<html> <h1>{post.name}</h1></html>Voir aussi : params
Astro.request
Titre de la section Astro.requestType : 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
Titre de la section Astro.responseType : 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 exemple200.statusText: Le message de statut associé au code de statut, par exemple'OK'.headers: Une instanceHeadersque 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
Titre de la section Astro.cookiesType : AstroCookies
astro@1.4.0
Astro.cookies contient des utilitaires pour lire et manipuler les cookies en mode rendu à la demande.
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.
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.
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.
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.
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
Titre de la section headersType : () => Iterator<string>
Obtient les valeurs de l’en-tête Set-Cookie qui seront envoyées avec la réponse.
AstroCookie
Titre de la section AstroCookieL’obtention d’un cookie via Astro.cookies.get() renvoie un type AstroCookie. Il a la structure suivante.
Type : string
La valeur brute de la chaîne du cookie.
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.
Type : () => number
Analyse la valeur du cookie en tant que nombre. Renvoie NaN s’il ne s’agit pas d’un nombre valide.
boolean
Titre de la section booleanType : () => boolean
Convertit la valeur du cookie en un booléen.
AstroCookieGetOptions
Titre de la section AstroCookieGetOptions
Ajouté à la version :
astro@4.1.0
L’obtention d’un cookie permet également de spécifier des options via l’interface AstroCookieGetOptions :
Type : (value: string) => string
Permet de personnaliser la manière dont un cookie est désérialisé en une valeur.
AstroCookieSetOptions
Titre de la section 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é.
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
Titre de la section expiresType : Date
Spécifie la date d’expiration du cookie.
httpOnly
Titre de la section httpOnlyType : boolean
Si la valeur est true, le cookie ne sera pas accessible côté client.
Type : number
Spécifie un nombre, en secondes, pour lequel le cookie est valide.
Type : string
Spécifie un sous-chemin du domaine dans lequel le cookie est appliqué.
sameSite
Titre de la section sameSiteType : boolean | 'lax' | 'none' | 'strict'
Spécifie la valeur de l’en-tête du cookie SameSite.
Type : boolean
Si c’est vrai, le cookie n’est défini que sur les sites https.
Type : (value: string) => string
Permet de personnaliser la façon dont le cookie est sérialisé.
Astro.redirect()
Titre de la section 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()
Titre de la section Astro.rewrite()Type : (rewritePayload: string | URL | Request) => Promise<Response>
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
Titre de la section Astro.urlType : URL
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 productionconst canonicalURL = new URL(Astro.url.pathname, Astro.site);// Exemple : Construire une URL pour les méta-tags SEO en utilisant votre domaine actuelconst socialImageURL = new URL('/images/preview.png', Astro.url);---<link rel="canonical" href={canonicalURL} /><meta property="og:image" content={socialImageURL} />Astro.clientAddress
Titre de la section Astro.clientAddressType : string
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
Titre de la section Astro.siteType : 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
Titre de la section Astro.generatorType : string
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
Titre de la section Astro.slotsAstro.slots contient des fonctions utilitaires pour modifier les enfants d’un composant Astro.
Astro.slots.has()
Titre de la section 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()
Titre de la section 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
Titre de la section Astro.selfAstro.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
Titre de la section 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
Titre de la section Astro.preferredLocaleType : string | undefined
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
Titre de la section Astro.preferredLocaleListType : string[] | undefined
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
Titre de la section Astro.currentLocaleType : string | undefined
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()
Titre de la section Astro.getActionResult()Type : (action: TAction) => ActionReturnType<TAction> | undefined
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()
Titre de la section 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
Titre de la section Contexte du point de terminaisonLes 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
Titre de la section context.paramscontext.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
Titre de la section 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
Titre de la section context.requestType : 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
Titre de la section context.cookiesType : AstroCookies
context.cookies contient des utilitaires pour lire et manipuler les cookies.
Voir aussi : Astro.cookies
context.url
Titre de la section context.urlType : URL
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
Titre de la section context.clientAddressType : string
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
Titre de la section context.siteType : URL | undefined
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
Titre de la section context.generatorType : string
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()
Titre de la section context.redirect()Type : (path: string, status?: number) => Response
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()
Titre de la section context.rewrite()Type : (rewritePayload: string | URL | Request) => Promise<Response>
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');}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 "../" :
import type { APIContext } from 'astro';
export function GET({ rewrite }: APIContext) { return 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 :
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
Titre de la section 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()
Titre de la section context.getActionResult()Type : (action: TAction) => ActionReturnType<TAction> | undefined
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()
Titre de la section 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()
Titre de la section 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.
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
Titre de la section Transfert de données avec propsPour 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()
Titre de la section 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 fonctionpaginate()options- Objet facultatif avec les propriétés suivantes :pageSize- Nombre d’éléments affichés par page (10par défaut)params- Envoi de paramètres supplémentaires pour la création de routes dynamiquesprops- 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].astrogénérerait les URL suivants/posts/1,/posts/2,/posts/3, etc./posts/[...page].astrogénérerait les URL suivants/posts,/posts/2,/posts/3, etc.
La propriété page de pagination
Titre de la section La propriété page de paginationType : 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
Titre de la section page.dataType : Array<TData>
Tableau des données renvoyées par la fonction paginate() pour la page en cours.
page.start
Titre de la section page.startType : 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
Titre de la section page.endType : number
Index du dernier élément de la page en cours.
page.size
Titre de la section page.sizeType : number
Par défaut : 10
Nombre d’éléments par page.
page.total
Titre de la section page.totalType : number
Le nombre total d’éléments sur toutes les pages.
page.currentPage
Titre de la section page.currentPageType : number
Le numéro de la page actuelle, en commençant par 1.
page.lastPage
Titre de la section page.lastPageType : number
Le nombre total de pages.
page.url.current
Titre de la section page.url.currentType : string
Obtenir l’URL de la page actuelle (utile pour les URL canoniques).
page.url.prev
Titre de la section page.url.prevType : 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
Titre de la section page.url.nextType : 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
Titre de la section page.url.firstType : string | undefined
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
Titre de la section page.url.lastType : string | undefined
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
Titre de la section import.metaTous 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 />;}