1 | # ngx-echarts
|
2 |
|
3 |
|
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 |
|
9 | Angular 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 |
|
43 | Latest 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 |
|
52 | A 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 |
|
136 | 1. import `echarts` and provide it in `NgxEchartsModule.forRoot({ echarts })`.
|
137 | 2. `NgxEchartsCoreModule` is removed.
|
138 |
|
139 | # Usage
|
140 |
|
141 | Please refer to the [demo](https://xieziyu.github.io/ngx-echarts) page.
|
142 |
|
143 | 1. 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 |
|
180 | 2. 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 |
|
238 | By 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 |
|
252 | If you need to access parts of the ECharts API such as `echarts.graphic`, please import it from echarts. For example:
|
253 |
|
254 | ```typescript
|
255 | import { graphic } from 'echarts';
|
256 |
|
257 | new 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
|
273 | onChartInit(ec) {
|
274 | this.echartsInstance = ec;
|
275 | }
|
276 |
|
277 | resizeChart() {
|
278 | if (this.echartsInstance) {
|
279 | this.echartsInstance.resize();
|
280 | }
|
281 | }
|
282 | ```
|
283 |
|
284 | ### ECharts Extensions
|
285 |
|
286 | Import echarts theme files or other extension files after you have imported `echarts` core. For example:
|
287 |
|
288 | ```typescript
|
289 | import * as echarts from 'echarts';
|
290 |
|
291 | /** echarts extensions: */
|
292 | import 'echarts-gl';
|
293 | import 'echarts/theme/macarons.js';
|
294 | import 'echarts/dist/extension/bmap.min.js';
|
295 | ```
|
296 |
|
297 | ### Service
|
298 |
|
299 | `NgxEchartsService` has been obsolete since v4.0
|
300 |
|
301 | # Events
|
302 |
|
303 | As 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 |
|
313 | It 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 |
|
353 | You 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 |
|
361 | If you want to produce a custom build of ECharts, prepare a file like `custom-echarts.ts`:
|
362 |
|
363 | ```ts
|
364 | // custom-echarts.ts
|
365 | export * from 'echarts/src/echarts';
|
366 |
|
367 | import 'echarts/src/chart/line';
|
368 | import 'echarts/src/chart/bar';
|
369 | // component examples:
|
370 | import 'echarts/src/component/tooltip';
|
371 | import 'echarts/src/component/title';
|
372 | import 'echarts/src/component/toolbox';
|
373 | ```
|
374 |
|
375 | And then inject it in your `NgxEchartsModule`:
|
376 |
|
377 | ```ts
|
378 | import { NgxEchartsModule } from 'ngx-echarts';
|
379 | import * as echarts from './custom-echarts';
|
380 |
|
381 | @NgModule({
|
382 | imports: [
|
383 | NgxEchartsModule.forRoot({
|
384 | echarts,
|
385 | }),
|
386 | ],
|
387 | })
|
388 | export class AppModule {}
|
389 | ```
|
390 |
|
391 | And if you want to use the global `echarts` object, please import it from `lib` or `src` instead:
|
392 |
|
393 | ```ts
|
394 | import * as echarts from 'echarts/lib/echarts';
|
395 | ```
|
396 |
|
397 | If 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:
|
401 | function (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 |
|
419 | There is no need for the `custom-echarts.ts` file anymore. The `app.modules.ts` should look like this:
|
420 |
|
421 | ```typescript
|
422 | import { BrowserModule } from '@angular/platform-browser';
|
423 | import { NgModule } from '@angular/core';
|
424 | import { HttpClientModule } from '@angular/common/http';
|
425 |
|
426 | import { NgxEchartsModule } from 'ngx-echarts';
|
427 |
|
428 | import { AppComponent } from './app.component';
|
429 |
|
430 | // Import the echarts core module, which provides the necessary interfaces for using echarts.
|
431 | import * as echarts from 'echarts/core';
|
432 | // Import bar charts, all with Chart suffix
|
433 | import { BarChart } from 'echarts/charts';
|
434 | import { TitleComponent, TooltipComponent, GridComponent } from 'echarts/components';
|
435 | // Import the Canvas renderer, note that introducing the CanvasRenderer or SVGRenderer is a required step
|
436 | import { CanvasRenderer } from 'echarts/renderers';
|
437 | import 'echarts/theme/macarons.js';
|
438 |
|
439 | echarts.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 | })
|
447 | export class AppModule {}
|
448 | ```
|
449 |
|
450 | # Custom Locale
|
451 |
|
452 | You 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
|
455 | import {NgxEchartsModule} from "ngx-echarts";
|
456 | import * as echarts from 'echarts/core';
|
457 | import langCZ from 'echarts/lib/i18n/langCZ';
|
458 |
|
459 | echarts.registerLocale("CZ", langCZ)
|
460 |
|
461 | @NgModule({
|
462 | imports: [NgxEchartsModule.forRoot({echarts})],
|
463 | declarations: [],
|
464 | providers: [],
|
465 | bootstrap: [AppComponent]
|
466 | })
|
467 | ```
|
468 |
|
469 | and 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 |
|
477 | You can clone this repo to your working copy and then launch the demo page in your local machine:
|
478 |
|
479 | ```bash
|
480 | npm install
|
481 | npm run demo
|
482 |
|
483 | # or
|
484 | yarn install
|
485 | yarn demo
|
486 | ```
|
487 |
|
488 | The 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
|