Templates¶

uvx library-skills

Vous pouvez utiliser n'importe quel moteur de templates avec FastAPI.

Un choix courant est Jinja2, le même que celui utilisé par Flask et d'autres outils.

Il existe des utilitaires pour le configurer facilement que vous pouvez utiliser directement dans votre application FastAPI (fournis par Starlette).

Installer les dépendances¶

Ajoutez jinja2 à votre projet :

$ uv add jinja2

---> 100%

Utiliser Jinja2Templates¶

• Importez Jinja2Templates.
• Créez un objet templates que vous pourrez réutiliser par la suite.
• Déclarez un paramètre Request dans le chemin d'accès qui renverra un template.
• Utilisez l'objet templates que vous avez créé pour rendre et retourner une TemplateResponse, en transmettant le nom du template, l'objet de requête et un dictionnaire de « context » avec des paires clé-valeur à utiliser dans le template 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}
    )

Écrire des templates¶

Vous pouvez ensuite écrire un template dans templates/item.html, par exemple :

<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>

Valeurs de contexte du template¶

Dans le HTML qui contient :

Item ID: {{ id }}

... il affichera l’id récupéré à partir du dict « context » que vous avez passé :

{"id": id}

Par exemple, avec un ID de 42, cela rendrait :

Item ID: 42

Arguments de url_for dans le template¶

Vous pouvez aussi utiliser url_for() dans le template ; elle prend en paramètres les mêmes arguments que ceux utilisés par votre fonction de chemin d'accès.

Ainsi, la section suivante :

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

... générera un lien vers la même URL que celle gérée par la fonction de chemin d'accès read_item(id=id).

url_for() renvoie une URL absolue, comprenant le schéma et l'hôte, basée sur la requête actuelle.

Par exemple, si votre application est servie à l'adresse https://example.com, avec un ID de 42, cela rendrait :

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

Chemins d'URL dans les templates¶

Pour les liens vers le même site, vous pouvez utiliser l'attribut .path pour obtenir uniquement le chemin de l'URL, par exemple, dans 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>

Passez le nom du template à 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}
    )

Avec le même exemple, le lien vers l'élément donnerait :

<a href="/items/42">

Le / initial rend ce chemin relatif à la racine du site actuel.

L'attribut .path exclut le schéma, l'hôte, les paramètres de requête et le fragment. Utilisez l'URL complète pour les liens vers un autre hôte.

Templates et fichiers statiques¶

Vous pouvez aussi utiliser url_for() dans le template, par exemple avec les StaticFiles que vous avez montés avec 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>

Dans cet exemple, cela créera un lien vers un fichier CSS static/styles.css avec :

h1 {
    color: green;
}

Et comme vous utilisez StaticFiles, ce fichier CSS est servi automatiquement par votre application FastAPI à l’URL /static/styles.css.

En savoir plus¶

Pour plus de détails, y compris sur la façon de tester des templates, consultez les documents de Starlette sur les templates.