v0.6.x Devlopment Note(2023)

[kinegratii]

1 运行环境支持

django-echarts v0.6.0默认使用 pyecharts 2.x 作为底层渲染库，其最大的变化是 echarts 版本由 4.8 升级至 5.4。

django-echarts 依赖库更新如下：

pyecharts 1.9 -> 2.0
typing_extensions 4.0 -> 4.5
borax 3.5 -> 4.0

2 图表构建函数支持自定义参数

图表构建函数支持自定义参数，可以根据不同的输入值，加载不同的数据，从而形成多个图表。

以之前的时间轴图表为例子，每次只显示一个年份的数据图表。

@site_obj.register_chart(title='{year}年福建省家庭户类型组成')
def yearly_family(year: int):
    family_types = [
        '一人户', '二人户', '三人户', '四人户', '五人户', '六人户', '七人户', '八人户', '九人户', '十人及其以上'
    ]
    data = [
        [1982, 7.7, 8.2, 12.2, 17.1, 18.4, 14.7, 10.1, 11.6, 0, 0],
        [1990, 5.8, 8.6, 16.8, 23.6, 21.4, 11.8, 5.9, 2.9, 1.4, 1.8],
        [2000, 9.1, 15.5, 25.4, 24.7, 15.8, 5.9, 2.2, 0.8, 0.3, 0.3],
        [2010, 12.1, 17.2, 24.3, 21.7, 13.7, 6.4, 2.6, 1.1, 0.5, 0.4],
        [2020, 27.3, 26.3, 19.4, 14.2, 6.9, 4, 1.1, 0.4, 0.2, 0.2]
    ]
    yearly_data = {item[0]: item[1:] for item in data}
    if year not in yearly_data:
        raise ChartDoesNotExist(f'year={year}')
    year_data = yearly_data[year]
    bar = (
        Bar()
            .add_xaxis(family_types).add_yaxis('百分比(%)', year_data)
            .set_global_opts(title_opts=opts.TitleOpts("福建省家庭户类型构成-{}年".format(year)))
    )
    return bar

说明：

• year为自定义参数，如未声明类型，默认为 str。
• 如果传入的year找不到对应的数据，抛出 ChartDoesNotExist 异常，web页面显示“找不到图表”的页面。
• title参数可以使用类似 {year}的模板字符串。

该图表对应的相关引用配置如下(以year=2020例子)：

项目	值	备注
图表URL	/chart/year/2020/	格式：<图表slug>/<参数名称1>/<参数值1>/...
python引用	reverse_lazy('dje_single_chart','yearly_family','year/2020/')
模板引用	{% url 'dje_single_chart' 'yearly_family', 'year/2020/' %}

2 新增声明式导航栏配置

django-echarts 0.6 新增了使用字典方式一次性配置导航栏配置。

# site_config.py

nav_config = {
    'nav_left': ['home', 'list'],
    'nav_right': ['settings'],
    'nav_footer': [
        {'text': '项目主页', 'slug': 'project_url', 'url': 'https://github.com/kinegratii/django-echarts'}
    ]
}

# urls.py

site_obj.config_nav(nav_config)

3 DJESite类移除导航栏相关方法

可使用 DJESite.nav 相关方法，参见下面的Nav API章节。

• DJESite.add_left_link
• DJESite.add_right_link
• DJESite.add_footer_link
• DJESite.add_menu_item

4 ChartInfo和ChartInfoManager

• 类 ChartInfo 增加 is_bound 布尔值属性，如果对应图表注册函数携带任何参数，则设置为 False，数据格式化后变为True。
• ChartInfoManagerMixin.get_or_none 增加 uri 参数。
• 在 is_bound = False 情况下，body title description的转义处理