Поле CharField

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

Синтаксис

from django import forms

class MyForm(forms.Form):
	my_field = forms.CharField(
		max_length=100,
		min_length=3,
		required=True,
		initial='Default value',
		widget=forms.TextInput(attrs={'class': 'form-control'})
	)

Основные параметры

Параметр max_length задаёт максимально допустимую длину строки, а min_length - минимальную. Если введённое значение не соответствует этим ограничениям, форма не пройдёт валидацию. Параметр required определяет, является ли поле обязательным для заполнения. С помощью initial можно задать начальное значение, которое будет отображаться в поле при загрузке формы.

Пример . С валидацией длины

Создадим форму для ввода имени пользователя с ограничением длины от 3 до 20 символов:

from django import forms

class UserForm(forms.Form):
	username = forms.CharField(
		min_length=3,
		max_length=20,
		required=True,
		label='Username',
		help_text='Enter a username between 3 and 20 characters.'
	)
	
# Создаём экземпляр формы с переданными данными
form = UserForm({'username': 'john_doe'})
if form.is_valid():
	print("Form is valid")
	print(form.cleaned_data['username'])

Результат выполнения кода:

"Form is valid"
"john_doe"

Пример . С использованием виджета

Параметр widget позволяет указать, какой HTML-элемент будет использоваться для отображения поля. По умолчанию используется TextInput. Можно использовать Textarea для многострочного ввода:

from django import forms

class ArticleForm(forms.Form):
	title = forms.CharField(max_length=200)
	content = forms.CharField(
		widget=forms.Textarea(attrs={'rows': 10, 'cols': 80}),
		label='Article content'
	)
	
# Пример работы с формой
form = ArticleForm({
	'title': 'My Article',
	'content': 'This is the content of the article.'
})
if form.is_valid():
	print("Article saved successfully")
	print(form.cleaned_data['title'])

Результат выполнения кода:

"Article saved successfully"
"My Article"

Пример . С начальным значением

Используем параметр initial для предзаполнения поля при отображении формы:

from django import forms

class ProfileForm(forms.Form):
	bio = forms.CharField(
		initial='Tell something about yourself',
		label='Biography',
		widget=forms.Textarea
	)
	
# Создаём пустую форму
form = ProfileForm()
print(form['bio'].value())

Результат выполнения кода:

"Tell something about yourself"

Пример . С кастомными сообщениями об ошибках

Параметр error_messages позволяет переопределить стандартные сообщения валидации:

from django import forms

class UserRegistrationForm(forms.Form):
	username = forms.CharField(
		min_length=3,
		max_length=20,
		required=True,
		error_messages={
			'required': 'Username is required.',
			'min_length': 'Username must be at least 3 characters.',
			'max_length': 'Username cannot exceed 20 characters.'
		}
	)
	
form = UserRegistrationForm({'username': 'ab'})
if not form.is_valid():
	print(form.errors['username'][0])

Результат выполнения кода:

"Username must be at least 3 characters."

Смотрите также

поле IntegerField,
которое используется для ввода целых чисел
поле EmailField,
которое валидирует ввод как email-адрес
виджет Textarea,
который отображает поле как многострочный текст
валидатор MaxLengthValidator,
который проверяет максимальную длину строки