Contexto de renderização Astro

Ao renderizar uma página, Astro fornece uma API de tempo de execução específica para a renderização atual. Isso inclui informações úteis como a URL da página atual, bem como APIs para realizar ações como redirecionar para outra página.

Em componentes .astro, esse contexto é disponível pelo objeto global Astro. Funções endpoint também são chamadas com esse mesmo contexto de objeto como seu primeiro argumento, cujas propriedades espelham as propriedades globais Astro.

Algumas propriedades estão disponíveis apenas para rotas renderizadas sob demanda ou podem ter funcionalidade limitada em páginas pré-renderizadas.

O objeto global Astro está disponível para todos os arquivos .astro. Use o objeto context em funções endpoint para servir endpoints de servidor estáticos ou dinâmicos, e em middleware para injetar comportamentos quando um endpoint ou página está prestes a ser renderizada.

O objeto context

As seguintes propriedades estão disponíveis no global Astro (como Astro.props, Astro.redirect()) e também estão disponíveis no objeto de contexto (como context.props, context.redirect()) passados para funções endpoint e middleware.

`props`

Astro.props é um objeto contendo quaisquer valores que foram passados como atributos do componente.

---
const { titulo, data } = Astro.props;
---
<div>
    <h1>{titulo}</h1>
    <p>{data}</p>
</div>

---
import Titulo from '../components/Titulo.astro';
---
<Titulo titulo="Minha Primeira Postagem" data="09 Ago 2022" />

Aprenda mais sobre como Layouts Markdown e MDX lidam com props.

O objeto props também contém quaisquer props passadas por getStaticPaths() ao renderizar rotas estáticas.

Astro.props
context.props

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

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

Veja também: Passando Dados com props (EN)

`params`

params é um objeto que contém os valores de segmentos dinâmicos de rota que correspondem a uma requisição. Suas chaves devem corresponder aos parâmetros da página ou ao caminho do arquivo endpoint.

Em builds estáticas, isto será o params retornado por getStaticPaths() usado para pré-renderizar rotas dinâmicas:

Astro.params
context.params

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

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

Quando rotas são renderizadas sob demanda, params pode ser qualquer valor correspondente aos segmentos de caminho no padrão de rotas dinâmicas.

---
import { getPost } from '../api';

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

// Nenhuma postagem encontrada com este ID
if (!post) {
  return Astro.redirect("/404")
}
---
<html>
  <h1>{post.name}</h1>
</html>

Veja também: params (EN)

`url`

Tipo: URL

Adicionado em: astro@1.0.0

url é um objeto URL construído do valor atual de request.url. É útil para interagir com propriedades individuais da URL de requisição, como o caminho e a origem.

Astro.url é equivalente a realizar new URL(Astro.request.url).

url será a URL localhost no modo de desenvolvimento. Ao construir um site, rotas pré-renderizadas receberão uma URL baseada nas opções site e base. Se site não estiver configurado, páginas pré-renderizadas receberão uma URL localhost também durante builds.

<h1>A URL atual é: {Astro.url}</h1>
<h1>O caminho da URL atual é: {Astro.url.pathname}</h1>
<h1>A origem da URL atual é: {Astro.url.origin}</h1>

Você também pdoe usar url para criar novas URLs ao passá-las como um argumento para new URL().

---
// Exemplo: Construir uma URL canônica usando seu domínio de produção
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// Exemplo: Construir uma URL para meta tags SEO usando seu domínio atual
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />

`site`

Tipo: URL | undefined

site retorna uma URL a partir do site de sua configuração Astro. Retorna undefined se você não definiu um valor de site em sua configuração Astro.

<link
    rel="alternate"
    type="application/rss+xml"
    title="Título do Seu Site"
    href={new URL("rss.xml", Astro.site)}
/>

`clientAddress`

Tipo: string

Adicionado em: astro@1.0.0

clientAddress especifica o endereço IP da requisição. Essa propriedade está disponível apenas para rotas renderizadas sob demanda e não podem ser usadas em páginas pré-renderizadas.

Astro.clientAddress
context.clientAddress

---
export const prerender = false; // Não exigido para o modo 'server'
---

<div>Seu endereço IP é: <span class="address">{Astro.clientAddress}</span></div>

