常用配置项（一）

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

在前面的学习中，我们已经掌握了如何使用 pyecharts 创建基础的柱状图、条形图等对比图表。这些图表虽然功能完整，但样式和交互往往依赖于默认设置。为了让图表更贴合业务需求、更具表现力，我们需要深入了解并灵活运用 pyecharts 强大的配置系统。本节将带你系统学习 pyecharts 配置项的核心概念、查看方法以及两种最基础的配置方式，并以标题和动画配置为例，开启你的图表定制之旅。

💡 核心导读

• 理解配置项体系：掌握 pyecharts 中“一切皆配置项”的设计哲学，了解全局配置项、系列配置项和图表配置项的分类与作用。
• 掌握配置项查看方法：学会通过官方文档和源码两种途径，精准定位和理解配置项的参数与用法。
• 学会两种配置方式：熟练运用“参数传递”和“字典传递”两种方式为图表添加配置，理解其背后的原理与适用场景。
• 实践常用配置项：通过为图表添加标题和自定义动画效果，掌握配置项的实际应用流程。

一、理解 pyecharts 的配置项体系

在 pyecharts 中，图表的每一个细节——从全局的标题、图例、工具箱，到系列的数据标签、标记点，再到图表的初始化尺寸、主题——都通过一个统一的 Options（配置项）体系来管理。我们可以形象地理解为：“在 pyecharts 中，一切皆 Options”。

这个体系主要分为三大类：

1. 全局配置项 (set_global_opts)：作用于整个图表的配置，如标题 (TitleOpts)、坐标轴 (AxisOpts)、工具箱 (ToolboxOpts)、视觉映射 (VisualMapOpts) 等。
2. 系列配置项 (set_series_opts)：作用于特定数据系列的配置，如数据标签 (LabelOpts)、标记线 (MarkLineOpts)、标记点 (MarkPointOpts)、系列样式 (ItemStyleOpts) 等。
3. 图表初始化配置 (init_opts)：在创建图表对象时传入，用于设置图表的初始状态，如画布尺寸、主题、渲染器、动画配置 (AnimationOpts) 等。

这种分层设计使得配置清晰、职责明确，我们可以像搭积木一样，组合不同的配置项来构建出功能丰富、样式精美的图表。

二、如何查找与理解配置项

面对如此多的配置项，如何快速找到并理解它们呢？主要有两种途径：

1. 查阅官方文档

pyecharts 官网提供了结构清晰的配置项文档，是首选的学习工具。

• 全局配置项：访问 https://pyecharts.org/#/zh-cn/global_options
• 系列配置项：访问 https://pyecharts.org/#/zh-cn/series_options

在文档中，你可以看到每个配置项类（如 TitleOpts）的所有属性、其含义以及默认值。例如，查找“标题配置”：

TitleOpts
    title: 主标题文本，支持 \n 换行。
    subtitle: 副标题文本。
    title_link: 主标题跳转链接。
    title_target: 指定主标题窗口打开方式，如 ‘self’ 或 ‘blank’。
    pos_left: 标题离容器左侧的距离。
    ... (更多属性)

2. 查看源码（进阶）

当文档信息不足或你想深入理解配置项的内部机制时，可以直接查看 pyecharts 的源码。配置项相关的源码主要位于 pyecharts/options/ 目录下。通过阅读源码中的类定义和注释，你可以获得最准确的信息。

例如，在代码编辑器中，你可以通过跳转到 TitleOpts 类的定义，查看其 __init__ 方法中的所有参数。

查找技巧：在文档页面的搜索框，或在你本地 IDE 的全局搜索中，直接输入配置项的名称（如 AnimationOpts），可以快速定位到其定义和使用位置，帮助你判断它属于哪一层配置（如 AnimationOpts 需要放在 InitOpts 中）。

三、配置项的两种使用方式

理解了配置项是什么以及如何查找后，我们来看看如何将它们应用到图表中。pyecharts 提供了两种等效的配置方式。

方式一：参数传递方式（推荐）

