GET 和 POST¶

GET 和 POST 是處理表單時唯一要使用的 HTTP 方法。

Django 的登入表單是使用 POST 方法傳回的，其中瀏覽器會將表單資料捆綁起來，進行傳輸編碼，傳送到伺服器，然後接收回其回應。

相較之下，GET 會將提交的資料捆綁到字串中，並以此來組成 URL。URL 包含必須傳送資料的地址，以及資料的索引鍵和值。如果您在 Django 文件中執行搜尋，您可以看到實際運作情況，這將產生格式為 https://django-docs.dev.org.tw/search/?q=forms&release=1 的 URL。

GET 和 POST 通常用於不同的目的。

任何可用於變更系統狀態的請求（例如，在資料庫中進行變更的請求）都應使用 POST。GET 僅應用於不影響系統狀態的請求。

GET 也不適用於密碼表單，因為密碼會出現在 URL 中，因此也會以純文字形式出現在瀏覽器歷史記錄和伺服器記錄中。它也不適用於大量資料或二進位資料（例如圖像）。將 GET 請求用於管理表單的 Web 應用程式是一種安全風險：攻擊者可以很容易地模仿表單的請求，以取得對系統敏感部分的存取權。POST 與其他保護機制（例如 Django 的CSRF 保護）搭配使用，可提供對存取權的更多控制。

另一方面，GET 適用於 Web 搜尋表單等項目，因為代表 GET 請求的 URL 可以很容易地加入書籤、共用或重新提交。

Django Form 類別¶

此元件系統的核心是 Django 的 Form 類別。就像 Django 模型描述物件的邏輯結構、其行為以及其各部分向我們呈現的方式一樣，Form 類別描述表單，並決定其運作方式和外觀。

與模型類別的欄位對應於資料庫欄位的方式類似，表單類別的欄位對應於 HTML 表單 <input> 元素。（ModelForm透過 Form 將模型類別的欄位對應至 HTML 表單 <input> 元素；這就是 Django 管理介面所基於的。）

表單的欄位本身就是類別；它們管理表單資料並在提交表單時執行驗證。DateField 和 FileField 處理非常不同類型的資料，並且必須對其執行不同的操作。

表單欄位在瀏覽器中以 HTML「小工具」（使用者介面機制）的形式呈現給使用者。每個欄位類型都有一個適當的預設Widget 類別，但是可以根據需要覆寫這些類別。

表單的實例化、處理和呈現¶

在 Django 中呈現一個物件時，我們通常會：

1. 在視圖中取得它（例如，從資料庫獲取）。

2. 將它傳遞給模板上下文。

3. 使用模板變數將其展開為 HTML 標記。

在模板中呈現表單所涉及的工作與呈現任何其他類型的物件幾乎相同，但有一些關鍵差異。

如果模型實例不包含任何資料，在模板中使用它幾乎沒有任何用處。另一方面，呈現一個未填寫的表單是很有意義的，這就是我們希望使用者填寫表單時的做法。

因此，當我們在視圖中處理模型實例時，通常會從資料庫中檢索它。當我們處理表單時，通常會在視圖中實例化它。

當我們實例化表單時，我們可以選擇將其留空或預先填寫，例如：

• 來自已儲存模型實例的資料（如用於編輯的管理表單）。

• 我們從其他來源收集的資料。

• 從先前的 HTML 表單提交接收的資料。

最後一種情況最有趣，因為它讓使用者不僅可以閱讀網站，還可以將資訊傳送回網站。

需要完成的工作¶

假設您想在您的網站上建立一個簡單的表單，以獲取使用者的姓名。您需要在模板中包含類似以下的內容：

<form action="/your-name/" method="post">
    <label for="your_name">Your name: </label>
    <input id="your_name" type="text" name="your_name" value="{{ current_name }}">
    <input type="submit" value="OK">
</form>

這會告知瀏覽器使用 POST 方法將表單資料傳回至 URL /your-name/。它將顯示一個標示為「你的姓名：」的文字欄位和一個標示為「確定」的按鈕。如果模板上下文包含 current_name 變數，則會使用該變數預先填寫 your_name 欄位。

您需要一個視圖來呈現包含 HTML 表單的模板，並且可以視情況提供 current_name 欄位。

當表單提交時，傳送到伺服器的 POST 請求將包含表單資料。

現在您還需要一個對應於 /your-name/ URL 的視圖，該視圖會在請求中找到適當的鍵/值對，然後處理它們。

這是一個非常簡單的表單。在實務上，表單可能包含數十個或數百個欄位，其中許多欄位可能需要預先填寫，並且我們可能期望使用者在完成操作之前多次完成編輯-提交週期。

我們可能需要一些驗證在瀏覽器中進行，甚至在提交表單之前；我們可能希望使用更複雜的欄位，讓使用者可以執行諸如從日曆中選擇日期等操作。

