官方图表样例

小象实战讲义 · ECharts 数据可视化

在上一节中，我们了解了 pyecharts 的基本代码结构。然而，面对丰富的图表类型和复杂的配置项，如何快速上手并找到符合自己需求的图表实现呢？本节将带你掌握一个高效的学习方法：查阅和使用 pyecharts 官方提供的图表示例库。通过下载、浏览和复用这些示例，你可以快速定位目标图表，理解其核心代码，并将其应用到自己的数据分析项目中。

💡 核心导读

• 获取资源：学会从 pyecharts 官方仓库下载完整的图表示例代码压缩包。
• 浏览结构：了解示例库的目录组织方式，能根据图表类型（如柱状图、折线图）快速定位文件。
• 学习与复用：掌握如何查看示例的 HTML 预览效果，并学习其对应的 Python 源码，将其复制到自己的环境中运行和修改。
• 高效学习路径：建立“预览效果 → 查看源码 → 复制运行 → 个性化修改”的高效学习流程。

一、下载官方图表示例

pyecharts 官方维护了一个丰富的示例库，包含了几乎所有图表类型的实现代码。这是学习 pyecharts 最直接、最有效的资源。

该示例库托管在 GitHub 上，地址为：

https://github.com/pyecharts/pyecharts-gallery

访问该页面，你会看到一个名为 Code 的绿色按钮。点击它，选择 Download ZIP 选项，即可将整个示例库以压缩包的形式下载到本地。

下载完成后，解压该压缩包，你将得到一个包含大量文件夹和文件的目录。每个文件夹通常对应一种图表类型，例如 bar（柱状图）、line（折线图）、pie（饼图）等。

二、浏览与使用示例：以柱状图为例

解压后的目录结构清晰，便于我们按需查找。让我们以柱状图为例，演示如何学习和使用这些示例。

1. 定位图表类型：在解压后的文件夹中，找到名为 bar 的目录，它包含了所有柱状图相关的示例。
2. 识别示例文件：进入 bar 目录，你会看到多个文件。文件名通常描述了图表的特点。例如：
   • bar_base.py：最基础的柱状图。
   • bar_with_dict_config.py：使用字典进行配置的柱状图。
   • bar_with_animation.py：带有动画效果的柱状图。
   • bar_custom_background_image.py：带有自定义背景图片的柱状图。 通过文件名，你可以快速判断该示例是否满足你的需求。
3. 预览效果：每个示例通常包含三个文件：.html、.py 和 .md。其中，.html 文件是图表渲染后的网页结果。你可以直接双击打开它，在浏览器中预览图表的最终交互效果。这是判断该示例是否符合你预期的第一步。
4. 学习源码：确认效果符合需求后，下一步就是学习其实现代码。我们推荐使用文本编辑器（如 VS Code、PyCharm 等）打开对应的 .py 文件。例如，打开 bar_base.py，你将看到类似以下的简洁代码结构：

# bar_base.py 示例代码结构示意
from pyecharts.charts import Bar
from pyecharts import options as opts

# 1. 准备数据
x_data = ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"]
y_data = [5, 20, 36, 10, 75, 90]

# 2. 创建图表对象并配置
bar = (
    Bar()
    .add_xaxis(x_data)
    .add_yaxis("商家A", y_data)
    .set_global_opts(title_opts=opts.TitleOpts(title="基础柱状图"))
)

# 3. 生成HTML文件
bar.render("bar_base.html")

5. 复制与运行：你可以将这段核心代码（从 import 到 render）完整地复制到你的 Python 环境（如 Jupyter Notebook 或 .py 脚本）中运行。运行后，会在当前目录生成一个 bar_base.html 文件，用浏览器打开即可看到与官方示例完全一致的图表。

.md 文件是 Markdown 格式的说明文档，通常包含与 .py 文件相同的代码以及一些文字说明，内容基本一致，直接查看 .py 文件即可。

三、再举一例：折线图

让我们用同样的方法学习折线图。

1. 在示例库目录中找到 line 文件夹。
2. 进入后，找到 line_base.py（或类似的基础示例文件）。
3. 先打开对应的 .html 文件预览基础折线图的效果。
4. 再用编辑器打开 line_base.py，查看其源码实现。

# line_base.py 示例代码结构示意
from pyecharts.charts import Line
from pyecharts import options as opts

