Templates¶

uvx library-skills

Você pode usar qualquer template engine com o FastAPI.

Uma escolha comum é o Jinja2, o mesmo usado pelo Flask e outras ferramentas.

Existem utilitários para configurá-lo facilmente que você pode usar diretamente em sua aplicação FastAPI (fornecidos pelo Starlette).

Instale dependências¶

Adicione jinja2 ao seu projeto:

$ uv add jinja2

---> 100%

Usando Jinja2Templates¶

• Importe Jinja2Templates.
• Crie um objeto templates que você possa reutilizar posteriormente.
• Declare um parâmetro Request na operação de rota que retornará um template.
• Use o templates que você criou para renderizar e retornar uma TemplateResponse, passe o nome do template, o objeto request e um dicionário "context" com pares chave-valor a serem usados dentro do template do Jinja2.

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

app = FastAPI()

app.mount("/static", StaticFiles(directory="static"), name="static")


templates = Jinja2Templates(directory="templates")


@app.get("/items/{id}", response_class=HTMLResponse)
async def read_item(request: Request, id: str):
    return templates.TemplateResponse(
        request=request, name="item.html", context={"id": id}
    )

Escrevendo templates¶

Então você pode escrever um template em templates/item.html com, por exemplo:

<html>
<head>
    <title>Item Details</title>
    <link href="{{ url_for('static', path='/styles.css') }}" rel="stylesheet">
</head>
<body>
    <h1><a href="{{ url_for('read_item', id=id) }}">Item ID: {{ id }}</a></h1>
</body>
</html>

Valores de contexto do template¶

No código HTML que contém:

Item ID: {{ id }}

...aparecerá o id obtido do "context" dict que você passou:

{"id": id}

Por exemplo, com um ID de 42, isso renderizará:

Item ID: 42

Argumentos do url_for no template¶

Você também pode usar url_for() dentro do template, ele recebe como argumentos os mesmos argumentos que seriam usados pela sua função de operação de rota.

Logo, a seção com:

<a href="{{ url_for('read_item', id=id) }}">

...irá gerar um link para a mesma URL que será tratada pela função de operação de rota read_item(id=id).

url_for() retorna uma URL absoluta, incluindo o esquema e o host, com base no request atual.

Por exemplo, se sua aplicação for servida em https://example.com, com um ID de 42, isso renderizará:

<a href="https://example.com/items/42">

Paths de URL em templates¶

Para links para o mesmo site, você pode usar o atributo .path para obter apenas o path da URL, por exemplo, em templates/item_path.html:

<html>
<head>
    <title>Item Details</title>
    <link href="{{ url_for('static', path='/styles.css').path }}" rel="stylesheet">
</head>
<body>
    <h1><a href="{{ url_for('read_item', id=id).path }}">Item ID: {{ id }}</a></h1>
</body>
</html>

Passe o nome do template para TemplateResponse:

# Code above omitted 👆

@app.get("/items/{id}", response_class=HTMLResponse)
async def read_item(request: Request, id: str):
    return templates.TemplateResponse(
        request=request, name="item_path.html", context={"id": id}
    )

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

app = FastAPI()

app.mount("/static", StaticFiles(directory="static"), name="static")


templates = Jinja2Templates(directory="templates")


@app.get("/items/{id}", response_class=HTMLResponse)
async def read_item(request: Request, id: str):
    return templates.TemplateResponse(
        request=request, name="item_path.html", context={"id": id}
    )

Com o mesmo exemplo, o link do item seria renderizado assim:

<a href="/items/42">

A / inicial torna esse path relativo à raiz do site atual.

O atributo .path exclui o esquema, o host, os parâmetros de consulta e o fragmento. Use a URL completa para links para outro host.

Templates e arquivos estáticos¶

Você também pode usar url_for() dentro do template e usá-lo, por exemplo, com o StaticFiles que você montou com o name="static".

<html>
<head>
    <title>Item Details</title>
    <link href="{{ url_for('static', path='/styles.css') }}" rel="stylesheet">
</head>
<body>
    <h1><a href="{{ url_for('read_item', id=id) }}">Item ID: {{ id }}</a></h1>
</body>
</html>

Neste exemplo, ele seria vinculado a um arquivo CSS em static/styles.css com:

h1 {
    color: green;
}

E como você está usando StaticFiles, este arquivo CSS será automaticamente servido pela sua aplicação FastAPI na URL /static/styles.css.

Mais detalhes¶

Para obter mais detalhes, incluindo como testar templates, consulte a documentação da Starlette sobre templates.