toolbox工具箱组件完全指南

📋 概述

**toolbox（工具箱）**是ECharts提供的内置工具栏组件，包含数据视图、动态类型切换、数据区域缩放、还原等实用功能。它为用户提供了一系列交互工具，增强图表的可探索性。

核心价值

• 数据查看：直接查看原始数据表格
• 类型切换：在柱状图、折线图、堆叠之间切换
• 区域缩放：框选数据区域进行放大
• 一键还原：恢复到初始状态
• 自定义扩展：添加自定义工具按钮

---

🎯 核心概念

1. 基础工具箱

option = {
  toolbox: {
    show: true,
    feature: {
      dataView: { show: true },      // 数据视图
      magicType: { show: true },     // 动态类型
      dataZoom: { show: true },      // 区域缩放
      restore: { show: true }        // 还原
    }
  }
};

2. 工具类型

工具	功能	配置项
dataView	显示数据表格	dataView
magicType	切换图表类型	magicType
dataZoom	框选缩放	dataZoom
restore	还原配置	restore
saveAsImage	保存图片	saveAsImage
自定义	扩展功能	myTool

---

🔧 详细配置项

完整toolbox配置

option = {
  toolbox: {
    // === 显示控制 ===
    show: true,
    
    // === 位置 ===
    left: 'right',
    top: 'top',
    right: 10,
    bottom: 'auto',
    
    // === 布局 ===
    orient: 'horizontal', // 'horizontal' | 'vertical'
    
    // === 尺寸 ===
    itemSize: 15,         // 工具图标大小
    itemGap: 10,          // 工具之间的间隔
    
    // === 样式 ===
    color: ['#5470c6', '#91cc75', '#fac858'], // 每个工具的颜色
    emphasis: {
      iconStyle: {
        borderColor: '#f00',
        borderWidth: 2
      }
    },
    
    // === 背景 ===
    backgroundColor: 'transparent',
    borderColor: '#ccc',
    borderWidth: 0,
    borderRadius: 0,
    
    // === 功能配置 ===
    feature: {
      // === 数据视图 ===
      dataView: {
        show: true,
        title: '数据视图',
        icon: 'M17.5,17.5H14V14h3.5V17.5z M10.5,17.5H7V14h3.5V17.5z M17.5,10.5H14V7h3.5V10.5z M10.5,10.5H7V7h3.5V10.5z',
        readOnly: false, // 是否只读
        lang: ['数据视图', '关闭', '刷新'],
        backgroundColor: '#fff',
        textareaColor: '#fff',
        textareaBorderColor: '#333',
        textColor: '#000',
        buttonColor: '#c23531',
        buttonTextColor: '#fff',
        
        // 自定义数据处理
        optionToContent: function(opt) {
          const series = opt.series;
          const table = '<table border="1"><tbody>' +
            '<tr><td>时间</td><td>' + series[0].name + '</td><td>' + 
            (series[1] ? series[1].name : '') + '</td></tr>' +
            opt.xAxis[0].data.map((val, idx) => {
              return '<tr><td>' + val + '</td><td>' + 
                series[0].data[idx] + '</td><td>' + 
                (series[1] ? series[1].data[idx] : '') + '</td></tr>';
            }).join('') +
            '</tbody></table>';
          return table;
        },
        
        contentToOption: function(html, opt) {
          // 自定义从HTML恢复数据的逻辑
          return opt;
        }
      },
      
      // === 动态类型切换 ===
      magicType: {
        show: true,
        title: {
          line: '切换为折线图',
          bar: '切换为柱状图',
          stack: '切换为堆叠',
          tiled: '切换为平铺'
        },
        type: ['line', 'bar', 'stack', 'tiled'],
        icon: {
          line: 'M4.5,3.5h15v2h-15V3.5z M4.5,10.5h15v2h-15V10.5z M4.5,17.5h15v2h-15V17.5z',
          bar: 'M7,7h3v10H7V7z M11.5,3h3v14h-3V3z M16,11h3v6h-3V11z',
          stack: 'M3.5,7h17v2h-17V7z M6.5,11h11v2h-11V11z M9.5,15h5v2h-5V15z',
          tiled: 'M3.5,3.5h8v8h-8V3.5z M12.5,3.5h8v8h-8V3.5z M3.5,12.5h8v8h-8V12.5z M12.5,12.5h8v8h-8V12.5z'
        }
      },
      
      // === 数据区域缩放 ===
      dataZoom: {
        show: true,
        title: {
          zoom: '区域缩放',
          back: '区域缩放还原'
        },
        icon: {
          zoom: 'M17.5,17.5l-5.1-5.1 M15.5,7c0,4.7-3.8,8.5-8.5,8.5S-1.5,11.7-1.5,7S2.3-1.5,7-1.5S15.5,2.3,15.5,7z M14.5,14.5l5,5',
          back: 'M16,8.5l-5-5l-5,5 M11,3.5v9 M7,11.5v-8 M3.5,11.5h8'
        },
        xAxisIndex: 0, // 控制的x轴索引
        yAxisIndex: 0  // 控制的y轴索引
      },
      
      // === 还原 ===
      restore: {
        show: true,
        title: '还原',
        icon: 'M7.5,14.5v-3 M7.5,11.5l-3,3 M7.5,11.5l3,3 M11.5,3.5v8 M3.5,7.5h8 M15.5,11.5l-3,3 M15.5,11.5l3,3'
      },
      
      // === 保存图片 ===
      saveAsImage: {
        show: true,
        title: '保存为图片',
        type: 'png', // 'png' | 'jpeg'
        name: 'echarts', // 文件名
        backgroundColor: 'auto', // 或 '#fff'
        connectedBackgroundColor: '#fff',
        excludeComponents: ['toolbox'], // 排除的组件
        pixelRatio: 2, // 像素比（影响清晰度）
        icon: 'M16,11.5c0,0.6-0.4,1-1,1s-1-0.4-1-1s0.4-1,1-1S16,10.9,16,11.5z M19,16H5c-0.6,0-1-0.4-1-1V6c0-0.6,0.4-1,1-1h5.5l1,1h7.5c0.6,0,1,0.4,1,1v9C19.9,15.6,19.6,16,19,16z'
      },
      
      // === 自定义工具 ===
      myTool1: {
        show: true,
        title: '自定义工具1',
        icon: 'path://M432.45,595.444...', // SVG路径
        onclick: function() {
          alert('自定义工具被点击');
        }
      },
      
      myTool2: {
        show: true,
        title: '导出数据',
        icon: 'image://https://example.com/icon.png', // 图片URL
        onclick: function() {
          // 导出CSV
          const csv = convertToCSV(chart.getOption());
          downloadFile(csv, 'data.csv');
        }
      }
    }
  }
};

