mirror of
https://github.com/pyecharts/pyecharts.git
synced 2025-12-08 20:59:23 +00:00
Update document
This commit is contained in:
kinegratii
parent
0b9c2215b0
commit
ff8841a5af
@ -2,9 +2,25 @@ pyecharts API
|
||||
|
||||
This document describes the public API for *pyecharts* library and it will be read by developers.
|
||||
|
||||
## Total Proccess
|
||||
|
||||
A common proccess can be listed as the following table:
|
||||
|
||||
| Step | Code Demo | Remark |
|
||||
| ------------------------ | ---------------------------------------- | ------ |
|
||||
| 1 Create chart instance | `bar = Bar()` | |
|
||||
| 2 Add data | `bar.add(**kwargs)` | |
|
||||
| 3 Create config instance | `config = PyEchartsConfig(**kwargs)` | |
|
||||
| 4 Create template engine | `engine = EchartsEnvironment(pyecharts_config=config)` | |
|
||||
| 5 Get template file | `tpl = engine.get_template('demo_tpl.html')` | |
|
||||
| 6 Render | `html = tpl.render(bar=bar)` | |
|
||||
| 7 Write to target file | `write_utf8_html_file('my_demo_chart.html', html)` | |
|
||||
|
||||
|
||||
|
||||
## pyecharts Config Items
|
||||
|
||||
The class `pyecharts.conf.PyEChartsConfig` contains all config items when using *pyecharts* library.Before building chart, you can use module function `configure` to set all config items.
|
||||
pyecharts follows the principle of "Config-Use" . The class `pyecharts.conf.PyEChartsConfig` contains all config items when using *pyecharts* library.Before building chart, you can use module function `configure` to set all config items.
|
||||
|
||||
```python
|
||||
import pyecharts
|
||||
@ -55,11 +71,11 @@ Data type:str.The identifier string for a chart. E.g.`'d2d9dcc4e28247518186c0882
|
||||
|
||||
**width**
|
||||
|
||||
Data type:number.The width(px) of div container for a chart.
|
||||
Data type:number/str.A valid string for css length.The width(px) of div container for a chart.
|
||||
|
||||
**height**
|
||||
|
||||
Data type:number.The height(px) of div container for a chart.
|
||||
Data type:number/str.A valid string for css length.The height(px) of div container for a chart.
|
||||
|
||||
**options**
|
||||
|
||||
@ -171,11 +187,22 @@ Data type `jinja2.Environment`。pyecharts provides a build-in environment objec
|
||||
|
||||
### Engine Class
|
||||
|
||||
**BaseEnvironment**
|
||||
|
||||
`pyecharts.engine.BaseEnvironment`
|
||||
|
||||
This class is the basic engine in pyecharts,and it inherits `jinja2.Environment` .It has the following features:
|
||||
|
||||
- Add *pyecharts_config* attribute
|
||||
- Add `echarts_*` template functions
|
||||
|
||||
This class can be used for integration with web framework.
|
||||
|
||||
**EChartsEnvironment**
|
||||
|
||||
`pyecharts.engine.EChartsEnvironment`
|
||||
|
||||
EChartsEnvironment class inherits `Jinja2.Environment` .
|
||||
EChartsEnvironment class inherits `BaseEnvironment` .And it use `pyecharts_config.echarts_template_dir` as the default value of template folder.
|
||||
|
||||
### 模板函数
|
||||
|
||||
@ -197,10 +224,29 @@ EChartsEnvironment contains some template functions, which receives a or some
|
||||
|
||||
Render script html nodes with internal embed mode or enternal link.The mode will follow this table.
|
||||
|
||||
| jshost/force_js_embed | True | False |
|
||||
| --------------------- | -------------- | -------------- |
|
||||
| local host | internal embed | internal embed |
|
||||
| remote host | internal embed | enternal link |
|
||||
Internal Embed(IE)
|
||||
|
||||
```html
|
||||
<script type="text/javascript">
|
||||
var a = 1;
|
||||
console.log(a):
|
||||
</script>
|
||||
```
|
||||
|
||||
Enternal Link(EL)
|
||||
|
||||
```html
|
||||
<script type="text/javascript" src="/static/js/echarts.min.js"></script>
|
||||
```
|
||||
|
||||
Which mode is used is determined by the `PyEchartsConfig.jshost` and `PyEchartsConfig.force_js_embed` .See this table.
|
||||
|
||||
| Value | local/remote | script mode | Use Case | Remark |
|
||||
| ---------------------------------------- | ------------ | ----------- | ------------------------- | --------------------- |
|
||||
| `/template/js/echarts` | local | IE | Generate one file locally | Default value |
|
||||
| `'https://chfw.github.io/jupyter-echarts/echarts'` | remote | IE | Generate on file | switch using `online` |
|
||||
| 其他本地模式 (如 `/static/js`) | local | EI | Integrate with Web | |
|
||||
| 其他远程模式（如 `hthttps://cdn.bootcss.com/echarts/3.7.2`） | remote | EI | Use remote JS | |
|
||||
|
||||
Example
|
||||
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# pyecharts V0.3.0 发布日志
|
||||
|
||||
pyecharts V0.3.0 发布，这是一个重大更新的版本，新增 **自定义模板** 、 **模板函数** 和 **web 框架整合** 等功能，并修正了一些Bug。
|
||||
|
||||
pyecharts V0.3.0 发布，这是一个重大更新的版本，新增 **自定义模板** 、 **模板函数 ** 和 **web 框架整合** 等功能，并修正了一些Bug。
|
||||
|
||||
pyecharts V0.3.0 对整个图表渲染和使用场景进行重新思考和设计，重写大量的底层逻辑，使得功能更加明确，代码更加整洁有序。
|
||||
|
||||
## 1 开放底层模板引擎类API，支持模板函数
|
||||
|
||||
@ -183,6 +183,10 @@ app = MyFlask(__name__)
|
||||
|
||||
之后和标准的 Flask 项目一样使用。
|
||||
|
||||
### 总结
|
||||
|
||||
以上两种使用场景基本上代表大多数的 web 框架的整合思路。两种的方式的区别是是否能够直接使用 `pyecharts.engine.BaseEnvironment` 。如果框架或项目已有模板引擎类，就只能继承该模板引擎类，相关 pyecharts 特性需手动自行添加。
|
||||
|
||||
## 7 其他改变
|
||||
|
||||
其他微小变更，包括变量重命名、函数定义改变等。
|
||||
|
||||
@ -26,9 +26,9 @@
|
||||
|
||||
## pyecharts 配置项
|
||||
|
||||
所有的配置项将统一于类 `pyecharts.conf.PyEChartsConfig` 类中。
|
||||
pyecharts 遵循 “先配置后使用” 的基本原则，所有的配置项将统一于类 `pyecharts.conf.PyEChartsConfig` 类中。
|
||||
|
||||
如果使用 `chart.render()` 这种方式，可以模块函数 `configure` 进行设置。
|
||||
如果使用 `chart.render()` 这种渲染方式，可以通过模块函数 `configure` 进行修改 pyecharts 中默认的配置类。
|
||||
|
||||
```python
|
||||
import pyecharts
|
||||
@ -76,11 +76,11 @@ pyecharts.configure(P1=V1, P2=V2,...)
|
||||
|
||||
* width
|
||||
|
||||
数字类型(number)。图表容器 div 的宽度，以 px 为单位。
|
||||
数字类型(number)或字符串(str)。图表容器 div 的宽度，以 px 为单位。
|
||||
|
||||
* height
|
||||
|
||||
数字类型(number)。图表容器 div 的高度，以 px 为单位。
|
||||
数字类型(number)或字符串(str)。图表容器 div 的高度，以 px 为单位。
|
||||
|
||||
* options
|
||||
|
||||
@ -90,9 +90,6 @@ pyecharts.configure(P1=V1, P2=V2,...)
|
||||
|
||||
集合类型(set)，js 依赖文件名称列表，元素不包含文件后缀(.js)，如 `{'echarts.min', 'fujian'}` 。
|
||||
|
||||
* charts
|
||||
|
||||
多图表对象中源图表对象列表，每个元素均为 `pyecharts.base.Base` 的子类对象。仅用于 `pyecharts.custom.page.Page` 类。
|
||||
|
||||
|
||||
### 方法
|
||||
@ -101,7 +98,7 @@ pyecharts.configure(P1=V1, P2=V2,...)
|
||||
|
||||
添加图表配置和数据。具体请参考其子类定义。
|
||||
|
||||
| 图表类 | 函数签名 |
|
||||
| 图表类 | 函数签名 |
|
||||
| -------- | ---------------------------------------- |
|
||||
| Base | `add(**echarts_options)` |
|
||||
| Grid | `add(grid_width=None, grid_height=None, grid_top=None, grid_bottom=None, grid_left=None, grid_right=None)` |
|
||||
@ -191,11 +188,22 @@ pyecharts库使用 [Jinja2](http://jinja.pocoo.org/) 作为其默认模板渲染
|
||||
|
||||
### 引擎对象
|
||||
|
||||
**BaseEnvironment**
|
||||
|
||||
`pyecharts.engine.BaseEnvironment`
|
||||
|
||||
该类是 pyecharts 基本的模板引擎类，该类直接继承 `jinja2.Environment` ，并且：
|
||||
|
||||
- 拥有 pyecharts_config 配置对象
|
||||
- 添加了 `echarts_*` 等模板函数
|
||||
|
||||
该类可用于 web 框架整合。
|
||||
|
||||
**EChartsEnvironment**
|
||||
|
||||
`pyecharts.engine.EChartsEnvironment(pyecharts_config=None, **kwargs)`
|
||||
|
||||
EChartsEnvironment 类继承自 `Jinja2.Environment` 。
|
||||
EChartsEnvironment 类继承自 `BaseEnvironment` 。并在此基础上改写了模板文件加载器(loader)的行为，默认使用 `pyecharts_config.echarts_template_dir` 作为模板文件目录。
|
||||
|
||||
### 模板函数
|
||||
|
||||
@ -213,7 +221,7 @@ EChartsEnvironment 引擎提供了一些模板函数，这些函数通常接收
|
||||
* echarts_js_dependencies
|
||||
|
||||
`pyecharts.template.echarts_js_dependencies(*args)`
|
||||
|
||||
|
||||
渲染包含图表所需要的 js 文件的 script 一个或多个节点，有内部嵌入或者外部链接两种结果。
|
||||
|
||||
内嵌模式
|
||||
@ -233,29 +241,30 @@ EChartsEnvironment 引擎提供了一些模板函数，这些函数通常接收
|
||||
|
||||
最终采用何种模板依据 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，需依赖网络 | |
|
||||
| 取值 | 本地/远程 | 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
|
||||
<script type="text/javascript" src="js/echarts.js"></script>
|
||||
|
||||
|
||||
# Python
|
||||
bar = Bar('Demo Bar')
|
||||
# Jinja2 Context function
|
||||
{{ echarts_js_dependencies(bar) }}
|
||||
# Html Output
|
||||
<script type="text/javascript" src="js/echarts.js"></script>
|
||||
```
|
||||
```
|
||||
|
||||
* echarts_js_dependencies_embed
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user