UNPKG

18.7 kBMarkdownView Raw
1# ngx-echarts
2
3<!-- Badges section here. -->
4
5[![npm](https://img.shields.io/npm/v/ngx-echarts.svg)][npm-badge-url]
6[![npm](https://img.shields.io/npm/dm/ngx-echarts.svg)][npm-badge-url]
7[![Build Status](https://travis-ci.org/xieziyu/ngx-echarts.svg?branch=master)][ci-url]
8
9Angular directive for [Apache ECharts (incubating)](https://github.com/apache/incubator-echarts)
10(version >= 3.x) (The project is renamed from **angular2-echarts**)
11
12- [Online Demo](https://xieziyu.github.io/ngx-echarts)
13- [Online Docs](https://xieziyu.github.io/ngx-echarts/api-doc)
14- [Starter Project](https://github.com/xieziyu/ngx-echarts-starter)
15- [Changelog](https://xieziyu.github.io/ngx-echarts/#/changelogs)
16
17## Table of contents
18
19- [ngx-echarts](#ngx-echarts)
20 - [Table of contents](#table-of-contents)
21- [Getting Started](#getting-started)
22- [Latest Update](#latest-update)
23- [Installation](#installation)
24 - [Upgrade from v4.x](#upgrade-from-v4x)
25- [Usage](#usage)
26- [API](#api)
27 - [Directive](#directive)
28 - [ECharts API](#echarts-api)
29 - [ECharts Instance](#echarts-instance)
30 - [ECharts Extensions](#echarts-extensions)
31 - [Service](#service)
32- [Events](#events)
33- [Custom Build](#custom-build)
34 - [Legacy Custom Build](#legacy-custom-build)
35 - [Treeshaking Custom Build](#treeshaking-custom-build)
36- [Custom Locale](#custom-locale)
37- [Demo](#demo)
38
39# Getting Started
40
41`ngx-echarts` is an Angular (ver >= 2.x) directive for ECharts (ver >= 3.x).
42
43Latest version @npm:
44
45- `v14.x` for Angular >= 14
46- `v8.x` for Angular >= 13
47- `v7.x` for Angular >= 11
48- `v6.x` for Angular >= 10, < 11
49- `v5.x` for Angular >= 6, < 10
50- `v2.3.1` for Angular < 6 (Please refer to https://github.com/xieziyu/ngx-echarts/blob/v2.x/README.md)
51
52A starter project on Github: https://github.com/xieziyu/ngx-echarts-starter
53
54# Latest Update
55
56- 2022.06.21: v14.0.0:
57
58 - Feat: upgrade to Angular 14
59
60- 2021.12.07: v8.0.1:
61
62 - Fix: NgxEchartsModule.forChild() issue [#334](https://github.com/xieziyu/ngx-echarts/issues/334)
63
64- 2021.11.08: v8.0.0 / v7.1.0:
65
66 - Fix: remove @juggle/resize-observer from the peer dependencies
67 - Perf: fix performance issue [#330](https://github.com/xieziyu/ngx-echarts/issues/330)
68
69- 2021.08.05: v7.0.2:
70
71 - [PR #322](https://github.com/xieziyu/ngx-echarts/pull/322): Add initOpts locale property (by [augustoicaro](https://github.com/augustoicaro))
72
73- 2021.05.17: v7.0.0:
74
75 - Feat: support Angular v11, ECharts v5
76 - Feat: support echart theme object
77 - Perf: resize animation
78
79- 2021.01.10: v6.0.1:
80
81 - [PR #295](https://github.com/xieziyu/ngx-echarts/pull/295): Guard dispose (by [taipeiwu](https://github.com/taipeiwu))
82
83- 2021.01.10: v6.0.0:
84
85 - [PR #285](https://github.com/xieziyu/ngx-echarts/pull/285): Guard dispose (by [gjsmith66](https://github.com/gjsmith66))
86 - update demo to use echarts v5.0
87 - [PR #282](https://github.com/xieziyu/ngx-echarts/pull/282): fix avoid "ResizeObserver loop limit exceeded" error (by [parkdihoon](https://github.com/parkdihoon))
88 - [PR #272](https://github.com/xieziyu/ngx-echarts/pull/272): Angular 10 support (by [Ghostbird](https://github.com/Ghostbird))
89
90- 2020.11.07: v5.2.1:
91
92 - Required `resize-observer-polyfill`
93 - [PR #271](https://github.com/xieziyu/ngx-echarts/pull/271): Fix autoResize functionality (by [ThomasBower](https://github.com/ThomasBower))
94 - Exposed methods: `refreshChart()` and `resize()`
95
96- 2020.07.24: v5.1.0:
97
98 - [PR #240](https://github.com/xieziyu/ngx-echarts/pull/240): Added output 'optionsError' (by [trajnisz](https://github.com/trajnisz))
99 - [PR #242](https://github.com/xieziyu/ngx-echarts/pull/242): Add output for brushEnd event (by [Uular](https://github.com/Uular))
100 - [PR #246](https://github.com/xieziyu/ngx-echarts/pull/246): Allow loading echarts library lazily via native import (by [smnbbrv](https://github.com/smnbbrv))
101
102- 2020.05.19: v5.0.0
103 - **BREAKING CHANGES**:
104 - `NgxEchartsModule` provides `.forRoot()` method to inject `echarts` core.
105 - Due to `.forRoot` method, we can do custom build without `NgxEchartsCoreModule`. Just import the `echarts` core from `echarts/src/echarts`, and other necessary charts.
106 - `NgxEchartsCoreModule` is removed.
107 - `[detectEventChanges]` is removed.
108
109# Installation
110
111- Since v5.0
112
113 ```bash
114 # if you use npm
115 npm install echarts -S
116 npm install ngx-echarts -S
117
118 # or if you use yarn
119 yarn add echarts
120 yarn add ngx-echarts
121 ```
122
123- If you need ECharts GL support, please install it first:
124
125 ```bash
126 npm install echarts-gl -S
127
128 # or
129 yarn add echarts-gl
130 ```
131
132- Import other extensions such as themes or `echarts-gl` in your `main.ts`: [ECharts Extensions](#echarts-extensions)
133
134## Upgrade from v4.x
135
1361. import `echarts` and provide it in `NgxEchartsModule.forRoot({ echarts })`.
1372. `NgxEchartsCoreModule` is removed.
138
139# Usage
140
141Please refer to the [demo](https://xieziyu.github.io/ngx-echarts) page.
142
1431. Firstly, import `NgxEchartsModule` in your app module (or any other proper angular module):
144
145 ```typescript
146 import { NgxEchartsModule } from 'ngx-echarts';
147
148 @NgModule({
149 imports: [
150 NgxEchartsModule.forRoot({
151 /**
152 * This will import all modules from echarts.
153 * If you only need custom modules,
154 * please refer to [Custom Build] section.
155 */
156 echarts: () => import('echarts'), // or import('./path-to-my-custom-echarts')
157 }),
158 ],
159 })
160 export class AppModule {}
161 ```
162
163 The echarts library will be imported **only when it gets called the first time** thanks to the function that uses the native import.
164
165 You can also directly pass the echarts instead which will slow down initial rendering because it will load the whole echarts into your main bundle.
166
167 ```typescript
168 import { NgxEchartsModule } from 'ngx-echarts';
169
170 @NgModule({
171 imports: [
172 NgxEchartsModule.forRoot({
173 echarts: () => import('echarts'),
174 }),
175 ],
176 })
177 export class AppModule {}
178 ```
179
1802. Then: use `echarts` directive in a div which has **pre-defined height**. (From v2.0, it has default height: 400px)
181
182 - Simple example:
183
184 - html:
185
186 ```html
187 <div echarts [options]="chartOption" class="demo-chart"></div>
188 ```
189
190 - scss:
191
192 ```css
193 .demo-chart {
194 height: 400px;
195 }
196 ```
197
198 - component:
199
200 ```typescript
201 import { EChartsOption } from 'echarts';
202
203 // ...
204
205 chartOption: EChartsOption = {
206 xAxis: {
207 type: 'category',
208 data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
209 },
210 yAxis: {
211 type: 'value',
212 },
213 series: [
214 {
215 data: [820, 932, 901, 934, 1290, 1330, 1320],
216 type: 'line',
217 },
218 ],
219 };
220 ```
221
222# API
223
224### Directive
225
226`echarts` directive support following input properties:
227
228| Input | Type | Default | Description |
229| --------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
230| `[options]` | object | null | The same as the options on the official demo site. |
231| `[merge]` | object | null | Used to update a 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`. Refer to [ECharts documentation](https://echarts.apache.org/en/api.html#echartsInstance.setOption) for details. |
232| `[loading]` | boolean | false | Used to toggle the echarts loading animation when your data is not ready. |
233| `[autoResize]` | boolean | true | If set to `true`, the chart will be automatically resized when the window's width is changed. |
234| `[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](https://echarts.apache.org/en/api.html#echarts.init) for details. |
235| `[theme]` | string | null | Used it to initialize echarts with theme. The theme file must also be imported in `main.ts`. |
236| `[loadingOpts]` | object | null | Input an object to customize the loading style. Refer to [ECharts documentation](https://echarts.apache.org/en/api.html#echartsInstance.showLoading) for details. |
237
238By default, `loadingOpts` is:
239
240```javascript
241{
242 text: 'loading',
243 color: '#c23531',
244 textColor: '#000',
245 maskColor: 'rgba(255, 255, 255, 0.8)',
246 zlevel: 0
247}
248```
249
250### ECharts API
251
252If you need to access parts of the ECharts API such as `echarts.graphic`, please import it from echarts. For example:
253
254```typescript
255import { graphic } from 'echarts';
256
257new graphic.LinearGradient(/* ... */);
258```
259
260### ECharts Instance
261
262`echartsInstance` is exposed (since v1.1.6) in the `(chartInit)` event, enabling you to directly call functions like: `resize()`, `showLoading()`, etc. For example:
263
264- html:
265
266```html
267<div echarts class="demo-chart" [options]="chartOptions" (chartInit)="onChartInit($event)"></div>
268```
269
270- component:
271
272```typescript
273onChartInit(ec) {
274 this.echartsInstance = ec;
275}
276
277resizeChart() {
278 if (this.echartsInstance) {
279 this.echartsInstance.resize();
280 }
281}
282```
283
284### ECharts Extensions
285
286Import echarts theme files or other extension files after you have imported `echarts` core. For example:
287
288```typescript
289import * as echarts from 'echarts';
290
291/** echarts extensions: */
292import 'echarts-gl';
293import 'echarts/theme/macarons.js';
294import 'echarts/dist/extension/bmap.min.js';
295```
296
297### Service
298
299`NgxEchartsService` has been obsolete since v4.0
300
301# Events
302
303As ECharts supports the `'click'`, `'dblclick'`, `'mousedown'`, `'mouseup'`, `'mouseover'`, `'mouseout'`, and `'globalout'` mouse events, our `ngx-echarts` directive also supports the same mouse events but with an additional `chart` prefix. For example:
304
305- html:
306
307```html
308<div echarts class="demo-chart" [options]="chartOptions" (chartClick)="onChartClick($event)"></div>
309```
310
311- The '\$event' is same with the 'params' that ECharts dispatches.
312
313It supports following event outputs:
314
315| @Output | Event |
316| ------------------------- | --------------------------------------- |
317| chartInit | Emitted when the chart is initialized |
318| chartClick | echarts event: `'click'` |
319| chartDblClick | echarts event: `'dblclick'` |
320| chartMouseDown | echarts event: `'mousedown'` |
321| chartMouseMove | echarts event: `'mousemove'` |
322| chartMouseUp | echarts event: `'mouseup'` |
323| chartMouseOver | echarts event: `'mouseover'` |
324| chartMouseOut | echarts event: `'mouseout'` |
325| chartGlobalOut | echarts event: `'globalout'` |
326| chartContextMenu | echarts event: `'contextmenu'` |
327| chartLegendSelectChanged | echarts event: `'legendselectchanged'` |
328| chartLegendSelected | echarts event: `'legendselected'` |
329| chartLegendUnselected | echarts event: `'legendunselected'` |
330| chartLegendScroll | echarts event: `'legendscroll'` |
331| chartDataZoom | echarts event: `'datazoom'` |
332| chartDataRangeSelected | echarts event: `'datarangeselected'` |
333| chartTimelineChanged | echarts event: `'timelinechanged'` |
334| chartTimelinePlayChanged | echarts event: `'timelineplaychanged'` |
335| chartRestore | echarts event: `'restore'` |
336| chartDataViewChanged | echarts event: `'dataviewchanged'` |
337| chartMagicTypeChanged | echarts event: `'magictypechanged'` |
338| chartPieSelectChanged | echarts event: `'pieselectchanged'` |
339| chartPieSelected | echarts event: `'pieselected'` |
340| chartPieUnselected | echarts event: `'pieunselected'` |
341| chartMapSelectChanged | echarts event: `'mapselectchanged'` |
342| chartMapSelected | echarts event: `'mapselected'` |
343| chartMapUnselected | echarts event: `'mapunselected'` |
344| chartAxisAreaSelected | echarts event: `'axisareaselected'` |
345| chartFocusNodeAdjacency | echarts event: `'focusnodeadjacency'` |
346| chartUnfocusNodeAdjacency | echarts event: `'unfocusnodeadjacency'` |
347| chartBrush | echarts event: `'brush'` |
348| chartBrushEnd | echarts event: `'brushend'` |
349| chartBrushSelected | echarts event: `'brushselected'` |
350| chartRendered | echarts event: `'rendered'` |
351| chartFinished | echarts event: `'finished'` |
352
353You can refer to the ECharts tutorial: [Events and Actions in ECharts](https://echarts.apache.org/en/tutorial.html#Events%20and%20Actions%20in%20ECharts) for more details of the event params. You can also refer to the [demo](https://xieziyu.github.io/#/ngx-echarts/demo) page for a detailed example.
354
355# Custom Build
356
357## Legacy Custom Build
358
359> Please refer to [ECharts Documentation](https://echarts.apache.org/en/tutorial.html#Create%20Custom%20Build%20of%20ECharts) for more details.
360
361If you want to produce a custom build of ECharts, prepare a file like `custom-echarts.ts`:
362
363```ts
364// custom-echarts.ts
365export * from 'echarts/src/echarts';
366
367import 'echarts/src/chart/line';
368import 'echarts/src/chart/bar';
369// component examples:
370import 'echarts/src/component/tooltip';
371import 'echarts/src/component/title';
372import 'echarts/src/component/toolbox';
373```
374
375And then inject it in your `NgxEchartsModule`:
376
377```ts
378import { NgxEchartsModule } from 'ngx-echarts';
379import * as echarts from './custom-echarts';
380
381@NgModule({
382 imports: [
383 NgxEchartsModule.forRoot({
384 echarts,
385 }),
386 ],
387})
388export class AppModule {}
389```
390
391And if you want to use the global `echarts` object, please import it from `lib` or `src` instead:
392
393```ts
394import * as echarts from 'echarts/lib/echarts';
395```
396
397If you need to import theme files, remember to change the `'echarts'` path to `'echarts/lib/echarts'`, for example:
398
399```ts
400// ... part of echarts/theme/dark.js:
401function (root, factory) {
402 if (typeof define === 'function' && define.amd) {
403 // AMD. Register as an anonymous module.
404 define(['exports', 'echarts/lib/echarts'], factory);
405 } else if (typeof exports === 'object' && typeof exports.nodeName !== 'string') {
406 // CommonJS
407 factory(exports, require('echarts/lib/echarts'));
408 } else {
409 // Browser globals
410 factory({}, root.echarts);
411 }
412}
413```
414
415## Treeshaking Custom Build
416
417> Since version 5.0.1 ECharts supports [Treeshaking with NPM](https://echarts.apache.org/en/tutorial.html#Use%20ECharts%20with%20bundler%20and%20NPM).
418
419There is no need for the `custom-echarts.ts` file anymore. The `app.modules.ts` should look like this:
420
421```typescript
422import { BrowserModule } from '@angular/platform-browser';
423import { NgModule } from '@angular/core';
424import { HttpClientModule } from '@angular/common/http';
425
426import { NgxEchartsModule } from 'ngx-echarts';
427
428import { AppComponent } from './app.component';
429
430// Import the echarts core module, which provides the necessary interfaces for using echarts.
431import * as echarts from 'echarts/core';
432// Import bar charts, all with Chart suffix
433import { BarChart } from 'echarts/charts';
434import { TitleComponent, TooltipComponent, GridComponent } from 'echarts/components';
435// Import the Canvas renderer, note that introducing the CanvasRenderer or SVGRenderer is a required step
436import { CanvasRenderer } from 'echarts/renderers';
437import 'echarts/theme/macarons.js';
438
439echarts.use([TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]);
440
441@NgModule({
442 declarations: [AppComponent],
443 imports: [BrowserModule, NgxEchartsModule.forRoot({ echarts }), HttpClientModule],
444 providers: [],
445 bootstrap: [AppComponent],
446})
447export class AppModule {}
448```
449
450# Custom Locale
451
452You can change the chart locale registering a built-in locale (located in `node_modules/echarts/lib/i18n/`) or a custom locale object. To register a locale, you will need to change the module that echart is being imported (usually `app.module.ts`).
453
454```ts
455import {NgxEchartsModule} from "ngx-echarts";
456import * as echarts from 'echarts/core';
457import langCZ from 'echarts/lib/i18n/langCZ';
458
459echarts.registerLocale("CZ", langCZ)
460
461@NgModule({
462 imports: [NgxEchartsModule.forRoot({echarts})],
463 declarations: [],
464 providers: [],
465 bootstrap: [AppComponent]
466})
467```
468
469and in your HTML file use:
470
471```html
472<div echarts [initOpts]="{ locale: 'CZ' }" [options]="options" class="demo-chart"></div>
473```
474
475# Demo
476
477You can clone this repo to your working copy and then launch the demo page in your local machine:
478
479```bash
480npm install
481npm run demo
482
483# or
484yarn install
485yarn demo
486```
487
488The demo page server is listening on: http://localhost:4202
489
490[npm-badge-url]: https://www.npmjs.com/package/ngx-echarts
491[ci-url]: https://travis-ci.org/xieziyu/ngx-echarts