Referência da API
Global Astro
Seção intitulada Global AstroA global Astro
está disponível em todos os contextos em arquivos .astro
. Ela tem as seguintes funções:
Astro.glob()
Seção intitulada Astro.glob()Astro.glob()
é uma forma de carregar vários arquivos locais em seu site estático.
---const postagens = await Astro.glob('../pages/postagens/*.md'); // retorna um array de postagens que estão em ./src/pages/postagens/*.md---
<div>{postagens.slice(0, 3).map((postagem) => ( <article> <h2>{postagem.frontmatter.titulo}</h2> <p>{postagem.frontmatter.descricao}</p> <a href={postagem.url}>Leia mais</a> </article>))}</div>
">.glob()
recebe apenas um parâmetro: uma URL relativa dos arquivos locais que você gostaria de importar. Ela é assíncrona e retorna um array das exportações dos arquivos correspondentes.
.glob()
não pode receber variáveis ou strings que são interpoladas já que não são estaticamente analisáveis. (Veja o guia de solução de problemas para uma solução alternativa.) Isso acontece pois Astro.glob()
é feito em cima do import.meta.glob()
do Vite.
Você também pode usar import.meta.glob()
em si em seu projeto Astro. Você pode querer fazer isso quando:
- Você precisa dessa funcionalidade em um arquivo que não é
.astro
, como uma rota de API.Astro.glob()
é apenas disponível em arquivos.astro
, enquantoimport.meta.glob()
está disponível em qualquer parte do projeto. - Você não quer carregar cada arquivo imediatamente.
import.meta.glob()
pode retornar funções que importam o conteúdo do arquivo, ao invés de retornar o conteúdo em si. Note que essa importação inclui todos os estilos e scripts para quaisquer arquivos importados. Eles vão ser empacotados e adicionados para a página sendo o arquivo usado ou não, já que isso é decidido por análise estática e não em tempo de execução. - Você quer acessar o caminho de cada arquivo.
import.meta.glob()
retorna um map do caminho do arquivo ao seu conteúdo, enquantoAstro.glob()
retorna uma lista de conteúdo. - Você quer passar múltiplos padrões; por exemplo, você quer adicionar um “padrão negativo” que remove certos arquivos filtrados.
import.meta.glob()
pode opcionalmente receber um array de strings blog, ao invés de uma única string.
Leia mais sobre na documentação do Vite.
Arquivos Markdown
Seção intitulada Arquivos MarkdownArquivos Markdown tem a seguinte interface:
export interface MarkdownInstance<T extends Record<string, any>> { /* Quaisquer dados especificados no frontmatter YAML deste arquivo */ frontmatter: T; /* O caminho do arquivo deste arquivo */ file: string; /* O caminho renderizado deste arquivo */ url: string | undefined; /* Componente Astro que renderiza os conteúdos deste arquivo */ Content: AstroComponent; /* Função que retorna um array de elementos h1...h6 deste arquivo */ getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;}
Você pode opcionalmente oferecer um tipo para a variável frontmatter
utilizando um generic do TypeScript.
---interface Frontmatter { titulo: string; descricao?: string;}const postagens = await Astro.glob<Frontmatter>('../pages/postagens/*.md');---
<ul> {postagens.map(postagem => <li>{postagem.frontmatter.titulo}</li>)}</ul>
Arquivos Astro
Seção intitulada Arquivos AstroArquivos Astro tem a seguinte interface:
export interface AstroInstance { /* O caminho de arquivo deste arquivo */ file: string; /* A URL para este arquivo (se ele estiver no diretório pages) */ url: string | undefined; default: AstroComponent;}
Outros Arquivos
Seção intitulada Outros ArquivosOutros arquivos podem ter várias diferentes interfaces, mas Astro.glob()
aceita um generic do TypeScript se você souber exatamente o que o tipo de um arquivo desconhecido contém.
---interface DadosCustomizadosArquivo { default: Record<string, any>;}const dados = await Astro.glob<DadosCustomizadosArquivo>('../dados/**/*.js');---
Astro.props
Seção intitulada Astro.propsAstro.props
é um objeto contendo quaisquer valores que foram passados como atributos do componente. Componentes de Layout para arquivos .md
e .mdx
recebem valores frontmatter como props.
---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.
📚 Aprenda mais sobre como adicionar definições de tipo do TypeScript para suas props.
Astro.params
Seção intitulada Astro.paramsAstro.params
é um objeto que contém os valores de segmentos dinâmicos de rota que correspondem a essa requisição.
Em builds estáticas, ele será o params
retornado por getStaticPaths()
usado para pré-renderizar rotas dinâmicas.
Em builds SSR, ele pode ser qualquer valor correspondente aos segmentos do caminho no padrão da rota dinâmica.
---export function getStaticPaths() { return [ { params: { id: '1' } }, { params: { id: '2' } }, { params: { id: '3' } } ];}
const { id } = Astro.params;---<h1>{id}</h1>
Veja também: params
Astro.request
Seção intitulada Astro.requestAstro.request
é um objeto Request padrão. Ele pode ser utilizado para obter a url
, headers
, method
e até mesmo o body de uma requisição.
<p>Recebido uma requisição {Astro.request.method} para "{Astro.request.url}".</p><p>Headers da requisição recebidos: <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>
Veja também: Astro.url
Com a opção padrão output: 'static'
, Astro.request.url
não contém parâmetros de pesquisa, como ?foo=bar
, já que não é possível determiná-los com antecedência durante builds estáticas. Porém, no modo output: 'server'
, Astro.request.url
contém parâmetros de busca já que podem ser determinados pela requisição do servidor.
Astro.response
Seção intitulada Astro.responseAstro.response
é um objeto ResponseInit
padrão. Ele tem a seguinte estrutura.
status
: O código numérico do status da resposta, e.x.,200
.statusText
: A mensagem de status associada com o código de status, e.x.,'OK'
headers
: Uma instância deHeaders
que você pode usar para definir os cabeçalhos HTTP da resposta.
Astro.response
é usado para definir o status
, statusText
e headers
para a resposta de uma página.
---if(condicao) { Astro.response.status = 404; Astro.response.statusText = 'Não encontrado';}---
Ou para definir um header:
---Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');---
Astro.cookies
Seção intitulada Astro.cookiesastro@1.4.0
Astro.cookies
contém utilitários para a leitura e manipulação de cookies no modo de renderização no lado do servidor.
Nome | Tipo | Descrição |
---|---|---|
get | (key: string) => AstroCookie | Pega o cookie como um objeto AstroCookie , que contém value e funções utilitários para converter o cookie em tipos que não sejam string. |
has | (key: string) => boolean | Se o cookie existe. Se o cookie foi definido com Astro.cookies.set() , ele irá retornar true, e caso contrário, ele irá checar cookies em Astro.request . |
set | (key: string, value: string | number | boolean | object, options?: CookieOptions) => void | Define o cookie key para o valor dado. Ele tentará converter o valor do cookie para uma string. Opções providenciam formas de definir funcionalidades de cookies, como maxAge ou httpOnly . |
delete | (key: string, options?: CookieDeleteOptions) => void | Marca o cookie como deletado. Assim que o cookie é deletado, Astro.cookies.has() irá retornar false e Astro.cookies.get() irá retornar um AstroCookie com o value igual a undefined . Opções permitem definir o domain e o path do cookie a ser deletado. |
headers | () => Iterator<string> | Pega os valores de header para Set-Cookie que serão enviados com a resposta. |
AstroCookie
Seção intitulada AstroCookiePegar um cookie com Astro.cookies.get()
retorna um tipo AstroCookie
. Ele tem a seguinte estrutura.
Nome | Tipo | Descrição |
---|---|---|
value | string| undefined | O valor bruto em string do cookie. |
json | () => Record<string, any> | Faz parse do valor do cookie com JSON.parse() , retornando um objeto. Joga um erro se o valor do cookie não é JSON válido. |
number | () => number | Faz parse do valor do cookie como um Number. Retorna NaN se não for um número válido. |
boolean | () => boolean | Converte o valor do cookie para uma boolean. |
Astro.redirect()
Seção intitulada Astro.redirect()Astro.redirect()
permite você redirecionar para outra página.
Uma página (e não um componente filho) precisa retornar (com return
) o resultado de Astro.redirect()
para o redirecionamento acontecer.
---import { estaLogado } from '../utils';
const cookie = Astro.request.headers.get('cookie');
// Se o usuário não está logado, redireciona ele para a página de loginif (!estaLogado(cookie)) { return Astro.redirect('/login');}---
Astro.canonicalURL
Seção intitulada Astro.canonicalURLUtilize Astro.url
para construir sua própria URL canônica.
A URL canônica da página atual.
Astro.url
Seção intitulada Astro.urlastro@1.0.0-rc
Um objeto URL construído a partir do valor da string URL atual do Astro.request.url
. Útil para interagir com propriedades individuais da URL da requisição, como o nome do caminho e origem.
Equivalente a fazer new URL(Astro.request.url)
.
<h1>A URL atual é: {Astro.url}</h1><h1>O nome do caminho da URL atual é: {Astro.url.pathname}</h1><h1>A origem da URL atual é: {Astro.url.origin}</h1>
Você também pode usar Astro.url
para criar novas URLs a passando como um argumento em new URL()
.
---// Exemplo: Construa uma URL canônica usando seu domínio em produçãoconst URLCanonica = new URL(Astro.url.pathname, Astro.site);// Exemplo: Construa uma URL para tags meta SEO usando seu domínio atualconst URLImagemSocial = new URL('/imagens/preview.png', Astro.url);---<link rel="canonical" href={URLCanonica} /><meta property="og:image" content={URLImagemSocial} />
Astro.clientAddress
Seção intitulada Astro.clientAddressastro@1.0.0-rc
Especifica o endereço de IP da requisição. Esta propriedade é apenas disponível ao fazer build para SSR (renderização no lado do servidor) e não deve ser usado em sites estáticos.
---const ip = Astro.clientAddress;---
<div>Your IP address is: <span class="address">{ ip }</span></div>
Astro.site
Seção intitulada Astro.siteAstro.site
retorna a URL
feita a partir do site
na sua configuração do Astro. Se site
na sua configuração do Astro não estiver definido, Astro.site
não será definido.
Astro.generator
Seção intitulada Astro.generatorastro@1.0.0
Astro.generator
é uma forma conveniente de adicionar uma tag <meta name="generator">
na sua versão atual do Astro. Ela segue o formato "Astro v1.x.x"
.
<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>