Aller au contenu

Contexte de rendu d'Astro

Lors du rendu d’une page, Astro fournit une API d’exécution spécifique au rendu actuel. Cela inclut des informations utiles telles que l’URL de la page actuelle ainsi que des API permettant d’effectuer des actions telles que la redirection vers une autre page.

Dans les composants .astro, ce contexte est disponible à partir de l’objet global Astro. Les fonctions de point de terminaison sont également appelées avec ce même objet de contexte comme premier argument, dont les propriétés reflètent les propriétés globales d’Astro.

Certaines propriétés ne sont disponibles que pour les routes rendues à la demande ou peuvent avoir des fonctionnalités limitées sur les pages pré-rendues.

L’objet global Astro est disponible pour tous les fichiers .astro. Utilisez l’objet context dans les fonctions de point de terminaison pour servir les points de terminaison de serveur statique ou en direct et dans le middleware pour injecter un comportement lorsqu’une page ou un point de terminaison est sur le point d’être rendu.

Les propriétés suivantes sont disponibles sur le global Astro (par exemple Astro.props, Astro.redirect()) et sont également disponibles sur l’objet de contexte (par exemple context.props, context.redirect()) passé aux fonctions de point de terminaison et au middleware.

props est un objet contenant toutes les valeurs qui ont été transmises en tant qu’attributs de composant.

src/components/Heading.astro
---
const { title, date } = Astro.props;
---
<div>
<h1>{title}</h1>
<p>{date}</p>
</div>
src/pages/index.astro
---
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.

L’objet props contient également tous les props transmis depuis getStaticPaths() lors du rendu des routes statiques.

src/pages/posts/[id].astro
---
export function getStaticPaths() {
return [
{ params: { id: '1' }, props: { author: 'Blu' } },
{ params: { id: '2' }, props: { author: 'Erika' } },
{ params: { id: '3' }, props: { author: 'Matthew' } }
];
}
const { id } = Astro.params;
const { author } = Astro.props;
---

Voir aussi : Transmission de données avec props

params est un objet contenant les valeurs des segments de route dynamiques correspondant à une requête. Ses clés doivent correspondre aux paramètres du chemin d’accès à la page ou au fichier de point de terminaison.

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

src/pages/posts/[id].astro
---
export function getStaticPaths() {
return [
{ params: { id: '1' } },
{ params: { id: '2' } },
{ params: { id: '3' } }
];
}
const { id } = Astro.params;
---
<h1>{id}</h1>

Lorsque les routes sont rendues à la demande, params peut être n’importe quelle valeur correspondant aux segments de chemin dans le modèle de route dynamique.

src/pages/posts/[id].astro
---
import { getPost } from '../api';
const post = await getPost(Astro.params.id);
// Aucun article trouvé avec cet identifiant
if (!post) {
return Astro.redirect("/404")
}
---
<html>
<h1>{post.name}</h1>
</html>

Voir aussi : params

Type : URL

Ajouté à la version : astro@1.0.0

url est un objet URL construit à partir de la valeur actuelle de request.url. Il est utile pour interagir avec les propriétés individuelles de l’URL de la requête, comme le chemin d’accès et l’origine.

Astro.url équivaut à faire new URL(Astro.request.url).

url sera une URL localhost en mode dev. Lors de la création d’un site, les routes pré-rendues recevront une URL basée sur les options site et base. Si site n’est pas configuré, les pages pré-rendues recevront également une URL localhost pendant la construction.

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

Vous pouvez également utiliser url pour créer de nouvelles URL en le passant comme argument à new URL().

src/pages/index.astro
---
// Exemple : créer une URL canonique à l'aide de votre domaine de production
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// Exemple : créez une URL pour les balises méta 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} />

Type : URL | undefined

site renvoie une URL créée à partir du site défini dans votre configuration Astro. Il renvoie undefined si vous n’avez pas défini de valeur pour site dans votre configuration Astro.

src/pages/index.astro
<link
rel="alternate"
type="application/rss+xml"
title="Le titre de votre site"
href={new URL("rss.xml", Astro.site)}
/>

Type : string

Ajouté à la version : astro@1.0.0

clientAddress spécifie l’adresse IP de la requête. Cette propriété est uniquement disponible pour les routes rendues à la demande et ne peut pas être utilisée sur les pages pré-rendues.