# 准备数据
x_data = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
y_data = [820, 932, 901, 934, 1290, 1330, 1320]

# 创建并配置折线图
line = (
    Line()
    .add_xaxis(x_data)
    .add_yaxis("销量", y_data, is_smooth=True) # 使用平滑曲线
    .set_global_opts(title_opts=opts.TitleOpts(title="基础折线图"))
)

line.render("line_base.html")

通过对比柱状图和折线图的代码，你会发现 pyecharts 的 API 设计非常一致：都是先导入对应的图表类（Bar/Line），然后通过 .add_xaxis() 和 .add_yaxis() 添加数据，最后用 .set_global_opts() 等进行全局配置。这种一致性大大降低了学习成本。

四、官方示例库的价值

本课程虽然涵盖了 pyecharts 最常用和核心的图表与功能，但无法做到面面俱到。官方示例库的价值在于：

• 全面性：它几乎包含了 pyecharts 支持的所有图表类型和高级特性（如动画、主题、复杂交互）。
• 现成解决方案：当你有特殊或定制化的图表需求时，可以先在示例库中搜索是否有现成或类似的实现，这能节省大量从零开始摸索的时间。
• 最佳实践参考：官方示例的代码通常体现了推荐的配置和写法，是学习 pyecharts 高级用法的绝佳材料。

因此，养成“先查官方示例”的习惯，是你从 pyecharts 初学者进阶为熟练使用者的关键一步。

📝 动手练一练

1. 基础操作：请按照本节介绍的方法，下载 pyecharts 官方示例库。找到 pie（饼图）目录下的一个基础示例（如 pie_base.py），将其代码复制到你的 Python 环境中运行，并成功在浏览器中打开生成的 HTML 文件查看饼图。

点击查看参考答案

# 基于 pie_base 示例的简化代码
from pyecharts.charts import Pie
from pyecharts import options as opts

# 准备数据：标签和对应值
data_pair = [("衬衫", 5), ("羊毛衫", 20), ("雪纺衫", 36), ("裤子", 10), ("高跟鞋", 75), ("袜子", 90)]

# 创建并配置饼图
pie = (
    Pie()
    .add("", data_pair)
    .set_global_opts(title_opts=opts.TitleOpts(title="基础饼图"))
    .set_series_opts(label_opts=opts.LabelOpts(formatter="{b}: {c}"))
)

pie.render("my_pie_base.html")
print("饼图已生成，请打开当前目录下的 'my_pie_base.html' 文件查看。")

饼图已生成，请打开当前目录下的 'my_pie_base.html' 文件查看。

运行此代码后，控制台会提示生成文件，在文件管理器中找到并双击 my_pie_base.html 即可用浏览器查看。

2. 探索学习：在官方示例库的 bar 目录中，除了 bar_base.py，再任选一个看起来有趣的示例（例如 bar_with_animation.py），查看其 Python 源码，尝试说明它比基础柱状图多了哪些配置或效果。

# 查看 bar_with_animation.py 核心部分（示意）
from pyecharts.charts import Bar
from pyecharts import options as opts

bar = (
    Bar()
    .add_xaxis(["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"])
    .add_yaxis("商家A", [5, 20, 36, 10, 75, 90])
    .add_yaxis("商家B", [15, 6, 45, 20, 35, 80])
    .set_global_opts(
        title_opts=opts.TitleOpts(title="带动画的柱状图"),
        # 关键配置：在 toolbox 中启用了数据区域缩放，这会带来滑动动画效果
        toolbox_opts=opts.ToolboxOpts(),
        datazoom_opts=[opts.DataZoomOpts()], # 添加数据区域缩放组件
        # 通常动画是默认开启的，此示例通过交互组件间接展示了动画
    )
)

本章小结

本节为你打开了 pyecharts 学习的“宝库”之门。官方示例库不仅是解决具体图表需求的快捷手册，更是深入理解 pyecharts 设计理念和高级功能的绝佳教材。

📋 行动清单

• 下载并解压 pyecharts-gallery 官方示例库到你的学习目录。
• 尝试运行至少两个不同类型的图表示例（如柱状图、折线图），确保能成功生成并查看 HTML 结果。
• 养成新需求“先查示例库”的习惯，浏览你感兴趣的图表类型目录，对其能力范围有一个初步印象。

—— 小象教研组