export const prerender = false; // Não exigido para o modo 'server'
import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Seu endereço IP é: ${clientAddress}`);
}

`isPrerendered`

Tipo: boolean

Adicionado em: astro@5.0.0

Um booleano representando se a página atual é ou não pré-renderizada.

Você pode usar essa propriedade para executar lógica condicional no middleware, por exemplo, para evitar acessar cabeçalhos em páginas pré-renderizadas.

`generator`

Tipo: string

Adicionado em: astro@1.0.0

generator fornece a versão atual Astro que seu projeto está rodando. Essa é uma maneira conveniente de adicionar uma tag <meta name="generator"> com sua versão atual Astro. Isto segue o seguinte formato "Astro v5.x.x".

Astro.generator
context.generator

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>Construído com <a href="https://astro.build">{Astro.generator}</a></p>
    </footer>
  </body>
</html>

import type { APIContext } from 'astro';

export function GET({ generator, site }: APIContext) {
  const body = JSON.stringify({ generator, site });
  return new Response(body);
}

`request`

Tipo: Request

request é um objeto Request padrão. Ele pode ser usado para obter url, headers, method, e até mesmo o corpo da requisição.

Astro.request
context.request

<p>Recebeu uma requisição {Astro.request.method} para "{Astro.request.url}".</p>
<p>Recebeu cabeçalhos de requisição:</p>
<p><code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code></p>

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Olá ${request.url}`);
}

`response`

Tipo: ResponseInit & { readonly headers: Headers }

response é um objeto ResponseInit padrão. Ele tem a seguinte estrutura.

status: O código de status numérico da resposta, como 200.
statusText: A mensagem de status associada com o código de status, como 'OK'.
headers: Uma instância Headers que você pode usar para definir os cabeçalhos HTTP da resposta.

Astro.response é usado para definir status, statusText, e headers para a resposta de uma página.

---
if (condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Não encontrado';
}
---

Ou para definir um cabeçalho:

---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---

`redirect()`

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

Adicionado em: astro@1.5.0

redirect() retorna um objeto Response que permite que você redirecione para outra página, e forneça opcionalmente um código de status de resposta HTTP como segundo parâmetro.

Uma página (e não um componente filho) deve return o resultado de Astro.redirect() para que o redirecionamento ocorra.

Para rotas geradas estaticamente, isso irá produzir um redirecionamento de cliente usando uma <meta http-equiv="refresh"> tag e não suporta códigos de status.

Para rotas renderizadas sob demanda, definir um código de status personalizado é suportado ao redirecionar. Se não especificado, redirecionamentos serão servidos com um código de status 302.

O exemplo seguinte redireciona o usuário para uma página de login:

Astro.redirect()
context.redirect()

---
import { isLoggedIn } from '../utils';

const cookie = Astro.request.headers.get('cookie');

// Se o usuário não estiver logado, redirecione-o para a página de login
if (!isLoggedIn(cookie)) {
  return Astro.redirect('/login');
}
---

<p>Informação do usuário</p>

import type { APIContext } from 'astro';

export function GET({ redirect, request }: APIContext) {
  const cookie = request.headers.get('cookie');
  if (!isLoggedIn(cookie)) {
    return redirect('/login', 302);
  } else {
    // retorne a informação do usuário
  }
}

`rewrite()`

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

Adicionado em: astro@4.13.0

rewrite() permite que você sirva conteúdo de uma URL ou caminho diferente sem redirecionar o navegador para uma nova página.

O método aceita tanto uma string, uma URL, ou um Request para a localização do caminho.

Use uma string para fornecer um caminho explícito:

Astro.rewrite()
context.rewrite()

---
return Astro.rewrite("/login")
---

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite('/login');
}

Use um tipo URL quando você precisar construir um caminho de URL para a reescrita. O exemplo seguinte renderiza o caminho pai de uma página criando uma nova URL do caminho relativo "../":

Astro.rewrite()
context.rewrite()

---
return Astro.rewrite(new URL("../", Astro.url))
---

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new URL("../", Astro.url));
}

Use um tipo Request para controle completo do Request enviado ao servidor para o novo caminho. O exemplo seguinte envia a requisição para renderizar a página pai enquanto também fornece cabeçalhos:

Astro.rewrite()
context.rewrite()

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

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

`locals`

Adicionado em: astro@2.4.0

