ECharts React Tools

🚀 一套基于 React 的 ECharts 封装库，提供简单易用的图表组件和灵活的底层 Hook。

✨ 特性

• 🎯 开箱即用：提供 BarChart、LineChart、PieChart 等常用图表组件
• 🔧 高度灵活：基于 useBaseChart Hook，支持完全自定义配置
• 📝 TypeScript 支持：完整的类型定义，优秀的开发体验
• 🎨 响应式设计：自动处理容器大小变化
• ⚡ 性能优化：内置防抖和懒加载机制

📦 安装

npm install echarts-react-tools
# 或
pnpm add echarts-react-tools

🎯 快速开始

方式一：使用封装组件（推荐新手）

import { BarChart } from 'echarts-react-tools'

function App() {
  const data = [
    { name: '周一', value: 120 },
    { name: '周二', value: 200 },
    { name: '周三', value: 150 },
  ]

  return (
    <BarChart
      data={data}
      xAxis={['周一', '周二', '周三']}
      height={400}
    />
  )
}

方式二：使用底层 Hook（推荐高级用户）

import { useBaseChart, useBarOption } from 'echarts-react-tools'

function App() {
  const data = [
    { name: '周一', value: 120 },
    { name: '周二', value: 200 },
    { name: '周三', value: 150 },
  ]

  const option = useBarOption({
    data,
    xAxis: ['周一', '周二', '周三'],
  })

  const ref = useBaseChart({ option })

  return <div ref={ref} style={{ height: 400 }} />
}

📚 组件文档

BarChart 柱状图

interface BarChartProps {
  /** 数据 */
  data?: BarData
  /** X轴数据 */
  xAxis?: string[]
  /** 自定义 ECharts 配置 */
  option?: EChartsOption
  /** 加载状态 */
  loading?: boolean
  /** 图表高度 */
  height?: number | string
  /** 图表就绪回调 */
  onReady?: (chart: ECharts) => void
}

使用示例：

// 基础用法
<BarChart data={data} xAxis={categories} />

// 自定义配置
<BarChart
  data={data}
  xAxis={categories}
  option={{
    grid: { left: 10 },
    tooltip: { trigger: 'axis' }
  }}
/>

// 多系列数据
<BarChart
  data={[
    { label: '系列A', data: [120, 200, 150] },
    { label: '系列B', data: [80, 120, 180] }
  ]}
  xAxis={['周一', '周二', '周三']}
/>

LineChart 折线图

interface LineChartProps {
  /** 数据 */
  data?: LineData
  /** X轴数据 */
  xAxis?: string[]
  /** 是否平滑曲线 */
  smooth?: boolean
  /** 是否显示区域 */
  area?: boolean
  /** 自定义 ECharts 配置 */
  option?: EChartsOption
  /** 加载状态 */
  loading?: boolean
  /** 图表高度 */
  height?: number | string
  /** 图表就绪回调 */
  onReady?: (chart: ECharts) => void
}

使用示例：

<LineChart
  data={data}
  xAxis={categories}
  smooth={true}
  area={true}
  height={400}
/>

PieChart 饼状图

interface PieChartProps {
  /** 数据 */
  data?: PieData
  /** 饼图半径 */
  radius?: string | [string, string]
  /** 饼图中心位置 */
  center?: [string, string]
  /** 自定义 ECharts 配置 */
  option?: EChartsOption
  /** 加载状态 */
  loading?: boolean
  /** 图表高度 */
  height?: number | string
  /** 图表就绪回调 */
  onReady?: (chart: ECharts) => void
}

使用示例：

<PieChart
  data={[
    { name: '类别A', value: 335 },
    { name: '类别B', value: 310 },
    { name: '类别C', value: 234 }
  ]}
  radius={['40%', '70%']}
  center={['50%', '50%']}
/>

🔧 底层 Hook

useBaseChart

核心 Hook，用于创建和管理 ECharts 实例。

interface UseBaseChartProps {
  option: EChartsOption
  loading?: boolean
  onReady?: (chart: ECharts) => void
}

const ref = useBaseChart({ option, loading, onReady })

useBarOption | useLineOption | usePieOption

用于生成对应图表类型的 ECharts 配置。

const option = useBarOption({
  data: barData,
  xAxis: categories,
})

🎨 高级用法

自定义主题

const ref = useBaseChart({
  option,
  onReady: (chart) => {
    // 注册主题
    echarts.registerTheme('custom', customTheme)
    // 切换主题
    chart.dispose()
    const newChart = echarts.init(ref.current, 'custom')
    newChart.setOption(option)
  }
})

事件监听

const ref = useBaseChart({
  option,
  onReady: (chart) => {
    chart.on('click', (params) => {
      console.log('点击了：', params)
    })
    
    chart.on('mouseover', (params) => {
      console.log('悬停了：', params)
    })
  }
})

动态更新数据

function DynamicChart() {
  const [data, setData] = useState(initialData)
  
  const option = useBarOption({ data, xAxis: categories })
  const ref = useBaseChart({ option })
  
  // 更新数据
  const updateData = () => {
    setData(newData)
  }
  
  return (
    <div>
      <div ref={ref} style={{ height: 400 }} />
      <button onClick={updateData}>更新数据</button>
    </div>
  )
}

📊 数据格式

BarData

// 单系列
type BarData = number[]

// 多系列
interface BarSeries {
  label: string
  data: number[]
}

type BarData = BarSeries[]

LineData

// 单系列
type LineData = number[]

// 多系列
interface LineSeries {
  label: string
  data: number[]
}

type LineData = LineSeries[]

PieData

interface PieSeries {
  name: string
  value: number
}

type PieData = PieSeries[]

🛠️ 开发

# 安装依赖
pnpm install

# 开发
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如果你在使用过程中遇到问题，可以：

1. 查看 ECharts 官方文档
2. 提交 GitHub Issue
3. 加入我们的讨论群

⭐ 如果这个项目对你有帮助，请给我们一个 Star！