Руководство по полям формы Django: Types и Usage

Некоторые распространенные поля формы в Django включают:

• CharField: для ввода коротких текстовых строк
• IntegerField: для ввода целых чисел
• DateField: для ввода дат
• BooleanField: для ввода логических значений (например, флажков)
• ChoiceField: для выбора опции из списка вариантов.

Чтобы использовать поля формы в форме Django, вы обычно определяете их как атрибуты класса формы. Например, простая форма, запрашивающая имя пользователя и адрес электронной почты, может выглядеть так:

from django import forms
 
class ContactForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()

Эта форма имеет два поля: CharField для имени пользователя и EmailField для его адреса электронной почты. Определив поля формы, вы можете отображать их в шаблоне с помощью {{ form }} тега шаблона или путем перебора полей формы и отображения их по отдельности.

Аргументы основного поля

В Django аргументы основного поля используются для настройки полей формы и определения их поведения. Некоторые распространенные аргументы основного поля включают в себя:

• required: логическое значение, указывающее, является ли поле обязательным (по умолчанию — True).
• label: удобочитаемое имя поля, которое будет отображаться в форме (по умолчанию используется имя поля с символами подчеркивания, замененными пробелами).
• initial: начальное значение поля при первом отображении формы (по умолчанию — None).
• help_text: дополнительный текст, отображаемый рядом с полем для предоставления рекомендаций или контекста (по умолчанию — '').
• widget: объект виджета формы, который определяет, как поле отображается в форме (по умолчанию используется виджет, соответствующий типу поля)
• validators: список функций проверки, проверяющих значение поля (по умолчанию — []).
• error_messages: словарь сообщений об ошибках, который будет отображаться, если поле не прошло проверку (по умолчанию используется набор встроенных сообщений об ошибках).

Поля формы:BooleanField

В Django — BooleanField это встроенный класс поля формы, который представляет логическое значение (True/False). Он часто используется для обозначения вопроса «да/нет» или ввода флажка.

Класс BooleanFieldимеет несколько необязательных аргументов, которые можно использовать для настройки его поведения, в том числе:

• required: логическое значение, указывающее, является ли поле обязательным (по умолчанию — True).
• label: удобочитаемое имя поля, которое будет отображаться в форме (по умолчанию используется имя поля с символами подчеркивания, замененными пробелами).
• initial: начальное значение поля при первом отображении формы (по умолчанию — False).
• help_text: дополнительный текст, отображаемый рядом с полем для предоставления рекомендаций или контекста (по умолчанию — '').
• disabled: логическое значение, указывающее, отключено ли поле (по умолчанию — False).
• widget: объект виджета формы, который определяет, как поле отображается в форме (по умолчанию — виджет флажка)

Вот пример использования BooleanField в форме Django:

# forms.py
from django import forms
 
class NewsletterForm(forms.Form):
    email = forms.EmailField(label='Your email')
    subscribe = forms.BooleanField(label='Subscribe to newsletter', required=False, initial=True)
 
# newsletter.html
<form method="post">
  {% csrf_token %}
  <label for="{{ form.email.id_for_label }}">Your email:</label>
  {{ form.email }}
  <label for="{{ form.subscribe.id_for_label }}">{{ form.subscribe.label }}</label>
  {{ form.subscribe }}
  <button type="submit">Submit</button>
</form>

В этом примере NewsletterForm определен в forms.py. В шаблоне newsletter.html мы используем form объект для отображения полей. Мы используем label атрибут subscribe для отображения метки флажка.

Когда форма будет отправлена, Django автоматически проверит поля и создаст словарь cleaned_data, содержащий очищенные и проверенные данные формы. В этом случае в cleaned_data словаре будет запись для subscribe поля с логическим значением, которое показывает, установлен ли флажок или нет.

Поле CharField

В Django — CharField это встроенный класс поля формы, который представляет поле ввода текста, которое может содержать строку символов. Он часто используется для представления таких полей, как имена, адреса и описания.

