Django xadmin 安装与全局配置实战指南

xadmin 简介与版本现状

一、简介

xadmin 是一个针对 Django Admin 开发的开源增强模块，旨在解决原生 Admin 页面美化不足及功能缺失的问题。目前 xadmin 最新版本已更新至 3.0，但该版本已转型为纯前端项目。由于原作者已停止对 xadmin 2.0 系列的维护，社区活跃度较低，建议开发者评估后选择其他持续维护的开源后台管理方案。

官方文档地址：https://xadmin.readthedocs.io/en/latest/index.html

xadmin 安装与环境配置

二、安装环境准备

本教程基于以下环境：Python 3.6 与 Django 2.2。

注意：xadmin 官方文档中的安装命令已长期未更新，直接执行可能导致安装失败。推荐使用以下 GitHub 仓库地址进行安装，以确保兼容性。

pip3 install https://codeload.github.com/sshwsfc/xadmin/zip/django2

在 Django 项目的 settings.py 配置文件中，注册以下应用：

INSTALLED_APPS = [
  ...
  'xadmin',
  'crispy_forms',
  'reversion',
  ...
]

修改项目的全局语言与时区设置，以支持中文界面。

# 修改使用中文界面
LANGUAGE_CODE = 'zh-Hans'

# 修改时区
TIME_ZONE = 'Asia/Shanghai'

xadmin 包含独立的数据库模型类，因此必须执行数据库迁移操作。

注意：在执行迁移前，请检查当前 Django 版本。

示例情况：若原环境为 Django 2.2，安装 xadmin 后可能自动升级至 3.2 版本，这会导致执行数据库迁移命令时出现报错，需根据实际报错信息调整。

python3 manage.py makemigrations
python3 manage.py migrate

配置 xadmin 的路由信息，使其可访问。

import xadmin
xadmin.autodiscover()

# version模块自动注册需要版本控制的 Model
from xadmin.plugins import xversion
xversion.register_models()

urlpatterns = [
  path(r'xadmin/', xadmin.site.urls),
]

若尚未创建超级用户，需执行创建命令；若已存在则跳过此步。

python3 manage.py createsuperuser

全局配置与 Model 管理参数

三、全局配置与 Model 管理

import xadmin
from xadmin import views

class BaseSetting(object):
  """xadmin的基本配置"""
  enable_themes = True # 开启主题切换功能
  use_bootswatch = True # 引导控制盘(其实就是我们的左侧菜单栏)

xadmin.site.register(views.BaseAdminView, BaseSetting)

class GlobalSettings(object):
  """xadmin的全局配置"""
  site_title = "kuokay" # 设置站点标题
  site_footer = "kuokay学python" # 设置站点的页脚
  menu_style = "accordion" # 设置菜单折叠

xadmin.site.register(views.CommAdminView, GlobalSettings)

站点 Model 管理配置

xadmin 的页面样式控制逻辑与 Django 原生 Admin 基本一致。

在 Model 类中定义 __str__ 方法，以指定对象在前端的显示内容。

• list_display：控制列表页展示的字段。
• search_fields：定义可通过搜索框查询的字段，xadmin 默认支持模糊查询。
• list_filter：设置可进行过滤操作的列，常用于分类、性别、状态等字段。
• ordering：设置列表的默认排序字段。
• show_detail_fields：在列表页提供快速查看详情的功能。
• list_editable：允许在列表页直接编辑指定字段。
• refresh_times：指定列表页自动刷新的时间间隔。
• list_export：控制列表页数据导出的可选格式。
• show_bookmarks：控制是否显示书签功能。
• data_charts：控制数据图表的显示样式。
• model_icon：设置菜单图标，可参考 font-awesome 的 CSS 类名。
• readonly_fields：定义编辑页面中的只读字段。
• exclude：在编辑页面隐藏指定字段，例如用于标识数据是否删除的 delete_status 字段（逻辑删除，数据库不物理删除）。

至此，关于 Django xadmin 的安装与基本使用介绍完毕。如需了解更多相关内容，请搜索本站往期文章或继续浏览后续教程，感谢支持！