用 ECharts markLine 标注节假日

使用 ECharts markLine 精准标注节假日

关键词：ECharts、markLine、节假日标注、数据可视化、交互一致性、时间序列图表

本文将详细介绍如何在 ECharts 时间序列折线图中，利用 markLine 功能精准标注节假日信息。重点在于保持视觉风格统一、不干扰现有交互行为（如缩放、联动、Tooltip） ，同时兼顾性能与可维护性。

一、背景与目标

在能源、交通、电商等业务场景中，节假日对数据波动具有显著影响。例如电力负荷在春节、国庆期间通常呈现明显低谷或高峰。因此，在趋势图中标注节假日，有助于用户快速识别异常波动背后的原因。

设计目标

• 视觉风格统一：采用静默线型标线（无端点符号）、末端红色标签，多个节日自动换行显示；
• 交互兼容：不影响图表的缩放（dataZoom）、联动（brush/link）、Tooltip 等核心交互；
• 轻量高效：仅在必要时渲染，避免冗余计算与 DOM 开销；
• 数据驱动：节假日信息与主数据索引严格对齐，支持动态更新。

---

二、数据模型设计

我们采用与主数据同索引对齐的方式组织节假日信息：

{
  "power": {
    "index": [
      "2025.01", "2025.02", "2025.03", "2025.04", "2025.05",
      "2025.06", "2025.07", "2025.08", "2025.09", "2025.10"
    ],
    "holiday": [
      "元旦", "春节", null, "清明节", "劳动节",
      "端午节", null, null, "中秋节", "国庆节"
    ]
  }
}

字段说明

• index：横轴时间标识，格式为 YYYY.MM，对应 ECharts 的 xAxis.data；
• holiday：与 index 同步的节假日字符串数组；若某月无节日，则为 null；
• 支持单月多个节日（如"元旦、除夕"），用中文顿号 、 分隔。

💡 扩展建议 ：实际项目中，节假日数据可由后端 API 提供，或通过 中国法定节假日 API 动态生成，提升通用性。

---

三、关键技术实现

1. 构建 markLine 数据结构

我们需要将原始数据转换为 ECharts markLine.data 所需的格式：

const eventMarkLines = (index || [])
  .map((d, i) => {
    const h = holiday?.[i];
    if (!h) return null;

    // 格式化时间标签（YYYY.MM → YYYY-MM）
    const [year, month] = String(d).split(".");
    const dateLabel = `${year}-${month.padStart(2, "0")}`;

    // 多节日换行显示（"元旦、春节" → "元旦\n春节"）
    const holidayLabel = String(h).replace(/、/g, "\n");

    return {
      xAxis: d, // 对齐 x 轴刻度
      name: `${dateLabel}\n${holidayLabel}` // 标签内容
    };
  })
  .filter(Boolean); // 剔除 null 项

关键点解析：

• xAxis: d：确保标线精确对齐到对应月份刻度；
• name 字段 ：作为 label.formatter 的输入，支持多行文本；
• 格式标准化 ：YYYY-MM 比 YYYY.MM 更符合国际日期惯例，提升可读性。

---

2. 配置 markLine 样式与行为

将生成的标线数据挂载到"电量"主序列（或其他指定序列）上：

const seriesItem = {
  name: "电量",
  type: "line",
  data: powerData,
  symbol: "none",
  smooth: true,
  lineStyle: { color: "#31A1F7", width: 2 },
  itemStyle: { color: "#31A1F7" },
  ...(eventMarkLines.length > 0 && {
    markLine: {
      silent: true, // ⭐ 关键：禁止响应鼠标事件，避免干扰交互
      symbol: ["none", "none"], // 隐藏两端箭头/圆点
      lineStyle: {
        color: "#7FACD9",
        width: 1,
        type: "solid"
      },
      label: {
        show: true,
        position: "end", // 标签置于线末端（右侧）
        color: "#FF5555", // 红色突出节假日
        fontSize: 12,
        formatter: ({ name }) => name // 直接使用预处理好的多行文本
      },
      data: eventMarkLines
    }
  })
};

为什么选择 markLine？

• 相比 markArea（区域标记）更轻量；
• 相比自定义 graphic 元素，天然支持坐标系对齐与缩放同步；
• 内置 silent 属性可轻松隔离交互干扰。

---

四、边界处理与容错机制

为保障系统鲁棒性，需考虑以下边界情况：

场景	处理方式
holiday[i] 为 null 或空字符串	跳过该月，不生成标线
index 与 holiday 长度不一致	以 index 为主，越界部分视为无节日
非"电量"Tab 页面	仅在特定序列（如电量）中注入 markLine，避免全局污染
缩放/拖拽时	silent: true 确保标线不捕获鼠标事件，不影响 dataZoom

✅ 最佳实践 ：可通过配置项控制是否启用节假日标注，例如 showHolidays: boolean，便于按需开关。

---

五、性能与用户体验优化

性能表现

• markLine 是 ECharts 内部轻量级图元，渲染开销极小；
• 数据预处理在 JS 层完成，避免在 formatter 中做复杂计算；
• 仅当存在节假日时才注入 markLine 配置，减少无效渲染。

用户体验

• 标签位置 ：position: "end" 避免与数据点或 Tooltip 重叠；
• 颜色对比：红色标签在蓝色主色调背景下高亮醒目；
• 多节日换行：提升密集信息的可读性，避免标签溢出或截断。

---

六、完整配置示例

const option = {
  legend: { show: false },
  grid: {
    left: "2%",
    right: "0%",
    bottom: "10%",
    top: "14%",
    containLabel: true
  },
  tooltip: { trigger: "axis" },
  xAxis: {
    type: "category",
    data: index // 如 ["2025.01", "2025.02", ...]
  },
  yAxis: {
    type: "value",
    name: "亿千瓦时"
  },
  series: [seriesItem] // 包含 markLine 的主序列
};

---