Django-Chartit 技术文档

2024-12-25 14:45:11作者：温玫谨Lighthearted

1. 安装指南

Django-Chartit 可以从 PyPI 安装。只需执行以下命令：

$ pip install django_chartit

然后，在 settings.py 文件中将 chartit 添加到 INSTALLED_APPS 中。

INSTALLED_APPS = [
    # 其他应用...
    'chartit',
]

你还需要支持 JavaScript 库。具体细节请参考下文的“所需 JavaScript 库”部分。

2. 项目使用说明

Django-Chartit 用于从数据库中轻松创建图表。图表使用 Highcharts 和 jQuery JavaScript 库渲染。数据库中的数据可以绘制为简单的线图、柱状图、区域图、散点图等多种图表类型。数据还可以作为透视图分组和/或按特定列进行透视。

使用 Django-Chartit 绘制图表或透视图表的步骤如下：

创建一个 DataPool 或 PivotDataPool 对象，指定你需要检索的数据和来源。
创建一个 Chart 或 PivotChart 对象，使用 DataPool 或 PivotDataPool 中的数据绘图。
从 Django 视图函数返回 Chart/PivotChart 对象到 Django 模板。
在 Django 模板中使用 load_charts 模板标签，将图表加载到具有特定 ids 的 HTML 标签中。

3. 项目API使用文档

以下是创建线图的一个简短示例。假设我们有一个包含三个月份和两个城市温度的简单模型：

class MonthlyWeatherByCity(models.Model):
    month = models.IntegerField()
    boston_temp = models.DecimalField(max_digits=5, decimal_places=1)
    houston_temp = models.DecimalField(max_digits=5, decimal_places=1)

假设我们想要创建一个简单的线图，横轴为月份，两个城市的温度作为纵轴：

from chartit import DataPool, Chart

def weather_chart_view(request):
    # 步骤 1: 创建一个 DataPool，包含我们想要检索的数据。
    weatherdata = DataPool(
        series=[
            {
                'options': {
                    'source': MonthlyWeatherByCity.objects.all()
                },
                'terms': [
                    'month',
                    'houston_temp',
                    'boston_temp'
                ]
            }
        ]
    )

    # 步骤 2: 创建 Chart 对象
    cht = Chart(
        datasource=weatherdata,
        series_options=[
            {
                'options': {
                    'type': 'line',
                    'stacking': False
                },
                'terms': {
                    'month': [
                        'boston_temp',
                        'houston_temp'
                    ]
                }
            }
        ],
        chart_options={
            'title': {
                'text': '波士顿与休斯顿的天气数据'
            },
            'xAxis': {
                'title': {
                    'text': '月份'
                }
            }
        }
    )

    # 步骤 3: 将图表对象发送到模板。
    return render_to_response({'weatherchart': cht})

在 Django 模板中，你可以使用 load_charts 过滤器渲染图表：

<head>
    <!-- 引入 highcharts 和 jQuery 库的代码 -->
    {% load chartit %}
    {{ weatherchart|load_charts:"container" }}
</head>
<body>
    <div id='container'>图表将在这里渲染</div>
</body>