---

💡 实战案例

案例1：标准工具箱

option = {
  title: {
    text: '销售数据分析'
  },
  
  toolbox: {
    feature: {
      dataView: { readOnly: false },
      magicType: { type: ['line', 'bar'] },
      restore: {},
      saveAsImage: {}
    }
  },
  
  xAxis: {
    type: 'category',
    data: ['一月', '二月', '三月', '四月', '五月']
  },
  
  yAxis: {
    type: 'value'
  },
  
  series: [{
    name: '销售额',
    type: 'bar',
    data: [120, 200, 150, 80, 70]
  }]
};

案例2：带自定义工具的toolbox

option = {
  toolbox: {
    feature: {
      dataView: {},
      restore: {},
      saveAsImage: {},
      
      // 自定义：导出Excel
      exportExcel: {
        show: true,
        title: '导出Excel',
        icon: 'path://M12,2C6.48,2,2,6.48,2,12s4.48,10,10,10s10-4.48,10-10S17.52,2,12,2z M16,13h-3v3h-2v-3H8v-2h3V8h2v3h3V13z',
        onclick: function() {
          const data = chart.getOption().series[0].data;
          const csv = '月份,销售额\n' + 
            data.map((val, idx) => `${idx + 1}月,${val}`).join('\n');
          
          const blob = new Blob(['\ufeff' + csv], { type: 'text/csv;charset=utf-8;' });
          const link = document.createElement('a');
          link.href = URL.createObjectURL(blob);
          link.download = '销售数据.csv';
          link.click();
        }
      }
    }
  }
};

---

⚠️ 常见问题

问题1：工具箱遮挡图表

解决：

toolbox: {
  right: 20,  // 调整位置
  top: 10
}

// 或者给grid留空间
grid: {
  right: '15%' // 为toolbox预留空间
}

问题2：dataView显示乱码

解决：

dataView: {
  lang: ['数据视图', '关闭', '刷新'],
  optionToContent: function(opt) {
    // 自定义渲染逻辑
    return customTableHTML;
  }
}

---

🎯 最佳实践

1. 选择合适的工具

// 商务报表：只需保存和还原
feature: {
  restore: {},
  saveAsImage: {}
}

// 数据分析：全功能
feature: {
  dataView: { readOnly: false },
  magicType: { type: ['line', 'bar', 'stack'] },
  dataZoom: {},
  restore: {},
  saveAsImage: {}
}

2. 响应式配置

const isMobile = window.innerWidth < 768;

toolbox: {
  show: !isMobile, // 移动端隐藏
  itemSize: isMobile ? 12 : 15,
  itemGap: isMobile ? 5 : 10
}

---

📊 性能指标

配置	影响	建议
基础工具箱	<1ms	无限制
带dataView	5ms	大数据时自定义渲染
多个工具	2-3ms	最多5个工具

---

🔗 相关链接

• legend图例
• dataZoom缩放

---

💎 总结

toolbox核心价值：

• ✅ 提供实用交互工具
• ✅ 数据查看和导出
• ✅ 图表类型切换
• ✅ 自定义扩展能力

关键配置原则：

1. 按需启用：只开启需要的工具
2. 位置合理：避免遮挡图表
3. 移动端隐藏：小屏幕不显示
4. 自定义扩展：根据业务需求添加工具

掌握toolbox，让图表更互动！🛠️

工具箱功能集

{
  "title": {
    "text": "工具箱组件",
    "left": "center"
  },
  "tooltip": {
    "trigger": "axis"
  },
  "toolbox": {
    "feature": {
      "dataView": {
        "show": true,
        "readOnly": false
      },
      "magicType": {
        "show": true,
        "type": [
          "line",
          "bar"
        ]
      },
      "restore": {
        "show": true
      },
      "saveAsImage": {
        "show": true
      }
    }
  },
  "xAxis": {
    "type": "category",
    "data": [
      "产品A",
      "产品B",
      "产品C",
      "产品D"
    ]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [
    {
      "type": "bar",
      "data": [
        120,
        200,
        150,
        80
      ],
      "itemStyle": {
        "color": "#5470c6"
      }
    }
  ]
}