Giter Club home page Giter Club logo

ngx-echarts's Introduction

ngx-echarts

npm npm Build Status

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

Table of contents

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

Getting Started

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

Latest version @npm:

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

Latest Update

  • 2020.05.19: v5.0.0
    • BREAKING CHANGES:
      • NgxEchartsModule provides .forRoot() method to inject echarts core.
      • Due to .forRoot method, we can do custom build without NgxEchartsCoreModule. Just import the echarts core from echarts/src/echarts, and other necessary charts.
      • NgxEchartsCoreModule is removed.
      • [detectEventChanges] is removed.

Installation

  • Since v5.0

    # if you use npm
    npm install echarts -S
    npm install ngx-echarts -S
    
    # or if you use yarn
    yarn add echarts
    yarn add ngx-echarts
  • If you need ECharts GL support, please install it first:

    npm install echarts-gl -S
    
    # or
    yarn add echarts-gl
  • Import other extentions such as themes or echarts-gl in your main.ts: ECharts Extensions

Upgrade from v4.x

  1. import echarts and provide it in NgxEchartsModule.forRoot({ echarts }).
  2. NgxEchartsCoreModule is removed.

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';
    
    /**
     * This will import all modules from echarts.
     * If you only need custom modules,
     * please refer to [Custom Build] section.
     */
    import * as echarts from 'echarts';
    
    @NgModule({
      imports: [
        NgxEchartsModule.forRoot({
          echarts,
        }),
      ],
    })
    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',
          },
        ],
      };

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 import the theme file in main.ts.
[loadingOpts] object null Input an object to customize loading style. Refer to ECharts documentation for details.

By default, loadingOpts is:

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

ECharts API

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

import { graphic } from 'echarts';

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

ECharts Instance

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

ECharts Extensions

Import echarts theme files or other extension files after you imported echarts core. For example:

import * as echarts from 'echarts';

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

Service

NgxEchartsService has been obsoleted since v4.0

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:

@Output Event
chartInit Emitted when chart is intialized
chartClick echarts event: 'click'
chartDblClick echarts event: 'dblclick'
chartMouseDown echarts event: 'mousedown'
chartMouseMove echarts event: 'mousemove'
chartMouseUp echarts event: 'mouseup'
chartMouseOver echarts event: 'mouseover'
chartMouseOut echarts event: 'mouseout'
chartGlobalOut echarts event: 'globalout'
chartContextMenu echarts event: 'contextmenu'
chartLegendSelectChanged echarts event: 'legendselectchanged'
chartLegendSelected echarts event: 'legendselected'
chartLegendUnselected echarts event: 'legendunselected'
chartLegendScroll echarts event: 'legendscroll'
chartDataZoom echarts event: 'datazoom'
chartDataRangeSelected echarts event: 'datarangeselected'
chartTimelineChanged echarts event: 'timelinechanged'
chartTimelinePlayChanged echarts event: 'timelineplaychanged'
chartRestore echarts event: 'restore'
chartDataViewChanged echarts event: 'dataviewchanged'
chartMagicTypeChanged echarts event: 'magictypechanged'
chartPieSelectChanged echarts event: 'pieselectchanged'
chartPieSelected echarts event: 'pieselected'
chartPieUnselected echarts event: 'pieunselected'
chartMapSelectChanged echarts event: 'mapselectchanged'
chartMapSelected echarts event: 'mapselected'
chartMapUnselected echarts event: 'mapunselected'
chartAxisAreaSelected echarts event: 'axisareaselected'
chartFocusNodeAdjacency echarts event: 'focusnodeadjacency'
chartUnfocusNodeAdjacency echarts event: 'unfocusnodeadjacency'
chartBrush echarts event: 'brush'
chartBrushEnd echarts event: 'brushend'
chartBrushSelected echarts event: 'brushselected'
chartRendered echarts event: 'rendered'
chartFinished echarts event: 'finished'

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.

Custom Build

Please refer to ECharts Document for more details.

If you want to custom build echarts, prepare a file like custom-echarts.ts:

// custom-echarts.ts
export * from 'echarts/src/echarts';

import 'echarts/src/chart/line';
import 'echarts/src/chart/bar';
// component examples:
import 'echarts/src/component/tooltip';
import 'echarts/src/component/title';
import 'echarts/src/component/toolbox';

And then inject it in your NgxEchartsModule:

import { NgxEchartsModule } from 'ngx-echarts';
import * as echarts from './custom-echarts';

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

And if you want to use the global echarts object, please import it from lib or src instead:

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

If you need to import theme files, remember to change their 'echarts' path to 'echarts/lib/echarts', for example:

// ... part of echarts/theme/dark.js:
function (root, factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD. Register as an anonymous module.
        define(['exports', 'echarts/lib/echarts'], factory);
    } else if (typeof exports === 'object' && typeof exports.nodeName !== 'string') {
        // CommonJS
        factory(exports, require('echarts/lib/echarts'));
    } else {
        // Browser globals
        factory({}, root.echarts);
    }
}

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

ngx-echarts's People

Contributors

amirch1 avatar arethore-actility avatar berichte avatar dependabot[bot] avatar jack-valentine avatar rozennk avatar smnbbrv avatar tian-hun avatar uular avatar xieziyu avatar yuri1969 avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.