数据看板 API 参考

Dashboard 类是 Django Admin Dashboards 的基础。本文档涵盖了所有方法、属性和配置选项。

目录

概述

什么是数据看板？

数据看板是一个 Python 类，用于定义：

1. 布局结构：组件如何排列
2. 数据源：数据来自何处
3. 配置：显示设置和行为
4. 集成：如何与 Django Admin 连接

基类层次结构

    Component (基类)
    ├── CardComponent
    ├── ChartComponent
    ├── FilterComponent
    └── TableComponent

    Layout (布局管理器)
    Dashboard (主数据看板类)

导入路径

    from django_admin_dashboards.base import Dashboard

类参考

Dashboard 类

    class Dashboard:
        """具有灵活布局的数据看板类"""

        # 核心属性

        title = None
        template_name = "admin/dashboard.html"
        layout = None

        # 显示设置

        show_dashboard_title = True
        show_admin_title = False

        # 全屏控制

        hide_others_in_fullscreen = False
        force_hide_others = False

        # 媒体资源

        class Media:
            css = {
                "all": (
                    "django_admin_dashboards/css/dashboard.css",
                    "remixicon/remixicon.css",
                )
            }
            js = ("django_admin_dashboards/js/chart.umd.js",)

        def __init__(self, request=None):
            """使用可选请求初始化数据看板"""

        @property
        def media(self):
            """返回数据看板的媒体资源"""

        def get_context_data(self, request, **kwargs):
            """获取用于数据看板渲染的上下文数据"""

        def get_layout(self):
            """创建并返回布局 - 在子类中重写此方法"""

属性

核心属性

属性	类型	默认值	描述
title	str 或 gettext_lazy	None	在界面中显示的数据看板标题（可选，为空时不显示）
template_name	str	"admin/dashboard.html"	用于渲染的模板
layout	Layout 或 None	None	布局管理器实例（自动创建）

显示设置

属性	类型	默认值	描述
show_dashboard_title	bool	True	在界面中显示数据看板标题
show_admin_title	bool	False	显示 Django Admin 的默认标题

全屏控制

属性	类型	默认值	描述
hide_others_in_fullscreen	bool	False	启用全屏隐藏功能（需要 URL 参数）
force_hide_others	bool	False	启用强制隐藏功能（需要 URL 参数）

媒体配置

Media 内部类定义静态资源：

    class Media:
        css = {
            "all": (
                "django_admin_dashboards/css/dashboard.css",
                "remixicon/remixicon.css",
            )
        }
        js = ("django_admin_dashboards/js/chart.umd.js",)

CSS 资源：

• dashboard.css：核心数据看板样式 - remixicon.css：组件图标库

JavaScript 资源：

• chart.umd.js：图表组件使用的 Chart.js 库

特性

media

类型：django.forms.widgets.Media

访问：只读

返回数据看板的聚合媒体资源（CSS/JS）。

    dashboard = MyDashboard()
    media = dashboard.media
    # 访问 CSS：media._css

    # 访问 JS：media._js

hide_others_in_fullscreen (属性)

类型：bool

访问：只读

指示全屏隐藏模式是否激活。

行为：

1. 检查类属性 hide_others_in_fullscreen = True
2. 检查 URL参数 _hide_others_in_fullscreen=true
3. 两个条件必须同时满足，属性才返回True

    # 在数据看板类中

    hide_others_in_fullscreen = True

    # 在模板中

    {% if dashboard.hide_others_in_fullscreen %}

    {% endif %}

force_hide_others (属性)

类型：bool

访问：只读

指示强制隐藏模式是否激活。

行为：

1. 检查类属性force_hide_others = True
2. 检查 URL 参数_force_hide_others=true
3. 两个条件必须同时满足，属性才返回True

    # 在数据看板类中

    force_hide_others = True

    # 在模板中

    {% if dashboard.force_hide_others %}

    {% endif %}

方法

__init__(request=None)

参数：

