@ticatec/uniface-echarts

English | 中文

A lightweight and powerful Svelte wrapper for Apache ECharts with full TypeScript support. Create beautiful, interactive charts with ease.

✨ Features

• 🎯 Easy Integration - Simple Svelte component wrapper for ECharts
• 📊 Full ECharts Support - Access to all ECharts chart types and features
• 🔧 TypeScript Ready - Complete TypeScript definitions included
• 📱 Responsive Design - Automatic chart resizing with ResizeObserver
• 🎨 Customizable - Extend the base class to create custom chart components
• ⚡ Performance Optimized - Lazy loading and efficient rendering
• 🔄 Reactive - Seamlessly integrates with Svelte's reactivity system
• 🖱️ Rich Event Support - Click, double-click, right-click, and mouse events
• 📋 Context Menu - Built-in support for custom context menus
• 🎯 Interactive - Highlight, tooltip, and selection capabilities

📦 Installation

npm install @ticatec/uniface-echarts

🚀 Quick Start

1. Create a custom chart class:

import UnifaceChart from '@ticatec/uniface-echarts';

export class LineChart extends UnifaceChart {
  protected createOption(): any {
    return {
      title: {
        text: 'Sample Line Chart'
      },
      tooltip: {},
      xAxis: {
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
      },
      yAxis: {},
      series: [{
        name: 'Sales',
        type: 'line',
        data: [120, 200, 150, 80, 70, 110, 130]
      }]
    };
  }
}

2. Use in your Svelte component:

<script>
  import ChartPanel from '@ticatec/uniface-echarts';
  import { LineChart } from './LineChart';
  
  const chart = new LineChart();
</script>

<div style="width: 600px; height: 400px;">
  <ChartPanel {chart} />
</div>

📖 API Reference

UnifaceChart (Base Class)

Methods

| Method | Description | Parameters | |--------|-------------|------------| | init(el: HTMLElement) | Initialize the chart | el - Container element | | invalidate() | Refresh the chart with current options | - | | resize() | Resize the chart to fit container | - | | showLoading(type?, opts?) | Show loading animation | type - Loading type, opts - Options | | hideLoading() | Hide loading animation | - |

Protected Methods (Override in subclasses)

| Method | Description | Return Type | |--------|-------------|-------------| | createOption() | Create ECharts option configuration | any | | postInitialize(chart) | Called after chart initialization | void | | formatNumber(value, precision?) | Format numbers with locale | string |

ChartPanel Component

Event Support

| Event Type | Description | Handler | |------------|-------------|---------| | onClick | Single click on chart elements | (params) => void | | onDoubleClick | Double click on chart elements | (params) => void | | onRightClick | Right click on chart elements | (params) => void | | onMouseOver | Mouse hover over elements | (params) => void |

Interactive Methods

| Method | Description | Parameters | |--------|-------------|------------| | setEventHandlers(handlers) | Set multiple event handlers | handlers - Event handler object | | addEventListener(type, handler) | Add single event handler | type - Event type, handler - Function | | removeEventListener(type) | Remove event handler | type - Event type | | highlight(seriesIndex?, dataIndex?) | Highlight data point | Series and data indices | | downplay(seriesIndex?, dataIndex?) | Remove highlight | Series and data indices | | showTip(seriesIndex, dataIndex) | Show tooltip | Series and data indices | | hideTip() | Hide tooltip | - |

🎨 Advanced Usage

Custom Chart with Event Handling

export class InteractiveChart extends UnifaceChart {
  protected createOption(): any {
    return {
      // ... your chart configuration
      series: [{
        data: [120, 200, 150, 80, 70, 110]
      }]
    };
  }
  
  protected postInitialize(chart: any): void {
    // Set up event handlers
    this.setEventHandlers({
      onClick: (params) => {
        console.log('Chart clicked:', params);
        this.highlight(params.seriesIndex, params.dataIndex);
      },
      onDoubleClick: (params) => {
        alert(`Double clicked: ${params.name} = ${params.value}`);
      },
      onRightClick: (params) => {
        console.log('Right clicked:', params);
        // Show custom context menu
      },
      onMouseOver: (params) => {
        this.showTip(params.seriesIndex, params.dataIndex);
      }
    });
  }
}

Event Handler Methods

// Set multiple event handlers
chart.setEventHandlers({
  onClick: (params) => { /* handle click */ },
  onDoubleClick: (params) => { /* handle double click */ },
  onRightClick: (params) => { /* handle right click */ }
});

// Add single event handler
chart.addEventListener('onClick', (params) => {
  console.log('Clicked:', params);
});

// Remove event handler
chart.removeEventListener('onClick');

// Interactive methods
chart.highlight(seriesIndex, dataIndex);  // Highlight data point
chart.downplay();                         // Remove highlight
chart.showTip(seriesIndex, dataIndex);    // Show tooltip
chart.hideTip();                          // Hide tooltip

### Responsive Chart

```svelte
<script>
  import ChartPanel from '@ticatec/uniface-echarts';
  import { MyChart } from './MyChart';
  
  const chart = new MyChart();
</script>

<!-- Chart automatically resizes with container -->
<div class="chart-container">
  <ChartPanel {chart} />
</div>

<style>
  .chart-container {
    width: 100%;
    height: 50vh;
    min-height: 300px;
  }
</style>

🔧 Requirements

• Node.js >= 18.0.0
• Svelte >= 5.0.0
• ECharts >= 6.0.0

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation

Made with ❤️ by Henry Feng