Класс CharField имеет несколько необязательных аргументов, которые можно использовать для настройки его поведения, в том числе:

• max_length: максимальное количество символов, разрешенное в поле (обязательный аргумент)
• min_length: минимальное количество символов, разрешенное в поле (по умолчанию — None).
• strip: логическое значение, указывающее, следует ли удалять начальные и конечные пробелы из входных данных (по умолчанию — True).
• empty_value: значение, используемое для пустых входных данных, по умолчанию — пустая строка.''
• label: удобочитаемое имя поля, которое будет отображаться в форме (по умолчанию используется имя поля с символами подчеркивания, замененными пробелами).
• initial: начальное значение поля при первом отображении формы (по умолчанию — '').
• help_text: дополнительный текст, отображаемый рядом с полем для предоставления рекомендаций или контекста (по умолчанию — '').
• disabled: логическое значение, указывающее, отключено ли поле (по умолчанию — False).
• widget: объект виджета формы, который определяет, как поле отображается в форме (по умолчанию — виджет ввода текста)

# forms.py
from django import forms
 
class ContactForm(forms.Form):
    name = forms.CharField(label='Your name', max_length=100)
    email = forms.EmailField(label='Your email')
    message = forms.CharField(label='Your message', widget=forms.Textarea)
 
# contact.html
<form method="post">
  {% csrf_token %}
  <label for="{{ form.name.id_for_label }}">Your name:</label>
  {{ form.name }}
  <label for="{{ form.email.id_for_label }}">Your email:</label>
  {{ form.email }}
  <label for="{{ form.message.id_for_label }}">Your message:</label>
  {{ form.message }}
  <button type="submit">Submit</button>
</form>

В этом примере ContactForm определен в forms.py. В шаблоне contact.html мы используем form объект для отображения полей. Мы используем label атрибут каждого поля для отображения метки для каждого поля ввода текста, а также атрибут widget поля message для отображения большей области ввода текста.

Когда форма будет отправлена, Django автоматически проверит поля и создаст словарь cleaned_data, содержащий очищенные и проверенные данные формы. В этом случае cleaned_dataсловарь будет содержать записи для полей name, emailи messageс соответствующими значениями ввода текста.

Поле ChoiceField

В Django — ChoiceField это встроенный класс поля формы, который представляет собой раскрывающееся меню, содержащее набор предопределенных вариантов выбора. Он часто используется для представления таких полей, как страна, пол или возрастной диапазон, где существует фиксированный набор возможных вариантов выбора.

Класс ChoiceField принимает choices аргумент, определяющий доступные варианты. Аргумент choices может принимать несколько различных форм, включая список двух кортежей, список строк или словарь. Каждый кортеж или строка представляет собой один вариант выбора и должен иметь уникальное значение, которое будет отправлено при отправке формы, а также удобочитаемую метку, которая будет отображаться в раскрывающемся меню.

Вот пример того, как ChoiceField можно использовать в форме и модели Django и как его можно отобразить с помощью формы HTML:

from django.db import models
 