这是最直观、最符合 Python 风格的方式。直接导入 options 模块（通常别名为 opts），然后创建对应的配置项对象。

from pyecharts import options as opts
from pyecharts.charts import Bar

# 创建基础柱状图
categories = ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"]
sales_a = [5, 20, 36, 10, 75, 90]
sales_b = [15, 6, 45, 20, 35, 10]
bar = (
    Bar()
    .add_xaxis(categories)
    .add_yaxis("商家A", sales_a)
    .add_yaxis("商家B", sales_b)
)

# 使用参数传递方式设置全局标题
bar.set_global_opts(
    title_opts=opts.TitleOpts(title="主标题", subtitle="副标题")
)

# 生成HTML文件
bar.render("bar_with_title.html")
print(f"图表已生成，包含主标题和副标题。")

输出摘要：

图表已生成，包含主标题和副标题。

方式解析：

• title_opts 是 set_global_opts 方法的一个参数名。
• opts.TitleOpts(title="主标题", subtitle="副标题") 创建了一个标题配置项对象。
• 这种方式的优点是代码自解释性强，IDE 能提供参数提示和自动补全，并且与官方文档的示例完全对应，学习成本低。

方式二：字典传递方式

你也可以直接传入一个字典来设置配置项。

from pyecharts import options as opts
from pyecharts.charts import Bar

categories = ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"]
bar_dict = (
    Bar()
    .add_xaxis(categories)
    .add_yaxis("商家A", [5, 20, 36, 10, 75, 90])
    .add_yaxis("商家B", [15, 6, 45, 20, 35, 10])
    .set_global_opts(
        # 使用字典方式设置标题
        title_opts={"text": "主标题（字典方式）", "subtext": "副标题"}
    )
)

# 注意：此处不渲染，仅展示配置方式。实际字典中的键需与源码映射一致。
print("已使用字典方式配置标题。")

输出摘要：

已使用字典方式配置标题。

方式解析与对比：

• 字典中的键（如 "text", "subtext"）需要与配置项类内部定义的属性映射名称一致。这些映射关系定义在源码中（例如 TitleOpts 类的初始化方法里）。
• 为什么不推荐初学者使用？
  1. 不易查找：字典的键名在官方文档中通常不直接列出，需要查阅源码才能知道。
  2. 易出错：手打键名容易拼写错误，且没有IDE提示。
  3. 可读性差：无法直观看出配置项的类型和结构。
• 那为什么存在这种方式？ 它更接近于 ECharts 原生 JavaScript 选项的格式，在某些从 JS 配置迁移或动态生成配置的场景下可能有用。作为学习者，我们强烈建议优先使用“参数传递方式”。

四、实战：配置标题与动画

现在，让我们综合运用所学，为一个柱状图添加更丰富的标题并自定义其动画效果。

1. 配置带链接的标题

from pyecharts import options as opts
from pyecharts.charts import Bar

categories = ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"]
bar_linked = (
    Bar()
    .add_xaxis(categories)
    .add_yaxis("产品A", [120, 132, 101, 134, 90, 230])
    .add_yaxis("产品B", [220, 182, 191, 234, 290, 330])
    .set_global_opts(
        title_opts=opts.TitleOpts(
            title="2023年产品销售对比",
            subtitle="数据来源：内部统计",
            title_link="https://www.xxketang.com", # 为主标题添加链接
            title_target="blank", # 在新窗口打开链接
            pos_left="center" # 标题水平居中
        )
    )
)

bar_linked.render("bar_linked_title.html")
print("图表已生成，主标题带有可点击链接。")

输出摘要：

图表已生成，主标题带有可点击链接。

2. 配置自定义动画

动画配置 (AnimationOpts) 比较特殊，它不属于全局或系列配置，而是图表初始化配置的一部分，需要在创建图表对象时通过 init_opts 参数传入。

from pyecharts import options as opts
from pyecharts.charts import Bar

