From 65fd47ffa0077da9760d4ee1d51eeceda4a6dc0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 1 Jul 2026 12:42:52 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20for=20pt?= =?UTF-8?q?=20(add-missing)=20(#15883)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: github-actions[bot] --- docs/pt/docs/tutorial/frontend.md | 133 ++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/pt/docs/tutorial/frontend.md diff --git a/docs/pt/docs/tutorial/frontend.md b/docs/pt/docs/tutorial/frontend.md new file mode 100644 index 0000000000..872c32e9e6 --- /dev/null +++ b/docs/pt/docs/tutorial/frontend.md @@ -0,0 +1,133 @@ +# Frontend { #frontend } + +Você pode servir aplicações frontend estáticas com `app.frontend()` ou `router.frontend()`. + +Isso é útil para ferramentas de frontend que geram arquivos estáticos, como React com Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid e outras. + +Com essas ferramentas, normalmente há uma etapa que faz o build do frontend, com um comando como: + +```bash +npm run build +``` + +Isso geraria um diretório como `./dist/` com seus arquivos de frontend. + +Você pode usar `app.frontend()` para servir esse diretório seguindo as convenções necessárias por esses frameworks de frontend. + +**FastAPI** verifica as *operações de rota* primeiro. Os arquivos de frontend são verificados somente se nenhuma rota normal corresponder, então sua API não será afetada. + +## Sirva um Frontend { #serve-a-frontend } + +Depois de fazer o build do seu frontend, por exemplo com `npm run build`, coloque os arquivos gerados em um diretório, por exemplo, `dist`. + +A estrutura do seu projeto poderia ser assim: + +```text +. +├── pyproject.toml +├── app +│ ├── __init__.py +│ └── main.py +└── dist + ├── index.html + └── assets + └── app.js +``` + +Então sirva-o com `app.frontend()`: + +{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *} + +Com isso, um request para `/assets/app.js` pode servir `dist/assets/app.js`. + +Se você também tiver uma *operação de rota* do **FastAPI**, a *operação de rota* tem prioridade. + +## Roteamento no Lado do Cliente { #client-side-routing } + +Muitas aplicações frontend, incluindo **aplicações de página única** (SPAs), usam roteamento no lado do cliente. Um path como `/dashboard/settings` pode não ser um arquivo real, mas o framework cuidaria de lidar com ele. + +Então, ao acessar essa URL diretamente (em vez de navegar pela aplicação), o backend deveria servir a aplicação frontend a partir de `index.html`, para que o framework de frontend possa então lidar com o roteamento no lado do cliente. + +Para isso, use `fallback="index.html"`: + +{* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} + +**FastAPI** usa esse fallback somente para requests `GET` e `HEAD` que parecem navegação do navegador. Arquivos ausentes como JavaScript, CSS e imagens ainda retornam `404`. + +Requests com outros métodos, como `POST` ou `PUT`, para paths que correspondem apenas ao fallback do frontend também retornam `404`. *Operações de rota* regulares do **FastAPI** ainda têm prioridade maior que rotas de frontend. + +/// tip | Dica + +Por padrão, `fallback` tem o valor `fallback="auto"`. Na maioria dos casos, você não precisará especificar `fallback`. Leia abaixo para detalhes. + +/// + +Isso é o que você desejaria com muitas aplicações frontend que usam roteamento no lado do cliente, por exemplo, React com TanStack Router, Vue, Angular, SvelteKit ou Solid. + +## Página 404 Personalizada { #custom-404-page } + +Você também pode servir uma página estática `404.html` para paths de frontend ausentes: + +{* ../../docs_src/frontend/tutorial003_py310.py hl[5] *} + +Essa response mantém um código de status `404`. + +Neste caso, **FastAPI** não servirá `index.html` para paths de frontend ausentes. Ele retornará o arquivo `404.html` em vez disso. + +/// tip | Dica + +Por padrão, `fallback` tem o valor `fallback="auto"`. Com isso, se um arquivo `404.html` for encontrado, ele será usado automaticamente como fallback. + +Então, normalmente você pode omitir o argumento `fallback`. + +/// + +Isso é útil com ferramentas de frontend que geram arquivos HTML estáticos para cada página, como Astro. + +## Fallback Automático { #fallback-auto } + +Por padrão, `app.frontend()` usa `fallback="auto"`. + +Se houver um arquivo `404.html` no diretório do frontend, paths de frontend ausentes servem esse arquivo com código de status `404`. + +Caso contrário, se houver um arquivo `index.html`, paths de navegação do navegador ausentes servem `index.html`, que é o que muitas aplicações frontend com roteamento no lado do cliente esperam. + +Então, na maioria dos casos, você pode usar `app.frontend("/", directory="dist")` sem especificar o argumento `fallback`. + +{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *} + +## Desative o Fallback { #disable-fallback } + +Se você não quiser servir um arquivo de fallback para paths de frontend ausentes, use `fallback=None`: + +{* ../../docs_src/frontend/tutorial005_py310.py hl[5] *} + +Então paths de frontend ausentes retornam o `404` normal. + +## Verifique o Diretório { #check-directory } + +Por padrão, `app.frontend()` verifica se o diretório existe quando a aplicação é criada. + +Isso ajuda a identificar erros de configuração cedo. Por exemplo, se o diretório de saída do build do frontend estiver ausente, **FastAPI** gerará um erro na inicialização. + +Se seus arquivos de frontend forem criados depois, por exemplo por uma etapa de build separada após o objeto da aplicação ser criado, defina `check_dir=False`: + +{* ../../docs_src/frontend/tutorial006_py310.py hl[5] *} + +Com `check_dir=False`, **FastAPI** não verificará o diretório quando a aplicação for criada. Se o diretório configurado ainda estiver ausente quando um request for processado, **FastAPI** gerará um erro nesse momento. + +## Use com `APIRouter` { #use-it-with-apirouter } + +Você também pode adicionar arquivos de frontend a um `APIRouter` e incluí-lo com um prefixo: + +{* ../../docs_src/frontend/tutorial004_py310.py hl[6,7] *} + +Neste exemplo, os paths de frontend são servidos em `/app`. + +Quaisquer *operações de rota* regulares na aplicação ainda terão precedência, inclusive em outros routers. + +## Apenas Saída de Build Estático { #static-build-output-only } + +`app.frontend()` serve arquivos já gerados pelo build do seu frontend. + +Ele não executa renderização no lado do servidor. Ele é para frameworks de frontend que geram arquivos estáticos, não para frameworks que precisam de renderização dinâmica no servidor para cada request.