在這一點上，讓 Django 為我們完成大部分工作會容易得多。

在 Django 中建立表單¶

from django import forms


class NameForm(forms.Form):
    your_name = forms.CharField(label="Your name", max_length=100)

<label for="your_name">Your name: </label>
<input id="your_name" type="text" name="your_name" maxlength="100" required>

from django.http import HttpResponseRedirect
from django.shortcuts import render

from .forms import NameForm


def get_name(request):
    # if this is a POST request we need to process the form data
    if request.method == "POST":
        # create a form instance and populate it with data from the request:
        form = NameForm(request.POST)
        # check whether it's valid:
        if form.is_valid():
            # process the data in form.cleaned_data as required
            # ...
            # redirect to a new URL:
            return HttpResponseRedirect("/thanks/")

    # if a GET (or any other method) we'll create a blank form
    else:
        form = NameForm()

    return render(request, "name.html", {"form": form})

<form action="/your-name/" method="post">
    {% csrf_token %}
    {{ form }}
    <input type="submit" value="Submit">
</form>

綁定和未綁定的表單實例¶

綁定和未綁定的表單之間的區別非常重要。

• 未綁定的表單沒有關聯的資料。當渲染給使用者時，它將是空的或包含預設值。

• 綁定的表單有已提交的資料，因此可以用於判斷該資料是否有效。如果渲染了無效的綁定表單，它可以包含內嵌錯誤訊息，告知使用者要更正哪些資料。

表單的 is_bound 屬性會告訴您表單是否已綁定資料。

更多關於欄位的資訊¶

考慮一個比我們上面的最小範例更有用的表單，我們可以利用它在個人網站上實作「聯絡我」的功能。

from django import forms


class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    message = forms.CharField(widget=forms.Textarea)
    sender = forms.EmailField()
    cc_myself = forms.BooleanField(required=False)

我們之前的表單使用單一欄位 your_name，這是一個 CharField。在這個例子中，我們的表單有四個欄位：subject、message、sender 和 cc_myself。CharField、EmailField 和 BooleanField 只是可用的欄位類型中的三個；完整的列表可以在 表單欄位 中找到。

from django.core.mail import send_mail

if form.is_valid():
    subject = form.cleaned_data["subject"]
    message = form.cleaned_data["message"]
    sender = form.cleaned_data["sender"]
    cc_myself = form.cleaned_data["cc_myself"]

    recipients = ["info@example.com"]
    if cc_myself:
        recipients.append(sender)

    send_mail(subject, message, sender, recipients)
    return HttpResponseRedirect("/thanks/")

可重複使用的表單模板¶

渲染表單時的 HTML 輸出本身是透過模板產生的。您可以透過建立適當的模板檔案並設定自訂的 FORM_RENDERER 來控制它，以在整個網站範圍內使用該 form_template_name。您也可以透過覆蓋表單的 template_name 屬性來為每個表單自訂，以使用自訂模板渲染表單，或將模板名稱直接傳遞給 Form.render()。

下面的範例將導致 {{ form }} 被渲染為 form_snippet.html 模板的輸出。

在您的模板中

# In your template:
{{ form }}

