legend图例组件完全指南

📋 概述

**legend（图例）**是用于标识不同系列或类别的组件，帮助用户理解图表中各种颜色、符号代表的含义。它是多系列图表不可或缺的说明性组件。

核心价值

• 系列标识：清晰标识每个数据系列
• 交互控制：点击切换系列显示/隐藏
• 信息汇总：展示系列名称和数值
• 布局灵活：支持多种位置和排列方式

---

🎯 核心概念

1. 基础图例

option = {
  legend: {
    data: ['邮件营销', '联盟广告', '视频广告']
  },
  
  series: [
    { name: '邮件营销', type: 'line', data: [...] },
    { name: '联盟广告', type: 'line', data: [...] },
    { name: '视频广告', type: 'line', data: [...] }
  ]
};

2. 图例类型

// 普通图例
legend: {
  type: 'plain' // 默认
}

// 滚动图例（数据多时）
legend: {
  type: 'scroll',
  orient: 'horizontal', // 或 'vertical'
  pageButtonItemGap: 5,
  pageButtonGap: 10
}

---

🔧 详细配置项

完整legend配置

option = {
  legend: {
    // === 类型 ===
    type: 'plain', // 'plain' | 'scroll'
    
    // === 数据 ===
    data: [
      '系列1',
      '系列2',
      {
        name: '系列3',
        icon: 'circle', // 自定义图标
        textStyle: { color: '#f00' }
      }
    ],
    
    // === 位置 ===
    left: 'center', // 'left' | 'center' | 'right' | 像素值
    top: 'top',     // 'top' | 'middle' | 'bottom' | 像素值
    right: 'auto',
    bottom: 'auto',
    width: 'auto',
    height: 'auto',
    
    // === 方向 ===
    orient: 'horizontal', // 'horizontal' | 'vertical'
    
    // === 对齐方式 ===
    align: 'auto', // 'auto' | 'left' | 'right'
    
    // === 间距 ===
    itemGap: 10,      // 图例项之间的间隔
    itemWidth: 25,    // 图例标记宽度
    itemHeight: 14,   // 图例标记高度
    
    // === 图标形状 ===
    // 支持：'circle', 'rect', 'roundRect', 'triangle', 
    //       'diamond', 'pin', 'arrow', 'none'
    // 或使用图片：'image://path/to/icon.png'
    
    // === 选中模式 ===
    selectedMode: true, // true | false | 'single' | 'multiple'
    
    // === 初始选中状态 ===
    selected: {
      '系列1': true,
      '系列2': false // 默认不显示
    },
    
    // === 文本样式 ===
    textStyle: {
      color: '#333',
      fontSize: 12,
      fontWeight: 'normal',
      
      // 富文本
      rich: {
        a: { color: '#f00' }
      }
    },
    
    // === 格式化 ===
    formatter: '{name}',
    // formatter: function(name) {
    //   return '【' + name + '】';
    // },
    
    // === 提示框 ===
    tooltip: {
      show: false,
      formatter: function(name) {
        return '点击切换：' + name;
      }
    },
    
    // === 翻页按钮（scroll类型）===
    pageButtonItemGap: 5,
    pageButtonGap: 10,
    pageButtonPosition: 'end',
    pageFormatter: '{current}/{total}',
    
    // === 背景 ===
    backgroundColor: 'transparent',
    borderColor: '#ccc',
    borderWidth: 0,
    borderRadius: 0,
    
    // === 阴影 ===
    shadowBlur: 0,
    shadowColor: 'transparent',
    shadowOffsetX: 0,
    shadowOffsetY: 0,
    
    // === 其他 ===
    silent: false // 是否不响应鼠标事件
  }
};

---

💡 实战案例

案例1：标准多系列图例

option = {
  title: {
    text: '销售趋势分析'
  },
  
  legend: {
    data: ['2021年', '2022年', '2023年'],
    top: 30,
    itemGap: 20,
    textStyle: {
      fontSize: 13
    }
  },
  
  xAxis: {
    type: 'category',
    data: ['Q1', 'Q2', 'Q3', 'Q4']
  },
  
  yAxis: {
    type: 'value'
  },
  
  series: [
    {
      name: '2021年',
      type: 'line',
      data: [320, 332, 301, 334]
    },
    {
      name: '2022年',
      type: 'line',
      data: [350, 380, 360, 390]
    },
    {
      name: '2023年',
      type: 'line',
      data: [380, 420, 400, 450]
    }
  ]
};

案例2：滚动图例

const categories = Array.from({length: 20}, (_, i) => `产品${i + 1}`);

option = {
  legend: {
    type: 'scroll',
    orient: 'vertical',
    right: 10,
    top: 50,
    bottom: 20,
    data: categories,
    textStyle: {
      fontSize: 11
    },
    pageButtonGap: 5,
    pageButtonItemGap: 3
  },
  
  series: categories.map((name, i) => ({
    name: name,
    type: 'bar',
    data: [Math.floor(Math.random() * 100)]
  }))
};

