配置

Django Admin Dashboards 在项目中的完整配置参考。

目录

• 基础配置
• 数据看板映射
• 导航配置
• 数据看板类设置
• URL 参数控制
• 高级设置
• 环境特定配置
• 配置故障排除
• 下一步

基础配置

必需设置

添加到您的 settings.py：

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.contrib.admin` 之前。

### 数据看板配置 {#dashboard-configuration}

```python
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.UserDashboard",
        ("myapp", "product"): "myapp.dashboards.ProductDashboard",
    },
}

数据看板映射

可用视图类型

视图类型	描述	示例
admin:index	管理首页	"admin:index": "path.to.Dashboard"
admin:app_list	应用程序列表页面	"admin:app_list": {"app_label": "path.to.Dashboard"}
admin:app_model_changelist	模型更改列表	"admin:app_model_changelist": {("app", "model"): "path.to.Dashboard"}

回退行为

如果未为视图配置数据看板，Django Admin Dashboards 将：

1. 检查应用程序特定的数据看板
2. 检查模型特定的数据看板
3. 回退到默认的 Django Admin 视图

多数据看板配置

DJANGO_ADMIN_DASHBOARDS = {
    # 管理首页的默认数据看板
    "admin:index": "django_admin_dashboards.contrib.auth.dashboard.AuthAppDashboard",

    # 应用程序特定的数据看板
    "admin:app_list": {
        "auth": "django_admin_dashboards.contrib.auth.dashboard.AuthAppDashboard",
        "sales": "sales.dashboards.SalesDashboard",
        "inventory": "inventory.dashboards.InventoryDashboard",
    },

    # 模型特定的数据看板（更细粒度）
    "admin:app_model_changelist": {
        ("sales", "order"): "sales.dashboards.OrderDashboard",
        ("sales", "customer"): "sales.dashboards.CustomerDashboard",
        ("inventory", "product"): "inventory.dashboards.ProductDashboard",
    },
}

导航配置

使用 Django Admin Global Sidebar

# 推荐以获得最佳用户体验
DJANGO_ADMIN_GLOBAL_SIDEBAR_MENUS = [
    {
        "title": "首页",  # Home
        "url": "/admin/",
        "icon": "fas fa-home",
        "active": True,  # 可选：标记为活动
    },
    {
        "title": "销售管理",  # Sales Management
        "icon": "fas fa-chart-line",
        "children": [
            {
                "title": "数据看板",  # Dashboard
                "url": "/admin/",
                "icon": "fas fa-tachometer-alt",
            },
            {
                "title": "订单管理",  # Order Management
                "url": "/admin/sales/order/",
                "icon": "fas fa-shopping-cart",
            },
            {
                "title": "客户管理",  # Customer Management
                "url": "/admin/sales/customer/",
                "icon": "fas fa-users",
            },
        ],
    },
    {
        "title": "库存管理",  # Inventory Management
        "icon": "fas fa-boxes",
        "children": [
            {
                "title": "产品管理",  # Product Management
                "url": "/admin/inventory/product/",
                "icon": "fas fa-box",
            },
            {
                "title": "库存报表",  # Inventory Report
                "url": "/admin/inventory/report/",
                "icon": "fas fa-chart-bar",
            },
        ],
    },
    {
        "title": "系统设置",  # System Settings
        "icon": "fas fa-cog",
        "children": [
            {
                "title": "用户管理",  # User Management
                "url": "/admin/auth/user/",
                "icon": "fas fa-user-cog",
            },
            {
                "title": "权限设置",  # Permission Settings
                "url": "/admin/auth/group/",
                "icon": "fas fa-shield-alt",
            },
        ],
    },
]

图标配置

# FontAwesome 图标（推荐）
"icon": "fas fa-home"
"icon": "fas fa-chart-line"
"icon": "fas fa-users"

# Remix Icon（如果已安装）
"icon": "ri-home-line"
"icon": "ri-pie-chart-line"
"icon": "ri-user-line"

数据看板类设置

基础数据看板属性

创建自定义数据看板类时，配置这些属性：

class MyDashboard(Dashboard):
    # 可选：数据看板标题（为空时不显示）
    title = _("我的数据看板")

    # 可选：控制标题显示
    show_dashboard_title = True  # 显示数据看板标题
    show_admin_title = False     # 隐藏默认管理标题

    # 可选：模板自定义
    template_name = "admin/dashboard.html"  # 默认模板

    # 可选：全屏功能
    hide_others_in_fullscreen = True   # 启用全屏隐藏功能
    force_hide_others = False          # 启用力隐藏功能

    # 可选：媒体资源覆盖
    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
        )

媒体配置

添加自定义 CSS/JS

class CustomDashboard(Dashboard):
    class Media:
        css = {
            "all": (
                "django_admin_dashboards/css/dashboard.css",
                "remixicon/remixicon.css",
                # 添加您的自定义样式表
                "css/custom-dashboard.css",
                "css/theme-overrides.css",
            )
        }
        js = (
            "django_admin_dashboards/js/chart.umd.js",
            # 添加您的自定义脚本
            "js/dashboard-extensions.js",
            "js/data-refresh.js",
        )

覆盖默认媒体资源

class MinimalDashboard(Dashboard):
    class Media:
        css = {
            "all": (
                "django_admin_dashboards/css/dashboard.css",
                # 如果不需要则不包含 remixicon
            )
        }
        js = (
            # 如果不使用图表则不包含 Chart.js
        )

