pyecharts/docs/release-note/v030.md

pyecharts V0.3.0 发布日志

pyecharts V0.3.0 发布，这是一个重大更新的版本，新增 自定义模板 、 **模板函数 ** 和 web 框架整合 等功能，并修正了一些Bug。

pyecharts V0.3.0 对整个图表渲染和使用场景进行重新思考和设计，重写大量的底层逻辑，使得功能更加明确，代码更加整洁有序。

1 开放底层模板引擎类API，支持模板函数

新增模板引擎类 pyecharts.engine.EchartsEnvironment 和配置类 pyecharts.conf.PyEchartsConfig。

# coding=utf8

from __future__ import unicode_literals

from pyecharts import Bar
from pyecharts.conf import PyEchartsConfig
from pyecharts.engine import EchartsEnvironment
from pyecharts.utils import write_utf8_html_file

attr = ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"]
v1 = [5, 20, 36, 10, 75, 90]
v2 = [10, 25, 8, 60, 20, 80]
bar = Bar("柱状图数据堆叠示例")
bar.add("商家A", attr, v1, is_stack=True)
bar.add("商家B", attr, v2, is_stack=True)
config = PyEchartsConfig(echarts_template_dir='my_tpl', jshost='https://cdn.bootcss.com/echarts/3.6.2')
env = EchartsEnvironment(pyecharts_config=config)
tpl = env.get_template('tpl_demo.html')
html = tpl.render(bar=bar)
write_utf8_html_file('my_tpl_demo2.html', html)

pyecharts V0.3.0 提供了一些模板函数，这些函数通常接收一个或多个的 Chart 或 Page 的参数，详细的调用形式见下表。

标签/调用形式	F(chart)	F(page)	F(chart1,chart2,...)/F(*page)
echarts_js_dependencies	✓	✓	✓
echarts_js_dependencies_embed	✓	✓	✓
echarts_container	✓
echarts_js_content	✓	✓	✓
echarts_js_content_wrap	✓	✓	✓

2 重写图表render函数逻辑，新增自定义模板文件

render 函数签名为：

Chart.render(
    path='render.html',
    template_name='simple_chart.html',
    object_name='chart',
    extra_context=None
)

各参数的意义如下：

• path ：最终生成文件名称
• template_name: 模板文件名称，其目录可通过 pyecharts.configure() 全局函数进行配置
• object_name: 模板文件中，该图表类所使用变量的名称
• extra_context 额外数据字典。

内部实现逻辑也有所变化：

• 现在每次调用 render 函数都会重新创建一个新的模板引擎对象（jinja2.Environment 的子类），这在同时渲染多个图表时，耗时有所增加，如果对耗时有所考虑，可依据第1节所述的方式自行创建模板引擎对象。
• 现在 Python 函数传递给模板的是图表实例本身，而不再是其属性组成的字典。

3 新增统一配置函数 pyecharts.configure

新增统一的配置函数 pyecharts.configure ，在构建渲染图表之前使用该函数可统一配置你所需要的参数，每个参数都有默认值。

原有的 online 不再推荐使用，可用 configure 函数代替。

# 旧版本
pyecharts.online('http://demo') 
# 新版本
pyecharts.configure(jshost='http://demo')

4 支持js文件外链引用方式

在HTML代码中，js引入方式共有两种，外部链接方式

<script type="text/javascript" src="https://cdn.bootcss.com/echarts/3.7.0/echarts.min.js"></script>

内部嵌入方式

<script type="text/javascript">
var s = '';
//...
</script>

在 V0.2.X 中，pyecharts 只支持内部嵌入方式，即使通过 pyecharts.online('https://cdn.bootcss.com/echarts/3.7.0') ，将 js 仓库设置为远程地址，最后生成的 HTML 代码也是使用内部嵌入方式，这不利于 web 项目的整合工作。

在 V0.3.0 中，上述行为将默认采用外部链接方式引入 js 文件，但其 js 文件有效性需由使用者自行保证；同时也可以通过 force_embed 参数强制采用内部嵌入方式。

5 Page支持列表协议和自定义布局

