安装¶
本指南介绍如何在您的 Django 项目中安装 Django Admin Dashboards。
先决条件¶
- Python 3.8 或更高版本
- Django 5.2 或更高版本
- 一个正常运行的 Django 项目
安装方法¶
方法 1：从 PyPI 安装（推荐）¶
这将自动安装：
django-admin-dashboardsdjango-static-remixicon（图标必需）
方法 2：从源代码安装¶
如果您想要贡献或使用最新的开发版本：
# 克隆仓库
git clone https://gitee.com/rRR0VrFP/django-admin-dashboards.git
cd django-admin-dashboards
# 以开发模式安装
pip install -e .
# 或安装所有依赖项
pip install -e ".[dev]"
方法 3：使用 pip 指定版本¶
依赖管理 (使用 django_app_requires)¶
对于需要自动管理 Django 应用程序依赖关系的项目，可以使用 django_app_requires 库。该库可以帮助确保依赖的 Django 应用程序（如 django_static_remixicon 和 django_admin_global_sidebar）被正确加载和配置。
安装 django_app_requires¶
配置 django_app_requires¶
在您的 Django 项目的 settings.py 文件末尾添加以下代码：
这将在 Django 启动时自动处理应用程序依赖关系，确保所有必需的应用程序被正确初始化。
工作原理¶
django_app_requires 会：
- 自动检测 Django 应用程序之间的依赖关系
- 确保依赖的应用程序在
INSTALLED_APPS中以正确的顺序加载 - 简化复杂项目中的应用程序配置
注意事项¶
- 使用
django_app_requires是可选的，但推荐用于大型项目或多个相互依赖的 Django 应用程序 - 在
INSTALLED_APPS中只需要列出项目直接依赖的应用程序，应用程序的间接依赖可以交由django_app_requires自动处理 - 该库特别适用于管理像
django_static_remixicon（必需）和django_admin_global_sidebar（推荐）这样的依赖关系
项目配置¶
1. 添加到 INSTALLED_APPS¶
在您的 Django 项目的 settings.py 中，将必需的应用程序添加到 django.contrib.admin 之前：
INSTALLED_APPS = [
# 数据看板应用程序（必须在 django.contrib.admin 之前）
"django_admin_dashboards",
"django_static_remixicon", # 图标必需
# 可选的增强导航
"django_admin_global_sidebar", # 可选但推荐
# Django 核心应用程序
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
# 您的应用程序...
]
重要：顺序很重要！django_admin_dashboards 必须在 django.contrib.admin 之前。
2. 配置数据看板映射¶
在您的 settings.py 中定义要为不同的管理视图使用哪些数据看板：
# Django Admin Dashboards 配置
DJANGO_ADMIN_DASHBOARDS = {
# 管理首页（主页）
"admin:index": "django_admin_dashboards.contrib.auth.dashboard.AuthAppDashboard",
# 应用程序列表页面（特定应用程序）
"admin:app_list": {
"auth": "django_admin_dashboards.contrib.auth.dashboard.AuthAppDashboard",
# 根据需要添加更多应用程序：
# "myapp": "myapp.dashboards.MyAppDashboard",
},
# 可选：模型更改列表页面
# "admin:app_model_changelist": {
# ("auth", "user"): "path.to.ModelDashboard",
# },
}
3. 可选：配置导航菜单¶
如果使用 Django Admin Global Sidebar（推荐），配置导航菜单：
# Django Admin Global Sidebar 配置（可选）
DJANGO_ADMIN_GLOBAL_SIDEBAR_MENUS = [
{
"title": "首页", # Home
"url": "/admin/",
"icon": "fas fa-home",
},
{
"title": "系统管理", # System Management
"icon": "fas fa-cog",
"children": [
{
"title": "用户管理", # User Management
"url": "/admin/auth/user/",
"icon": "fas fa-users",
},
{
"title": "用户组管理", # Group Management
"url": "/admin/auth/group/",
"icon": "fas fa-user-friends",
},
],
},
]
数据库设置¶
运行迁移以设置所需的数据库表：
收集静态文件¶
收集静态文件以使数据看板资源可用：
系统将提示您确认覆盖现有的管理模板。输入 yes 继续。
验证安装¶
1. 检查管理界面¶
启动您的 Django 开发服务器：
访问 http://localhost:8000/admin/ 并登录。您应该看到数据看板而不是默认的管理首页。
2. 测试数据看板功能¶
- 检查是否显示卡片
- 验证图表是否正确加载
- 测试深色模式切换（如果可用）
- 尝试按 F11 进入全屏模式
3. 验证配置¶
创建一个测试数据看板以确保一切正常：
# test_dashboard.py
from django_admin_dashboards.base import Dashboard, CardComponent, Layout
class TestDashboard(Dashboard):
title = "测试数据看板"
def get_layout(self):
layout = Layout(columns=12)
layout.add_row([
(CardComponent(
title="测试卡片",
value=42,
color="primary",
icon_class="ri-check-line"
), 12)
], height="auto")
return layout
故障排除¶
常见问题¶
1. 数据看板未显示¶
- 确保
django_admin_dashboards在INSTALLED_APPS中 位于django.contrib.admin之前 - 检查
DJANGO_ADMIN_DASHBOARDS是否正确配置 - 确认您以超级用户身份登录
2. 缺少图标或样式¶
- 运行
python manage.py collectstatic - 检查浏览器控制台是否有 404 错误
- 验证
django_static_remixicon是否安装
3. 模板错误¶
- 清除模板缓存：
python manage.py clearcache - 检查
TEMPLATES设置中的模板加载器 - 确保包含应用程序目录（
APP_DIRS: True）
4. JavaScript 错误¶
- 检查浏览器控制台是否有错误
- 确保 Chart.js 正在加载（检查网络选项卡）
- 验证静态文件是否正确提供服务
调试模式¶
启用 Django 调试模式以获取详细的错误消息：
检查 Django 调试工具栏以获取模板渲染信息。