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.
L’objet de contexte
Titre de la section L’objet de contexteLes 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.
L’objet props
contient également tous les props
transmis depuis getStaticPaths()
lors du rendu des routes statiques.
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.
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.
Voir aussi : params
Type : URL
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.
Vous pouvez également utiliser url
pour créer de nouvelles URL en le passant comme argument à new URL()
.
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.
clientAddress
Titre de la section clientAddressType : string
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.
isPrerendered
Titre de la section isPrerenderedType : boolean
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.
generator
Titre de la section generatorType : string
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"
.
request
Titre de la section 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.
Sur les pages pré-rendues, request.url
ne contient pas de paramètres de recherche, comme ?type=new
, car il n’est pas possible de les déterminer à l’avance lors des constructions statiques. Cependant, request.url
contient des paramètres de recherche pour les pages rendues à la demande car ils peuvent être déterminés à partir d’une requête serveur.
response
Titre de la section responseType : 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 exemple200
.statusText
: Le message de statut associé au code de statut, par exemple'OK'
.headers
: Une instanceHeaders
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.
Ou de définir un en-tête :
redirect()
Titre de la section redirect()Type : (path: string, status?: number) => Response
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 :
rewrite()
Titre de la section rewrite()Type : (rewritePayload: string | URL | Request) => Promise<Response>
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 :
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 "../"
:
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 :
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
:
Les composants Astro et les points de terminaison de l’API peuvent lire les valeurs depuis locals
lorsqu’elles s’affichent :
preferredLocale
Titre de la section preferredLocaleType : string | undefined
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.
preferredLocaleList
Titre de la section preferredLocaleListType : string[] | undefined
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.
currentLocale
Titre de la section currentLocaleType : string | undefined
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
.
getActionResult()
Titre de la section getActionResult()Type : (action: TAction) => ActionReturnType<TAction> | undefined
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
.
callAction()
Titre de la section callAction()
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.
routePattern
Titre de la section routePatternType : string
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.
cookies
Titre de la section cookiesType : AstroCookies
astro@1.4.0
cookies
contient des utilitaires pour lire et manipuler les cookies pour les routes rendues à la demande.
Utilitaires de cookies
Titre de la section Utilitaires de cookiescookies.get()
Titre de la section cookies.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.
cookies.has()
Titre de la section cookies.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
.
cookies.set()
Titre de la section cookies.set()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
.
cookies.delete()
Titre de la section cookies.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
.
cookies.merge()
Titre de la section cookies.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.
cookies.headers()
Titre de la section cookies.headers()Type : () => Iterator<string>
Obtient les valeurs de l’en-tête Set-Cookie
qui seront envoyées avec la réponse.
Type AstroCookie
Titre de la section Type AstroCookieLe 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.
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’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.
AstroCookieSetOptions
Titre de la section AstroCookieSetOptions
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.
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é.
Propriétés d’objet obsolètes
Titre de la section Propriétés d’objet obsolètesAstro.glob()
Titre de la section Astro.glob()Utilisez import.meta.glob
de Vite pour interroger les fichiers de projet.
Astro.glob('../pages/post/*.md')
peut être remplacé par :
Object.values(import.meta.glob('../pages/post/*.md', { eager: true }));
Consultez le guide d’importation pour plus d’informations et d’utilisation.
Astro.glob()
est un moyen de charger de nombreux fichiers locaux dans la configuration de votre site statique.
.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.
Vous pouvez également utiliser import.meta.glob()
lui-même dans votre projet Astro. Vous pouvez le faire lorsque :
- Vous avez besoin de cette fonctionnalité dans un fichier autre que
.astro
, comme une route API.Astro.glob()
n’est disponible que dans les fichiers.astro
, tandis queimport.meta.glob()
est disponible n’importe où dans le projet. - Vous ne souhaitez pas charger chaque fichier immédiatement.
import.meta.glob()
peut renvoyer des fonctions qui importent le contenu du fichier, plutôt que de renvoyer le contenu lui-même. Notez que cette importation inclut tous les styles et scripts de 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 cela est décidé par une analyse statique, et non au moment de l’exécution. - Vous souhaitez accéder au chemin de chaque fichier.
import.meta.glob()
renvoie une association du chemin d’un fichier et de son contenu, tandis queAstro.glob()
renvoie une liste de contenu. - Vous souhaitez transmettre plusieurs modèles ; par exemple, vous souhaitez ajouter un « modèle négatif » qui filtre certains fichiers.
import.meta.glob()
peut éventuellement prendre un tableau de chaînes glob, plutôt qu’une seule chaîne de caractères.
En savoir plus dans la documentation de Vite.
Fichiers Markdown
Titre de la section Fichiers MarkdownLes fichiers Markdown chargés avec Astro.glob()
renvoient l’interface MarkdownInstance
suivante :
Vous pouvez éventuellement fournir un type pour la variable frontmatter
à l’aide d’un générique TypeScript.
Fichiers Astro
Titre de la section Fichiers AstroLes fichiers Astro ont l’interface suivante :
Autres fichiers
Titre de la section Autres fichiersD’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.