常用配置项

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

在前几节，我们学习了折线图、面积图、K线图等用于展示时间趋势的核心图表。掌握了基础绘制方法后，我们常常需要根据分析需求，对图表进行精细化调整，例如优化交互提示、通过颜色映射数据区间、自定义线条和标记点的样式等。本节将聚焦于时间趋势图表中几个高频使用的配置项，让你能够灵活定制图表，使其信息传递更清晰、视觉表达更专业。

💡 核心导读

• 提示框（Tooltip）配置：掌握如何改变提示框的触发方式（如从“数据项触发”改为“坐标轴触发”），以提升多系列数据对比时的交互体验。
• 视觉映射（VisualMap）配置：学习如何为折线图等图表添加颜色标尺，将连续或分段的数据值映射为不同的颜色，直观揭示数据在不同区间的分布。
• 样式自定义：了解如何通过 LineStyleOpts 和 ItemStyleOpts 等配置项，修改折线的颜色、线型、宽度，以及数据标记点（symbol）的形状、大小和边框样式。
• 配置项分类：理解全局配置项（set_global_opts）与系列配置项（在 add_yaxis 中设置）的区别与应用场景。

一、全局配置项：提示框（Tooltip）

提示框是用户与图表交互时获取详细信息的关键组件。在 pyecharts 中，我们通过 TooltipOpts 来配置它，并将其传入 set_global_opts 方法。

默认情况下，提示框的触发类型（trigger）为 'item'，这意味着鼠标必须悬停在具体的数据点（如折线上的点）上才会显示该点的信息。这在查看单系列数据细节时很合适。

然而，在对比多系列数据时，我们更希望同时看到同一时间点上所有系列的数据。这时，可以将 trigger 设置为 'axis'（坐标轴触发）。当鼠标在横坐标轴附近移动时，提示框会显示该时间点下所有数据系列的值。

下面通过一个简单的双系列折线图示例来演示这两种触发模式的区别：

from pyecharts import options as opts
from pyecharts.charts import Line
import pandas as pd

# 创建示例数据（模拟两个产品随时间变化的销量）
dates = pd.date_range(start='2024-01-01', periods=7, freq='D').strftime('%Y-%m-%d').tolist()
product_a = [15, 22, 18, 25, 30, 28, 35]
product_b = [20, 25, 22, 30, 28, 32, 40]

# 创建图表，并设置提示框为坐标轴触发
chart_with_axis_trigger = (
    Line()
    .add_xaxis(dates)
    .add_yaxis("产品A", product_a)
    .add_yaxis("产品B", product_b)
    .set_global_opts(
        title_opts=opts.TitleOpts(title="产品销量趋势 - 坐标轴触发提示框"),
        tooltip_opts=opts.TooltipOpts(trigger="axis")  # 关键配置
    )
)

# 打印图表类型和配置摘要
print(f"图表类型: {type(chart_with_axis_trigger).__name__}")
print(f"X轴数据点数量: {len(dates)}")
print(f"系列名称: {['产品A', '产品B']}")
print("提示框触发模式: axis")

印刷输出：

图表类型: Line
X轴数据点数量: 7
系列名称: ['产品A', '产品B']
提示框触发模式: axis

如果将上述代码中的 trigger="axis" 改为 trigger="item"（或直接省略，因为这是默认值），提示框将变回数据项触发模式。TooltipOpts 还支持许多其他配置，如格式化显示内容（formatter）、调整背景色和边框等，我们将在后续综合案例中深入讲解。

二、全局配置项：视觉映射（VisualMap）

视觉映射（VisualMap）是一个强大的组件，它能将数据值映射到视觉元素（如颜色）。在时间趋势图中，我们可以用它为折线不同区间的线段着色，从而直观地表达数据所处的等级或状态。

例如，在空气质量指数（AQI）监测中，不同数值区间对应不同的污染等级。我们可以用 VisualMapOpts 创建一个分段（is_piecewise=True）的颜色映射组件。

核心参数解析：

• pos_top, pos_right: 控制组件在图表容器中的位置。
• is_piecewise: 设为 True 表示使用分段式视觉映射，显示为多个色块；设为 False 则为连续式，显示为一个可拖动的滑杆。
• pieces: 定义分段规则。每个分段是一个字典，包含 min（最小值）、max（最大值）和 color（颜色）。可以定义 {"min": 300} 来表示“300及以上”。
• out_of_range: 为所有未在 pieces 中定义的数据范围指定一个颜色，作为兜底。

