ngx-echarts

ngx-echarts

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

• Online Demo
• Online Docs
• Starter Project

Table of contents

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

Getting Started

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

Latest version @npm:

• v3.2.0 for Angular >= 6
• v2.3.1 for Angular < 6

Github branches:

• master for Angular >= 6
• v2.x for Angular < 6

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

Latest Update

• 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. Please see demo

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

Installation

# if you use npm
npm install echarts --save
npm install ngx-echarts --save

# or if you use yarn
yarn add echarts
yarn add ngx-echarts

How to use it within:

• angular-cli: If you already have an angular-cli project. You need to import echarts in the "scripts" list of angular-cli.json just like:

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

• Webpack: You need to edit webpack.common.js, just like:

new webpack.ProvidePlugin({
  // ...

  // add this:
  echarts: "echarts"
})

• SystemJS: For example: angular quickstart. You need to modify systemjs.config.js file just like:

{
  map: {
    // ...

    // ngx-echarts
    'echarts':              'npm:echarts',
    'ngx-echarts':          'npm:ngx-echarts'
  },
  packages: {
    // other packages ...

    // ngx-echarts
    echarts: {
      defaultExtension: 'js',
      main: 'dist/echarts.min.js',
      meta: {
        './*.js': {
          format: 'global', // load this module as a global
          exports: 'echarts', // the global property to take as the module value
        }
      }
    },
    'ngx-echarts': {
      defaultExtension: 'js',
      main: 'bundles/ngx-echarts.umd.js',
      meta: {
        './*.js': {
          deps: ['echarts']
        }
      }
    }
  }
}

Usage

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>
     

     • css:

     .demo-chart {
       height: 400px;
     }
     

     • component:

     chartOption = {
       title: {
         text: '堆叠区域图'
       },
       tooltip : {
         trigger: 'axis'
       },
       legend: {
         data:['邮件营销','联盟广告','视频广告','直接访问','搜索引擎']
       },
       toolbox: {
         feature: {
           saveAsImage: {}
         }
       },
       grid: {
         left: '3%',
         right: '4%',
         bottom: '3%',
         containLabel: true
       },
       xAxis : [
         {
           type : 'category',
           boundaryGap : false,
           data : ['周一','周二','周三','周四','周五','周六','周日']
         }
       ],
       yAxis : [
         {
           type : 'value'
         }
       ],
       series : [
         {
           name:'邮件营销',
           type:'line',
           stack: '总量',
           areaStyle: {normal: {}},
           data:[120, 132, 101, 134, 90, 230, 210]
         },
         {
           name:'联盟广告',
           type:'line',
           stack: '总量',
           areaStyle: {normal: {}},
           data:[220, 182, 191, 234, 290, 330, 310]
         },
         {
           name:'视频广告',
           type:'line',
           stack: '总量',
           areaStyle: {normal: {}},
           data:[150, 232, 201, 154, 190, 330, 410]
         },
         {
           name:'直接访问',
           type:'line',
           stack: '总量',
           areaStyle: {normal: {}},
           data:[320, 332, 301, 334, 390, 330, 320]
         },
         {
           name:'搜索引擎',
           type:'line',
           stack: '总量',
           label: {
             normal: {
               show: true,
               position: 'top'
             }
           },
           areaStyle: {normal: {}},
           data:[820, 932, 901, 934, 1290, 1330, 1320]
         }
       ]
     }
     

API

Directive

echarts directive support following input porperties:

Input	Type	Default	Description
[options]	object	null	It's the same with the options in official demo site.
[merge]	object	null	You can use it to update part of the options, especially helpful when you need to update the chart data. In fact, the value of merge will be used in echartsInstance.setOption() with notMerge = false. So you can refer to ECharts documentation for details
[loading]	boolean	false	Use it to toggle the echarts loading animation when your data is not ready.
[autoResize]	boolean	true	Charts will be automatically resized when container's width changed.
[initOpts]	object	null	The value of [initOpts] will be used in echarts.init(). It may contain devicePixelRatio, renderer, width or height properties. Refer to ECharts documentation for details
[theme]	string	null	Use it to init echarts with theme. You need to include the theme file in angular-cli.json or other module resolver.
[loadingOpts]	object	null	Input an object to customize loading style. Refer to ECharts documentation for details.

For example, if we want to use dark.js in Echarts Themes Page:

<div echarts theme="dark" class="demo-chart" [options]="chartOptions"></div>

By default, loadingOpts is:

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

echartsInstance

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();
  }
}

Service

NgxEchartsService is a wrapper for global echarts object. You can get native echarts object or use wrapper method directly. For example:

• usage:

  import {NgxEchartsService} from 'ngx-echarts';
  
  //...
  constructor(private es: NgxEchartsService) {}
  
  ngOnInit() {
    const echarts = this.es.echarts;
    echarts.registerMap('HK', HK_GEO_JSON);
    // Or you can:
    // this.es.registerMap('HK', HK_GEO_JSON);
  }
  

More details in Document and Demo

Events

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)

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.

Demo

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