diff --git a/docs/zh/docs/tutorial/request-forms.md b/docs/zh/docs/tutorial/request-forms.md new file mode 100644 index 000000000..0840c9274 --- /dev/null +++ b/docs/zh/docs/tutorial/request-forms.md @@ -0,0 +1,63 @@ +# 表单数据 + +接收的不是 JSON,而是表单字段时,要使用 `Form`。 + +!!! info "说明" + + 要使用表单,需预先安装 `python-multipart`。 + + 例如,`pip install python-multipart`。 + +## 导入 `Form` + +从 `fastapi` 导入 `Form`: + +```Python hl_lines="1" +{!../../../docs_src/request_forms/tutorial001.py!} +``` + +## 定义 `Form` 参数 + +创建表单(`Form`)参数的方式与 `Body` 和 `Query` 一样: + +```Python hl_lines="7" +{!../../../docs_src/request_forms/tutorial001.py!} +``` + +例如,OAuth2 规范的 "密码流" 模式规定要通过表单字段发送 `username` 和 `password`。 + +该规范要求字段必须命名为 `username` 和 `password`,并通过表单字段发送,不能用 JSON。 + +使用 `Form` 可以声明与 `Body` (及 `Query`、`Path`、`Cookie`)相同的元数据和验证。 + +!!! info "说明" + + `Form` 是直接继承自 `Body` 的类。 + +!!! tip "提示" + + 声明表单体要显式使用 `Form` ,否则,FastAPI 会把该参数当作查询参数或请求体(JSON)参数。 + +## 关于 "表单字段" + +与 JSON 不同,HTML 表单(`
`)向服务器发送数据通常使用「特殊」的编码。 + +**FastAPI** 要确保从正确的位置读取数据,而不是读取 JSON。 + +!!! note "技术细节" + + 表单数据的「媒体类型」编码一般为 `application/x-www-form-urlencoded`。 + + 但包含文件的表单编码为 `multipart/form-data`。文件处理详见下节。 + + 编码和表单字段详见 MDN Web 文档的POST
小节。
+
+!!! warning "警告"
+
+ 可在一个*路径操作*中声明多个 `Form` 参数,但不能同时声明要接收 JSON 的 `Body` 字段。因为此时请求体的编码是 `application/x-www-form-urlencoded`,不是 `application/json`。
+
+ 这不是 **FastAPI** 的问题,而是 HTTP 协议的规定。
+
+## 小结
+
+本节介绍了如何使用 `Form` 声明表单数据输入参数。
\ No newline at end of file
diff --git a/docs/zh/mkdocs.yml b/docs/zh/mkdocs.yml
index f63f341f0..1bceab212 100644
--- a/docs/zh/mkdocs.yml
+++ b/docs/zh/mkdocs.yml
@@ -73,6 +73,7 @@ nav:
- tutorial/schema-extra-example.md
- tutorial/extra-data-types.md
- tutorial/cookie-params.md
+ - tutorial/request-forms.md
- tutorial/request-files.md
- tutorial/body-updates.md
- 安全性: