Декоратор admin.display

Декоратор admin.display применяется к методам модели или методам, определенным в классе административной панели. Он используется в связке с атрибутом list_display для тонкой настройки отображения данных. Декоратор позволяет задать несколько параметров: description, ordering, empty_value, boolean и цветовые стили. Основное назначение - сделать административную панель более информативной и удобной для пользователей.

Синтаксис

@admin.display(
	description="Custom Header",
	ordering="field_name",
	empty_value="-",
	boolean=True,
)
def method_name(self, obj):
	return obj.some_value

Декоратор принимает следующие параметры:

description - задает заголовок колонки в таблице админки. Если не указан, используется имя метода.

ordering - указывает поле модели, по которому будет производиться сортировка при клике на заголовок колонки.

empty_value - задает строку, которая будет отображаться, если метод возвращает пустое значение или None.

boolean - если установлен в True, отображает значение в виде иконки галочки или крестика для булевых значений.

Пример . С моделью Article

Рассмотрим модель статьи, в которой есть метод для отображения статуса публикации:

from django.db import models
from django.contrib import admin

class Article(models.Model):
	title = models.CharField(max_length=100)
	content = models.TextField()
	is_published = models.BooleanField(default=False)
	published_at = models.DateTimeField(null=True, blank=True)

	@admin.display(
		description="Status",
		ordering="published_at",
		empty_value="Not published"
	)
	def get_publish_status(self):
		if self.is_published:
			return f"Published at {self.published_at.strftime('%Y-%m-%d')}"
		return "Draft"

	@admin.display(boolean=True)
	def is_ready(self):
		return self.is_published

В классе административной панели добавим эти методы в список отображаемых полей:

from django.contrib import admin
from .models import Article

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
	list_display = ['title', 'get_publish_status', 'is_ready']
	list_filter = ['is_published']
	search_fields = ['title']

В результате в админке появятся две дополнительные колонки:

"Title: My First Article, Status: Published at 2025-01-15, is_ready: True"
"Title: Draft Article, Status: Not published, is_ready: False"

Пример . С параметром ordering

Параметр ordering позволяет сортировать записи по полю, указанному в качестве значения. Рассмотрим пример с сортировкой по дате создания:

from django.db import models
from django.contrib import admin

class Product(models.Model):
	name = models.CharField(max_length=100)
	created_at = models.DateTimeField(auto_now_add=True)
	price = models.DecimalField(max_digits=10, decimal_places=2)

	@admin.display(
		description="Product Info",
		ordering="created_at"
	)
	def get_product_info(self):
		return f"{self.name} (${self.price})"

Теперь при клике на заголовок колонки "Product Info" записи будут сортироваться по полю created_at:

from django.contrib import admin
from .models import Product

@admin.register(Product)
class ProductAdmin(admin.ModelAdmin):
	list_display = ['name', 'get_product_info']
	ordering = ['-created_at']

Пример . С параметром empty_value

Параметр empty_value определяет, что будет отображаться, если метод возвращает пустое значение. Рассмотрим пример с пользователями:

from django.db import models
from django.contrib import admin

class UserProfile(models.Model):
	username = models.CharField(max_length=50)
	first_name = models.CharField(max_length=50, blank=True)
	last_name = models.CharField(max_length=50, blank=True)

	@admin.display(
		description="Full Name",
		empty_value="Anonymous"
	)
	def get_full_name(self):
		if self.first_name and self.last_name:
			return f"{self.first_name} {self.last_name}"
		return None

Теперь если у пользователя не заполнены имя и фамилия, в колонке будет отображаться строка "Anonymous":

from django.contrib import admin
from .models import UserProfile

@admin.register(UserProfile)
class UserProfileAdmin(admin.ModelAdmin):
	list_display = ['username', 'get_full_name']
	search_fields = ['username']

Пример . С параметром boolean

Параметр boolean используется для отображения булевых значений в виде иконок. Рассмотрим пример с задачей:

from django.db import models
from django.contrib import admin

class Task(models.Model):
	title = models.CharField(max_length=100)
	is_completed = models.BooleanField(default=False)
	is_urgent = models.BooleanField(default=False)

	@admin.display(boolean=True)
	def is_done(self):
		return self.is_completed

	@admin.display(boolean=True)
	def is_important(self):
		return self.is_urgent

В админке эти методы будут отображаться как иконки галочки или крестика:

from django.contrib import admin
from .models import Task

@admin.register(Task)
class TaskAdmin(admin.ModelAdmin):
	list_display = ['title', 'is_done', 'is_important']
	list_filter = ['is_completed', 'is_urgent']

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

декоратор admin.register,
который регистрирует модель в административной панели
атрибут list_display,
который определяет поля для отображения в списке объектов
атрибут readonly_fields,
который делает поля доступными только для чтения
декоратор admin.action,
который определяет кастомные действия для выбранных объектов