class Person(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField()
    gender = models.CharField(max_length=1, choices=(
        ('M', 'Male'),
        ('F', 'Female'),
        ('O', 'Other'),
    ))
    age = models.IntegerField()
 
 
from django import forms
from .models import Person
 
class PersonForm(forms.ModelForm):
    GENDER_CHOICES = (
        ('M', 'Male'),
        ('F', 'Female'),
        ('O', 'Other'),
    )
    gender = forms.ChoiceField(choices=GENDER_CHOICES)
 
    class Meta:
        model = Person
        fields = ('name', 'email', 'gender', 'age')
 
 
<form method="post">
  {% csrf_token %}
  <label for="{{ form.name.id_for_label }}">Name:</label>
  {{ form.name }}
  <label for="{{ form.email.id_for_label }}">Email:</label>
  {{ form.email }}
  <label for="{{ form.gender.id_for_label }}">Gender:</label>
  {{ form.gender }}
  <label for="{{ form.age.id_for_label }}">Age:</label>
  {{ form.age }}
  <button type="submit">Submit</button>
</form>

В этом примере класс PersonForm расширяется ModelForm и включает поле ChoiceField for gender.

Модель Person также включает gender поле с вариантами выбора, и gender поле в форме связано с этим полем в модели.

В форме HTML каждое поле отображается с использованием синтаксиса {{ form.<fieldname> }}, а метки добавляются с помощью label тега. Поле gender отображается в виде раскрывающегося меню, содержащего доступные варианты выбора.

Когда форма будет отправлена, Django автоматически проверит данные формы и создаст новый Person объект с отправленными данными. Поле gender будет сохранено в базе данных как один символ, соответствующий выбранному значению в раскрывающемся меню.

Поле DateField

В Django — DateField это встроенный класс поля формы, представляющий дату (год, месяц и день). Он часто используется для представления таких полей, как дата рождения, дата начала или дата окончания.

Класс DateField принимает несколько необязательных аргументов, таких как widget, input_formatsи initial. Аргумент widget определяет виджет ввода HTML, который будет использоваться для поля формы. По умолчанию он использует DateInput виджет, который предоставляет стандартное поле ввода даты HTML5. Аргумент input_formats можно использовать для указания списка форматов, в которых можно вводить дату, а аргумент initial можно использовать для указания начального значения для поля.

Вот пример того, как DateField можно использовать в форме и модели Django и как его можно отобразить с помощью формы HTML:

from django.db import models
 
class Event(models.Model):
    name = models.CharField(max_length=100)
    start_date = models.DateField()
    end_date = models.DateField()
 
from django import forms
from .models import Event
 
class EventForm(forms.ModelForm):
    start_date = forms.DateField(widget=forms.DateInput(attrs={'type': 'date'}))
    end_date = forms.DateField(widget=forms.DateInput(attrs={'type': 'date'}))
 
    class Meta:
        model = Event
        fields = ('name', 'start_date', 'end_date')
 
 
<form method="post">
  {% csrf_token %}
  <label for="{{ form.name.id_for_label }}">Name:</label>
  {{ form.name }}
  <label for="{{ form.start_date.id_for_label }}">Start date:</label>
  {{ form.start_date }}
  <label for="{{ form.end_date.id_for_label }}">End date:</label>
  {{ form.end_date }}
  <button type="submit">Submit</button>
</form>

В этом примере класс EventForm расширяется ModelForm и включает DateField объекты для полей start_date и end_date. Модель Event также включает поля start_date и end_date, которые сопоставлены с этими полями формы.

В форме HTML каждое поле отображается с использованием синтаксиса {{ form.<fieldname> }}, а метки добавляются с помощью label тега. Поля start_dateи end_dateотображаются как поля ввода даты с виджетом календаря для выбора даты.

Когда форма будет отправлена, Django автоматически проверит данные формы и создаст новый Event объект с отправленными данными. Поля start_date и end_dateбудут храниться в базе данных как date объекты.

Поле DateTimeField

В Django — DateTimeField это встроенный класс поля формы, представляющий дату и время. Он часто используется для представления таких полей, как дата и время события, дата и время записи журнала или дата и время сообщения.

Класс DateTimeField принимает несколько необязательных аргументов, таких как widget, input_formats и initial. Аргумент widget определяет виджет ввода HTML, который будет использоваться для поля формы. По умолчанию он использует DateTimeInput виджет, который предоставляет стандартное поле ввода даты и времени HTML5. Аргумент input_formats можно использовать для указания списка форматов, в которых можно вводить дату и время, а аргумент initial можно использовать для указания начального значения для поля.

Вот пример того, как DateTimeField можно использовать в форме и модели Django и как его можно отобразить с помощью формы HTML:

from django.db import models
 
class Event(models.Model):
    name = models.CharField(max_length=100)
    start_datetime = models.DateTimeField()
    end_datetime = models.DateTimeField()
 
from django import forms
from .models import Event
 
class EventForm(forms.ModelForm):
    start_datetime = forms.DateTimeField(widget=forms.DateTimeInput(attrs={'type': 'datetime-local'}))
    end_datetime = forms.DateTimeField(widget=forms.DateTimeInput(attrs={'type': 'datetime-local'}))
 
    class Meta:
        model = Event
        fields = ('name', 'start_datetime', 'end_datetime')
 
 
<form method="post">
  {% csrf_token %}
  <label for="{{ form.name.id_for_label }}">Name:</label>
  {{ form.name }}
  <label for="{{ form.start_datetime.id_for_label }}">Start date and time:</label>
  {{ form.start_datetime }}
  <label for="{{ form.end_datetime.id_for_label }}">End date and time:</label>
  {{ form.end_datetime }}
  <button type="submit">Submit</button>
</form>

В этом примере класс EventForm расширяется ModelForm и включает DateTimeFieldобъекты для полей start_datetimeи end_datetime. Модель Event также включает поля start_datetime и end_datetime, которые сопоставлены с этими полями формы.

В форме HTML каждое поле отображается с использованием синтаксиса {{ form.<fieldname> }}, а метки добавляются с помощью label тега. Поля start_datetime и end_datetime отображаются как локальные поля ввода даты и времени с виджетом календаря для выбора даты и виджетом раскрывающегося списка для выбора времени.

Когда форма будет отправлена, Django автоматически проверит данные формы и создаст новый Event объект с отправленными данными. Поля start_datetime и end_datetimeбудут храниться в базе данных как datetime объекты.

Поле DecimalField

В Django — DecimalField это встроенный класс поля формы, представляющий десятичное число. Он используется для хранения и обработки числовых значений с десятичными точками, таких как цены, проценты и десятичные дроби.

Класс DecimalField принимает несколько необязательных аргументов, таких как max_digits, decimal_places и initial. Аргумент max_digits используется для указания максимального количества цифр, которые можно сохранить в числе, а аргумент decimal_places используется для указания максимального количества цифр, которые можно сохранить после десятичной точки. Аргумент initial можно использовать для указания начального значения поля.

Вот пример того, как DecimalField можно использовать в форме и модели Django и как его можно отобразить с помощью формы HTML:

from django.db import models
 
class Product(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()
    price = models.DecimalField(max_digits=7, decimal_places=2)
 
from django import forms
from .models import Product
 
class ProductForm(forms.ModelForm):
    price = forms.DecimalField(max_digits=7, decimal_places=2)
 
    class Meta:
        model = Product
        fields = ('name', 'description', 'price')
 
<form method="post">
  {% csrf_token %}
  <label for="{{ form.name.id_for_label }}">Name:</label>
  {{ form.name }}
  <label for="{{ form.description.id_for_label }}">Description:</label>
  {{ form.description }}
  <label for="{{ form.price.id_for_label }}">Price:</label>
  {{ form.price }}
  <button type="submit">Submit</button>
</form>

В этом примере класс ProductForm расширяется ModelForm и включает поле DecimalField for price.

Модель Product также включает price поле, которое сопоставлено с этим полем формы.

В форме HTML это price поле отображается как поле ввода, куда пользователь может ввести десятичное значение. Аргументу max_digits присвоено значение 7, а decimal_places аргументу присвоено значение 2, что означает, что максимальное количество цифр в числе равно 7, а максимальное количество цифр после десятичной точки — 2.

Когда форма будет отправлена, Django автоматически проверит данные формы и создаст новый Product объект с отправленными данными. Поле price будет храниться в базе данных как decimal объект с указанным количеством цифр и десятичных знаков.

Поле DurationField

В Django — DurationField это встроенное поле модели, представляющее продолжительность времени. Он используется для хранения временных интервалов, таких как продолжительность фильма или продолжительность спортивного мероприятия.

Хранит DurationField продолжительность как datetime.timedelta объект, который представляет продолжительность в днях, секундах и микросекундах. Не DurationField принимает никаких аргументов.

Вот пример того, как DurationField можно использовать в форме и модели Django и как его можно отобразить с помощью формы HTML:

from django.db import models
 
class Movie(models.Model):
    title = models.CharField(max_length=100)
    duration = models.DurationField()
 
    def __str__(self):
        return self.title
 
from django import forms
from .models import Movie
 
class MovieForm(forms.ModelForm):
    duration = forms.DurationField()
 
    class Meta:
        model = Movie
        fields = ('title', 'duration')
 
 
<form method="post">
  {% csrf_token %}
  <label for="{{ form.title.id_for_label }}">Title:</label>
  {{ form.title }}
  <label for="{{ form.duration.id_for_label }}">Duration:</label>
  {{ form.duration }}
  <button type="submit">Submit</button>
</form>

В этом примере класс MovieForm расширяется ModelForm и включает поле DurationFieldfor duration. Модель Movie также включает duration поле, которое сопоставлено с этим полем формы.

В форме HTML это duration поле отображается как поле ввода, где пользователь может ввести продолжительность в формате HH:MM:SSили HH:MM:SS.microseconds. Введенные данные проверяются Django, чтобы убедиться, что они имеют допустимую продолжительность.

Когда форма будет отправлена, Django автоматически проверит данные формы и создаст новый Movieобъект с отправленными данными. Поле duration будет сохранено в базе данных как datetime.timedelta объект, который представляет продолжительность фильма.

Поле EmailField

В Django — EmailField это встроенное поле модели, представляющее адрес электронной почты. Он используется для хранения и проверки адресов электронной почты в модели Django.

A EmailField сохраняет адрес электронной почты в виде строки и проверяет, что адрес электронной почты имеет правильный формат, включая символ «@» и действительное имя домена.

Вот пример использования EmailField модели и формы Django, а также пример внешнего кода:

from django.db import models
 
class Contact(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField()
    message = models.TextField()
 
    def __str__(self):
        return self.name
 
from django import forms
from .models import Contact
 
class ContactForm(forms.ModelForm):
    class Meta:
        model = Contact
        fields = ('name', 'email', 'message')
 
 
{% extends "base.html" %}
 
{% block content %}
  <h1>Contact Us</h1>
  <form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Submit</button>
  </form>
{% endblock %}

В этом примере Contact модель имеет три поля: name, email и message. Поле email представляет собой файл EmailField. Расширение и включает ContactForm в ModelForm себя все три поля. В коде внешнего интерфейса форма отображается с помощью метода as_p, который отображает поля формы как абзацы.

Когда форма будет отправлена, Django проверит адрес электронной почты, чтобы убедиться, что он имеет правильный формат. Если адрес электронной почты недействителен, Django выдаст ValidationError сообщение с объяснением проблемы. Если адрес электронной почты действителен, Django сохранит данные формы в базе данных.

Поле FileField

FileFieldэто поле в библиотеке форм Django, используемое для обработки загрузки файлов. Он позволяет пользователю загрузить файл на сервер.

Вот пример использования FileField в модели и форме Django:

from django.db import models
 
class MyModel(models.Model):
    name = models.CharField(max_length=50)
    file = models.FileField(upload_to='uploads/%Y/%m/%d/')
 
    def __str__(self):
        return self.name

В этом примере MyModel имеется два поля: name, которое представляет собой CharField, и file, которое представляет собой FileField. Аргумент upload_to указывает каталог, в котором должен быть сохранен загруженный файл.

forms.py:

from django import forms
from .models import MyModel
 
class MyModelForm(forms.ModelForm):
    class Meta:
        model = MyModel
        fields = ['name', 'file']

В MyModelForm и name включены file как поля. Когда форма будет отправлена, Django проверит файл, чтобы убедиться, что он является допустимым типом файла и не превышает ограничений по размеру.

Вот пример того, как можно отобразить форму в шаблоне:

index.html:

{% extends "base.html" %}
 
{% block content %}
  <h1>Upload a File</h1>
  <form method="post" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Submit</button>
  </form>
{% endblock %}

В тег формы enctype="multipart/form-data" включено разрешение загрузки файлов. Метод as_p отображает поля формы как абзацы.