# 创建带有自定义动画配置的图表
bar_animated = (
    Bar(
        init_opts=opts.InitOpts(
            # 在初始化配置中设置动画
            animation_opts=opts.AnimationOpts(
                animation_delay=1000,  # 动画延迟1000毫秒开始
                animation_easing="elasticOut",  # 使用弹性缓动效果
                animation_duration=2000,  # 动画持续2000毫秒
            )
        )
    )
    .add_xaxis(["Q1", "Q2", "Q3", "Q4"])
    .add_yaxis("营收", [450, 520, 480, 600])
    .set_global_opts(
        title_opts=opts.TitleOpts(title="季度营收报告（带动画）")
    )
)

bar_animated.render("bar_animated.html")
print("图表已生成，带有延迟和弹性动画效果。")

输出摘要：

图表已生成，带有延迟和弹性动画效果。

代码解读：

• Bar(init_opts=opts.InitOpts(...))：在实例化 Bar 图表时，传入初始化选项。
• opts.InitOpts(animation_opts=...)：在初始化选项中设置动画选项。
• opts.AnimationOpts(...)：具体配置动画行为。
  • animation_delay: 动画开始前的延迟时间（毫秒）。
  • animation_easing: 动画的缓动效果。"elasticOut" 是一种类似弹簧的弹性效果，其他还有 "linear", "quadraticInOut", "bounceOut" 等。
  • animation_duration: 动画的持续时间（毫秒）。

运行后生成的 HTML 页面中，柱状图将在页面加载后等待1秒，然后以弹性动画的方式在2秒内完成绘制。

📝 动手练一练

1. 修改动画效果：将上面动画示例中的 animation_easing 参数改为 "bounceOut"（弹跳效果），并调整 animation_duration 为 1500 毫秒，观察生成的图表动画有何不同。

from pyecharts import options as opts
from pyecharts.charts import Bar

bar_exercise = (
    Bar(
        init_opts=opts.InitOpts(
            animation_opts=opts.AnimationOpts(
                animation_delay=500,
                animation_easing="bounceOut",  # 改为弹跳效果
                animation_duration=1500,       # 持续时间改为1.5秒
            )
        )
    )
    .add_xaxis(["A", "B", "C"])
    .add_yaxis("数值", [10, 20, 15])
    .set_global_opts(title_opts=opts.TitleOpts(title="动画效果练习"))
)

bar_exercise.render("exercise_animation.html")
print("已修改为 bounceOut 缓动效果，时长为1500ms。")

已修改为 bounceOut 缓动效果，时长为1500ms。

2. 复合配置：创建一个柱状图，要求：①主标题为“我的第一个定制图表”，副标题为“学习配置项”，并居右显示（提示：查文档找 pos_right 参数）。②使用“参数传递方式”进行配置。

点击查看参考答案

from pyecharts import options as opts
from pyecharts.charts import Bar

bar_composite = (
    Bar()
    .add_xaxis(["苹果", "香蕉", "橙子"])
    .add_yaxis("销量", [80, 55, 70])
    .set_global_opts(
        title_opts=opts.TitleOpts(
            title="我的第一个定制图表",
            subtitle="学习配置项",
            pos_right="right"  # 标题整体靠右对齐
        )
    )
)

bar_composite.render("composite_config.html")
print("图表已生成，标题居右显示。")

输出摘要：

图表已生成，标题居右显示。

本章小结

本节我们深入到了 pyecharts 图表定制的核心——配置项系统。你不仅理解了“一切皆 Options”的设计理念和配置项的分类，更重要的是掌握了如何查找配置项以及如何应用配置项的两种方法。通过为图表添加标题和动画的实战，你已迈出了从“能用”到“好用”的关键一步。

📋 行动清单

• 尝试在官方文档的“全局配置项”页面，浏览 ToolboxOpts（工具箱）和 LegendOpts（图例）的配置参数，思考它们可能用在什么场景。
• 将“参数传递方式”配置标题的代码亲手敲一遍，并尝试修改 title_link 为你熟悉的网址，查看效果。
• 回顾“字典传递方式”，理解其原理即可，在后续自己动手编码时，坚持使用更规范的“参数传递方式”。

—— 小象教研组