# In form_snippet.html:
{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

然後您可以設定 FORM_RENDERER 設定

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    form_template_name = "form_snippet.html"


FORM_RENDERER = "project.settings.CustomFormRenderer"

… 或對於單一表單

class MyForm(forms.Form):
    template_name = "form_snippet.html"
    ...

… 或對於表單實例的單一渲染，將模板名稱傳遞給 Form.render()。以下是此方法在視圖中使用的範例

def index(request):
    form = MyForm()
    rendered_form = form.render("form_snippet.html")
    context = {"form": rendered_form}
    return render(request, "index.html", context)

請參閱 將表單輸出為 HTML 以取得更多詳細資訊。

可重複使用的欄位組模板¶

每個欄位都可作為表單的屬性使用，在範本中使用 {{ form.欄位名稱 }}。欄位有一個 as_field_group() 方法，它會將欄位的相關元素（如標籤、小工具、錯誤和輔助文字）渲染為一個群組。

這允許編寫通用的範本，以所需的佈局排列欄位元素。例如：

{{ form.non_field_errors }}
<div class="fieldWrapper">
  {{ form.subject.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.message.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.sender.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.cc_myself.as_field_group }}
</div>

預設情況下，Django 使用 "django/forms/field.html" 範本，該範本設計用於預設的 "django/forms/div.html" 表單樣式。

可以透過在專案層級的 FORM_RENDERER 中設定 field_template_name 來客製化預設範本。

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    field_template_name = "field_snippet.html"

... 或在單個欄位上進行設定：

class MyForm(forms.Form):
    subject = forms.CharField(template_name="my_custom_template.html")
    ...

... 或者透過呼叫 BoundField.render() 並提供範本名稱，在每個請求的基礎上進行設定：

def index(request):
    form = ContactForm()
    subject = form["subject"]
    context = {"subject": subject.render("my_custom_template.html")}
    return render(request, "index.html", context)

手動渲染欄位¶

也可以更精細地控制欄位的渲染。這通常會在自訂欄位範本中完成，以便範本可以編寫一次並重複用於每個欄位。但是，也可以直接從表單上的欄位屬性進行存取。例如：

{{ form.non_field_errors }}
<div class="fieldWrapper">
    {{ form.subject.errors }}
    <label for="{{ form.subject.id_for_label }}">Email subject:</label>
    {{ form.subject }}
</div>
<div class="fieldWrapper">
    {{ form.message.errors }}
    <label for="{{ form.message.id_for_label }}">Your message:</label>
    {{ form.message }}
</div>
<div class="fieldWrapper">
    {{ form.sender.errors }}
    <label for="{{ form.sender.id_for_label }}">Your email address:</label>
    {{ form.sender }}
</div>
<div class="fieldWrapper">
    {{ form.cc_myself.errors }}
    <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>
    {{ form.cc_myself }}
</div>

完整的 <label> 元素也可以使用 label_tag() 產生。例如：

<div class="fieldWrapper">
    {{ form.subject.errors }}
    {{ form.subject.label_tag }}
    {{ form.subject }}
</div>

<ul class="errorlist">
    <li>Sender is required.</li>
</ul>

{% if form.subject.errors %}
    <ol>
    {% for error in form.subject.errors %}
        <li><strong>{{ error|escape }}</strong></li>
    {% endfor %}
    </ol>
{% endif %}

<ul class="errorlist nonfield">
    <li>Generic validation error</li>
</ul>

迴圈遍歷表單的欄位¶

如果您為每個表單欄位使用相同的 HTML，可以使用 {% for %} 迴圈來依序迴圈遍歷每個欄位，以減少重複的程式碼：

{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
        {% if field.help_text %}
          <p class="help" id="{{ field.auto_id }}_helptext">
            {{ field.help_text|safe }}
          </p>
        {% endif %}
    </div>
{% endfor %}

{{ field }} 上有用的屬性包括：

{{ field.errors }}

輸出一個 <ul class="errorlist">，其中包含與此欄位對應的任何驗證錯誤。您可以使用 {% for error in field.errors %} 迴圈來自訂錯誤的呈現方式。在這種情況下，迴圈中的每個物件都是一個包含錯誤訊息的字串。

{{ field.field }}

此 BoundField 包裝的表單類別中的 Field 實例。您可以使用它來存取 Field 屬性，例如 {{ char_field.field.max_length }}。

{{ field.help_text }}

已與欄位關聯的任何輔助文字。

{{ field.html_name }}

將在輸入元素的 name 欄位中使用的欄位名稱。如果已設定，這會將表單前綴納入考量。

{{ field.id_for_label }}

將用於此欄位的 ID（在上面的範例中為 id_email）。如果您要手動建構標籤，您可能想使用它來代替 label_tag。例如，如果您有一些內嵌 JavaScript 並且想避免硬式編碼欄位的 ID，這也很有用。

{{ field.is_hidden }}

如果表單欄位是隱藏欄位，則此屬性為 True，否則為 False。作為範本變數，它並不是特別有用，但在條件測試中可能很有用，例如：

{% if field.is_hidden %}
   {# Do something special #}
{% endif %}

{{ field.label }}

欄位的標籤，例如 Email address。

{{ field.label_tag }}

用適當的 HTML <label> 標籤包裝的欄位標籤。這包含表單的 label_suffix。例如，預設的 label_suffix 是冒號：

<label for="id_email">Email address:</label>

{{ field.legend_tag }}

與 field.label_tag 類似，但使用 <legend> 標籤代替 <label>，適用於以 <fieldset> 包裝的多個輸入的小工具。

{{ field.use_fieldset }}

如果表單欄位的小工具包含多個應在語義上分組到 <fieldset> 中並帶有 <legend> 以提高輔助功能，則此屬性為 True。在範本中的範例用法：

{% if field.use_fieldset %}
  <fieldset>
  {% if field.label %}{{ field.legend_tag }}{% endif %}
{% else %}
  {% if field.label %}{{ field.label_tag }}{% endif %}
{% endif %}
{{ field }}
{% if field.use_fieldset %}</fieldset>{% endif %}

{{ field.value }}

欄位的值。例如 someone@example.com。

{# Include the hidden fields #}
{% for hidden in form.hidden_fields %}
{{ hidden }}
{% endfor %}
{# Include the visible fields #}
{% for field in form.visible_fields %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}