下面我们使用模拟的AQI数据来演示：

from pyecharts import options as opts
from pyecharts.charts import Line
import pandas as pd

# 模拟一段时间内的AQI数据
dates_aqi = pd.date_range(start='2024-05-01', periods=30, freq='D').strftime('%m-%d').tolist()
# 生成包含不同区间的AQI数据
aqi_values = [45, 38, 120, 85, 65, 180, 220, 90, 110, 75,
              55, 310, 280, 150, 130, 95, 70, 40, 160, 200,
              250, 100, 80, 60, 35, 140, 170, 190, 260, 50]
aqi_rules = [
    {"min": 0, "max": 50, "label": "优", "color": "#096"},
    {"min": 50, "max": 100, "label": "良", "color": "#ffde33"},
    {"min": 100, "max": 150, "label": "轻度污染", "color": "#ff9933"},
    {"min": 150, "max": 200, "label": "中度污染", "color": "#cc0033"},
    {"min": 200, "max": 300, "label": "重度污染", "color": "#660099"},
    {"min": 300, "label": "严重污染", "color": "#7e0023"},
]

chart_with_visualmap = (
    Line()
    .add_xaxis(dates_aqi)
    .add_yaxis(
        series_name="AQI",
        y_axis=aqi_values,
        is_smooth=True,           # 使用平滑曲线
        is_symbol_show=False,     # 不显示数据点标记
        label_opts=opts.LabelOpts(is_show=False) # 不显示数据标签
    )
    .set_global_opts(
        title_opts=opts.TitleOpts(title="空气质量指数 (AQI) 趋势与等级映射"),
        tooltip_opts=opts.TooltipOpts(trigger="axis"),
        # 配置分段式视觉映射
        visualmap_opts=opts.VisualMapOpts(
            pos_top="50",  # 距离顶部50像素
            pos_right="20", # 距离右侧20像素
            is_piecewise=True,
            pieces=aqi_rules,
            out_of_range={"color": "#999"},
        )
    )
)

# 打印摘要信息
print(f"图表类型: {type(chart_with_visualmap).__name__}")
print(f"数据天数: {len(dates_aqi)}")
print("视觉映射类型: 分段式 (piecewise)")
print(f"定义的分段数量: {len(aqi_rules)}")

印刷输出：

图表类型: Line
数据天数: 30
视觉映射类型: 分段式 (piecewise)
定义的分段数量: 6

运行后，图表右上角会出现一个颜色图例。折线会根据其Y值（AQI）所在区间，显示为对应的颜色。点击图例中的某个色块，可以高亮或隐藏该区间的线段，交互式地分析不同污染等级的时间分布。

三、其他配置项：折线与标记点样式

除了全局配置，我们还可以对每个数据系列自身的视觉样式进行精细调整。这通常在 add_yaxis 方法中通过相应的参数或配置项对象来完成。

常用样式配置项：

• linestyle_opts: 对应 LineStyleOpts，控制折线的样式，如颜色（color）、宽度（width）、线型（type_，如 'solid'（实线）、'dashed'（虚线）、'dotted'（点线））。
• itemstyle_opts: 对应 ItemStyleOpts，控制数据项（即标记点）的样式，如填充色（color）、边框色（border_color）、边框宽度（border_width）等。
• symbol: 控制标记点的形状，如 'circle'（圆形，默认）、'rect'（矩形）、'triangle'（三角形）、'diamond'（菱形）等。
• symbol_size: 控制标记点的大小。

下面我们将创建一个样式高度自定义的折线图：

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

# 示例数据
categories = ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
values = [12, 8, 15, 10, 18, 14, 20]

