ngx-echarts

ngx-echarts

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

• Online Demo
• Online Docs

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.0.1 for Angular >= 6
• v2.1.1 for Angular < 6

Github branches:

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

Latest Update

• 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:

{
  "scripts": [
    // ...

    // add this:
    "../node_modules/echarts/dist/echarts.min.js"  // or echarts.js for debug purpose
  ],
}

• 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:

• [options]: It's the same with the options in official demo site.

• [merge]: 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 property. Use it to toggle the echarts loading animation when your data is not ready.

• [initOpts]: 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]: use it to init echarts with theme. You need to include the theme file in .angular-cli.json or other module resolver.

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

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

• [loadingOpts]: Input an object to customize loading style. Refer to ECharts documentation for details. By default:

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

It exposes the echartsInstance (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