Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

i18n(pt-BR): update astro-pages.mdx #9446

Merged
merged 9 commits into from
Sep 23, 2024
Merged

i18n(pt-BR): update astro-pages.mdx #9446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
45c9d40
i18n(pt-BR): update and review i18n/pt-br/basics/astro-pages.mdx
viniciusdeliz Sep 19, 2024
1d15dc6
Merge branch 'main' into 18n/pt-br/basics/astro-pages
viniciusdeliz Sep 19, 2024
166c93d
i18n(pt-BR): fix typo in title of `i18n/pt-br/basics/astro-pages.mdx`
viniciusdeliz Sep 19, 2024
9ce34f5
i18n(pt-BR): fix links in `i18n/pt-br/basics/astro-pages.mdx`
viniciusdeliz Sep 19, 2024
33f2833
i18n(pt-BR): update fragment link of endpoints.mdx that pointed to `i…
viniciusdeliz Sep 19, 2024
04902c4
Merge branch 'main' into 18n/pt-br/basics/astro-pages
yanthomasdev Sep 20, 2024
2d54598
i18n(pt-BR): update `i18n/pt-br/guides/endpoints.mdx`
viniciusdeliz Sep 20, 2024
4d22488
i18n(pt-BR): fix typo in `i18n/pt-br/guides/endpoints.mdx`
viniciusdeliz Sep 20, 2024
b294889
Merge branch 'main' into 18n/pt-br/basics/astro-pages
yanthomasdev Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 56 additions & 24 deletions src/content/docs/pt-br/basics/astro-pages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ i18nReady: true
import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro'

**Páginas** são arquivos que vivem dentro do subdiretório `src/pages/` do seu projeto Astro. Elas são responsáveis por lidar com roteamento, carregamento de dados e com o layout geral de cada página do seu website.
**Páginas** são arquivos que vivem dentro do subdiretório `src/pages/` do seu projeto Astro. Elas são responsáveis por manipular o roteamento, o carregamento de dados e com o layout de toda página do seu website.

## Tipos de arquivos suportados

Expand All @@ -20,17 +20,17 @@ Astro suporta os seguintes tipos de arquivo no diretório `src/pages/`:

## Roteamento baseado em arquivos

Astro se beneficia de uma estratégia de roteamento chamada **roteamento baseado em arquivos**. Cada arquivo em seu diretório `src/pages` se torna um endpoint no seu site com base no seu caminho de arquivo.
Astro aproveita uma estratégia de roteamento chamada **roteamento baseado em arquivos**. Cada arquivo no diretório `src/pages` torna-se um endpoint no site com base no caminho do arquivo.

Um único arquivo também pode gerar múltiplas páginas utilizando [roteamento dinâmico](/pt-br/guides/routing/#rotas-dinâmicas). Isso te permite criar páginas mesmo que seu conteúdo esteja fora do diretório especial `/pages/`, como em uma [coleção de conteúdo](/pt-br/guides/content-collections/) ou em um [CMS](/pt-br/guides/cms/).
Um único arquivo também pode gerar múltiplas páginas utilizando [roteamento dinâmico](/pt-br/guides/routing/#rotas-dinâmicas). Isso permite que você crie páginas mesmo que seu conteúdo esteja fora do diretório especial `/pages/`, como em uma [coleção de conteúdo](/pt-br/guides/content-collections/) ou em um [CMS](/pt-br/guides/cms/).

<ReadMore>Leia mais sobre [Roteamento no Astro](/pt-br/guides/routing/).</ReadMore>

### Link entre páginas

Escreva [elementos `<a>`](https://developer.mozilla.org/pt-BR/docs/Web/HTML/Element/a) padrões do HTML em suas páginas Astro para fazer o link para outras páginas em seu site. Utilize como seu link o **caminho URL relativo para a raiz do seu domínio**, não o caminho relativo para o arquivo.
Escreva [elementos `<a>`](https://developer.mozilla.org/pt-BR/docs/Web/HTML/Element/a) padrão HTML em suas páginas Astro para ligar a outras páginas no site. Utilize como link o **caminho URL relativo ao domínio raiz**, não um caminho de arquivo relativo.

Por exemplo, para acessar `https://exemplo.com/autores/sonali/` de uma outra página dentro de `exemplo.com`:
Por exemplo, para acessar `https://exemplo.com/autores/sonali/` de qualquer outra página dentro de `exemplo.com`:

