Apache ECharts

https://echarts.apache.org/en/
Admin
Apache ECharts is an open-source JavaScript visualization library and a declarative framework for...
Tokens:67,232
Snippets:654
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install ECharts from npm

Source: https://echarts.apache.org/en/download.html

Installs the latest version of Apache ECharts via npm. Requires Node.js and npm.

```bash
npm install echarts
```

--------------------------------

### Register a map with GeoJSON

Source: https://echarts.apache.org/en/api.html

Example of registering a map using a minimal GeoJSON object.

```javascript
  const geoJSONSample = {
      "type": "FeatureCollection",
      "features": [
          {
              "type": "Feature",
              "geometry": {
                  "type": "Polygon",
                  "coordinates": [
                      [[200, 3000], [500, 3000], [500, 5000], [200, 5000]]
                  ]
              },
              "properties": {
                  "name": "Some Place",
                  "cp": [220, 2100]
              }
          }
      ]
  };
  echarts.registerMap('my_geo_sample', {geoJSON: geoJSONSample});
```

--------------------------------

### Initialize ECharts instance with SVG renderer

Source: https://echarts.apache.org/en/api.html

Example of initializing an ECharts instance with a null theme and SVG renderer configuration.

```javascript
const chart = echarts.init(dom, null, {renderer: 'svg'});
```

--------------------------------

### Listen for map georoam event

Source: https://echarts.apache.org/en/faq.html

To get the zoom event of a map, set the series's roam to true and then listen for the 'georoam' event. The example logs the event parameters to the console.

```javascript
myChart.on('georoam', function (params) {
   console.log(params);
});
```

--------------------------------

### Register a map with SVG

Source: https://echarts.apache.org/en/api.html

Example of registering a map using an SVG string.

```javascript
  const mySVG = `<?xml version="1.0" encoding="utf-8"?>
  <svg xmlns="http://www.w3.org/2000/svg" xmlns:ooo="http://xml.openoffice.org/svg/export" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.2" fill-rule="evenodd" xml:space="preserve">
  <path name="left_rect" d="M 0,0 L 0,100 100,100 100,0 Z" fill="#765" stroke="rgb(56,93,138)" stroke-width="0" stroke-linecap="square" stroke-linejoin="miter"/>
  </svg>`;
  echarts.registerMap('my_geo_sample', {svg: mySVG});
```

--------------------------------

### Example: Register custom shape and use in custom series

Source: https://echarts.apache.org/en/api.html

Shows how to define a custom shape class with extendShape, register it as 'myCustomShape', and use it in a custom series renderItem. The shape draws a rectangle based on data values.

```javascript
var MyShape = echarts.graphic.extendShape({
    shape: {
        x: 0,
        y: 0,
        width: 0,
        height: 0
    },
    buildPath: function (ctx, shape) {
        ctx.moveTo(shape.x, shape.y);
        ctx.lineTo(shape.x + shape.width, shape.y);
        ctx.lineTo(shape.x, shape.y + shape.height);
        ctx.lineTo(shape.x + shape.width, shape.y + shape.height);
        ctx.closePath();
    }
});
echarts.graphic.registerShape('myCustomShape', MyShape);

var option = {
    series: {
        type: 'custom',
        coordinateSystem: 'none',
        renderItem: function (params, api) {
            return {
                type: 'myCustomShape',
                shape: {
                    x: api.value(0),
                    y: api.value(1),
                    width: api.value(2),
                    height: api.value(3)
                },
                style: {
                    fill: 'red'
                }
            };
        },
        data: [[10, 20, 30, 40]]
    }
};


```

--------------------------------

### echarts.init

Source: https://echarts.apache.org/en/api.html

Documentation for the echarts.init function, which creates an ECharts instance.

