O Django Admin é uma interface administrativa pronta para uso que acompanha o framework Django e permite criar, editar e consultar dados do sistema de forma rápida. Em aplicações simples, a configuração padrão costuma ser suficiente, mas sistemas reais frequentemente possuem relacionamentos entre modelos que tornam a gestão mais exigente.
A personalização do Django Admin resolve esse cenário ao adaptar telas, formulários e listagens para refletirem melhor as regras do domínio. Com ajustes como inlines, filtros de consulta e otimizações de desempenho, o Admin pode se tornar uma interface robusta para lidar com relações um-para-muitos e muitos-para-muitos, inclusive com campos extras e necessidades de performance.
Visão geral: modelos, relacionamentos e o papel do Admin
No Django, um modelo é uma classe que representa uma tabela no banco de dados e define seus campos e regras básicas. Um relacionamento é a forma de conectar modelos, como um-para-muitos (por exemplo, Livro e Capítulos) e muitos-para-muitos (por exemplo, Aluno e Curso). O Django Admin gera telas para esses modelos automaticamente, mas a experiência pode ficar fragmentada quando os dados relacionados precisam ser editados em conjunto.
A personalização existe para tornar o fluxo mais coerente e reduzir retrabalho operacional. Ela permite embutir edições de objetos relacionados dentro do “pai”, ajustar o que aparece na tela e controlar como os dados são buscados no banco. Também abre espaço para melhorar campos complexos com widgets (componentes de formulário) mais adequados. Com isso, a administração se aproxima do modo como as pessoas e processos realmente operam.
Inline Models: editando relacionamentos “filho” dentro do “pai”
Inline no Django Admin é um recurso que permite editar objetos relacionados diretamente na página do modelo principal. Esse padrão é especialmente útil em relacionamentos um-para-muitos, em que o “pai” possui vários “filhos”, como um Livro com vários Capítulos. Sem inline, seria necessário salvar o Livro, voltar à listagem e criar Capítulos separadamente, o que fragmenta o fluxo.
A seguir está um exemplo completo com modelos e a configuração do Admin, demonstrando como Capítulos aparecem dentro do formulário do Livro. O uso de TabularInline organiza os itens em formato de tabela, enquanto StackedInline exibe cada item em bloco, útil quando há muitos campos. A propriedade extra define quantas linhas vazias de cadastro aparecem por padrão. Esse padrão mantém o conjunto de dados coeso e mais fácil de manter.
from django.db import models
from django.contrib import admin
class Book(models.Model):
titulo = models.CharField(max_length=200)
publicado_em = models.DateField(null=True, blank=True)
def __str__(self):
return self.titulo
class Chapter(models.Model):
livro = models.ForeignKey(Book, on_delete=models.CASCADE, related_name="capitulos")
titulo = models.CharField(max_length=200)
numero = models.PositiveIntegerField()
class Meta:
ordering = ["numero"]
unique_together = [("livro", "numero")] # evita capítulos repetidos no mesmo livro
def __str__(self):
return f"{self.numero} - {self.titulo}"
class ChapterInline(admin.TabularInline):
model = Chapter
extra = 1 # quantidade de linhas vazias para novo capítulo
fields = ("numero", "titulo")
ordering = ("numero",)
@admin.register(Book)
class BookAdmin(admin.ModelAdmin):
list_display = ("titulo", "publicado_em")
search_fields = ("titulo",)
inlines = [ChapterInline]Relacionamentos reversos: gerindo “filhos” a partir do “pai” organizacional
Um relacionamento reverso é o acesso ao conjunto de objetos “filhos” a partir do “pai”, como Departamento acessando seus Funcionários. No Django, quando existe uma ForeignKey em Employee apontando para Department, o Admin do Department pode exibir Employees em um inline, mesmo que o campo esteja do lado do Employee. Isso transforma a tela do Departamento em um ponto central para organizar pessoas e alocações.
Esse formato ajuda quando o cadastro do “pai” faz sentido como eixo principal do trabalho. Em empresas, por exemplo, departamentos são estruturas e os funcionários entram e saem, o que torna conveniente ajustar tudo em uma só tela. Além disso, o inline permite inserir novos funcionários já vinculados ao departamento, reduzindo erros de vinculação. A seguir está um exemplo completo com modelos e Admin.
from django.db import models
from django.contrib import admin
class Department(models.Model):
nome = models.CharField(max_length=120, unique=True)
def __str__(self):
return self.nome
class Employee(models.Model):
departamento = models.ForeignKey(
Department, on_delete=models.PROTECT, related_name="funcionarios"
)
nome = models.CharField(max_length=200)
ativo = models.BooleanField(default=True)
class Meta:
ordering = ["nome"]
def __str__(self):
return self.nome
class EmployeeInline(admin.TabularInline):
model = Employee
extra = 1
fields = ("nome", "ativo")
show_change_link = True # mostra link para editar o funcionário em tela própria
@admin.register(Department)
class DepartmentAdmin(admin.ModelAdmin):
list_display = ("nome",)
search_fields = ("nome",)
inlines = [EmployeeInline]Custom Querysets em inlines: exibindo apenas o que é relevante
Queryset é o conjunto de dados retornado por uma consulta no Django, representado por um objeto que pode receber filtros e ordenações. No Admin, é comum querer mostrar apenas itens “acionáveis”, como envios pendentes, e esconder itens concluídos para reduzir ruído. Em inlines, isso pode ser feito sobrescrevendo o método get_queryset do inline.
Esse filtro afeta somente o que aparece na interface, sem apagar dados, e pode tornar telas grandes muito mais claras. É importante notar que o filtro muda a visibilidade do conjunto relacionado no contexto do inline, mas não impede que o objeto exista ou seja acessado em outras telas. A seguir está um exemplo em que apenas remessas com status pendente aparecem dentro do Pedido. Esse padrão é útil quando o histórico é grande, mas a operação diária depende de poucos estados.
from django.db import models
from django.contrib import admin
class Order(models.Model):
criado_em = models.DateTimeField(auto_now_add=True)
def __str__(self):
return f"Pedido #{self.id}"
class Shipment(models.Model):
STATUS_PENDENTE = "pendente"
STATUS_ENVIADO = "enviado"
STATUS_CANCELADO = "cancelado"
STATUS_CHOICES = [
(STATUS_PENDENTE, "Pendente"),
(STATUS_ENVIADO, "Enviado"),
(STATUS_CANCELADO, "Cancelado"),
]
pedido = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="remessas")
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default=STATUS_PENDENTE)
atualizado_em = models.DateTimeField(auto_now=True)
def __str__(self):
return f"Remessa {self.id} ({self.status})"
class ShipmentInline(admin.TabularInline):
model = Shipment
extra = 0
fields = ("status", "atualizado_em")
readonly_fields = ("atualizado_em",)
def get_queryset(self, request):
qs = super().get_queryset(request)
return qs.filter(status=Shipment.STATUS_PENDENTE)
@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
list_display = ("id", "criado_em")
inlines = [ShipmentInline]Many-to-many com modelo intermediário (through): quando a relação tem atributos
Um relacionamento muitos-para-muitos liga dois modelos em que ambos podem ter vários registros associados. Em muitos casos reais, essa associação possui campos próprios, como nota, data de matrícula ou status, o que exige um modelo intermediário (também chamado de “through”). No Django, esse modelo intermediário vira uma tabela com chaves para os dois lados e colunas extras.
No Admin, a forma mais clara de gerenciar isso costuma ser por inline do modelo intermediário. Assim, em vez de apenas selecionar cursos, é possível registrar também a nota daquela matrícula. Esse padrão também permite manter regras como unicidade de matrícula por aluno e curso. A seguir está um exemplo completo com Aluno, Curso e Matrícula, incluindo a configuração da relação through.
from django.db import models
from django.contrib import admin
class Course(models.Model):
nome = models.CharField(max_length=200, unique=True)
def __str__(self):
return self.nome
class Student(models.Model):
nome = models.CharField(max_length=200)
cursos = models.ManyToManyField(Course, through="Enrollment", related_name="alunos")
def __str__(self):
return self.nome
class Enrollment(models.Model):
aluno = models.ForeignKey(Student, on_delete=models.CASCADE, related_name="matriculas")
curso = models.ForeignKey(Course, on_delete=models.CASCADE, related_name="matriculas")
nota = models.DecimalField(max_digits=4, decimal_places=2, null=True, blank=True)
class Meta:
unique_together = [("aluno", "curso")] # impede matrícula duplicada
def __str__(self):
return f"{self.aluno} em {self.curso}"
class EnrollmentInline(admin.TabularInline):
model = Enrollment
extra = 1
fields = ("curso", "nota")
@admin.register(Student)
class StudentAdmin(admin.ModelAdmin):
list_display = ("nome",)
search_fields = ("nome",)
inlines = [EnrollmentInline]
@admin.register(Course)
class CourseAdmin(admin.ModelAdmin):
list_display = ("nome",)
search_fields = ("nome",)
inlines = [EnrollmentInline]Widgets personalizados: melhorando campos complexos em formulários do Admin
Um widget é o componente visual usado para editar um campo em um formulário, como um input de texto, uma área de texto ou uma seleção. Campos complexos, como JSONField (campo para armazenar dados estruturados em JSON), podem ficar difíceis de ler e editar no Admin se renderizados de forma simples. Uma forma comum de melhorar isso é definir um formulário personalizado e substituir o widget do campo.
Essa abordagem não muda o tipo do dado no banco, apenas melhora a apresentação e a ergonomia do formulário. Ela também permite definir validações e regras adicionais no formulário, quando necessário, mantendo a lógica próxima à interface administrativa. O exemplo a seguir troca o widget de um JSONField para um Textarea com mais linhas, facilitando visualização e edição. Esse ajuste tende a ser suficiente em muitos cenários em que a estrutura do JSON é moderada.
from django.db import models
from django import forms
from django.contrib import admin
class Product(models.Model):
nome = models.CharField(max_length=200)
metadata = models.JSONField(default=dict, blank=True) # dados estruturados em JSON
def __str__(self):
return self.nome
class ProductForm(forms.ModelForm):
class Meta:
model = Product
fields = "__all__"
widgets = {
"metadata": forms.Textarea(attrs={"rows": 6, "cols": 60}),
}
@admin.register(Product)
class ProductAdmin(admin.ModelAdmin):
form = ProductForm
list_display = ("nome",)
search_fields = ("nome",)Otimização de desempenho: select_related e prefetch_related no Admin
Em telas administrativas, relacionamentos podem gerar muitas consultas ao banco, especialmente em listagens com colunas que acessam chaves estrangeiras e coleções relacionadas. Esse problema é conhecido como “N+1 queries”, quando uma consulta inicial é seguida por muitas consultas adicionais para buscar dados relacionados. No Django, select_related e prefetch_related são técnicas para reduzir esse custo.
select_related faz um “join” para carregar objetos de relação um-para-um ou muitos-para-um (ForeignKey) na mesma consulta. prefetch_related faz consultas adicionais planejadas e as combina em memória, sendo mais adequado para relações muitos-para-muitos e um-para-muitos. No Admin, isso costuma ser aplicado sobrescrevendo get_queryset no ModelAdmin. O exemplo a seguir mostra um Pedido com Cliente (ForeignKey) e Itens (um-para-muitos), reduzindo consultas em listagens e páginas de detalhes.
from django.db import models
from django.contrib import admin
class Customer(models.Model):
nome = models.CharField(max_length=200)
def __str__(self):
return self.nome
class Order(models.Model):
cliente = models.ForeignKey(Customer, on_delete=models.PROTECT, related_name="pedidos")
criado_em = models.DateTimeField(auto_now_add=True)
def __str__(self):
return f"Pedido #{self.id}"
class OrderItem(models.Model):
pedido = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="itens")
descricao = models.CharField(max_length=200)
quantidade = models.PositiveIntegerField(default=1)
def __str__(self):
return self.descricao
@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
list_display = ("id", "cliente", "criado_em")
def get_queryset(self, request):
qs = super().get_queryset(request)
return qs.select_related("cliente").prefetch_related("itens")Encerramento: Admin como interface consistente para relacionamentos complexos
A personalização do Django Admin permite que a interface administrativa acompanhe a complexidade natural de modelos com múltiplos relacionamentos. Recursos como inlines, filtros de queryset e modelos intermediários tornam possível editar dados conectados de forma organizada e com menos fricção. Widgets personalizados melhoram a legibilidade e a manutenção de campos que, por padrão, seriam pouco amigáveis.
Em paralelo, otimizações como select_related e prefetch_related mantêm o Admin responsivo mesmo quando o volume de dados cresce. O resultado é um backend administrativo mais fiel ao domínio, capaz de consolidar operações em telas consistentes e reduzir erros de cadastro. Esse conjunto de técnicas fecha o ciclo entre modelagem, usabilidade e desempenho dentro do próprio Admin. Com isso, o Django Admin deixa de ser apenas um painel genérico e passa a refletir relações complexas de maneira prática e sustentável.