URL 参数控制

深色模式控制

参数	值	描述
_dark_mode_on	true	强制深色模式
_dark_mode_on	false	强制浅色模式
_dark_mode_on	auto	跟随 Django 管理主题

示例： - /admin/?_dark_mode_on=true - /admin/?_dark_mode_on=false - /admin/?_dark_mode_on=auto

全屏控制

参数	值	描述	需要数据看板支持
_hide_others_in_fullscreen	true/false	在全屏模式下隐藏周围元素	hide_others_in_fullscreen = True
_force_hide_others	true/false	始终隐藏周围元素	force_hide_others = True

示例： - /admin/?_hide_others_in_fullscreen=true - /admin/?_force_hide_others=true

组合参数

可以组合多个参数：

# 深色模式 + 全屏隐藏
/admin/?_dark_mode_on=true&_hide_others_in_fullscreen=true

# 浅色模式 + 强制隐藏
/admin/?_dark_mode_on=false&_force_hide_others=true

Advanced Settings

Custom Dashboard Discovery

# Auto-discover dashboards in apps
def auto_discover_dashboards():
    import importlib
    import pkgutil
    from django.conf import settings

    dashboards = {}

    for app in settings.INSTALLED_APPS:
        try:
            module = importlib.import_module(f"{app}.dashboards")
            for attr_name in dir(module):
                attr = getattr(module, attr_name)
                if isinstance(attr, type) and issubclass(attr, Dashboard) and attr != Dashboard:
                    # Auto-register dashboard
                    view_name = getattr(attr, 'default_view', 'admin:index')
                    dashboards[view_name] = f"{app}.dashboards.{attr_name}"
        except ImportError:
            continue

    return dashboards

# Merge with existing configuration
DJANGO_ADMIN_DASHBOARDS = {
    **auto_discover_dashboards(),
    **DJANGO_ADMIN_DASHBOARDS,  # Manual configurations take precedence
}

Performance Optimization

# Cache dashboard configurations
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
        'LOCATION': 'dashboard-cache',
    }
}

# Cache dashboard rendering (optional)
DJANGO_ADMIN_DASHBOARDS_CACHE_TIMEOUT = 300  # 5 minutes

Security Settings

# Restrict dashboard access by permission
DJANGO_ADMIN_DASHBOARDS_PERMISSION_REQUIRED = {
    "admin:index": "auth.view_user",  # Require user view permission
    "admin:app_list": {
        "auth": "auth.view_user",
        "sales": "sales.view_dashboard",
    },
}

# Custom permission check function
def check_dashboard_permission(request, dashboard_class):
    """Custom permission checking"""
    if request.user.is_superuser:
        return True
    # Add custom logic
    return hasattr(request.user, 'can_access_dashboard')

Localization Settings

# Language configuration
LANGUAGE_CODE = 'zh-hans'  # Chinese (Simplified)
# LANGUAGE_CODE = 'en-us'  # English

TIME_ZONE = 'Asia/Shanghai'
USE_I18N = True
USE_L10N = True
USE_TZ = True

# Available languages
LANGUAGES = [
    ('zh-hans', '简体中文'),
    ('en', 'English'),
]

# Translation files location
LOCALE_PATHS = [
    BASE_DIR / 'locale',
]

Environment-Specific Configuration

Development Settings

# development.py
DEBUG = True
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

# Enable debug toolbar
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE = ['debug_toolbar.middleware.DebugToolbarMiddleware'] + MIDDLEWARE
INTERNAL_IPS = ['127.0.0.1']

# Disable caching for development
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.dummy.DummyCache',
    }
}

Production Settings

# production.py
DEBUG = False
ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']

# Security settings
SECURE_SSL_REDISRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

# Performance
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/1',
    }
}

# Static files served by web server
STATIC_ROOT = '/var/www/yourproject/staticfiles'

Troubleshooting Configuration

Common Issues

1. Dashboard Not Appearing

# Check: App order in INSTALLED_APPS
INSTALLED_APPS = [
    "django_admin_dashboards",  # Must be before django.contrib.admin
    "django_static_remixicon",
    "django.contrib.admin",  # After dashboard apps
    # ...
]

2. Missing Icons

# Run collectstatic
python manage.py collectstatic

# Check remixicon is installed
pip list | grep django-static-remixicon

3. Template Errors

# Ensure APP_DIRS is True
TEMPLATES = [
    {
        'APP_DIRS': True,  # This enables app template loading
        # ...
    }
]

4. Static Files Not Loading

# Check static files configuration
python manage.py findstatic django_admin_dashboards/css/dashboard.css

# Check DEBUG mode
# In development: DEBUG = True
# In production: run collectstatic and configure web server

Debug Configuration

Add to settings.py for debugging:

# Enable detailed logging
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django_admin_dashboards': {
            'handlers': ['console'],
            'level': 'DEBUG',
        },
    },
}

# Enable template debugging
TEMPLATES = [
    {
        'OPTIONS': {
            'string_if_invalid': 'INVALID: %s',  # Shows invalid template variables
        },
    },
]

Next Steps

• Creating Dashboards - Learn how to create custom dashboards
• Components Guide - Detailed component documentation
• Layout System - Advanced layout configuration
• Examples - Real-world configuration examples

---