```APIDOC
## echarts.init

### Description
Creates an ECharts instance and returns an echartsInstance. You shall not initialize multiple ECharts instances on a single container.

### Method
Function

### Signature
```
(dom: HTMLDivElement|HTMLCanvasElement, theme?: Object|string, opts?: {
    devicePixelRatio?: number,
    renderer?: string,
    useDirtyRect?: boolean,     // Since `5.0.0`
    useCoarsePointer?: boolean, // Since `5.4.0`
    pointerSize?: number,       // Since `5.4.0`
    ssr?: boolean,              // Since `5.3.0`
    width?: number|string,
    height?: number|string,
    locale?: string             // Since `5.0.0`
}) => ECharts
```

### Parameters
- **dom** (HTMLDivElement|HTMLCanvasElement) - Required - Instance container, usually is a DIV element with height and width defined. It's only optional when `opts.ssr` is enabled for server-side rendering. It can also be a `canvas` element.
- **theme** (Object|string) - Optional - Theme to be applied. This can be a configuring object of a theme, or a theme name registered through echarts.registerTheme.
- **opts** (Object) - Optional - Optional chart configurations; which may contain:
  - **devicePixelRatio** (number) - Optional - Ratio of one physical pixel to the size of one device independent pixels. Browser's `window.devicePixelRatio` is used by default.
  - **renderer** (string) - Optional - Supports `'canvas'` or `'svg'`.
  - **ssr** (boolean) - Optional - Whether to use server-side rendering. Only available in SVG rendering mode. When enabled, it will no longer render automatically every frame, you have to use the renderToSVGString method to get the rendered SVG string.
  - **useDirtyRect** (boolean) - Optional - Enable dirty rectangle rendering or not, `false` by default.
  - **useCoarsePointer** (boolean) - Optional - Whether to expand the response area when interacting with elements. `null` means enabling for mobile devices; `true` means always enabling; `false` means always disabling.
  - **pointerSize** (number) - Optional - Size of expanded interaction size in pixels. It should be used along with `opts.useCoarsePointer`.
  - **width** (number|string) - Optional - Specify width explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, width of `dom` (instance container) will be used.
  - **height** (number|string) - Optional - Specify height explicitly, in pixel. If setting to `null`/`undefined`/`'auto'`, height of `dom` (instance container) will be used.
  - **locale** (string) - Optional - Specify the locale. There are two builtins: `'ZH'` and `'EN'`. Or you can use echarts.registerLocale to register a new locale.

### Request Example
```
const chart = echarts.init(dom, null, {renderer: 'svg'});
```

### Response
Returns an ECharts instance.

### Note
If DIV is hidden, ECharts initialization tends to fail due to the lack of width and height information. In this case, you can explicitly specify `style.width` and `style.height` of DIV, or manually call echartsInstance.resize after showing DIV. The height and width must be set via `opts.width` and `opts.height` in the server side rendering.
```

--------------------------------

### Using a theme in ECharts

Source: https://echarts.apache.org/en/download-theme.html

Shows how to import a theme file and initialize a chart with it. The second parameter of echarts.init is the theme name.

```html
<script src="echarts.js"></script>
<!-- import vintage theme -->
<script src="theme/vintage.js"></script>
<script>
// The second parameter is the name of the theme imported
var chart = echarts.init(document.getElementById('main'), 'vintage');
chart.setOption({
    ...
});
</script>
```

--------------------------------

### echarts.getMap

Source: https://echarts.apache.org/en/api.html

Gets a registered map in a specific format.

```APIDOC
## echarts.getMap

### Description
Gets a registered map in a specific format.

### Method
Function

### Signature
`getMap(mapName: string)`

### Parameters
- **mapName** (string) - Required - The name of the map to retrieve.

### Return Value
Returns an object with the following structure:
```
{
    geoJSON: Object,
    specialAreas: Object
}
```

### Notes
- `geoJSON` can also be `geoJson`, they have the same reference.
- SVG registered by `registerMap` cannot be obtained by this method yet.
- If you only import the required components, starting from v5.3.0 `getMap` has to be used after the `MapChart` or `GeoComponent` is imported.
```

--------------------------------

### Get registered map signature

Source: https://echarts.apache.org/en/api.html

The function signature for retrieving a registered map.

```typescript
(mapName: string)
```

--------------------------------

### Example: Register custom series and use in option

Source: https://echarts.apache.org/en/api.html

Shows how to define a renderItem function that draws circles based on data values, register it as 'bubble', and use it in a custom series option. The renderItem uses api.coord, api.value, api.visual, and params.itemPayload.

```javascript
const renderItem = (params, api) => {
    return {
        type: 'circle',
        shape: {
            cx: api.coord([api.value(0), api.value(1)])[0],
            cy: api.coord([api.value(0), api.value(1)])[1],
            r: api.value(2) * (params.itemPayload.scale || 1)
        },
        style: {
            fill: api.visual('color'),
            opacity: params.itemPayload.opacity() || 1,
        }
    }
};
echarts.registerCustomSeries('bubble', renderItem);

const option = {
    xAxis: {},
    yAxis: {},
    series: {
        type: 'custom',
        renderItem: 'bubble',
        itemPayload: {
            scale: 2,
            opacity: () => Math.random() * 0.5 + 0.5
        },
        data: [[11, 22, 20], [33, 44, 40], [18, 24, 10]]
    }
};
chart.setOption(option);


```

--------------------------------

### Initialize ECharts with devicePixelRatio 2 for supersampling

Source: https://echarts.apache.org/en/option-gl.html

