本文档描述了 pyecharts 库一些公开的 API，以供开发者之使用。
总体流程
一个通用的 pyecharts 使用流程可描述如下：
步骤
简略代码
备注
1 创建图表实例
bar = Bar()
2 添加数据
bar.add(**kwargs)
3 创建配置实例
config = PyEchartsConfig(**kwargs)
4 构建模板引擎
engine = EchartsEnvironment(pyecharts_config=config)
5 获取模板文件
tpl = engine.get_template('demo_tpl.html')
6 渲染
html = tpl.render(bar=bar)
7 写入目标文件
write_utf8_html_file('my_demo_chart.html', html)
pyecharts 配置项
pyecharts 遵循 “先配置后使用” 的基本原则，所有的配置项将统一于类 pyecharts.conf.PyEChartsConfig 类中。
如果使用 chart.render() 这种渲染方式，可以通过模块函数 configure 进行修改 pyecharts 中默认的配置类。
import pyecharts
pyecharts.configure(P1=V1, P2=V2,...)
配置列表
echarts_template_dir
模板文件目录，默认值：'.'(当前目录)。用于自定义模板文件，即 render 的 template_name 参数构成全部的路径。
jshost
js 文件仓库路径。可以设置本地或者远程地址。所有的远程地址必须以 http:// 或者 https:// 开头。
也可以使用 pyecharts.online() 函数设置此选项。
为了保持兼容性， jshost 并不是必须使用 '/' 等分隔符作为结尾。
force_js_embed
是否强制采用内部嵌入方式渲染js文件标签， echarts_js_dependencies 模板函数受此影响，具体可参考该函数。
图表类
图表类是 pyecharts 库中最为核心的内容，每一个类代表了 Echarts 中一个图表类型。下表显示了这些图表的继承体系。
属性
图表类和属性表如下：
属性/图表
Base
Chart/FOO_CHART
Grid
Overlap
Timeline
Page
chart_id
✓
✓
✓
✓
✓
width
✓
✓
✓
✓
✓
heigth
✓
✓
✓
✓
✓
options
✓
✓
✓
✓
✓
js_dependencies
✓
✓
✓
✓
✓
✓
chart_id
字符串类型(str)，图表唯一标识符，默认 uuid 格式的字符串，如 'd2d9dcc4e28247518186c0882d356ba8' 。
width
数字类型(number)或字符串(str)。图表容器 div 的宽度，以 px 为单位。
height
数字类型(number)或字符串(str)。图表容器 div 的高度，以 px 为单位。
options
字典类型(dict)，Echarts 图表配置。不同图表类型具有不同数据格式。具体请参考 ECharts 文档。
js_dependencies
集合类型(set)，js 依赖文件名称列表，元素不包含文件后缀(.js)，如 {'echarts.min', 'fujian'} 。
方法
add()
添加图表配置和数据。具体请参考其子类定义。
图表类
函数签名
Base
add(**echarts_options)
Grid
add(grid_width=None, grid_height=None, grid_top=None, grid_bottom=None,grid_left=None, grid_right=None)
Overlap
add(chart, xaix_index=0, yaix_index=0, id_add_xaxis=False, is_add_yaxis=False)
Timeline
add(chart, time_point)
Page
add(achart_or_charts)
get_js_dependencies()
获取 js 依赖文件列表。和 属性 js_dependencies 不同， 这里的元素是包含了文件完整路径。
render(path='render.html', template_name='simple_chart.html', object_name='chart', extra_context=None)
渲染至指定的 HTML 页面，不同图表类型使用默认的模板文件。各参数意义如下：
path ：最终生成文件名称
template_name: 模板文件名称，其目录可通过 pyecharts.configure() 全局函数进行配置
object_name: 模板文件中，该图表类所使用变量的名称
extra_context 额外数据字典。
render_embed()
渲染包含选项的 js 代码。
show_config()
打印全部 options 属性。
多图表
pyecharts.custom.page.Page 用于在同一页面显示多个图表，也拥有上述的属性和方法。
同时 Page 类继承自 list ，因此也支持长度计算(len)、迭代(iter)、索引(index)、切片(slice)、添加(append)、扩展(extend)等操作。
例子：按顺序打印 page 中每个图表的 echarts 选项字典。
page = Page()
line = Line('Demo Line')
# ... Add data to line
page.add(line)
kline = KLine('Demo kline')
# ... Add data to kline
page.append(kline)
for chart in page:
chart.show_config()
数据处理工具
以下几个方法为数据处理的类方法，
cast
pyecharts.base.Base.cast(seq)
数据格式化处理函数，能够将源数据转化为符合 pyecharts 的数据。
例子:
o_data = [('A', '34'), ('B', '45'), ('C', '12')]
x, y = Base.cast(o_data)
print(x) # ['A', 'B', 'C']
print(y) # ['34', '45', '12']
json_dumps
pyecharts.utils.json_dumps(data, indent=0)
将 data 转换为 JSON 字符串，和默认的 json.dumps 方法增加了：
将日期和时间转化为 ISO8601 字符串
对于 numpy 数组，增加了类型强制转化，可参考 astype 和 tolist .
模板引擎
概述
pyecharts库使用 Jinja2 作为其默认模板渲染引擎，并添加了若干个 echarts 图表相关的模板函数。
模板函数和模板标签是同一特性的不同术语，在 Django 模板系统中称为标签，Jinja2 模板系统中称之为函数。二者语法形式也有所不同。
引擎对象
pyecharts.engine 定义了若干个继承自 jinja2.Environment 的模板引擎类，每个类都有其适合的使用场景。
BaseEnvironment
pyecharts.engine.BaseEnvironment
该类是 pyecharts 基本的模板引擎类，该类直接继承 jinja2.Environment ，并且：
添加了 pyecharts_config 属性，这是一个 PyEchartsConfig 对象。
添加了 echarts_* 等模板函数。
该类可用于 web 框架整合。
EChartsEnvironment
pyecharts.engine.EChartsEnvironment(pyecharts_config=None, **kwargs)
EChartsEnvironment 类继承自 BaseEnvironment 。并在此基础上改写了模板文件加载器(loader)的行为，默认使用 pyecharts_config.echarts_template_dir 作为模板文件目录。
由于该类重写模板文件加载器的行为，因此不应当用于 web 整合。
ECHAERTS_TEMPLATE_FUNCTIONS
pyecharts.engine.ECHAERTS_TEMPLATE_FUNCTIONS
包含模板函数的字典。可用于 web 框架整合。
模板函数
pyecharts 内置的引擎提供了一些模板函数，这些函数通常接收一个或多个的 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
✓
✓
✓
echarts_js_dependencies
pyecharts.template.echarts_js_dependencies(*args)
渲染包含图表所需要的 js 文件的 script 一个或多个节点，有内部嵌入或者外部链接两种结果。
内嵌模式
html
var a = 1;
console.log(a):
外链模式
最终采用何种模板依据 PyEchartsConfig.jshost 和 PyEchartsConfig.force_js_embed 配置项决定的，具体可参考下表：
取值
本地/远程
script 模式
使用场景
备注
/template/js/echarts
本地
内嵌
本地生成单一文件，直接移植
此为默认是设置
'https://chfw.github.io/jupyter-echarts/echarts'
远程
内嵌
生成单一文件
使用 online 可切换到此项
其他本地模式 (如 /static/js)
本地
外链，可以通过force_embed改成内嵌
可用于web框架整合
其他远程模式(如 hthttps://cdn.bootcss.com/echarts/3.7.2)
远程
外链
使用外部js，需依赖网络
例子
```
# Jinja2 Context function
{{ echarts_js_dependencies('echarts') }}
# Html Output
# Python
bar = Bar('Demo Bar')
# Jinja2 Context function
{{ echarts_js_dependencies(bar) }}
# Html Output
echarts_js_dependencies_embed
pyecharts.template.echarts.js_dependencies_embed(*args)
渲染 js 的 script 一个或多个节点，采用内嵌方式引入。仅支持本地 jshost 。
echarts_container
pyecharts.template.echarts_container(chart)
渲染图表容器，为一个
例子
# Python Code
bar = Bar('Demo Bar')
# Jinjia2 Context Function
{{ echarts_container(bar) }}
# Html Output
echarts_js_content
pyecharts.template.echarts_container(*chart)
渲染js初始化代码片段，不包含 。
echarts_js_content_wrap
pyecharts.template.echarts_js_content_wrap(*args)
渲染js初始化代码片段，包含首尾的 。
完整的例子
使用模板函数和自定义模板的例子。
demo.py
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)
tpl_demo.html 模板
自定义模板{{ echarts_js_dependencies(bar) }}
{{ echarts_container(bar) }}
{{ echarts_js_content(bar) }}
151
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
