Angular directive for echarts (version >= 3.x) (The project is renamed from angular2-echarts)

• Online Demo
• Online Docs
• Starter Project

1. Getting Started
2. Latest Update
3. Installation
4. Usage
5. API
6. Events
7. Demo

ngx-echarts is an Angular (ver >= 2.x) directive for ECharts (ver >= 3.x).

Latest version @npm:

• v4.0.1 for Angular >= 6
• v2.3.1 for Angular < 6 (Please refer to https://github.com/xieziyu/ngx-echarts/blob/v2.x/README.md)

A starter project on Github: https://github.com/xieziyu/ngx-echarts-starter

• 2018.11.11: v4.0.1

  • Add map events support: (chartMapSelectChanged), (chartMapSelected), (chartMapUnselected). (by amirch1 - PR #147)

• 2018.08.20: v4.0.0

  • Change: ECharts instance creating is delayed until view initialized.
  • New: [detectEventChanges] Use it to avoid unwanted change detections.
    • If you set it false, chartClick and some other event-emitters become silent. demo
  • Change: [theme] now detect changes at runtime.
    • When you change theme at runtime, the chart would be destroyed first and then initialized again. demo
  • BREAKING CHANGES:
    • ES6 import instead of polluting global namespace. issue #123
    • NgxEchartsService is now obsoleted. If you want to use echarts API, please just import it

    import * as echarts from 'echarts';
    /** or */
    import { graphic, registerMap } from 'echarts';

    • Import echarts theme files or other extension files in main.ts. Refer to ECharts Extensions

• 2018.07.24: v3.2.0 & v2.3.1:

  • New: [autoResize] now detects its container element's offset height.
  • Change: Resizing detection is now debounced.

• 2018.06.13: v3.1.0 & v2.2.0:

  • New: [autoResize] now detects its container element's offset width. Especially useful for charts inside <ng-template> such as NG-ZORRO components.

• 2018.06.12: v3.0.1 & v2.1.1:

  • Bugfix: Line chart is not animated on init. issue#102

• 2018.05.08: v3.0.0:

  • Change: Support Angular 6
  • Docs: generate demo app by @angular/cli-6.0.0

• 2018.03.14: v2.1.0

  • New: [loadingOpts] to customize loading style. Refer to API
  • Bugfix: double check dom.style.height before setting default value.

• 2018.02.07: v2.0.2. New: [autoResize] input (default: true). PR #73 by arethore-actility

• 2017.12.11: v2.0.1. Fix issue: No change detection involved in event handler. Refer to issue #26, #28

• 2017.12.04: v2.0.0. Provide an echarts wrapper service: NgxEchartsService.

• 2017.11.25: v2.0.0-beta.0. It has some BREAKING CHANGES you should know.

• Since v4.0

  # if you use npm
  npm install echarts -S
  npm install ngx-echarts -S
  npm install @types/echarts -D
  
  # or if you use yarn
  yarn add echarts
  yarn add ngx-echarts
  yarn add @types/echarts -D

• Update angular.json:

  {
    ...,
    "architect": {
      "build": {
        "options": {
          "scripts": [
            ...,
  +         "node_modules/echarts/dist/echarts.min.js"
          ]
        }
      }
  }

• If you need ECharts GL support, please install it first:

  npm install echarts-gl -S
  
  # or
  yarn add echarts-gl

• And then angular.json:

  {
    ...,
    "architect": {
      "build": {
        "options": {
          "scripts": [
            ...,
  +         "node_modules/echarts-gl/dist/echarts-gl.min.js"
          ]
        }
      }
  }

• Import other extentions such as themes or echarts-gl in your main.ts: ECharts Extensions

1. Install @types/echarts
2. Import necessary theme or extension files in main.ts. Refer to ECharts Extensions.

Please refer to the demo page.

1. Firstly, import NgxEchartsModule in your app module (or any other proper angular module):

   import { NgxEchartsModule } from 'ngx-echarts';
   
   @NgModule({
     imports: [
       ...,
       NgxEchartsModule
     ],
     ...
   })
   export class AppModule { }

2. Then: use echarts directive in a div which has pre-defined height. (From v2.0, it has default height: 400px)

   • Simple example:

     • html:

     <div echarts [options]="chartOption" class="demo-chart"></div>

     • scss:

     .demo-chart {
       height: 400px;
     }

     • component:

     import { EChartOption } from 'echarts';
     
     // ...
     
     chartOption: EChartOption = {
       xAxis: {
         type: 'category',
         data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
       },
       yAxis: {
         type: 'value'
       },
       series: [{
         data: [820, 932, 901, 934, 1290, 1330, 1320],
         type: 'line'
       }]
     }

echarts directive support following input porperties:

By default, loadingOpts is:

{
  text: 'loading',
  color: '#c23531',
  textColor: '#000',
  maskColor: 'rgba(255, 255, 255, 0.8)',
  zlevel: 0
}

If you need echarts API such as echarts.graphic, please import it from echarts. For example:

/** import all */
import * as echarts from 'echarts';

new echarts.graphic.LinearGradient(/** ... */);

/** or you can */
import { graphic } from 'echarts';

new graphic.LinearGradient(/** ... */);

echartsInstance is exposed (since v1.1.6) in (chartInit) event. So you can directly call the APIs just like: resize(), showLoading(), etc. For example:

• html:

<div echarts class="demo-chart" [options]="chartOptions" (chartInit)="onChartInit($event)"></div>

• component:

onChartInit(ec) {
  this.echartsIntance = ec;
}

resizeChart() {
  if (this.echartsIntance) {
    this.echartsIntance.resize();
  }
}

Import echarts theme files or other extension files in main.ts. For example:

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

/** echarts extensions: */
import 'echarts-gl';
import 'echarts/theme/macarons.js';
import 'echarts/dist/extension/bmap.min.js';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.log(err));

NgxEchartsService has been obsoleted since v4.0

As echarts support the 'click', 'dblclick', 'mousedown', 'mouseup', 'mouseover', 'mouseout', 'globalout' mouse events, our ngx-echarts directive also support the same mouse events but with additional chart prefix.

• html:

<div echarts class="demo-chart" [options]="chartOptions" (chartClick)="onChartClick($event)"></div>

• The '$event' is same with the 'params' that Echarts dispatches

It supports following event outputs:

• chartClick: It emits the same params of 'click' event
• chartDblClick: It emits the same params of 'dblclick' event
• chartMouseDown: It emits the same params of 'mousedown' event
• chartMouseUp: It emits the same params of 'mouseup' event
• chartMouseOver: It emits the same params of 'mouseover' event
• chartMouseOut: It emits the same params of 'mouseout' event
• chartGlobalOut: It emits the same params of 'globalout' event
• chartContextMenu: It emits the same params of 'contextmenu' event (since v1.2.1)
• chartDataZoom: It emits the same params of 'dataZoom' event (thanks to averhaegen)
• chartMapSelectChanged: It emits the same params of 'mapselectchanged' event (thanks to amirch1)
• chartMapSelected: It emits the same params of 'mapselected' event (thanks to amirch1)
• chartMapUnselected: It emits the same params of 'mapunselected' event (thanks to amirch1)

You can refer to the echarts tutorial: Events and Actions in ECharts for more details of the event params. You can also refer to the demo page for the detailed example.

You can clone this repo to your working copy and then launch the demo page in your local machine:

npm install
npm run demo

# or
yarn install
yarn demo

The demo page server is listening to: http://localhost:4202