Données de formulaire¶
AI coding agents
Use the official FastAPI skill for your installed version. Install it from your project directory:
uvx library-skills
See Develop with AI.
🌐 Traduction par IA et humains
Cette traduction a été réalisée par une IA guidée par des humains. 🤝
Elle peut contenir des erreurs d'interprétation du sens original, ou paraître peu naturelle, etc. 🤖
Vous pouvez améliorer cette traduction en nous aidant à mieux guider le LLM d'IA.
Lorsque vous devez recevoir des champs de formulaire au lieu de JSON, vous pouvez utiliser Form.
Remarque
Pour utiliser les formulaires, installez d'abord python-multipart.
Ajoutez-le à votre projet :
$ uv add python-multipart
Importer Form¶
Importez Form depuis fastapi :
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
Définir les paramètres Form¶
Créez des paramètres de formulaire comme vous le feriez pour Body ou Query :
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
Par exemple, dans l'une des manières dont la spécification OAuth2 peut être utilisée (appelée « password flow »), il est requis d'envoyer un username et un password comme champs de formulaire.
La spécification exige que les champs soient exactement nommés username et password, et qu'ils soient envoyés en tant que champs de formulaire, pas en JSON.
Avec Form, vous pouvez déclarer les mêmes configurations que pour Body (ainsi que Query, Path, Cookie), y compris la validation, des exemples, un alias (p. ex. user-name au lieu de username), etc.
Remarque
Form est une classe qui hérite directement de Body.
Astuce
Pour déclarer des corps de formulaire, vous devez utiliser Form explicitement, car sinon les paramètres seraient interprétés comme des paramètres de requête ou des paramètres de corps (JSON).
Champs de formulaire booléens¶
Les navigateurs omettent les cases à cocher non cochées lors de l'envoi des formulaires HTML. Déclarez un paramètre de formulaire booléen avec une valeur par défaut de False pour recevoir False lorsque la case n'est pas cochée :
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/preferences/")
async def update_preferences(subscribe: Annotated[bool, Form()] = False):
return {"subscribe": subscribe}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/preferences/")
async def update_preferences(subscribe: bool = Form(default=False)):
return {"subscribe": subscribe}
Une case cochée envoie sa valeur, qui est par défaut "on". FastAPI accepte "on" comme True.
À propos des « champs de formulaire »¶
La manière dont les formulaires HTML (<form></form>) envoient les données au serveur utilise normalement un encodage « spécial » pour ces données, différent de JSON.
FastAPI s'assure de lire ces données au bon endroit au lieu de JSON.
Détails techniques
Les données issues des formulaires sont normalement encodées avec le « type de média » application/x-www-form-urlencoded.
Mais lorsque le formulaire inclut des fichiers, il est encodé en multipart/form-data. Vous lirez la gestion des fichiers dans le chapitre suivant.
Vous pouvez utiliser Form(media_type="multipart/form-data") pour décrire un formulaire multipart dans OpenAPI. Le définir sur un seul paramètre suffit lorsque vous combinez des paramètres ou des modèles de formulaire.
Si vous voulez en savoir plus sur ces encodages et les champs de formulaire, consultez les documents web de la MDN pour POST.
Alertes
Vous pouvez déclarer plusieurs paramètres Form dans un chemin d'accès, mais vous ne pouvez pas aussi déclarer des champs Body que vous vous attendez à recevoir en JSON, car la requête aura le corps encodé en application/x-www-form-urlencoded au lieu de application/json.
Ce n'est pas une limitation de FastAPI, cela fait partie du protocole HTTP.
Récapitulatif¶
Utilisez Form pour déclarer les paramètres d'entrée des données de formulaire.