• request (django.http.HttpRequest, 可选)：当前 HTTP 请求

描述：

初始化数据看板实例。如果 layout 为 None，则调用 get_layout() 创建布局。

使用：

    # 无请求（用于测试）

    dashboard = MyDashboard()

    # 有请求（在视图中）

    dashboard = MyDashboard(request=request)

get_context_data(request, **kwargs)

参数：

• request (django.http.HttpRequest)：当前 HTTP 请求
• **kwargs：额外的上下文数据

返回：

dict - 模板上下文字典

描述：

准备用于模板渲染的上下文数据。此方法：

1. 处理组件上下文
2. 将上下文数据合并到组件对象中
3. 返回完整的上下文字典

默认上下文：

    {
        "title": self.title,
        "dashboard": self,
        "request": request,
        "layout": self.layout,
        "show_dashboard_title": self.show_dashboard_title,
        "show_admin_title": self.show_admin_title,
        "hide_others_in_fullscreen": self.hide_others_in_fullscreen,
        "force_hide_others": self.force_hide_others,
    }

重写示例：

    def get_context_data(self, request, **kwargs):
        context = super().get_context_data(request, **kwargs)

        # 添加自定义上下文

        context['custom_data'] = self.get_custom_data(request)
        context['timestamp'] = timezone.now()

        return context

get_layout()

返回：

Layout - 布局管理器实例

描述：

创建并返回布局结构。必须在子类中重写。

基类实现：

返回 None（必须重写）

示例实现：

    def get_layout(self):
        layout = Layout(columns=12)

        # 创建组件

        card = CardComponent(title="Users", value=100)
        chart = ChartComponent(
            title="User Growth",
            chart_type="line",
            data={"labels": ["Jan", "Feb"], "datasets": [{"data": [10, 20]}]}
        )

        # 添加到布局

        layout.add_row([(card, 6), (chart, 6)])

        return layout

配置示例

数据看板

    from django_admin_dashboards.base import Dashboard, Layout, CardComponent

    class BasicDashboard(Dashboard):
        title = "My Dashboard"

        def get_layout(self):
            layout = Layout(columns=12)

            card = CardComponent(
                title="Total Users",
                value=150,
                change="+5%",
                color="primary",
                icon_class="ri-user-line"
            )

            layout.add_row([(card, 12)])
            return layout

支持全屏的数据看板

    class PresentationDashboard(Dashboard):
        title = "Presentation Mode"

        # 启用全屏功能

        hide_others_in_fullscreen = True
        force_hide_others = False

        # 自定义显示设置

        show_dashboard_title = True
        show_admin_title = False

        def get_layout(self):
            layout = Layout(columns=12)

            # 为演示优化的布局

            components = self.get_presentation_components()

            # 用于演示的全宽组件

            for component in components:
                layout.add_row([(component, 12)])

            return layout

动态数据看板

    class DynamicDashboard(Dashboard):
        title = "Dynamic Dashboard"

        def __init__(self, request=None):
            super().__init__(request)

            # 存储请求以供后续使用

            self._user_request = request

        def get_layout(self):
            layout = Layout(columns=12)

            # 基于请求动态创建组件

            if self._user_request and self._user_request.user.is_superuser:
                components = self.get_admin_components()
            else:
                components = self.get_user_components()

            # 排列组件

            for i, component in enumerate(components):
                width = 6 if i % 2 == 0 else 6
                if i == len(components) - 1 and i % 2 == 0:
                    width = 12
                layout.add_component(component, width=width)

            return layout

多语言数据看板

    from django.utils.translation import gettext_lazy as _

    class InternationalDashboard(Dashboard):
        # 使用 gettext_lazy 进行翻译

        title = _("Dashboard")

        def get_layout(self):
            layout = Layout(columns=12)

            # 翻译的组件

            card = CardComponent(
                title=_("User Statistics"),
                value=100,
                change=_("Increased"),
                color="primary"
            )

            layout.add_row([(card, 12)])
            return layout

