Matplotlib 的 vlines() 返回 LineCollection 对象，无法直接用于 legend()；本文详解三种可靠方案：创建时设 label、后续调用 set_label()，或手动传入 LineCollection 到 legend()，并说明各方法对 get_legend_handles_labels() 的影响。
matplotlib 的 `vlines()` 返回 linecollection 对象，无法直接用于 `legend()`；本文详解三种可靠方案：创建时设 `label`、后续调用 `set_label()`，或手动传入 linecollection 到 `legend()`，并说明各方法对 `get_legend_handles_labels()` 的影响。
在使用 Matplotlib 绘制垂直线（如触发事件标记）时，ax.vlines() 是常用方法。但它返回的是 LineCollection 对象，而非单个 Line2D 实例——这导致无法像普通折线那样直接拼接到 legend() 的 handles 列表中。不过，无需强行“提取 Line2D”（LineCollection 本质是多线集合，不包含独立的 Line2D 子对象），正确做法是让图例系统原生支持该 collection。
✅ 推荐方案一：创建时直接指定 label
最简洁、最符合 Matplotlib 设计逻辑的方式是在调用 vlines() 时传入 label 参数：
fig, ax = plt.subplots() ax.plot(meas['times'], meas['data'], label='measurement') ax.vlines([trigger_time], 0, 100, colors='red', linestyles='--', label='trigger event') ax.legend() # 自动收集所有带 label 的 artists
此方式下，ax.get_legend_handles_labels() 将正确返回包含 Line2D 和 LineCollection 的混合列表，且标签顺序与绘图顺序一致。
✅ 推荐方案二：动态设置 label（适用于已有 LineCollection）
若 vlines() 已执行完毕，可对返回的 LineCollection 对象调用 set_label()：
vlins = ax.vlines([trigger_time], 0, 100, colors='red', linestyles='--')
vlins.set_label('trigger event')
ax.legend() # 无需手动传参，legend 自动识别
该方法同样能被 get_legend_handles_labels() 捕获，确保后续图例更新或批量管理的一致性。
⚠️ 备选方案：手动传入 LineCollection（不推荐用于长期维护）
虽然可绕过自动收集机制，显式构造 handles 列表：
lines, labels = ax.get_legend_handles_labels() ax.legend(lines + [vlins], labels + ['trigger event']) # 注意：[vlins]，非 vlins.to_list()
但需注意：LineCollection 没有 to_list() 方法（该调用会报错），必须以单元素列表 [vlins] 形式传入。此外，此方式不会将 vlins 注册进 Axes 内部的 legend handle 管理链，后续调用 get_legend_handles_labels() 将不包含该条目，易引发图例状态不一致问题。
总结与最佳实践
- ✅ 始终优先使用
label=参数或set_label()—— 它们使LineCollection成为“一等图例公民”，兼容所有自动图例逻辑； - ❌ 避免尝试从
LineCollection中“提取 Line2D”——技术上不可行，语义上也不合理（它是独立的 artist 类型）； - ? 若需调试图例内容，可用
ax.get_legend_handles_labels()验证是否已正确注册； - ? 补充提示：
LineCollection在图例中默认渲染为一条短线（长度约 20 pt），可通过handler_map自定义其图例样式（如改用HandlerLine2D并设置marker_pad或numpoints），但通常默认表现已足够清晰。
遵循上述方法，即可稳健、可维护地为 vlines、hlines、fill_between 等返回集合类对象的绘图函数添加图例支持。