案例3：自定义图标和样式

option = {
  legend: {
    data: [
      {
        name: '销售额',
        icon: 'rect',
        textStyle: {
          color: '#333',
          fontWeight: 'bold'
        }
      },
      {
        name: '利润',
        icon: 'circle',
        textStyle: {
          color: '#666'
        }
      },
      {
        name: '增长率',
        icon: 'triangle',
        textStyle: {
          color: '#999'
        }
      }
    ],
    top: 30,
    itemGap: 15,
    itemWidth: 20,
    itemHeight: 12
  },
  
  series: [
    { name: '销售额', type: 'bar', data: [...] },
    { name: '利润', type: 'bar', data: [...] },
    { name: '增长率', type: 'line', data: [...] }
  ]
};

案例4：带数值的图例

const seriesData = [
  { name: '邮件营销', value: 1234 },
  { name: '联盟广告', value: 2345 },
  { name: '视频广告', value: 1890 }
];

option = {
  legend: {
    data: seriesData.map(item => item.name),
    top: 30,
    formatter: function(name) {
      const item = seriesData.find(d => d.name === name);
      return `${name}: ${item.value}`;
    }
  },
  
  series: seriesData.map(item => ({
    name: item.name,
    type: 'pie',
    radius: '50%',
    data: [{ value: item.value, name: item.name }]
  }))
};

---

⚠️ 常见问题

问题1：图例与series名称不匹配

解决：

// ❌ 错误：名称不一致
legend: {
  data: ['系列A']
}
series: [
  { name: '系列a', ... } // 大小写不同
]

// ✅ 正确：完全一致
legend: {
  data: ['系列A']
}
series: [
  { name: '系列A', ... }
]

问题2：图例太多拥挤

解决：

// 使用滚动图例
legend: {
  type: 'scroll',
  orient: 'vertical',
  right: 10,
  top: 50,
  bottom: 20
}

// 或者减少显示的图例
legend: {
  selected: {
    '系列1': true,
    '系列2': true,
    '系列3': false, // 默认隐藏
    '系列4': false
  }
}

---

🎯 最佳实践

1. 位置选择

// 顶部水平（最常用）
legend: {
  top: 30,
  left: 'center',
  orient: 'horizontal'
}

// 右侧垂直
legend: {
  right: 10,
  top: 'middle',
  orient: 'vertical'
}

// 底部
legend: {
  bottom: 10,
  left: 'center'
}

2. 响应式配置

const isMobile = window.innerWidth < 768;

legend: {
  orient: isMobile ? 'horizontal' : 'vertical',
  top: isMobile ? 'bottom' : 30,
  left: 'center',
  itemGap: isMobile ? 5 : 10,
  textStyle: {
    fontSize: isMobile ? 10 : 12
  }
}

3. 交互增强

legend: {
  selectedMode: 'single', // 单选模式
  tooltip: {
    show: true,
    formatter: function(name) {
      return `点击显示/隐藏：${name}`;
    }
  }
}

---

📊 性能指标

配置	渲染时间	建议
<10个图例	2ms	无限制
10-50个图例	5ms	正常
>50个图例	10ms	使用scroll类型

---

🔗 相关链接

• dispatchAction控制
• toolbox工具箱

---

💎 总结

legend核心价值：

• ✅ 清晰标识数据系列
• ✅ 交互式显示/隐藏
• ✅ 支持滚动分页
• ✅ 自定义图标和样式

关键配置原则：

1. 确保名称一致：legend.data与series.name完全匹配
2. 合理选择位置：避免遮挡图表内容
3. 数据多用scroll：超过10个使用滚动图例
4. 响应式适配：移动端调整方向和字体

掌握legend，让图表更易理解！📋

图例组件样式

{
  "title": {
    "text": "图例配置示例",
    "left": "center"
  },
  "tooltip": {
    "trigger": "axis"
  },
  "legend": {
    "orient": "horizontal",
    "top": "10%",
    "left": "center",
    "backgroundColor": "#eee",
    "borderColor": "#ccc",
    "borderWidth": 1,
    "borderRadius": 4,
    "padding": [
      10,
      20
    ]
  },
  "xAxis": {
    "type": "category",
    "data": [
      "Q1",
      "Q2",
      "Q3",
      "Q4"
    ]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [
    {
      "name": "产品A",
      "type": "bar",
      "data": [
        100,
        150,
        200,
        250
      ]
    },
    {
      "name": "产品B",
      "type": "bar",
      "data": [
        120,
        170,
        220,
        270
      ]
    },
    {
      "name": "产品C",
      "type": "bar",
      "data": [
        80,
        130,
        180,
        230
      ]
    }
  ]
}