与 Django Admin 集成

数据看板发现

框架提供了一个实用函数，用于基于 Django Admin 视图获取数据看板：

    from django_admin_dashboards.base import get_dashboard_for_view

    # 获取管理员首页的数据看板

    dashboard_class = get_dashboard_for_view("admin:index")

    # 获取特定应用的数据看板

    dashboard_class = get_dashboard_for_view("admin:app_list", app_label="auth")

设置配置

在 settings.py 中配置数据看板：

    DJANGO_ADMIN_DASHBOARDS = {
        # 管理员首页数据看板

        "admin:index": "myapp.dashboards.MyDashboard",

        # 应用特定数据看板

        "admin:app_list": {
            "auth": "django_admin_dashboards.contrib.auth.dashboard.AuthAppDashboard",
            "myapp": "myapp.dashboards.AppDashboard",
        },
    }

模板集成

Django Admin Dashboards 与 Django Admin 模板集成：

admin/index.html（默认数据看板模板）：

    {% extends "admin/base_site.html" %}
    {% load dashboard_tags %}

    {% block content %}
        {% dashboard %}
    {% endblock %}

自定义模板：

    {% extends "admin/base_site.html" %}
    {% load dashboard_tags %}

    {% block extrastyle %}
        {{ block.super }}
        {{ dashboard.media.css }}
    {% endblock %}

    {% block extrahead %}
        {{ block.super }}
        {{ dashboard.media.js }}
    {% endblock %}

    {% block content %}
        <div class="dashboard-container">
            {% if dashboard.show_dashboard_title %}
                <h1 class="dashboard-title">{{ dashboard.title }}</h1>
            {% endif %}

            {% include "admin/dashboard_layout.html" %}
        </div>
    {% endblock %}

高级使用

自定义媒体资源

扩展 Media 类以添加自定义资源：

    class CustomMediaDashboard(Dashboard):

        class Media:
            css = {
                "all": (
                    "django_admin_dashboards/css/dashboard.css",
                    "remixicon/remixicon.css",
                    "myapp/css/custom.css",  # 自定义 CSS

                )
            }
            js = (
                "django_admin_dashboards/js/chart.umd.js",
                "myapp/js/custom.js",  # 自定义 JavaScript

            )

        @property
        def media(self):
            media = super().media
            # 动态添加额外媒体

            media.add_css({"all": ("myapp/css/dynamic.css",)})
            return media

基于请求的配置

根据请求参数配置数据看板：

    class ParameterizedDashboard(Dashboard):

        def get_context_data(self, request, **kwargs):
            context = super().get_context_data(request, **kwargs)

            # 读取 URL 参数

            view_mode = request.GET.get('view', 'standard')
            refresh_rate = request.GET.get('refresh', 30)

            # 添加到上下文

            context['view_mode'] = view_mode
            context['refresh_rate'] = refresh_rate

            # 根据参数调整布局

            if view_mode == 'minimal':
                self.layout = self.get_minimal_layout()
            elif view_mode == 'detailed':
                self.layout = self.get_detailed_layout()

            return context

数据看板继承

通过继承创建专门的数据看板：

    class BaseDashboard(Dashboard):
        """具有通用功能的数据看板"""

        title = "Base Dashboard"

        def get_common_components(self):
            """返回所有数据看板通用的组件"""
            return [
                CardComponent(title="System Status", value="OK", color="success"),
                CardComponent(title="Last Updated", value=timezone.now().date()),
            ]

    class UserDashboard(BaseDashboard):
        """用户特定数据看板"""

        title = "User Dashboard"

        def get_layout(self):
            layout = Layout(columns=12)

            # 添加通用组件

            common = self.get_common_components()
            layout.add_row([(common[0], 6), (common[1], 6)])

            # 添加用户特定组件

            user_components = self.get_user_components()
            for component in user_components:
                layout.add_component(component, width=6)

            return layout

    class AdminDashboard(BaseDashboard):
        """管理员特定数据看板"""

        title = "Admin Dashboard"

        def get_layout(self):
            layout = super().get_layout()  # 获取基础布局

            # 添加仅管理员组件

            admin_components = self.get_admin_components()
            for component in admin_components:
                layout.add_component(component, width=4)

            return layout