```astro title="src/pages/index.astro"
Leia mais <a href="/autores/sonali/">sobre Sonali</a>.
Expand All @@ -40,9 +40,8 @@ Leia mais <a href="/autores/sonali/">sobre Sonali</a>.

Páginas Astro usam a extensão de arquivo `.astro` e suportam as mesmas funcionalidades que [componentes Astro](/pt-br/basics/astro-components/).

```astro
```astro title="src/pages/index.astro"
---
// Example: src/pages/index.astro
---
<html lang="pt-BR">
<head>
Expand All @@ -54,7 +53,7 @@ Páginas Astro usam a extensão de arquivo `.astro` e suportam as mesmas funcion
</html>
```

Uma página deve produzir um documento HTML completo. Se não for explicitamente incluido, Astro adicionará automaticamente declarações necessárias como `<!DOCTYPE html>` e o conteúdo do `<head>` em qualquer componente `.astro` localizado em `src/pages/`. Você pode optar por não utilizar esse comportamento de maneira individual por componente, marcando-o como uma página [parcial](#parciais-de-páginas).
Uma página deve produzir um documento HTML completo. Se não for explicitamente incluído, Astro adicionará a declaração `<!DOCTYPE html>` necessária e conteúdo `<head>` em qualquer componente `.astro` localizado em `src/pages/` por padrão. Você pode optar não utilizar esse comportamento de maneira individual por componente, marcando-o como uma página [parcial](#parciais-de-páginas).

Para evitar repetir os mesmos elementos HTML em cada página, você pode mover elementos `<head>` e `<body>` comuns em seus próprios [componentes de layout](/pt-br/basics/layouts/). Você pode usar quantos componentes de layout você quiser.

Expand All @@ -72,11 +71,13 @@ import LayoutDoMeuSite from '../layouts/LayoutDoMeuSite.astro';

## Páginas Markdown/MDX

Astro também trata quaisquer arquivos Markdown (`.md`) dentro de `src/pages/` como páginas no seu website final. Se você tiver a [Integração MDX instalada](/pt-br/guides/integrations-guide/mdx/#installation), ele também irá tratar arquivos MDX (`.mdx`) da mesma forma. Eles são comumente utilizados para páginas cheias de texto como postagens de um blog e documentação.
Astro trata quaisquer arquivos Markdown (`.md`) dentro de `src/pages/` como páginas em seu site final. Se você tiver a [Integração MDX instalada](/pt-br/guides/integrations-guide/mdx/#installation), ele tratará arquivos MDX (`.mdx`) da mesma forma.

[Coleções de conteúdo de páginas Markdown ou MDX](/pt-br/guides/content-collections/) em `src/content/` podem ser utilizados para [gerar páginas dinamicamente](/pt-br/guides/routing/#rotas-dinâmicas).
:::tip
Considere criar [coleções de conteúdo](/pt-br/guides/content-collections/) em vez de páginas para diretórios de arquivos Markdown relacionados que partilham estrutura similar, como posts de blog ou produtos.
:::

Layouts de página são especialmente úteis para [arquivos Markdown](#páginas-markdownmdx). Arquivos MMarkdown podem utilizar a propriedade especial `layout` do frontmatter para especificar um [componente de layout](/pt-br/basics/layouts/) que irá envolver seu conteúdo Markdown em uma página de documento `<html>...</html>` completo.
Arquivos Markdown podem usar a propriedade frontmatter especial `layout` para especificar um [layout de componente](/pt-br/basics/layouts/) que envolverá o conteúdo Markdown em um documento `<html>...</html>`.

```md {3}
---
Expand All @@ -93,30 +94,61 @@ Está é minha página, escrita em **Markdown.**

## Páginas HTML

Arquivos com a extensão de arquivo `.html` podem ser colocados dentro de `src/pages/` e usados diretamente como páginas no seu site. Note que algumas funcionalidades importantes do Astro não são suportadas em [Componentes HTML](/pt-br/basics/astro-components/#componentes-html).
Arquivos com a extensão `.html` podem ser colocados dentro de `src/pages/` e usados diretamente como páginas no seu site. Note que algumas funcionalidades-chave Astro não funcionam em [Componentes HTML](/pt-br/basics/astro-components/#componentes-html).

## Página de Erro 404 Personalizada

Para uma página de erro 404 personalizada, você pode criar um arquivo `404.astro` ou `404.md` em `src/pages`.

Isso construirá uma página `404.html`. A maioria dos [serviços de deploy](/pt-br/guides/deploy/) irão encontrá-la e utilizá-la.

## Página de Erro 500 Personalizada

Para uma página de erro 500 personalizada aparecer para páginas que são [geradas sob demanda](/pt-br/guides/server-side-rendering/#habilitando-a-renderização-no-servidor-sob-demanda), crie o arquivo `src/pages/500.astro`. Essa página personalizada não está disponível para páginas pré-geradas e não podem ser geradas previamente.

Se um erro ocorrer ao gerar essa página, a página padrão da sua hospedagem será mostrada ao visitante.

<p><Since v="4.10.3" /></p>

## Página Customizada de Erro 404
Durante o desenvolvimento, se você tiver um `500.astro`, o erro lançado em tempo de execução é registrado em seu terminal, em vez de ser mostrado na janela de erros.

Para uma página customizada de erro 404, você pode criar um arquivo `404.astro` ou `404.md` em `/src/pages`.
### `error`

<p><Since v="4.11.0" /></p>

`src/pages/500.astro` é uma página especial que recebe automaticamente uma prop `error` para qualquer erro lançado durante a apresentação. Isso permite que você use os detalhes de um erro (como de uma página, de um middleware, etc.) para mostrar informações ao seu visitante.

O tipo de dado da prop error pode ser qualquer coisa, que pode afetar como você tipa ou usa o valor no seu código:

```astro title="src/pages/500.astro"
---
interface Props {
error: unknown
}

const { error } = Astro.props
---

<div>{error instanceof Error ? error.message : 'Erro desconhecido'}</div>
```

Isso irá construir uma página `404.html`. A maioria dos [serviços de deploy](/pt-br/guides/deploy/) irão a encontrar e utilizar.
Para evitar vazar informações snsíveis ao mostrar o conteúdo da prop `error`, considere avaliar o erro primeiro, e retornar o conteúdo apropriado baseado no erro lançado. Por exemplo, você deve evitar mostrar a pilha do erro pois ela contém informações sobre como seu código é estruturado no servidor

## Parciais de páginas

<p><Since v="3.4.0" /></p>

:::caution
É esperado que parciais de páginas sejam utilizadas em conjunto com uma biblioteca front-end, como [htmx](https://htmx.org/) ou [Unpoly](https://unpoly.com/). Você também pode utiliza-las caso se sinta confortável escrevendo JavaScript front-end low-level. Por conta disso elas são consideradas um recurso avançado.
Parciais de páginas são projetadas para serem utlizadas em conjunto com uma biblioteca front-end, como [htmx](https://htmx.org/) ou [Unpoly](https://unpoly.com/). Você também pode usá-las caso se sinta confortável escrevendo front-end JavaScript em baixo nível. Por esse motivo são um recurso avançado.

Adicionalmente, parciais não devem ser usadas se o componente possuir estilos com escopo ou scripts, pois esses elementos serão removidos do HTML gerado. Se você precisa de estilos com escopo, melhor utilizar páginas padrões não-parciais em conjunto com uma biblioteca frontend que saiba mesclar conteúdos no head.
Adicionalmente, parciais não devem ser usadas se o componente contém estilos em escopo ou scripts, pois esses elementos serão removidos do HTML gerado. Se você precisa de estilos em escopo, é melhor utilizar páginas não-parciais regulares em conjunto com uma biblioteca front-end que saiba mesclar conteúdos ao head.
:::

Parciais são componentes de página localizados em `src/pages/` que não tem como objetivo serem renderizados em páginas completas.
Parciais são componentes de página localizados em `src/pages/` que não têm como objetivo serem apresentados como páginas completas.

Assim como componentes localizados fora dessa pasta, esses arquivos não incluem a declaração `<!DOCTYPE html>` automaticamente, nem qualquer outro conteúdo do `<head>` como estilos com escopo e scripts.
Como componentes localizados fora dessa pasta, esses arquivos não incluem automaticamente a declaração `<!DOCTYPE html>`, nem qualquer outro conteúdo do `<head>` como estilos em escopo e scripts.

Porém, por estarem localizados no diretório especial `src/pages/`, o código HTML gerado fica disponível em uma URL que corresponde ao caminho do arquivo. Isso permite que uma biblioteca de renderização (ex: htmx, Stimulus, jQuery) possa acessá-lo no cliente e carregar sessões do HTML dinamicamente em uma página, sem a necessecidade de um recarregamento ou navegação entre páginas.
Entretanto, por estarem localizados no diretório especial `src/pages/`, o HTML gerado fica disponível em uma URL que corresponde ao caminho do arquivo. Isso permite que uma biblioteca de renderização (como htmx, Stimulus, jQuery) possa acessá-lo no cliente e carregar seções do HTML dinamicamente em uma página sem recarregar o navegador ou navegar entre páginas.

Parciais, quando combinados com uma biblioteca de renderização, proporcionam uma alternativa às [Ilhas Astro](/pt-br/concepts/islands/) e [tags `<script>`](/pt-br/guides/client-side-scripts/) na construção de conteúdo dinâmico em Astro.

Expand All @@ -132,16 +164,16 @@ export const partial = true;
<li>Eu sou uma parcial!</li>
```

O `export const partial` deve ser identificável estaticamente. Ele pode conter os seguintes valores.
O `export const partial` deve ser identificável estaticamente. Ele pode ter o valor de:

- O booleano __`true`__.
- Uma variável de ambiente usando import.meta.env como `import.meta.env.USE_PARTIALS`.

### Usando com uma biblioteca

Parciais são usadas para atualizar dinamicamente sessões de uma página usando bibliotecas como [htmx](https://htmx.org/).
Parciais são usadas para atualizar dinamicamente a seção de uma página usando bibliotecas como [htmx](https://htmx.org/).

O exemplo a seguir mostra um atributo `hx-post` direcionado para uma URL parcial. O conteúdo da página parcial será utilizado para atualizar o elemento HTML escolhido na página.
O exemplo a seguir mostra um atributo `hx-post` direcionado para a URL de uma parcial. O conteúdo da página parcial será usado para atualizar o elemento HTML escolhido na página.

```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"'
<html>
Expand Down Expand Up @@ -174,4 +206,4 @@ export const partial = true;
<div>Eu fui clicado!</div>
```

Visite a [documentação do htmx](https://htmx.org/docs/) para mais detalhes sobre como utilizá-lo.
Visite a [documentação htmx](https://htmx.org/docs/) para mais detalhes sobre como utilizar htmx.
8 changes: 5 additions & 3 deletions src/content/docs/pt-br/guides/endpoints.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,12 +94,14 @@ export const GET: APIRoute = ({ params, request }) => {

Tudo descrito na seção de endpoints de arquivos estáticos também pode ser utilizado no modo SSR: arquivos podem exportar uma função `GET` que recebe um [objeto de contexto](/pt-br/reference/api-reference/#contexto-de-endpoint) com propriedades similares a global `Astro`.

Porém, diferente do modo `static`, quando você configura o modo `server`, os endpoints serão construídos no momento em que são requisitados. Isso desbloqueia novas funcionalidades que estão indisponíveis durante a build e permite que você construa rotas de API que respondem requisições e seguramente executam código no servidor em runtime.
Porém, diferente do modo `static`, quando você habilita a renderização sob demanda para uma rota, o endpoint será construído ao ser requisitado. Isso destrava novas funcionalidades que são indisponíveis em tempo de construção, e permite que você construa rotas de API que ouvem a requisições e executam código de maneira segura no servidor em tempo de execução.

Suas rotas serão renderizadas sob demanda por padrão no modo `server`. No modo `hybrid`, você deve desativar a pré-renderização para cada endpoint personalizado com `export const prerender = false`.

<RecipeLinks slugs={["pt-br/recipes/call-endpoints" ]}/>

:::note
Não se esqueça de [habilitar o modo SSR no seu projeto](/pt-br/guides/server-side-rendering/) antes de testar esses exemplos.
Certifique-se de [habilitar o modo de renderização sob demanda](/pt-br/guides/server-side-rendering/) antes de tentar esses exemplos, e desativar a pré-renderização no modo `hybrid`.
:::

Os endpoints do servidor tem acesso a propriedade `params` sem exportar a função `getStaticPaths` e podem retornar um objeto [`Response`](https://developer.mozilla.org/pt-BR/docs/Web/API/Response), permitindo que você defina códigos de status e cabeçalhos HTTP.
Expand Down Expand Up @@ -147,7 +149,7 @@ export async function GET({ params, request }) {

Além da função `GET`, você pode exportar uma função com o nome de qualquer [método HTTP](https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Methods). Assim, quando uma requisição for recebida, o Astro irá checar o método e chamar a função correspondente.

Também é possível exportar uma função `ALL` para corresponder a todos os métodos que já não tenham suas respectivas funções exportadas. Se houver uma requisição sem método correspondente, ela será redirecionada para a sua [página de 404](/pt-br/basics/astro-pages/#página-customizada-de-erro-404).
Também é possível exportar uma função `ALL` para corresponder a todos os métodos que já não tenham suas respectivas funções exportadas. Se houver uma requisição sem método correspondente, ela será redirecionada para a sua [página de 404](/pt-br/basics/astro-pages/#página-de-erro-404-personalizada).

```ts title="src/pages/methods.json.ts"
export const GET: APIRoute = ({ params, request }) => {
Expand Down
Loading