custom_style_chart = (
    Line()
    .add_xaxis(categories)
    .add_yaxis(
        series_name="活跃用户数",
        y_axis=values,
        # 配置标记点样式
        symbol="triangle",  # 三角形标记
        symbol_size=20,
        # 配置折线样式
        linestyle_opts=opts.LineStyleOpts(
            color="#2E8B57",  # 海绿色
            width=4,
            type_="dashed"    # 虚线
        ),
        # 配置数据项（标记点）样式
        itemstyle_opts=opts.ItemStyleOpts(
            color="#1E90FF",      # 道奇蓝（填充色）
            border_color="#FFD700", # 金色（边框色）
            border_width=3
        )
    )
    .set_global_opts(title_opts=opts.TitleOpts(title="自定义样式的折线图"))
)

# 打印已知的样式参数摘要
print(f"图表类型: {type(custom_style_chart).__name__}")
print("标记点形状: triangle")
print("折线颜色: #2E8B57")
print("折线类型: dashed")
print("标记点填充色: #1E90FF")

印刷输出：

图表类型: Line
标记点形状: triangle
折线颜色: #2E8B57
折线类型: dashed
标记点填充色: #1E90FF

生成的图表将显示为金色的三角形标记点，带有蓝色填充，并由海绿色的虚线连接。通过灵活组合这些样式配置，你可以让图表更好地匹配品牌风格或突出特定数据特征。

📝 动手练一练

1. 修改提示框内容：使用本章第一节的“产品销量趋势”双系列折线图代码，尝试在 TooltipOpts 中添加 formatter 参数，将默认提示内容改为更友好的格式，例如“日期：{b}
   产品A：{c0} 件
   产品B：{c1} 件”。（提示：{b} 对应类目轴值，{c0}、{c1} 对应第一个和第二个系列的值）。

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

dates = ['2024-01-01', '2024-01-02', '2024-01-03']
product_a = [15, 22, 18]
product_b = [20, 25, 22]

chart = (
    Line()
    .add_xaxis(dates)
    .add_yaxis("产品A", product_a)
    .add_yaxis("产品B", product_b)
    .set_global_opts(
        title_opts=opts.TitleOpts(title="自定义提示框格式"),
        tooltip_opts=opts.TooltipOpts(
            trigger="axis",
            formatter="日期：{b}<br/>产品A：{c0} 件<br/>产品B：{c1} 件"
        )
    )
)
print(f"提示框格式化器: {chart.options['tooltip'].get('formatter')[:50]}...") # 截断显示

提示框格式化器: 日期：{b}<br/>产品A：{c0} 件<br/>产品B：{c1} 件...

2. 创建连续式视觉映射：修改AQI示例中的 VisualMapOpts，将 is_piecewise 设为 False，并设置 min 和 max 为数据的大致范围（如0和350），观察图表右上角的组件和折线颜色如何变化。

# 基于之前AQI的dates_aqi和aqi_values数据
chart_continuous = (
    Line()
    .add_xaxis(dates_aqi[:5]) # 取前5天简化显示
    .add_yaxis("AQI", aqi_values[:5], is_symbol_show=False)
    .set_global_opts(
        visualmap_opts=opts.VisualMapOpts(
            is_piecewise=False, # 改为连续式
            min_=0,
            max_=350,
            range_color=['#096', '#7e0023'] # 从优到严重污染的颜色渐变
        )
    )
)
print(f"视觉映射类型: {'连续式' if chart_continuous.options['visualMap'].get('type') == 'continuous' else '分段式'}")
print(f"值域范围: [{chart_continuous.options['visualMap'].get('min')}, {chart_continuous.options['visualMap'].get('max')}]")

视觉映射类型: 连续式
值域范围: [0, 350]

本章小结

本节我们深入探讨了时间趋势可视化中三类极为实用的配置项：提示框（Tooltip）、视觉映射（VisualMap） 和系列样式（LineStyle/ItemStyle）。掌握这些配置，你就能从“画出图表”进阶到“优化图表”，使其交互更友好、信息层次更分明、视觉表达更精准。

📋 行动清单

• 练习提示框触发：在一个多系列折线图中，分别使用 trigger: 'item' 和 trigger: 'axis'，体会两者在不同分析场景下的优劣。
• 应用视觉映射：为你手头的一份带有数值等级（如温度、湿度、销售额达成率）的时间序列数据，配置一个分段式视觉映射，用颜色直观表达数据状态。
• 定制图表样式：尝试修改折线图的线条类型、颜色和标记点形状，制作一个符合你个人或项目品牌色的定制化图表。

—— 小象教研组