最佳实践

1. 使用描述性标题

    # 良好

    title = "User Analytics Dashboard"

    # 避免

    title = "Dashboard"

2. 实现 get_layout() 方法

始终在子类中实现 get_layout()：

    def get_layout(self):
        """返回数据看板布局 - 必需"""
        layout = Layout(columns=12)
        # ... 创建和排列组件

        return layout

3. 优雅处理缺失数据

    def get_cards(self):
        try:
            user_count = User.objects.count()
        except DatabaseError:
            user_count = 0  # 出错时的默认值

        return CardComponent(
            title="Users",
            value=user_count,
            color="primary" if user_count > 0 else "secondary"
        )

4. 缓存昂贵操作

    from django.core.cache import cache

    class CachedDashboard(Dashboard):

        def get_user_stats(self):
            cache_key = f"dashboard_user_stats_{self._request.user.pk}"
            stats = cache.get(cache_key)

            if not stats:
                stats = self.calculate_user_stats()  # 昂贵操作

                cache.set(cache_key, stats, timeout=300)  # 缓存 5 分钟

            return stats

5. 测试数据看板渲染

    from django.test import TestCase
    from django.test.client import RequestFactory

    class DashboardTests(TestCase):

        def test_dashboard_creation(self):
            dashboard = MyDashboard()
            self.assertIsNotNone(dashboard)

        def test_dashboard_layout(self):
            dashboard = MyDashboard()
            layout = dashboard.get_layout()
            self.assertIsNotNone(layout)
            self.assertGreater(len(layout.rows), 0)

        def test_dashboard_context(self):
            factory = RequestFactory()
            request = factory.get('/admin/')

            dashboard = MyDashboard(request)
            context = dashboard.get_context_data(request)

            self.assertIn('dashboard', context)
            self.assertIn('layout', context)

常见问题与解决方案

数据看板不显示

问题：

数据看板未在 Django Admin 中显示。

解决方案：

1. 检查settings.DJANGO_ADMIN_DASHBOARDS配置
2. 验证get_dashboard_for_view()返回正确的类
3. 确保模板使用{% dashboard %}标签

布局不渲染

问题：

组件不显示或布局为空。

解决方案：

1. 在子类中实现 get_layout() 方法
2. 检查组件是否已添加到布局
3. 验证组件初始化

媒体资源未加载

问题：

CSS/JS 文件未加载。

解决方案：

1. 检查 Media 类配置
2. 验证静态文件已收集（collectstatic）
3. 确保模板包含{{ dashboard.media.css }}和{{ dashboard.media.js }}

全屏控制不起作用

问题：

URL 参数不影响数据看板。

解决方案：

1. 在数据看板类中设置hide_others_in_fullscreen = True或force_hide_others = True
2. 使用正确的URL参数（?_hide_others_in_fullscreen=true）
3. 检查JavaScript控制台是否有错误

API 参考摘要

方法/属性	描述	返回
__init__(request)	初始化数据看板	Dashboard 实例
get_context_data(request)	获取模板上下文	dict
get_layout()	创建布局（需重写）	Layout
media	CSS/JS 资源	Media
hide_others_in_fullscreen	全屏隐藏状态	bool
force_hide_others	强制隐藏状态	bool
title	数据看板标题	str
template_name	模板路径	str
show_dashboard_title	显示标题标志	bool
show_admin_title	显示管理员标题标志	bool

相关文档

• 组件 API - 组件类和使用
• 布局 API - 布局管理和配置
• URL 控制指南 - 通过 URL 参数控制数据看板
• 创建数据看板 - 逐步创建数据看板

---