locals é um objeto usado para armazenar e acessar informações arbitrárias durante o ciclo de vida de uma requisição. Astro.locals é um objeto contendo quaisquer valores do objeto context.locals definidos pelo middleware. Use isso para acessar dados retornados pelo middleware em seus arquivos .astro.

Funções middleware podem tanto ler quanto escrever os valores de context.locals:

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Título Padrão";
  }
  return next();
}

Componentes Astro e API endpoints podem ler valores de locals quando são renderizados:

Astro.locals
context.locals

---
const title = Astro.locals.title;
---
<h1>{title}</h1>

import type { APIContext } from 'astro';

export function GET({ locals }: APIContext) {
  return new Response(locals.title); // "Título Padrão"
}

`preferredLocale`

Tipo: string | undefined

Adicionado em: astro@3.5.0

preferredLocale é um valor computado para encontrar a melhor correspondência entre as preferências de idioma do navegador do visitante e as localizações suportadas pelo seu site.

Ele é computado ao conferir as localizações configuradas em seu array i18n.locales e as localizações suportadas pelo navegador do usuário através do cabeçalho Accept-Language. Este valor é undefined se nenhuma correspondência existir.

Esta propriedade só está disponível para rotas renderizadas sob demanda e não pode ser usada em páginas estáticas pré-renderizadas.

`preferredLocaleList`

Tipo: string[] | undefined

Adicionado em: astro@3.5.0

preferredLocaleList representa o array de todas as localizações que são ao mesmo tempo requisitadas pelo navegador e suportadas pelo seu site. Isso produz uma lista de todos os idiomas compatíveis entre seu site e o visitante.

Se nenhum dos idiomas requisitados pelo navegador forem encontratas em seu array de localizações, então o valor é []. Isso ocorre quando você não suporta nenhum dos idiomas de preferência do seu visitante.

Se o navegador não especificar qualquer idioma de preferência, então este valor será i18n.locales: todas as suas localizações suportadas serão consideradas igualmente preferidas pelo visitante sem preferências.

Esta propriedade só está disponível para rotas renderizadas sob demanda e não pode ser usada em páginas estáticas pré-renderizadas.

`currentLocale`

Tipo: string | undefined

Adicionado em: astro@3.5.6

A localização computada da sua URL atual, usando a sintaxe especificada na sua configuração locales. Se a URL não contém um prefixo /[locale]/, então o valor irá mostrar o padrão i18n.defaultLocale.

`getActionResult()`

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

Adicionado em: astro@4.15.0

getActionResult() é uma função que retorna o resultado do envio de uma Action (EN). Ela aceita uma função action como argumento (como actions.logout) e retorna um objeto data ou error quando o envio é recebido. Caso contrário, retornará undefined.

---
import { actions } from 'astro:actions';

const result = Astro.getActionResult(actions.logout);
---

<form action={actions.logout}>
  <button type="submit">Log out</button>
</form>
{result?.error && <p>Falha ao sair. Por favor, tente novamente.</p>}

`callAction()`

Adicionado em: astro@4.15.0

callAction() é uma função usada para chamar diretamente um manipulador Action de seu componente Astro. Essa função aceita uma função Action como primeiro argumento (como actions.logout) e qualquer entrada que aquela action recebe como segundo argumento. Ela retorna o resultado da action como uma promise.

---
import { actions } from 'astro:actions';

const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---

`routePattern`

Tipo: string

Adicionado em: astro@5.0.0

O padrão de rota responsável por gerar a página ou rota atual. Em roteamento baseado em arquivos, isso assemelha-se ao caminho de arquivo no seu projeto usado para criar a rota. Quando integrações criam rotas para seu projeto, context.routePattern é idêntico ao valor de injectRoute.pattern.

O valor começará com uma barra inicial e parecerá similar ao caminho do componente de página relativo à sua pasta src/pages/ sem qualquer extensão de arquivo.

Por exemplo, o arquivo src/pages/en/blog/[slug].astro retornará /en/blog/[slug] para routePattern. Toda página do seu site gerada por aquele arquivo (como /en/blog/post-1/, /en/blog/post-2/, etc.) compartilha o mesmo valor de routePattern. No caso de rotas index.*, o padrão de rota não incluirá a palavra “index.” Por exemplo, src/pages/index.astro retornará /.

