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.
.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:
Você pode opcionalmente oferecer um tipo para a variável frontmatter
utilizando um generic do TypeScript.
Arquivos Astro
Seção intitulada Arquivos AstroArquivos Astro tem a seguinte interface:
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.
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.
📚 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.
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.
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.
Ou para definir um header:
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.
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)
.
Você também pode usar Astro.url
para criar novas URLs a passando como um argumento em new URL()
.
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.
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"
.
Astro.slots
Seção intitulada Astro.slotsAstro.slots
contém funções utilitárias para modificar os filhos em slots de um componente Astro.
Astro.slots.has()
Seção intitulada Astro.slots.has()Tipo: (slotName: string) => boolean
Você pode checar se existe conteúdo para um nome de slot específico com Astro.slots.has()
. Isso pode ser útil quando você quer envolver conteúdos de slots, mas apenas quer renderizar os elementos que os envolvem quando o slot está sendo utilizado.
Astro.slots.render()
Seção intitulada Astro.slots.render()Tipo: (slotName: string, args?: any[]) => Promise<string>
Você pode renderizar de forma assíncrona os conteúdos de um slot para uma string de HTML utilizando Astro.slots.render()
.
Isso é para casos de uso avançados! Na maioria das circunstâncias, é mais simples renderizar os conteúdos do slot com o elemento <slot />
.
Astro.slots.render()
opcionalmente aceita um segundo argumento: um array de parâmetros que serão passados para quaisquer funções filho. Isso pode ser útil para componentes utilitários customizados.
Por exemplo, esse componente <Grito />
converte sua prop mensagem
para letras maiúsculas e o passa como o slot padrão:
Uma função de callback passada como filho de <Grito />
receberá o parâmetro mensagem
em letras maiúsculas:
Astro.self
Seção intitulada Astro.selfAstro.self
permite que componentes Astro sejam recursivamente invocados. Este comportamento te permite renderizar um componente Astro em si mesmo utilizando <Astro.self>
no template do componente. Isto pode ser útil para iterar sobre grandes coleções e estruturas de dados aninhadas.
Este componente pode ser utilizado assim:
E renderizaria HTML assim:
Astro.locals
Seção intitulada Astro.localsAstro.locals
é um objeto contendo quaisquer valores do objeto context.locals
de um middleware. Use isso para acessar dados retornados por um middleware em seus arquivos .astro
.
Astro.preferedLocale
Seção intitulada Astro.preferedLocaleAstro.perferedLocale
é um valor computado que representa o idioma de preferência do usuário.
Ele é computado checando as configurações de idioma do seu array i18n.locales
e os idiomas suportados pelo navegado do usuário através do cabeçalho Accept-Language
. Esse valor é undefined
se não houver uma correspondência.
Essa propriedade só está disponível ao fazer o build em modo SSR (renderização do lado do servidor) e não deve ser utilizada em sites estáticos.
Astro.preferedLocaleList
Seção intitulada Astro.preferedLocaleListAstro.preferedLocaleList
representa a lista de todos o slocales que são tanto requisitados pelo navegador quanto suportados pelo seu website. Isso produz uma lista de todas as linguagens compatíveis entre o seu site e seu visitante.
Se nenhuma das linguagens requesitadas pelo navegador forem encontradas na sua lista de idiomas, então o valor é []
: você não suporta nenhum dos idiomas de preferência do seu visitante.
Se o navegador não especificar nenhuma linguagem de preferência, então esse valor será igual ao i18n.locales
: todas os seus idiomas suportados serão considerados igualmente aceitáveis pelo visitante sem nenhuma preferênca.
Essa propriedade só está disponível ao fazer o build em modo SSR (renderização do lado do servidor) e não deve ser utilizada em sites estáticos.
Astro.currentLocale
Seção intitulada Astro.currentLocaleO idioma computado a partir da URL atual, utilizando a sintaxe definida em sua configuração locales
. Se a URL não incluir um prefixo /[locale]/
, então o valor será o padrão definido em i18n.defaultLocale
.
Contexto de Endpoint
Seção intitulada Contexto de EndpointFunções de Endpoint recebem um objeto de contexto como primeiro parâmetro. Ele copia muitas das propriedades da global Astro
.
context.params
Seção intitulada context.paramscontext.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.
Veja também: params
context.props
Seção intitulada context.propscontext.props
é um objeto que contém quaisquer props
passadas de getStaticPaths()
. Por conta de getStaticPaths()
não ser usado ao fazer build para SSR (renderização no lado do servidor), context.props
está disponível apenas em builds estáticas.
Veja também: Passagem de dados com props
context.request
Seção intitulada context.requestUm objeto Request padrão. Ele pode ser utilizado para conseguir a url
, headers
, method
e até mesmo body da requisição.
Veja também: Astro.request
context.cookies
Seção intitulada context.cookiescontext.cookies
contém utilitários para a leitura e manipulação de cookies.
Veja também: Astro.cookies
context.url
Seção intitulada context.urlUm objeto URL construído do valor string context.request.url
da URL atual.
Veja também: Astro.url
context.clientAddress
Seção intitulada context.clientAddressEspecifica o endereço de IP da requisição. Essa propriedade só está disponível ao fazer build para SSR (renderização no lado do servidor) e não deve ser utilizada para sites estáticos.
Veja também: Astro.clientAddress
context.site
Seção intitulada context.sitecontext.site
retorna uma URL
feita do site
na sua configuração do Astro. Se for undefined, ela irá retornar uma URL gerada a partir de localhost
.
Veja também: Astro.site
context.generator
Seção intitulada context.generatorcontext.generator
é uma forma conveniente de indicar a versão do Astro em que seu projeto está. Ela segue o formato "Astro v1.x.x"
.
Veja também: Astro.generator
context.redirect()
Seção intitulada context.redirect()context.redirect()
retorna um objeto Response que te permite redirecionar para outra página. Essa função está disponível apenas ao fazer build para SSR (renderização no lado do servidor) e não deve ser utilizada para sites estáticos.
Veja também: Astro.redirect
context.locals
Seção intitulada context.localscontext.locals
é um objeto usado para armazenar e acessar informações arbitrárias durante o ciclo de vida de uma requisição.
Funções de middleware podem ler e escrever valores do context.locals
:
Endpoints de API so podem ler informações do context.locals
:
Veja também: Astro.locals
getStaticPaths()
Seção intitulada getStaticPaths()Se uma página utiliza parâmetros dinâmicos em seu nome de arquivo, tal componente precisará exportar uma função getStaticPaths()
.
Esta função é necessária pois Astro é um gerador de sites estáticos. Isso significa que o seu site inteiro é construído previamente. Se Astro não sabe como gerar uma página em tempo de build, seus usuários não o irão ver quando visitarem o seu site.
A função getStaticPaths()
deve retornar um array de objetos para determinar quais caminhos serão pré-renderizados pelo Astro.
Ela também pode ser utilizada para endpoints de arquivos estáticos para roteamento dinâmico.
A função getStaticPaths()
é executada em seu próprio escopo isolado unicamente, antes de qualquer página carregar. Portanto você não pode referenciar nada de seu escopo parente além de importações de arquivos. O compilador irá te avisar se você quebrar esse requisito.
params
Seção intitulada paramsA chave params
de todos os objetos retornados diz ao Astro quais rotas construir. Os parâmetros retornados devem ser mapeados de volta para os parâmetros dinâmicos e rest definidos no caminho de arquivo do seu componente.
params
são codificados na URL, então apenas strings são suportadas como valores. O valor para cada objeto params
deve corresponder aos parâmetros utilizados no nome da página.
Por exemplo, suponha que você tem uma página em src/pages/postagens/[id].astro
. Se você exportar getStaticPaths
dessa página e retornar os seguintes caminhos:
Então Astro irá estaticamente gerar postagens/1,
, postagens/2
, e postagens/3
em tempo de build.
Passagem de Dados com props
Seção intitulada Passagem de Dados com propsPara passar dados adicionais para cada página gerada, você também pode definir um valor a props
para cada objeto de caminho retornado. Diferente de params
, props
não são codificadas na URL, então não estão limitadas a apenas strings.
Por exemplo, supomos que você gera páginas baseando-se em dados buscados a partir de uma API remota. Você pode passar o objeto inteiro dos dados para o componente da página dentro de getStaticPaths
:
Você também pode passar um array normal, que pode ser útil quando for gerar ou esboçar uma lista conhecida de rotas.
Então Astro irá estaticamente gerar postagens/1
e postagens/2
em tempo de build utilizando o componente da página em pages/postagens/[id].astro
. A página pode referenciar esses dados utilizando Astro.props
:
paginate()
Seção intitulada paginate()Paginação é um caso de uso comum para websites que Astro nativamente suporta através da função paginate()
. paginate()
irá automaticamente gerar o array para retornar de getStaticPaths()
que cria uma URL para cada página da coleção paginada. O número da página será passado como um parâmetro, e os dados da página serão passados como a prop page
.
paginate()
assume um nome de arquivo [page].astro
ou [...page].astro
. O parâmetro page
se torna o número da página em sua URL:
/postagens/[page].astro
geraria as URLs/postagens/1
,/postagens/2
,/postagens/3
, etc./postagens/[...page].astro
geraria as URLs/postagens
,/postagens/2
,/postagens/3
, etc.
paginate()
recebe os seguintes argumentos:
pageSize
- O número de itens exibidos por páginaparams
- Envie parâmetros adicionais para criar rotas dinâmicasprops
- Envie props adicionais para serem disponibilizadas em cada página
A prop page
da paginação
Seção intitulada A prop page da paginaçãoA paginação irá passar a prop page
para cada página renderizada que representa uma única página de dados na coleção paginada. Isso inclui dados que você paginou (page.data
) assim como metadados para a página (page.url
, page.start
, page.end
, page.total
, etc). Estes metadados são úteis para coisas como um botão de “Próxima Página” ou uma mensagem “Mostrando 1-10 de 100”.
Nome | Tipo | Descrição |
---|---|---|
page.data | Array | Array dos dados retornados de data() para a página atual. |
page.start | number | Índice do primeiro item na página atual, começando em 0 (e.x. se pageSize: 25 , isso seria 0 na página 1, 25 na página 2, etc.). |
page.end | number | Índice do último item na página atual. |
page.size | number | Quantos itens há por página. |
page.total | number | O número total de itens em todas as páginas. |
page.currentPage | number | O número da página atual, começando por 1 . |
page.lastPage | number | O número total de páginas. |
page.url.current | string | URL da página atual (útil para URLs canônicas) |
page.url.prev | string | undefined | URL da página anterior (será undefined se estiver na página 1). |
page.url.next | string | undefined | URL da próxima página (será undefined se não houverem mais páginas). |
import.meta
Seção intitulada import.metaTodos os módulos ESM incluem a propriedade import.meta
. Astro adiciona import.meta.env
através do Vite.
import.meta.env.SSR
pode ser utilizado para saber quando se está sendo renderizado no servidor. As vezes você pode querer uma lógica diferente, por exemplo, para um componente que deve ser apenas renderizado no cliente:
Imagens (astro:assets
)
Seção intitulada Imagens (astro:assets)getImage()
Seção intitulada getImage()getImage()
depende de APIs exclusivas do servidor e faz o build falhar quando utilizado no cliente.
A função getImage()
tem a intenção de gerar imagens para serem usadas em lugares não diretamente no HTML, por exemplo em uma Rota de API. Ela também permite que você crie seu próprio componente <Image />
customizado.
getImage()
recebe um objeto de opções com as mesmas propriedades do componente “Image” (exceto alt
).
Ela retorna um objeto com as seguintes propriedades:
Coleções de Conteúdo (astro:content
)
Seção intitulada Coleções de Conteúdo (astro:content)
Adicionado em:
astro@2.0.0
Coleções de conteúdo oferecem APIs para configurar e buscar seus documentos Markdown ou MDX em src/content/
. Para funcionalidades e exemplos de uso, veja nosso guia de coleções de conteúdo.
defineCollection()
Seção intitulada defineCollection()defineCollection()
é um utilitário para configurar uma coleção em um arquivo src/content/config.*
.
Essa função aceita as seguintes propriedades:
Adicionado em:astro@2.5
Tipo: 'content' | 'data'
Padrão: 'content'
O type
é uma string que define o tipo das entidades armazenadas dentro de uma coleção:
'content'
- para formatos de autoria de conteúdo como Markdown (.md
), MDX (.mdx
) ou Markdoc (.mdoc
)'data'
- para formatos exclusivamente de dados como JSON (.json
) ou YAML (.yaml
)
Isso significa que coleções não podem armazenar uma mistura de conteúdos e formatos de dados. Você precisa dividir essas entidades em coleções separadas por tipo.
schema
Seção intitulada schemaTipo: TSchema extends ZodType
schema
é um objeto Zod opcional para configurar o tipo e formato do frontmatter do documento para uma coleção. Cada valor do objeto deve utilizar um validador do Zod.
Veja o guia de Coleções de Conteúdo
para exemplos de uso.
reference()
Seção intitulada reference()Tipo: (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>
A função reference()
é usada na configuração de conteúdo para definir uma relação, ou “referência”, de uma coleção com a outra. Ela aceita um nome de coleção e valida o(s) identificador(es) de entrada especificados no frontmatter do seu conteúdo ou arquivo de dados.
Esse exemplo define referências de um autor de blog para a coleção autores
e um array de postagens relacionadas na mesma coleção blog
:
Veja o guia Coleções de Conteúdo
para um exemplo de uso.
getCollection()
Seção intitulada getCollection()Tipo: (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]
getCollection()
é uma função que devolve a lista de entradas de coleções de conteúdo por nome de coleção.
Ela retorna todos os itens em uma coleção por padrão, e aceita uma função filter
opcional para limitar por propriedades de entradas. Isso te permite buscar apenas alguns itens em uma coleção com base no id
, slug
, ou valores do frontmatter pelo objeto data
.
Veja a seção guia de getCollection()
para exemplos completos de uso.
getEntry()
Seção intitulada getEntry()
Adicionado em:
astro@2.5.0
Tipos:
(collection: string, contentSlugOrDataId: string) => CollectionEntry<collection>
({ collection: string, id: string }) => CollectionEntry<collection>
({ collection: string, slug: string }) => CollectionEntry<collection>
getEntry()
é uma função que recupera uma única entrada de coleção pelo nome da coleção e tanto pelo id
da entrada (para coleções type: 'data'
) ou pelo slug
da entrada (para coleções type: 'content'
). getEntry()
também pode ser usada para obter entradas referenciadas para acessar as propriedades data
, body
ou render()
:
Veja o guia Coleções de Conteúdo
para exemplos de como consultar entradas de coleção.
getEntries()
Seção intitulada getEntries()
Adicionado em:
astro@2.5
Tipos:
(Array<{ collection: string, id: string }>) => CollectionEntry<collection>
(Array<{ collection: string, slug: string }>) => CollectionEntry<collection>
getEntries()
é uma função que recupera múltiplas entradas de uma mesma coleção. Isso é útil para retornar um array de entradas referenciadas para acessar as propriedades data
, body
e render()
associadas a elas.
getEntryBySlug()
Seção intitulada getEntryBySlug()Tipo: (collection: string, slug: string) => CollectionEntry<collection>
Use a função getEntry()
para consultar entradas de conteúdo. Ela aceita os mesmos argumentos que getEntryBySlug()
, e suporta consultar pelo id
para coleções JSON ou YAML.
getEntry()
é uma função que devolve uma única entrada de coleção por nome de coleção e slug
da entrada.
Veja o guia de Coleções de Conteúdo
para exemplos de uso.
Tipo da Entrada da Coleção
Seção intitulada Tipo da Entrada da ColeçãoAs funções de consulta getCollection()
, getEntry()
e getEntries()
retornam entradas com o tipo CollectionEntry
. Esse tipo está disponível como um utilitário de astro:content
:
O tipo CollectionEntry<TCollectionName>
é um objeto com os seguintes valores. TCollectionName
é o nome da coleção que você está consultando (e.x. CollectionEntry<'blog'>
).
Disponível para: coleções type: 'content'
e type: 'data'
Tipos de Exemplo:
- coleções de conteúdo:
'entrada-1.md' | 'entrada-2.md' | ...
- coleções de dados:
'autor-1' | 'autor-2' | ...
Um ID único utilizando o caminho de arquivo relativo a src/content/[coleção]
. Enumera todos os valores de string possíveis com base nos caminhos de arquivo da entrada de coleção. Note que coleções definidas como type: 'content'
incluem a extensão do arquivo em seus ID, enquanto coleções definidas como type: 'data'
nao incluem.
collection
Seção intitulada collectionDisponível para: coleções type: 'content'
e type: 'data'
Tipo de Exemplo: 'blog' | 'autores' | ...
O nome de uma pasta de nível superior dentro de src/content/
onde as entradas são localizadas. Este é o nome usado para referenciar a coleção no seu esquema e em funções de consulta.
Disponível para: coleções type: 'content'
e type: 'data'
Tipo: CollectionSchema<TCollectionName>
Um objeto de propriedades frontmatter inferidas do schema da sua coleção (veja a referência de defineCollection()
). Por padrão é any
se nenhum schema é configurado.
Disponível para: apenas coleções type: 'content'
Tipo de Exemplo: 'entrada-1' | 'entrada-2' | ...
Uma slug pronta para URLs para documentos Markdown ou MDX. Por padrão é o id
sem a extensão de arquivo, mas pode ser sobreescrita ao definir a propriedade slug
no frontmatter de um arquivo.
Disponível para: apenas coleções type: 'content'
Tipo: string
Uma string contendo o body bruto e não-compilado do documento Markdown ou MDX.
render()
Seção intitulada render()Disponível para: apenas coleções type: 'content'
Tipo: () => Promise<RenderedEntry>
Uma função para compilar dado documento Markdown ou MDX document para renderização. Ela retorna as seguintes propriedades:
<Content />
- Um componente utilizado para renderizar os conteúdos do documento em um arquivo Astro.headings
- A lista gerada de títulos, imitando a utilidadegetHeadings()
do Astro em importações Markdown e MDX.remarkPluginFrontmatter
- O objeto frontmatter modificado após quaisquer plugins remark ou rehype terem sido aplicados. Definido ao tipoany
.
Veja a seção guia de getCollection()
para exemplos completos de uso.
Outros tipos de Coleções de Conteúdo
Seção intitulada Outros tipos de Coleções de ConteúdoO módulo astro:content
também exporta os seguintes tipos para utilizar em seu projeto Astro:
CollectionKey
Seção intitulada CollectionKeyUma união de strings de todos os nomes de coleções definidas em seu arquivo src/content/config.*
. Esse tipo pode ser útil ao definir uma função genérica que aceite o nome de qualquer coleção.
ContentCollectionKey
Seção intitulada ContentCollectionKeyUma união de strings de todos os nomes de coleções type: 'content'
definidos em seu arquivo src/content/config.*
.
DataCollectionKey
Seção intitulada DataCollectionKeyUma união de strings de todos os nomes de coleções type: 'data'
definidoes em seu arquivo src/content/config.*
.
SchemaContext
Seção intitulada SchemaContextO objeto context
que defineCollection
passa para a construção do schema
. Esse tipo pode ser útil ao criar schemas reutilizáveis para múltiplas coleções.
Isso inclui as seguintes propriedades:
image
- O schema auxiliarimage()
que lhe permite utilizar imagens locais em Coleções de Conteúdo
Middleware (astro:middleware
)
Seção intitulada Middleware (astro:middleware)
Adicionado em:
astro@2.6.0
Middleware lhe permite interceptar chamadas e respostas e injetar comportamentos dinamicamente cada vez que uma página ou endpoint estiver prestes ser renderizada. Para funcionalidades e exemplos de uso, veja nosso guia sobre middleware.
onRequest()
Seção intitulada onRequest()Uma função exportada obrigatória do arquivo src/middleware.js
que será chamada antes da renderização de cada página ou rota da API. Ela aceita dois argumentos opcionais: context e next(). onRequest()
deve retornar uma Response
: ou diretamente, ou chamando next()
.
next()
Seção intitulada next()Uma função que intercepta (lê e modifica) a resposta (Response
) de uma requisição (Request
) ou invoca o próximo middleware na sequência e retorna uma Response
. Por exemplo, essa função pode modificar o corpo HTML de uma resposta.
Esse é um argumento opcional de onRequest()
, e pode prover a Response
que o middleware deve retornar.
sequence()
Seção intitulada sequence()Uma função que aceita funções de middleware como argumentos, e os executará na ordem que foram passados.
createContext()
Seção intitulada createContext()Uma API de baixo nível para criar um APIContext
que pode ser utilizado pelo middleware Astro.
Essa função pode ser usada por integrações/adaptadores para executar programaticamente os middlewares Astro.
trySerializeLocals()
Seção intitulada trySerializeLocals()Uma API de baixo nível que recebe qualquer valor e tenta retornar uma versão serializada (uma string) desse valor. Se o valor não puder ser serializado, essa função irá lançar um erro de runtime.
Componentes Integrados
Seção intitulada Componentes IntegradosAstro inclui vários componentes integrados para você utilizar em seus projetos. Todos os componentes integrados estão disponíveis em arquivos .astro
via import {} from 'astro:components';
.
<Code />
Seção intitulada <Code />Este componente providencia syntax highlighting para blocos de código em tempo de build (sem JavaScript no lado do cliente). O componente é viabilizado internamente por Shiki e suporta todos os temas e linguagens populares. Além disso, você pode adicionar temas e linguagens customizadas as passando para theme
e lang
respectivamente.
<Fragment />
Seção intitulada <Fragment />Um componente utilizado com diretivas set:*
para renderizar conteúdo HTML sem nenhum elemento adicional em volta:
Veja mais sobre o uso de fragmentos na sintaxe do Astro.
<Prism />
Seção intitulada <Prism />Para usar o componente highlighter Prism
, primeiro instale o pacote @astrojs/prism
:
Este componente providencia syntax highlighting de linguagens específicas para blocos de código aplicando as classes CSS do Prism. Note que você precisa providenciar uma folha de estilos CSS do Prism (ou utilizar sua própria) para aparecer o syntax highlighting! Veja a seção de configuração do Prism para mais detalhes.
Veja a lista de linguagens suportadas pelo Prism aonde você pode ver o alias correspondente de uma linguagem. E, você também pode mostrar seus blocos de código Astro com lang="astro"
!
<Image />
Seção intitulada <Image />Propriedades
Seção intitulada Propriedades- src (obrigatório)
- alt (obrigatório)
- width e height (obrigatórios para imagens em
public/
ou remotas) - format
- quality
- densities
- widths
Adicionalmente às propriedades acima, o componente <Image />
aceita todas as propriedades da tag HTML <img>
.
Veja mais detalhes no Guia de Imagens.
<Picture />
Seção intitulada <Picture />astro@3.3.0
Use o componente Astro integrado <Picture />
para exibir imagens responsivas com múltiplos formatos e/ou tamanhos.
Veja mais no Guia de Imagens.
Propriedades
Seção intitulada Propriedades<Picture />
aceita todas as propriedades do componente <Image />
, juntamente com:
formats
Seção intitulada formatsUm array de formatos de imagem a serem utilizados nas tags <source>
. Por padrão, isso é configurado como ['webp']
.
fallbackFormat
Seção intitulada fallbackFormatFormato a ser usado como um valor de fallback para a tag <img>
. Por padrão, é configurado como .png
para imagens estáticas, .gif
para imagens animadas e .svg
para arquivos SVG.
pictureAttributes
Seção intitulada pictureAttributesUse essa propriedade para aplicar atributos ao elemento externo <picture>
. Atributos aplicados diretamente ao componente <Picture />
serão aplicados internamente ao elemento <img>
, exceto aqueles usados para a transformação da imagem.
<Content />
Seção intitulada <Content />Um componente genérico utilizado para renderizar o conteúdo de uma entrada de uma coleção de conteúdo.
Primeiro, busque por uma ou mais entradas utilizando getCollection()
ou getEntry()
. Com isso, a função entrada.render()
pode retornar o componente <Content />
para ser utilizado em um arquivo de template .astro
.
<ViewTransitions />
Seção intitulada <ViewTransitions />Opte por usar transições de visualização on páginas individuais importando e adicionando o componente de roteamento <ViewTransitions />
ao <head>
em cada página desejada.
Veja mais sobre como controlar o roteamento e adicionar diretivas de transição em elementos e componentes da página.
<Debug />
Seção intitulada <Debug />Este componente providencia uma forma de inspecionar valores no lado do cliente, sem utilizar JavaScript.
Reference