CheckboxSelectMultiple

Виджет CheckboxSelectMultiple применяется в формах Django для полей с множественным выбором. Он отображает каждый вариант выбора в виде отдельного флажка, что позволяет пользователю выбрать несколько значений одновременно. Виджет используется с полями типа MultipleChoiceField и ModelMultipleChoiceField. В отличие от SelectMultiple, который отображает список с множественным выбором, CheckboxSelectMultiple представляет все варианты визуально, что удобно при небольшом количестве вариантов.

Синтаксис

from django import forms

class MyForm(forms.Form):
	field_name = forms.MultipleChoiceField(
		choices=CHOICES_LIST,
		widget=forms.CheckboxSelectMultiple
	)

Виджет принимает следующие параметры при инициализации:

forms.CheckboxSelectMultiple(
	attrs=None,
	choices=()
)

Где attrs - словарь с HTML-атрибутами для виджета, а choices - список или кортеж вариантов выбора.

Пример . С MultipleChoiceField

Рассмотрим простой пример формы для выбора предпочтений пользователя:

from django import forms

class UserPreferencesForm(forms.Form):
	FRUIT_CHOICES = [
		('apple', 'Apple'),
		('banana', 'Banana'),
		('orange', 'Orange'),
		('grape', 'Grape'),
		('strawberry', 'Strawberry'),
	]

	favorite_fruits = forms.MultipleChoiceField(
		choices=FRUIT_CHOICES,
		widget=forms.CheckboxSelectMultiple,
		required=False,
		label="Favorite fruits"
	)

В шаблоне HTML виджет будет отображён следующим образом:

<form method="post">
	{% csrf_token %}
	{{ form.favorite_fruits }}
	<button type="submit">Save</button>
</form>

Результат будет выглядеть как набор флажков:

<label><input type="checkbox" value="apple"> Apple</label>
<label><input type="checkbox" value="banana"> Banana</label>
<label><input type="checkbox" value="orange"> Orange</label>
<label><input type="checkbox" value="grape"> Grape</label>
<label><input type="checkbox" value="strawberry"> Strawberry</label>

Пример . С ModelMultipleChoiceField

Теперь рассмотрим пример с моделью и выбором нескольких объектов:

from django import forms
from myapp.models import Category

class ArticleForm(forms.Form):
	categories = forms.ModelMultipleChoiceField(
		queryset=Category.objects.all(),
		widget=forms.CheckboxSelectMultiple,
		label="Select categories"
	)

В этом случае виджет будет отображать все категории из базы данных в виде флажков. При отправке формы будут переданы ID выбранных категорий.

Обработка данных формы

После отправки формы данные можно получить через cleaned_data:

from django import forms
from myapp.models import Category

class ArticleForm(forms.Form):
	categories = forms.ModelMultipleChoiceField(
		queryset=Category.objects.all(),
		widget=forms.CheckboxSelectMultiple,
		label="Select categories"
	)

# В view-функции:
def article_view(request):
	if request.method == 'POST':
		form = ArticleForm(request.POST)
		if form.is_valid():
			selected_categories = form.cleaned_data['categories']
			print(f"Selected categories: {selected_categories}")
			# selected_categories - это QuerySet с выбранными объектами

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

"Selected categories: [<Category: Technology>, <Category: Science>]"

Настройка атрибутов виджета

Можно добавлять HTML-атрибуты для дополнительной настройки внешнего вида:

from django import forms

class UserPreferencesForm(forms.Form):
	FRUIT_CHOICES = [
		('apple', 'Apple'),
		('banana', 'Banana'),
		('orange', 'Orange'),
	]

	favorite_fruits = forms.MultipleChoiceField(
		choices=FRUIT_CHOICES,
		widget=forms.CheckboxSelectMultiple(
			attrs={
				'class': 'fruit-checkbox',
				'id': 'fruit-selector'
			}
		),
		label="Favorite fruits"
	)

Работа с начальными значениями

Для предустановки выбранных значений используется параметр initial:

from django import forms

class EditUserForm(forms.Form):
	FRUIT_CHOICES = [
		('apple', 'Apple'),
		('banana', 'Banana'),
		('orange', 'Orange'),
		('grape', 'Grape'),
	]

	favorite_fruits = forms.MultipleChoiceField(
		choices=FRUIT_CHOICES,
		widget=forms.CheckboxSelectMultiple,
		label="Favorite fruits"
	)

# Создаём форму с начальными значениями:
initial_data = {
	'favorite_fruits': ['apple', 'banana']
}
form = EditUserForm(initial=initial_data)

В результате флажки для 'Apple' и 'Banana' будут отмечены при загрузке формы.

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

виджет SelectMultiple,
который отображает множественный выбор в виде списка
виджет RadioSelect,
который позволяет выбрать только один вариант из списка
виджет CheckboxInput,
который используется для одного флажка
поле ModelMultipleChoiceField,
которое предназначено для выбора нескольких моделей