Você pode usar essa propriedade para entender qual rota está renderizando seu componente. Isso permite que você foque ou analise URLs de página geradas de forma similar em conjunto. Por exemplo, você pode usar para renderizar certas informações condicionalmente, ou coletar métricas sobre quais rotas são mais lentas.

`cookies`

Tipo: AstroCookies

Adicionado em: astro@1.4.0

cookies contêm utilidades para ler e manipular cookies para rotas renderizadas sob demanda (EN).

`cookies.get()`

Tipo: (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

Obtém o cookie como um objeto AstroCookie, que contém value e funções utilitárias para converter o cookie em tipos não-string.

`cookies.has()`

Tipo: (key: string, options?: AstroCookieGetOptions) => boolean

Confere se o cookie existe. Se o cookie foi definido via Astro.cookies.set() ele retornará verdadeiro, caso contrário, conferirá os cookies em Astro.request.

`cookies.set()`

Tipo: (key: string, value: string | object, options?: AstroCookieSetOptions) => void

Define o cookie key com o valor fornecido. Isso tentará converter o valor do cookie para uma string. Opções fornecem maneiras de definir funcionalidades de cookie, como maxAge ou httpOnly.

`cookies.delete()`

Tipo: (key: string, options?: AstroCookieDeleteOptions) => void

Invalida um cookie ao definir sua data de validade no passado (0 no tempo Unix).

Uma vez que um cookie é “deletado” (expirado), Astro.cookies.has() retornará false e Astro.cookies.get() retornará um AstroCookie com value de undefined. Opções disponíveis ao deletador um cookie são: domain, path, httpOnly, sameSite, e secure.

`cookies.merge()`

Tipo: (cookies: AstroCookies) => void

Mescla uma nova instância AstroCookies com a instância atual. Quaisquer novos cookies serão adicionados à instância atual e quaisquer cookies com o mesmo nome serão sobrescritos.

`cookies.headers()`

Tipo: () => Iterator<string>

Obtém os valores de cabeçalho de Set-Cookie que serão enviados com a resposta.

Tipo `AstroCookie`

O tipo retornado ao obter um cookie via Astro.cookies.get(). Ele possui as seguintes propriedades:

`value`

Tipo: string

O valor string bruto do cookie.

`json`

Tipo: () => Record<string, any>

Processa o valor do cookie via JSON.parse(), retornando um objeto. Lança um erro se o valor do cookie não for um JSON válido.

`number`

Tipo: () => number

Processa o valor do cookie como Número. Retorna NaN se não for um número válido.

`boolean`

Tipo: () => boolean

Converte o valor do cookie para um booleano.

`AstroCookieGetOptions`

Adicionado em: astro@4.1.0

A interface AstroCookieGetOption permite que você especifique opções ao obter um cookie.

`decode`

Tipo: (value: string) => string

Permite personalização de como um cookie é desserializado em um valor.

`AstroCookieSetOptions`

Adicionado em: astro@4.1.0

AstroCookieSetOptions é um objeto que pode ser passado para Astro.cookies.set() ao definir um cookie para personalizar como o cookie é serializado.

`domain`

Tipo: string

Especifica o domínio. Se nenhum domínio estiver definido, a maioria dos clientes interpretará que é para aplicar o domínio atual.

`expires`

Tipo: Date

Especifica a data em que o cookie expirará.

`httpOnly`

Tipo: boolean

Se verdadeiro, o cookie não será acessível no lado do cliente.

`maxAge`

Tipo: number

Especifica um número, em segundos, para qual o cookie é válido.

`path`

Tipo: string

Especifica um subcaminho do domínio em qual o cookie é aplicado.

`sameSite`

Tipo: boolean | 'lax' | 'none' | 'strict'

Especifica o valor SameSite do cabeçalho do cookie.

`secure`

Tipo: boolean

Se verdadeiro, o cookie é definido somente em sites https.

`encode`

Tipo: (value: string) => string

Permite personalizar como o cookie é serializado.

Propriedades de objeto descontinuadas

`Astro.glob()`

Astro.glob() é uma maneira de carregar muitos arquivos locais na configuração do seu site estático.

---
const posts = await Astro.glob('../pages/post/*.md'); // retorna um array de postagens que vivem em ./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}>Leia mais</a>
  </article>
))}
</div>

.glob() leva apenas um parâmetro: a glob de URL relativa de cada arquivo local que você deseja importar. É assíncrono e retorna um array de exportações dos arquivos correspondentes.