pyecharts.custom.Page 直接继承 list 类，也能支持长度(len)、索引(index)、切片(splice)、添加(append)、扩展(extend)等操作。

相应的，Page 类移除了 charts 属性，目前可直接迭代 Page 对象本身。

Page 默认采用纵向列表布局渲染多个图表，可以通过使用自己的模板文件来采用其他布局。

6 更容易整合web框架

pyecharts 现在和 web 框架的整合工作变得十分容易，无论你是刚开始开发 web 项目还是整合已有的项目。这主要得益于 python 语言的灵活性和面向对象特点，使得整合工作不会破坏原有的功能和代码层次结构。

pyecharts 已经开放内部的 jinja2 模板引擎相关接口，因此从理论上来说，pyecharts 能够胜任那些使用 jinja2 模板引擎的 web 框架。

下面分别以 Django 和 Flask 为例子，描述如何与 pyecharts 进行整合。

Django + jinja2 + pyecharts

Django 1.8 内置了对 jinja2 的支持，使得通过简单的配置也可以在 Django 模板文件中使用 jinja2 的一些独有特性。

根据 Django自定义模板引擎 教程，主要将其中 jinja2.Environment 改变为其子类 pyecharts.engine.BaseEnvironment 即可。

from django.contrib.staticfiles.storage import staticfiles_storage
from django.urls import reverse

from pyecharts.conf import PyEchartsConfig
from pyecharts.engine import BaseEnvironment


def environment(**options):
    env = BaseEnvironment(pyecharts_config=PyEchartsConfig(jshost='/static/'), **options)
    # Add template functions to the environment object
    env.globals.update({
        'static': staticfiles_storage.url,
        'url': reverse,
    })
    return env

其余配置方式请参考官方文档。

背后原理： pyecharts.engine.BaseEnvironment 直接继承 jinja2.Environment ，并添加了以下 pyecharts 特性到模板引擎类：

• 配置属性 pyecharts_config
• 模板函数

Flask + pyecharts

Flask 应用也支持自定义模板引擎，但是其默认的引擎类 flask.templating.Environment 也实现了自己的一些特性，因此无法直接使用 pyecharts.engine.BaseEnvironment ，需手动添加。如下。

from __future__ import unicode_literals

import random
import datetime

from flask import Flask, render_template
from flask.templating import Environment

from pyecharts import HeatMap
from pyecharts.engine import PyEchartsConfigMixin, ECHAERTS_TEMPLATE_FUNCTIONS
from pyecharts.conf import PyEchartsConfig

class FlaskEchartsEnvironment(Environment, PyEchartsConfigMixin):
    pyecharts_config = PyEchartsConfig(
        jshost='https://cdn.bootcss.com/echarts/3.7.2'
    )

    def __init__(self, *args, **kwargs):
        super(FlaskEchartsEnvironment, self).__init__(*args, **kwargs)
        self.globals.update(ECHAERTS_TEMPLATE_FUNCTIONS)

class MyFlask(Flask):
    jinja_environment = FlaskEchartsEnvironment

app = MyFlask(__name__)

之后和标准的 Flask 项目一样使用。

总结

以上两种使用场景基本上代表大多数的 web 框架的整合思路。两种的方式的区别是是否能够直接使用 pyecharts.engine.BaseEnvironment 。如果框架或项目已有模板引擎类，就只能继承该模板引擎类，相关 pyecharts 特性需手动自行添加。

7 其他改变

其他微小变更，包括变量重命名、函数定义改变等。

• pyecharts.utils.get_resource_dir(*paths) 目前支持不定参数调用。
• 图表 width 和 height 支持 '50%' 、'78px' 等其他 css 有效长度形式。
• pyecharts.base.json_dumps 移到 pyecharts.utils.json_dumps 。
• 移除 pyecharts.template.JINJA2_EVN 对象。
• 移除 pyecharts.constants.CONFIGURATION 。

8 参考资料

• 在 Django 框架中使用 jinja2 https://docs.djangoproject.com/en/1.11/topics/templates/#django.template.backends.jinja2.Jinja2
• 在 Flask 使用自定义模板引擎 http://flask.pocoo.org/docs/0.12/api/#flask.Flask.jinja_environment