src/pages/ip-address.astro
---
export const prerender = false; // Pas nécessaire en mode `server`
---
<div>Votre adresse IP est : <span class="address">{Astro.clientAddress}</span></div>

Type : boolean

Ajouté à la version : astro@5.0.0

Un booléen indiquant si la page actuelle est pré-rendue ou non.

Vous pouvez utiliser cette propriété pour exécuter une logique conditionnelle dans un middleware, par exemple, pour éviter d’accéder aux en-têtes dans les pages pré-rendues.

Type : string

Ajouté à la version : astro@1.0.0

generator fournit la version actuelle d’Astro que votre projet exécute. C’est un moyen pratique d’ajouter une balise <meta name="generator"> avec votre version actuelle d’Astro. Il suit le format "Astro v5.x.x".

src/pages/site-info.astro
<html>
<head>
<meta name="generator" content={Astro.generator} />
</head>
<body>
<footer>
<p>Construit avec <a href="https://astro.build">{Astro.generator}</a></p>
</footer>
</body>
</html>

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.

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

Type : ResponseInit & { readonly headers: Headers }

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=/;');
---

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

Ajouté à la version : astro@1.5.0

redirect() renvoie un objet Response qui vous permet de rediriger vers une autre page et éventuellement de fournir un code d’état de réponse HTTP comme deuxième paramètre.

Une page (et non un composant enfant) doit renvoyer le résultat de Astro.redirect() pour que la redirection se produise.

Pour les routes générées de manière statique, cela produira une redirection client à l’aide d’une balise <meta http-equiv="refresh"> et ne prend pas en charge les codes d’état.

Pour les routes rendues à la demande, la définition d’un code d’état personnalisé est prise en charge lors de la redirection. S’il n’est pas spécifié, les redirections seront servies avec un code d’état 302.

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

src/pages/account.astro
---
import { isLoggedIn } from '../utils';
const cookie = Astro.request.headers.get('cookie');
// Si l'utilisateur n'est pas connecté, redirigez-le vers la page de connexion
if (!isLoggedIn(cookie)) {
return Astro.redirect('/login');
}
---
<p>Informations de l'utilisateur</p>

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

Ajouté à la version : astro@4.13.0

rewrite() vous permet de diffuser 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, une URL ou un objet Request pour l’emplacement du chemin.

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

src/pages/index.astro
---
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 "../" :

src/pages/blog/index.astro
---
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 :

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

Ajouté à la version : astro@2.4.0

locals est un objet utilisé pour stocker et accéder à des informations arbitraires pendant le cycle de vie d’une requête. Astro.locals est un objet contenant toutes les valeurs de l’objet context.locals défini par le middleware. Utilisez-le pour accéder aux données renvoyées par le middleware dans vos fichiers .astro.

Les fonctions middleware peuvent à la fois lire et écrire les valeurs de context.locals :

src/middleware.ts
import type { MiddlewareHandler } from 'astro';
export const onRequest: MiddlewareHandler = ({ locals }, next) => {
if (!locals.title) {
locals.title = "Titre par défaut";
}
return next();
}

Les composants Astro et les points de terminaison de l’API peuvent lire les valeurs depuis locals lorsqu’elles s’affichent :

src/pages/Orders.astro
---
const title = Astro.locals.title;
---
<h1>{title}</h1>

Type : string | undefined

Ajouté à la version : astro@3.5.0

preferredLocale est une valeur calculée pour trouver la meilleure correspondance entre les préférences linguistiques du navigateur de votre visiteur et les paramètres régionaux pris en charge par votre site.

Elle est calculée en vérifiant les paramètres régionaux configurés dans votre tableau i18n.locales et les paramètres régionaux pris en charge par le navigateur de l’utilisateur via l’en-tête Accept-Language. Cette valeur a pour valeur undefined si aucune correspondance de ce type n’existe.

Cette propriété est uniquement disponible pour les routes rendues à la demande et ne peut pas être utilisée sur des pages statiques pré-rendues.

Type : string[] | undefined

Ajouté à la version : astro@3.5.0

preferredLocaleList représente le tableau de tous les paramètres régionaux demandés par le navigateur et pris en charge par votre site web. Cela génère 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 locales, alors la valeur est []. Cela se produit lorsque vous ne prenez en charge aucun des paramètres régionaux préférés de vos visiteurs.

