常见问题¶
概述¶
Django Admin Dashboards 是什么？¶
Django Admin Dashboards 是一个 Django 包，它用可自定义的数据看板替换默认的 Django Admin 索引页面。它提供卡片、图表、表格和过滤器，让管理员更好地了解其应用程序数据。
它与我的 Django 版本兼容吗？¶
是的，Django Admin Dashboards 需要 Django 5.2 或更高版本，并支持 Python 3.8+。详细要求请查看安装指南。
这个包是免费的吗？¶
是的，Django Admin Dashboards 是开源的，基于 MIT 许可证发布。您可以在个人和商业项目中自由使用。
安装¶
为什么我需要安装 django-static-remixicon？¶
django-static-remixicon 提供了数据看板组件使用的图标字体。它是一个确保图标正确显示的依赖项。当您安装
Django Admin Dashboards 时，这个包会自动安装。
安装后数据看板没有显示。出了什么问题？¶
最常见的问题：
- INSTALLED_APPS 顺序：确保
DJANGO_ADMIN_DASHBOARDS在Django.contrib.admin之前 出现在INSTALLED_APPS列表中。 - 缺少配置：验证
DJANGO_ADMIN_DASHBOARDS已在settings.py中配置。 - 静态文件未收集：运行
Python manage.py collectstatic以确保数据看板资源可用。 - 缓存问题：清除浏览器缓存和 Django 模板缓存。
详见故障排除部分。
我可以与 Django Admin Global 侧边栏一起使用吗？¶
是的，Django Admin Dashboards 与 Django Admin Global 侧边栏兼容良好。实际上，为了更好的导航集成，推荐使用。请根据各自的文档配置这两个包。
配置¶
如何自定义每个管理页面显示的数据看板？¶
在您的 settings.py 中使用 DJANGO_ADMIN_DASHBOARDS 设置：
DJANGO_ADMIN_DASHBOARDS = {
# Admin index page
"admin:index": "myapp.dashboards.MainDashboard",
# App-specific dashboards
"admin:app_list": {
"auth": "django_admin_dashboards.contrib.auth.dashboard.AuthAppDashboard",
"myapp": "myapp.dashboards.MyAppDashboard",
},
# Model-specific dashboards (optional)
"admin:app_model_changelist": {
("auth", "user"): "path.to.UserDashboard",
},
}
详细示例请参阅配置指南。
我可以为不同的用户组设置不同的数据看板吗？¶
是的，您可以基于用户权限或组自定义数据看板。在您的数据看板类中，重写
get_context_data 方法：
class CustomDashboard(Dashboard):
def get_context_data(self, request, **kwargs):
context = super().get_context_data(request, **kwargs)
if request.user.groups.filter(name='Managers').exists():
# 为经理用户添加特定组件
# 可以在这里动态修改 layout 或添加额外的上下文数据
pass
return context
如何向我的数据看板添加自定义 CSS 或 JavaScript？¶
有几种方法：
- 扩展数据看板模板：创建扩展数据看板模板的自定义模板
- 使用组件 CSS 类：所有组件都接受
css_class和css_id参数 - 将静态文件添加到项目：在项目的静态文件中包含自定义 CSS/JS
添加自定义 CSS 的示例（通过 Dashboard 的 Media 类）：
class MyDashboard(Dashboard):
class Media:
css = {
'all': ('myapp/css/custom-dashboard.css',)
}
js = ('myapp/js/custom-dashboard.js',)
组件¶
有哪些可用组件？¶
该包包含以下内置组件：
- 卡片组件：带图标和颜色的卡片
- 图表组件：使用 图表.js 的图表（折线图、柱状图、饼图等）
- 表格组件：带排序和分页的数据表格
- 过滤器组件：用于数据看板数据的过滤器控件
- 自定义HTML组件：自定义 HTML 内容
使用示例请参阅组件指南。
我可以创建自定义组件吗？¶
是的，您可以通过扩展 Component 创建自定义组件。详情请参阅API
参考，逐步说明请参阅贡献指南。
如何向我的数据看板添加图表？¶
使用 ChartComponent：
from django_admin_dashboards.base import ChartComponent
chart = ChartComponent(
title="User Registrations",
chart_type="line",
data={
"labels": ["Jan", "Feb", "Mar", "Apr", "May"],
"datasets": [{
"label": "Registrations",
"data": [65, 59, 80, 81, 56],
"borderColor": "rgb(75, 192, 192)",
}]
},
height="300px"
)
为什么我的表格样式不正确？¶
Django Admin 的 base.CSS 具有侵略性的表格样式，可能会造成干扰。数据看板包含特定的 CSS 来覆盖这些样式。如果仍有问题：
- 确保
dashboard.css已加载（检查浏览器开发者工具） - 使用包含正确样式的
TableComponent - 如果需要，添加具有更高特异性的自定义 CSS
布局¶
布局系统如何工作？¶
布局使用类似于 Bootstrap 的 12 列网格系统。您定义行并为每个组件指定列宽：
def get_layout(self):
layout = Layout(columns=12)
layout.add_row([
(CardComponent(title="Users", value=150), 6), # 6 columns = half width
(CardComponent(title="Orders", value=42), 6), # 6 columns = half width
])
return layout
详细示例请参阅布局系统指南。
我可以使布局响应式吗？¶
是的，数据看板布局默认是响应式的。组件在较小屏幕上会垂直堆叠。如果需要，您可以通过 CSS 媒体查询控制响应式行为。
如何更改组件之间的间距？¶
使用 Layout 类中的 间距 参数：
或调整单独的行：
深色模式¶
深色模式如何工作？¶
深色模式遵循 Django Admin 的主题系统。数据看板会自动检测 Django Admin 何时处于深色模式并应用适当的样式。
我可以强制使用深色或浅色模式吗？¶
是的，使用 URL 参数：
?_dark_mode_on=true- 强制深色模式?_dark_mode_on=false- 强制浅色模式?_dark_mode_on=auto- 遵循 Django Admin 的主题（默认）
详情请参阅深色模式指南。
为什么我的自定义组件不支持深色模式？¶
为了支持深色模式，您的组件的 CSS 需要处理 HTML[数据-主题="dark"]
选择器：
/* Light mode (default) */
.dashboard .my-component {
background: white;
color: black;
}
/* Dark mode */
html[data-theme="dark"] .dashboard .my-component {
background: #1e1e1e;
color: white;
}
全屏模式¶
如何启用全屏模式？¶
按 F11 或使用浏览器的全屏功能。数据看板包含 JavaScript
来处理全屏事件并可选择隐藏周围元素。
hide_others_in_fullscreen 和 force_hide_others 有什么区别？¶
hide_others_in_fullscreen：仅在浏览器全屏模式时隐藏周围元素（页眉、侧边栏等）force_hide_others：无论全屏状态如何，始终隐藏周围元素
两者都需要显式的 URL 参数来激活：
?_hide_others_in_fullscreen=true?_force_hide_others=true
详情请参阅全屏模式指南。
我可以使组件全屏吗？¶
目前不行，但您可以创建使用 CSS 扩展以填充可用空间的自定义组件。
性能¶
数据看板会减慢我的管理界面吗？¶
数据看板设计为高性能。然而，具有许多数据库查询或大型数据集的复杂数据看板可能会影响性能。最佳实践：
- 缓存昂贵查询：使用 Django 的缓存框架
- 限制数据点：仅显示基本信息
- 使用分页：对于多行表格
- 优化数据库查询：使用
select_related和prefetch_related
如何缓存数据看板数据？¶
在您的数据看板类中使用 Django 的缓存：
from django.core.cache import cache
class MyDashboard(Dashboard):
def get_layout(self):
cache_key = f"dashboard_layout_{self.request.user.id}"
layout = cache.get(cache_key)
if not layout:
layout = self.build_layout()
cache.set(cache_key, layout, timeout=300) # Cache for 5 minutes
return layout
def build_layout(self):
# Expensive layout building logic
pass
有任何数据库要求吗？¶
没有特殊的数据库要求。该包使用标准的 Django 模型和查询。
自定义¶
我可以更改数据看板标题吗？¶
是的，在您的数据看板类中设置 title 属性：
class MyDashboard(Dashboard):
title = "My Custom Dashboard"
# Or make it dynamic
def get_title(self):
return f"Dashboard for {self.request.user.username}"
如何更改颜色/主题？¶
数据看板使用 CSS 变量进行主题设置。您可以在项目的 CSS 中覆盖它们：
:root {
--dashboard-primary: #4f46e5;
--dashboard-secondary: #64748b;
--dashboard-success: #10b981;
--dashboard-danger: #ef4444;
--dashboard-warning: #f59e0b;
--dashboard-info: #3b82f6;
}
为了更多控制，创建自定义 CSS 文件并将其包含在数据看板上下文中。
我可以使用不同的图标集吗？¶
数据看板默认使用 Remix Icon。要使用不同的图标集：
- 安装图标包
- 覆盖组件模板以使用不同的图标类
- 更新 CSS 以加载新的图标字体
故障排除¶
我遇到模板错误¶
常见原因及解决方案：
- 模板未找到：确保
DJANGO_ADMIN_DASHBOARDS在INSTALLED_APPS中 - 模板语法错误：检查自定义模板中的拼写错误
- 缺少上下文变量：验证您的数据看板的
get_context方法返回所有必需的变量
启用 Django 调试模式以获取详细错误信息。
JavaScript 不工作¶
检查这些常见问题：
- 控制台错误：打开浏览器开发者工具并检查 Console 标签页
- 静态文件未加载：检查 Network 标签页中的 404 错误
- jQuery 冲突：数据看板使用 Django Admin 自带的 jQuery
- 图表.js 未加载：确保 图表.js 已包含（它与数据看板捆绑在一起）
图表未显示¶
- 检查 图表.js 加载：打开浏览器开发者工具，检查 图表.js 是否已加载
- 验证数据格式：图表数据必须遵循 图表.js 格式
- 检查控制台错误：图表.js 会将错误记录到控制台
- 确保 canvas 元素存在：组件模板包含 canvas 元素
深色模式样式未应用¶
- 检查 数据-主题 属性：确保当深色模式激活时，
HTML元素具有数据-主题="dark" - CSS 特异性：您的自定义 CSS 可能需要更高的特异性
- 缓存问题：清除浏览器缓存
- 检查 URL 参数：
?_dark_mode_on=true应强制深色模式
迁移与升级¶
如何升级到新版本？¶
然后运行：
检查发布说明以了解任何破坏性更改。
升级会破坏我的数据看板吗？¶
我们遵循语义化版本控制：
- 补丁版本 (0.1.x)：向后兼容的错误修复
- 次要版本 (0.x.0)：新功能，向后兼容
- 主要版本 (x.0.0)：破坏性更改（预计在 1.0.0 之前不会发生）
始终先在 staging 环境中测试升级。
如何从旧版本迁移？¶
检查发布说明以获取迁移说明。对于重大更改，我们将提供迁移指南。
贡献指南¶
如何贡献？¶
详情请参阅贡献指南。欢迎贡献！
我应该做什么？¶
检查 Gitee Issues 中的：
- 错误报告
- 功能请求
- 文档改进
- 翻译更新
如何报告错误？¶
在 Gitee 上创建 issue，包含：
- 问题的清晰描述
- 重现步骤
- 预期与实际行为
- 截图（如果适用）
- 环境详细信息
支持¶
在哪里可以获得帮助？¶
- 文档：本常见问题解答和用户指南
- Gitee Issues：用于错误报告和功能请求
- 社区：（如果可用）讨论论坛或聊天
有商业支持吗？¶
目前没有官方的商业支持。对于企业需求，考虑雇佣熟悉该包的 Django 开发人员。
我可以请求功能吗？¶
是的，在 GitHub 上创建功能请求。包含：
- 用例描述
- 预期行为
- 为什么它有价值
- 任何实现想法