Extra text label (pyecharts#659)

* Docs: 文档完善

* Add: pyecharts#651 为 Scatter 图新增 extra_name 参数

* Update: 版本号更新

* Add: 新增 assert 判断

* Update: pyecharts#657 新增额外的文本标签

* Docs: 对应文档更新

* Format: 代码格式化

Author: chenjiandongx

docs/zh-cn/changelog.md

@@ -4,6 +4,8 @@
 
     #### Added
     * [issue#651](https://github.com/pyecharts/pyecharts/issues/651) Scatter 图新增 `extra_name` 参数，额外的数据项的名称，可以为每个数据点指定一个名称。
+    * [issue#657](https://github.com/pyecharts/pyecharts/issues/657) 基本图形新增 `extra_html_text_label` 参数用于显示额外的文本标签，仅限于在单图形或者 Page 时使用。
+
 
 * ### version 0.5.6 - 2018.7.28（current）
 

docs/zh-cn/charts.md

@@ -76,7 +76,9 @@
     指定生成的 html 文件中 `<title>` 标签的值。默认为'Echarts'
 * renderer -> str  
     指定使用渲染方式，有 'svg' 和 'canvas' 可选，默认为 'canvas'。3D 图仅能使用 'canvas'。
-    
+* extra_html_text_label -> list  
+    额外的 HTML 文本标签，(<p> 标签)。类型为 list，list[0] 为文本内容，list[1] 为字体风格样式（选填）。如 ["this is a p label", "color:red"]。**仅限于在单个图形或者 page 类时使用。**
+
 
 # 通用配置项
 **通用配置项均在 ```add()``` 中设置**
@@ -709,6 +711,18 @@ bar.render()
 ![bar-demo](https://user-images.githubusercontent.com/19553554/35081822-3e090748-fc51-11e7-8bba-b775d29671e4.png)
 
 
+**额外的文本标签**
+```python
+from pyecharts import Bar
+
+bar = Bar("柱状图", extra_html_text_label=["bar_extra_html_text_label", "color:red"])
+bar.add("商家A", CLOTHES, clothes_v1, is_stack=True)
+bar.add("商家B", CLOTHES, clothes_v2, is_stack=True)
+bar.render()
+```
+![bar-demo](https://user-images.githubusercontent.com/19553554/43812932-31f22e0a-9af6-11e8-8fbe-c62b65daec41.png)
+
+
 ## Bar3D（3D 柱状图）
 Bar3D.add() 方法签名
 ```python
@@ -3822,6 +3836,43 @@ page.render()
 ```
 ![page-demo](https://user-images.githubusercontent.com/19553554/35104305-66f2a766-fca3-11e7-8ffd-8e85911fdea5.gif)
 
+**Page 类的额外的文本标签，由各图形本身携带**
+```python
+from pyecharts import *
+
+page = Page()
+line = Line("折线图示例", extra_html_text_label=["LINE TEXT LABEL", "color:red"])
+line.add(
+    "最高气温",
+    WEEK,
+    [11, 11, 15, 13, 12, 13, 10],
+    mark_point=["max", "min"],
+    mark_line=["average"],
+)
+page.add(line)
+
+v1 = [11, 12, 13, 10, 10, 10]
+pie = Pie("饼图-圆环图示例", title_pos="center", extra_html_text_label=["PIE TEXT LABEL"])
+pie.add(
+    "",
+    CLOTHES,
+    v1,
+    radius=[40, 75],
+    label_text_color=None,
+    is_label_show=True,
+    legend_orient="vertical",
+    legend_pos="left",
+)
+page.add(pie)
+
+v2 = [10, 25, 8, 60, 20, 80]
+bar = Bar("柱状图", extra_html_text_label=["BAR TEXT LABEL"])
+bar.add("商家B", CLOTHES, v2)
+page.add(bar)
+page.render()
+```
+![page-demo](https://user-images.githubusercontent.com/19553554/43813125-e4ef7e2c-9af6-11e8-96a0-a6b53b0c136f.gif)
+
 
 ## Timeline：提供时间线轮播多张图
 Timeline 类的使用：

pyecharts/base.py

@@ -26,6 +26,7 @@ def __init__(
         height=400,
         renderer=constants.CANVAS_RENDERER,
         page_title=constants.PAGE_TITLE,
+        extra_html_text_label=None,
     ):
         """
 
@@ -38,6 +39,9 @@ def __init__(
             3D 图仅能使用 'canvas'。
         :param page_title:
             指定生成的 html 文件中 <title> 标签的值。默认为 'Echarts'
+        :param extra_html_text_label:
+            额外的 HTML 文本标签，(<p> 标签)。类型为 list，list[0] 为文本内容，
+            list[1] 为字体风格样式（选填）。如 ["this is a p label", "color:red"]
         """
         self._option = {}
         self._js_dependencies = set()
@@ -49,6 +53,7 @@ def __init__(
         self.event_handlers = {}
         self.theme = None
         self.use_theme(CURRENT_CONFIG.theme)
+        self.extra_html_text_label = extra_html_text_label
 
     @property
     def chart_id(self):

pyecharts/chart.py

@@ -26,6 +26,7 @@ def __init__(
         background_color=None,
         page_title=constants.PAGE_TITLE,
         renderer=constants.CANVAS_RENDERER,
+        extra_html_text_label=None,
     ):
         """
 
@@ -58,12 +59,16 @@ def __init__(
         :param renderer:
             指定使用渲染方式，有 'svg' 和 'canvas' 可选，默认为 'canvas'。
             3D 图仅能使用 'canvas'。
+        :param extra_html_text_label:
+            额外的 HTML 文本标签，(<p> 标签)。类型为 list，list[0] 为文本内容，
+            list[1] 为字体风格样式（选填）。如 ["this is a p label", "color:red"]
         """
         super(Chart, self).__init__(
             width=width,
             height=height,
             renderer=renderer,
             page_title=page_title,
+            extra_html_text_label=extra_html_text_label,
         )
         self._colorlst = [
             "#c23531",

pyecharts/engine.py

@@ -25,6 +25,7 @@
 CHART_EVENT_FORMATTER = """
 myChart_{chart_id}.on("{event_name}", {handler_name});
 """
+EXTRA_TEXT_FORMATTER = """<p style="{style}">{text}</p>"""
 
 
 @environmentfunction
@@ -70,14 +71,22 @@ def echarts_container(env, chart):
     :param env:
     :param chart: A pyecharts.base.Base object
     """
-
-    return Markup(
-        CHART_DIV_FORMATTER.format(
-            chart_id=chart.chart_id,
-            width=utils.to_css_length(chart.width),
-            height=utils.to_css_length(chart.height),
-        )
+    _container_and_text = ""
+    _container_and_text += CHART_DIV_FORMATTER.format(
+        chart_id=chart.chart_id,
+        width=utils.to_css_length(chart.width),
+        height=utils.to_css_length(chart.height),
     )
+    _text_label = chart.extra_html_text_label
+    if _text_label:
+        if len(_text_label) == 1 and isinstance(_text_label, list):
+            _text_label.append("")
+        _text, _style = _text_label
+        _container_and_text += EXTRA_TEXT_FORMATTER.format(
+            text=_text,
+            style=_style
+        )
+    return Markup(_container_and_text)
 
 
 def generate_js_content(*charts):

pyecharts/templates/simple_chart.html

@@ -9,4 +9,4 @@
     {{ echarts_container(chart) }}
     {{ echarts_js_content(chart) }}
 </body>
-</html>
+</html>

pyecharts/templates/simple_page.html

@@ -6,9 +6,9 @@
     {{ echarts_js_dependencies(page) }}
 </head>
 <body>
-{% for chart in page %}
-    {{ echarts_container(chart) }}
-{% endfor %}
-{{ echarts_js_content(*page) }}
+    {% for chart in page %}
+        {{ echarts_container(chart) }}
+    {% endfor %}
+    {{ echarts_js_content(*page) }}
 </body>
-</html>
+</html>

test/test_bar.py

@@ -162,3 +162,11 @@ def test_bar_datazoom_xaxis_and_yaxis():
     assert ': "slider"' in html_content
     assert ': "vertical"' in html_content
     assert ': "horizontal"' in html_content
+
+
+def test_bar_extra_html_text_label():
+    bar = Bar("柱状图", extra_html_text_label=["bar_extra_html_text_label"])
+    bar.add("商家A", CLOTHES, clothes_v1, is_stack=True)
+    bar.add("商家B", CLOTHES, clothes_v2, is_stack=True)
+    html_content = bar._repr_html_()
+    assert '<p style="">bar_extra_html_text_label</p>' in html_content

test/test_page.py

@@ -4,6 +4,8 @@
 import sys
 import json
 import codecs
+import random
+
 from test.constants import RANGE_COLOR, CLOTHES, WEEK
 from pyecharts import (
     Bar,
@@ -53,7 +55,7 @@ def test_page_add_chart():
     )
 
 
-def create_three():
+def create_three_charts():
     page = Page(page_title=TEST_PAGE_TITLE)
 
     # bar
@@ -65,8 +67,6 @@ def create_three():
     page.add(bar)
 
     # scatter3D
-    import random
-
     data = [
         [
             random.randint(0, 100),
@@ -98,12 +98,12 @@ def create_three():
 
 @raises(NotImplementedError)
 def test_no_image_rendering_for_page():
-    page = create_three()
+    page = create_three_charts()
     page.render(path="page.png")
 
 
 def test_two_bars():
-    page = create_three()
+    page = create_three_charts()
     page.render()
     with codecs.open("render.html", "r", "utf-8") as f:
         actual_content = f.read()
@@ -119,7 +119,7 @@ def test_two_bars():
 
 
 def test_page_get_js_dependencies():
-    page = create_three()
+    page = create_three_charts()
     dependencies = page.get_js_dependencies()
     eq_(dependencies[0], "echarts.min")
     assert "guangdong" in dependencies
@@ -128,14 +128,14 @@ def test_page_get_js_dependencies():
 
 
 def test_page_embed():
-    page = create_three()
+    page = create_three_charts()
     html = page.render_embed()
     assert "<html>" not in html
     assert json.dumps("柱状图数据堆叠示例") in html
 
 
 def test_page_in_notebook():
-    page = create_three()
+    page = create_three_charts()
     html = page._repr_html_()
 
     assert "echartsgl" in html
@@ -148,7 +148,7 @@ def test_page_in_notebook():
     assert echarts_position < guangdong_position
 
 
-def test_more():
+def test_more_charts():
     page = Page()
 
     # line
@@ -251,8 +251,6 @@ def test_more():
     page.add(radar)
 
     # scatter3d
-    import random
-
     data = [
         [
             random.randint(0, 100),
@@ -325,3 +323,46 @@ def test_more():
         or ("echarts.min" in page.js_dependencies)
     )
     page.render()
+
+
+def test_page_extra_html_text_label():
+    page = Page()
+    line = Line(
+        "折线图示例", extra_html_text_label=["LINE TEXT LABEL", "color:red"]
+    )
+    line.add(
+        "最高气温",
+        WEEK,
+        [11, 11, 15, 13, 12, 13, 10],
+        mark_point=["max", "min"],
+        mark_line=["average"],
+    )
+    page.add(line)
+
+    v1 = [11, 12, 13, 10, 10, 10]
+    pie = Pie(
+        "饼图-圆环图示例",
+        title_pos="center",
+        extra_html_text_label=["PIE TEXT LABEL"],
+    )
+    pie.add(
+        "",
+        CLOTHES,
+        v1,
+        radius=[40, 75],
+        label_text_color=None,
+        is_label_show=True,
+        legend_orient="vertical",
+        legend_pos="left",
+    )
+    page.add(pie)
+
+    v2 = [10, 25, 8, 60, 20, 80]
+    bar = Bar("柱状图", extra_html_text_label=["BAR TEXT LABEL"])
+    bar.add("商家B", CLOTHES, v2)
+    page.add(bar)
+
+    html_content = page._repr_html_()
+    assert '<p style="">BAR TEXT LABEL</p>' in html_content
+    assert '<p style="color:red">LINE TEXT LABEL</p>' in html_content
+    assert '<p style="">PIE TEXT LABEL</p>' in html_content