Si le navigateur ne spécifie aucune langue préférée, alors cette valeur sera celle de i18n.locales : tous vos paramètres régionaux pris en charge seront considérés comme également préférés par un visiteur sans 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.

Type : string | undefined

Ajouté à la version : astro@3.5.6

Les paramètres régionaux calculés à partir de l’URL actuelle, en utilisant la syntaxe spécifiée dans votre configuration locales. Si l’URL ne contient pas de préfixe /[locale]/, la valeur par défaut sera i18n.defaultLocale.

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

Ajouté à la version : astro@4.15.0

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.

src/pages/index.astro
---
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>}

Ajouté à la version : astro@4.15.0

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.

src/pages/index.astro
---
import { actions } from 'astro:actions';
const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---

Type : string

Ajouté à la version : astro@5.0.0

Le modèle de route chargé de générer la page ou la route actuelle. Dans le routage basé sur des fichiers, cela ressemble au chemin d’accès au fichier de votre projet utilisé pour créer la route. Lorsque les intégrations créent des routes pour votre projet, context.routePattern est identique à la valeur de injectRoute.pattern.

La valeur commencera par une barre oblique et ressemblera au chemin d’un composant de page par rapport à votre dossier src/pages/ sans extension de fichier.

Par exemple, le fichier src/pages/en/blog/[slug].astro renverra /en/blog/[slug] pour routePattern. Chaque page de votre site générée par ce fichier (par exemple /en/blog/post-1/, /en/blog/post-2/, etc.) partage la même valeur pour routePattern. Dans le cas des routes index.*, le modèle de route n’inclura pas le mot « index ». Par exemple, src/pages/index.astro renverra /.

Vous pouvez utiliser cette propriété pour comprendre quelle route effectue le rendu de votre composant. Cela vous permet de cibler ou d’analyser ensemble les URL de pages générées de manière similaire. Par exemple, vous pouvez l’utiliser pour restituer certaines informations de manière conditionnelle ou collecter des mesures sur les routes les plus lentes.

Type : AstroCookies

Ajouté à la version : astro@1.4.0

cookies contient des utilitaires pour lire et manipuler les cookies pour les routes rendues à 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

Définit la clé du cookie (key) sur la valeur donnée. Cela 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.

Type : () => Iterator<string>

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

Le type renvoyé après l’obtention d’un cookie via Astro.cookies.get(). 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.

Type : () => boolean

Convertit la valeur du cookie en un booléen.

Ajouté à la version : astro@4.1.0

L’interface AstroCookieGetOption vous permet de spécifier des options lorsque vous recevez un cookie.

Type : (value: string) => string

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

Ajouté à la version : astro@4.1.0

AstroCookieSetOptions est un objet qui peut être transmis à Astro.cookies.set() lors de la définition d’un cookie pour personnaliser la manière 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.

Type : Date

Spécifie la date d’expiration du cookie.

Type : 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é.

Type : 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.glob() est un moyen de charger de nombreux fichiers locaux dans la configuration de votre site statique.

src/components/my-component.astro
---
const posts = await Astro.glob('../pages/post/*.md'); // renvoie un tableau d'articles qui se trouvent dans ./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}>Lire la suite</a>
</article>
))}
</div>

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

.glob() ne peut pas prendre de variables ou de chaînes de caractères qui les interpolent, car elles ne sont pas analysables statiquement. (Consultez le guide d’importation pour une solution de contournement.) Ceci est dû au fait que Astro.glob() est un wrapper de import.meta.glob() de Vite.

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 rendu de ce fichier */
url: string | undefined;
/* Composant Astro qui restitue le contenu de ce fichier */
Content: AstroComponentFactory;
/** (Markdown uniquement) Contenu du fichier Markdown brut, à l'exclusion de la mise en page HTML et du frontmat YAML */
rawContent(): string;
/** (Markdown uniquement) Fichier Markdown compilé en HTML, à l'exclusion de la mise en page HTML */
compiledContent(): string;
/* Fonction qui renvoie un tableau des éléments h1...h6 dans ce fichier */
getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
default: AstroComponentFactory;
}

Vous pouvez éventuellement fournir un type pour la variable frontmatter à l’aide d’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>

Les fichiers Astro ont l’interface suivante :

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

D’autres fichiers peuvent avoir différentes interfaces, 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');
---
Contribuer

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Le moyen le plus rapide d'alerter notre équipe d'un problème.

Communauté