Sets devicePixelRatio to 2 on the ECharts instance to achieve supersampling anti-aliasing when postEffect is enabled. Requires high computer performance, so temporalSuperSampling is usually preferred.

```javascript
var chart = echarts.init(dom, null, {
    devicePixelRatio: 2
})

```

--------------------------------

### Register map with specialAreas

Source: https://echarts.apache.org/en/api.html

Example of using specialAreas to zoom specific regions in a GeoJSON map.

```javascript
  echarts.registerMap('USA', usaJson, {
      // Move Alaska to the bottom left of United States
      Alaska: {
          // Upper left longitude
          left: -131,
          // Upper left latitude
          top: 25,
          // Range of longitude
          width: 15
      },
      // Hawaii
      Hawaii: {
          left: -110,
          top: 28,
          width: 5
      },
      // Puerto Rico
      'Puerto Rico': {
          left: -76,
          top: 26,
          width: 2
      }
  });
```

--------------------------------

### Multi-line Block Control Flow

Source: https://echarts.apache.org/en/coding-standard.html

Start a new line for 'else' and 'catch' keywords when using multi-line blocks.

```javascript
// good

if (condition) {
    // some statements;
}
else {
    // some statements;
}

try {
    // some statements;
}
catch (ex) {
    // some statements;
}


// bad

if (condition) {
    // some statements;
} else {
    // some statements;
}

try {
    // some statements;
} catch (ex) {
    // some statements;
```

--------------------------------

### Naming Conventions

Source: https://echarts.apache.org/en/coding-standard.html

Use lowerCamelCase for variables/functions and UpperCamelCase for classes.

```javascript
const loadingModules = {};
function loadProduct() {
}

function Element(options) {
}
```

--------------------------------

### echarts.use

Source: https://echarts.apache.org/en/api.html

Registers components for use with the tree-shaking API. Must be called before `echarts.init`.

```APIDOC
## echarts.use

### Description
Registers components for use with the tree-shaking API. Must be called before `echarts.init`.

### Method
Function

### Signature
`echarts.use(components: Array)`

### Parameters
- **components** (Array) - Required - An array of components to register, such as `GridComponent`, `BarChart`, `CanvasRenderer`.

### Example
```javascript
import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { GridComponent } from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';

echarts.use([GridComponent, BarChart, CanvasRenderer]);
```

### Notes
- Available since `v5.0.1`.
- Must be used before `echarts.init`.
```

--------------------------------

### Line Break and Indent Suggestions

Source: https://echarts.apache.org/en/coding-standard.html

Recommended patterns for complex conditions, function arguments, and chained method calls.

```javascript
if (user.isAuthenticated()
    && user.isInRole('admin')
    && user.hasAuthority('add-admin')
) {
    // Code
}

foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);

baidu.format(
    dateFormatTemplate,
    year, month, date, hour, minute, second
);

$('#items')
    .find('.selected')
    .highlight()
    .end();

const result = thisIsAVeryVeryLongCondition
    ? resultA : resultB;

const res = condition
    ? thisIsAVeryVeryLongResult
    : resultB;
```

--------------------------------

### Multi-line Bracket Indentation

Source: https://echarts.apache.org/en/coding-standard.html

Start a new line for closing brackets if the content occupies multiple lines, matching the indentation of the opening bracket.

```javascript
// good
if (product) {
    product.load();
    if (user.isAuthenticated()
        && user.isInRole('admin')
        && user.hasAuthority('add-admin')
    ) {
        sendProduct(user, product);
    }
}
const arr = [
    'candy', 'sugar'
];

// bad
if (product) {
    product.load();
    if (user.isAuthenticated()
        && user.isInRole('admin')
        && user.hasAuthority('add-admin')) {
        sendProduct(user, product);
    }
}
const arr = [
        'candy', 'sugar'
    ];
```

--------------------------------

### Space after colon in object

Source: https://echarts.apache.org/en/coding-standard.html

Shows spacing rules in object literals: one space after `:` but no space before it. The bad example misplaces spaces around the colon.

```javascript
// good
const obj = {
    a: 1,
    b: 2,
    c: 3
};

// bad
const obj = {
    a : 1,
    b:2,
    c :3
};
```

--------------------------------

### Connect chart interactions

Source: https://echarts.apache.org/en/api.html

Demonstrates how to link multiple chart instances using group IDs or an array of instances.

```javascript
// set group id of each instance respectively.
chart1.group = 'group1';
chart2.group = 'group1';
echarts.connect('group1');
// or incoming instance array that need to be linked.
echarts.connect([chart1, chart2]);
```
Tokens:
Raw