.glob() não leva variáveis ou strings que interpolam variáveis, pois elas não são analisáveis estaticamente. (Veja o guia de importações para uma solução alternativa.) Isto funciona assim porque Astro.glob() é um envoltório do import.meta.glob() de Vite.

Você também pode usar import.meta.glob() em seu projeto Astro. Você pode querer fazer isso quando:

Você precisa dessa funcionalidade para um arquivo que não é .astro, como uma rota de API. Astro.glob() só está disponível com arquivos .astro, enquanto import.meta.glob() está disponível em qualquer lugar do seu projeto.
Você não precisa carregar cada arquivo imediatamente. import.meta.glob() pode retornar funções que importam o conteúdo do arquivo, em vez de retornar o conteúdo em si. Note que esta importação inclui todos os estilos e scripts de quaisquer arquivos importados. Eles serão empacotados e adicionados à página com o arquivo sendo ou não usado, pois isto é decidido por análise estática, e não em tempo de execução.
Você quer acesso a cada caminho de arquivo. import.meta.glob() retorna um mapa de um caminho de arquivo para o seu conteúdo, enquanto Astro.glob() retorna uma lista de conteúdo.
Você quer passar múltiplos padrões; por exemplo, você quer adicioanr um “padrão negativo” que filtra certos arquivos. import.meta.glob() pode opcionalmente pegar um array de strings glob, em vez de uma string única.

Arquivos Markdown

Arquivos Markdown carregados com Astro.glob() retornam a seguinte interface MarkdownInstance:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Qualquer dado especificado no frontmatter YAML/TOML do arquivo */
  frontmatter: T;
  /* O caminho de arquivo absoluto deste arquivo */
  file: string;
  /* O caminho renderizado deste arquivo */
  url: string | undefined;
  /* O Componente Astro que renderiza os conteúdos deste arquivo */
  Content: AstroComponentFactory;
  /** (Apenas Markdown) O conteúdo bruto do arquivo Markdown, excluindo layout HTML e frontmatter YAML/TOML */
  rawContent(): string;
  /** (Apenas Markdown) O arquivo markdown compilado em HTML, excluindo layout HTML */
  compiledContent(): string;
  /* Função que retorna um array dos elementos h1...h6 deste arquivo */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

Você pode fornecer opcionalmente um tipo para a variável frontmatter utilizando um TypeScript genérico.

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

Arquivos Astro

Arquivos Astro possuem a seguinte interface:

export interface AstroInstance {
  /* O caminho de arquivo deste arquivo */
  file: string;
  /* A URL para esse arquivo (se estiver no diretório pages) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Outros Arquivos

Outros arquivos podem ter várias interfaces diferentes, mas Astro.glob() aceita um TypeScript genérico se você souber exatamente o quê um tipo de arquivo desconhecido contém.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
---

Contribua Comunidade Sponsor

Contexto de renderização Astro

O objeto context

props

params

url

site

clientAddress

isPrerendered

generator

request

response

redirect()

rewrite()

locals

preferredLocale

preferredLocaleList

currentLocale

getActionResult()

callAction()

routePattern

cookies

Utilidades de cookie

cookies.get()

cookies.has()

cookies.set()

cookies.delete()

cookies.merge()

cookies.headers()

Tipo AstroCookie

value

json

number

boolean

AstroCookieGetOptions

decode

AstroCookieSetOptions

domain

expires

httpOnly

maxAge

path

sameSite

secure

encode

Propriedades de objeto descontinuadas

Astro.glob()

Arquivos Markdown

Arquivos Astro

Outros Arquivos

`props`

`params`

`url`

`site`

`clientAddress`

`isPrerendered`

`generator`

`request`

`response`

`redirect()`

`rewrite()`

`locals`

`preferredLocale`

`preferredLocaleList`

`currentLocale`

`getActionResult()`

`callAction()`

`routePattern`

`cookies`

`cookies.get()`

`cookies.has()`

`cookies.set()`

`cookies.delete()`

`cookies.merge()`

`cookies.headers()`

Tipo `AstroCookie`

`value`

`json`

`number`

`boolean`

`AstroCookieGetOptions`

`decode`

`AstroCookieSetOptions`

`domain`

`expires`

`httpOnly`

`maxAge`

`path`

`sameSite`

`secure`

`encode`

`Astro.glob()`