Django-Echarts项目基础使用指南：从配置到图表展示-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00146/article/details/148647580

Django-Echarts项目基础使用指南：从配置到图表展示

django-echarts 基于pyecharts和django的可视化网站脚手架。项目地址: https://gitcode.com/gh_mirrors/dj/django-echarts

项目概述

Django-Echarts是一个将Echarts图表库深度集成到Django框架中的解决方案，它提供了完整的站点构建能力和丰富的图表展示功能。本文将详细介绍如何从零开始配置和使用Django-Echarts项目。

一、项目基础配置

1.1 安装与基本设置

首先需要在Django项目的settings.py文件中进行必要配置：

INSTALLED_APPS = [
    # 其他应用...
    'django_echarts',
    'django_echarts.contrib.bootstrap5'  # 选择一个主题
]

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(BASE_DIR, 'templates')],
        'APP_DIRS': True,  # 必须启用
        # 其他选项...
    },
]

STATIC_URL = '/static/'
STATICFILES_DIRS = (os.path.join(BASE_DIR, 'static'),)

DJANGO_ECHARTS = {
    'theme_name': 'bootstrap5.yeti'  # 主题配置
}

1.2 配置项详解

INSTALLED_APPS：必须包含django_echarts核心应用和至少一个主题应用
TEMPLATES：确保APP_DIRS为True以启用模板自动发现
STATIC设置：配置静态文件目录用于存放图表资源
DJANGO_ECHARTS：项目级配置字典，支持多种自定义选项

二、站点初始化与路由配置

2.1 创建站点对象

站点对象是Django-Echarts的核心入口，负责管理所有图表和页面：

from django_echarts.starter.sites import DJESite, SiteOpts

site_obj = DJESite(
    site_title='数据可视化平台',
    opts=SiteOpts(
        list_layout='grid',  # 网格布局
        nav_shown_pages=['home', 'collection'],  # 导航显示项
        paginate_by=10  # 分页设置
    )
)

2.2 路由集成

将站点路由集成到项目主路由中：

from django.urls import path, include

urlpatterns = [
    path('echarts/', include(site_obj.urls)),  # 集成图表站点路由
    # 其他路由...
]

三、图表开发与注册

3.1 基础图表创建

使用装饰器注册图表是最简单的方式：

@site_obj.register_chart
def basic_bar_chart():
    from pyecharts.charts import Bar
    bar = Bar()
    bar.add_xaxis(["衬衫", "羊毛衫", "雪纺衫"])
    bar.add_yaxis("商家A", [5, 20, 36])
    return bar

3.2 高级图表配置

通过装饰器参数提供更多元信息：

@site_obj.register_chart(
    name='sales_trend',
    title='销售趋势分析',
    description='展示季度销售数据变化',
    catalog='业务分析',
    top=1,  # 置顶显示
    tags=['销售', '趋势']
)
def sales_trend_chart():
    # 图表实现...

3.3 性能优化技巧

对于静态数据图表，使用缓存提升性能：

from functools import lru_cache

@site_obj.register_chart
@lru_cache(maxsize=32)
def cached_chart():
    # 复杂图表计算...

四、页面组件开发

4.1 数据面板组件

创建动态数据展示面板：

from django_echarts.entities import ValuesPanel, ValueItem

@site_obj.register_html_widget
def sales_panel():
    panel = ValuesPanel(title="销售数据")
    panel.add_widget(ValueItem(1200, "本月销售额", "万元"))
    panel.add_widget(ValueItem(85, "达成率", "%"))
    return panel

4.2 首页定制

定制首页展示内容：

from django_echarts.entities import Jumbotron, Copyright

site_obj.add_widgets(
    jumbotron=Jumbotron(
        title="欢迎来到数据可视化平台",
        lead_text="探索数据背后的故事"
    ),
    copyright_=Copyright(
        start_year=2020,
        powered_by="Django-Echarts"
    ),
    jumbotron_chart='featured_chart'  # 首页展示的特色图表
)

五、高级功能配置

5.1 列表页优化

布局选择：网格(grid)或列表(list)布局
搜索功能：支持标题、标签和描述的全文搜索
分页控制：通过paginate_by参数设置每页项目数

5.2 导航菜单定制

site_obj.config_nav(
    nav_items=[
        {'name': 'home', 'label': '首页'},
        {'name': 'collection', 'label': '图表集'},
        {'name': 'analysis', 'label': '业务分析'}
    ]
)