ngx-echarts

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

Online Demo
Online Docs
Starter Project

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.

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

import { NgxEchartsModule } from 'ngx-echarts';

@NgModule({
  imports: [
    ...,
    NgxEchartsModule
  ],
  ...
})
export class AppModule { }

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

ngx-echarts

Table of contents

Getting Started

Latest Update

Installation

How to use it within:

Usage

API

Directive

echartsInstance

Service

Events

Demo

Files

README.md

Latest commit

History

README.md

File metadata and controls

ngx-echarts

Table of contents

Getting Started

Latest Update

Installation

How to use it within:

Usage

API

Directive

echartsInstance

Service

Events

Demo