Apache ECharts Examples

E2E tests verify package publishing, module importing, bundling, and DTS correctness.

Prerequisites:

1. Update the example list: npm run build:examplelist.
2. Install Puppeteer if not present: npm i puppeteer -D.

Test Modes:

• Remote Repos (Standard): Downloads repos listed in echarts-examples/e2e/config.js to a temporary folder.
  • Webpack: npm run test:e2e
  • Esbuild (Faster): npm run test:e2e:esbuild
• Local Repos: Uses local versions of dependent repos (e.g., echarts, zrender). Requires local repos to have a release build (e.g., npm run release).
  • Webpack: npm run test:e2e:local
  • Esbuild (Faster): npm run test:e2e:esbuild:local

Checking Results:

• Review result.log.
• Open echarts-examples/e2e/report.html via a local HTTP server.

Partial Testing: If you have run the full suite at least once, you can skip stages using node e2e/main.js:

• --skip npm --local: Skip updating dependencies.
• --skip render,compare --local: Skip Puppeteer rendering/comparison.
• --skip bundle --local: Skip bundling.
• --tests <pattern>: Run specific tests (e.g., --tests bar3D*).

# Update list first
npm run build:examplelist

# Run remote tests with esbuild
npm run test:e2e:esbuild > result.log 2>&1

To add or edit examples, work within the public/examples/ts folder.

Important Rules:

• Do NOT add or edit files in the public/examples/js folder.
• Do NOT modify existing file paths unless you update all corresponding links in echarts-doc.
• Each example must include a metadata block as the first JavaScript comment in the file.

Compilation: After editing, you must compile the TypeScript/JavaScript files into the final JavaScript format using one of these commands:

# Compile all examples
npm run compile:example

# Compile a single specific example
npm run compile:example -- area-basic.ts

Handling TypeScript Errors: If compilation fails due to local modifications of the echarts TypeScript interface, you may need to point the installation to your local version of echarts:

cd your/echarts-examples
npm i --force your/local/echarts

To add interactive widgets (selections, ranges, buttons) to an example, configure the app.config and app.configParameters objects.

Implementation Pattern:

1. Define the state and callback logic in app.config.
2. Define the widget constraints (options, min/max) in app.configParameters.

app.config = {
  aNameForTheSelectionWidget: 'This is the initial value',
  aNameForTheRangeWidget: 45,
  aNameForTheButtonWidget: function () {
    // Click logic
  },
  onChange: function () {
    // Triggered when widgets change
    console.log(app.config.aNameForTheRangeWidget);
  }
};

app.configParameters = {
  aNameForTheSelectionWidget: {
    options: ['Value 1', 'Value 2', 333, false]
  },
  aNameForTheRangeWidget: {
    min: -90,
    max: 90
  }
};

app.config = {
  aNameForTheSelectionWidget: 'This is the initial value'
  aNameForTheRangeWidget: 45,
  aNameForTheButtonWidget: function () {
    // Do something on button click.
  },
  onChange: function () {
    // Do something on SelectionWidget or RangeWidget changed.
    // Read the current value.
    console.log(app.config.aNameForTheRangeWidget)
    console.log(app.config.aNameForTheSelectionWidget)
  }
};
app.configParameters = {
  // The keys below must exist in `app.config`.
  aNameForTheSelectionWidget: {
    options: [
      'This is the initial value',
      'This is another value',
      'This is the third value'
      333,   // value other than string is supported.
      false, // value other than string is supported.
    ]
  },
  aNameForTheRangeWidget: {
    min: -90,
    max: 90
  }
};

You can load external scripts or JSON data within an example using the provided $ utility.

Loading Scripts:

$.when(
  $.getScript(ROOT_PATH + '/data/asset/js/xxxx.js'),
  $.getScript('https://cdn.jsdelivr.net/npm/d3-contour@2.0.0/dist/d3-contour.js')
).done(function () {
  option = { /* ... */ };
  myChart.setOption(option);
});

Loading GeoJSON/Data:

$.get(ROOT_PATH + '/data/asset/geo/iceland.geo.json', function (geoJSON) {
  echarts.registerMap('iceland', geoJSON);
  option = { /* ... */ };
  myChart.setOption(option);
});

$.when(
  $.getScript(ROOT_PATH + '/data/asset/js/xxxx.js'),
  $.getScript(
    'https://cdn.jsdelivr.net/npm/d3-contour@2.0.0/dist/d3-contour.js'
  )
).done(function () {
  // ...
  // Set echarts option to the global variable `option`.
  option = {/*...*/};
  // The global variable `myChart` can be used there.
  myChart.setOption(option);
});

Every example source file must start with a JavaScript comment block containing metadata. This metadata is used for the example exploration page and video generation.

Available Metadata Properties:

• title (String, Optional): The title of the example.
• titleCN (String, Optional): The Chinese title of the example.
• category (String list, Optional): The main categories (e.g., 'line, visualMap'). Use quotation marks and commas for multiple categories.
• since (Semver string, Optional): The ECharts version when this example was added (e.g., 6.0.0). Do not use the v prefix.
• difficulty (Number, Optional): The difficulty level.
• theme (String, Optional): The theme used.
• noExplore (Boolean, Optional): If true, the example is excluded from the example exploration page.
• videoStart (Number, Optional): Start time for video recording during screenshot generation.
• videoEnd (Number, Optional): End time for video recording during screenshot generation.

Example Metadata Block:

/*
title: Bar Race
titleCN: 动态排序柱状图
category: bar
difficulty: 5
videoStart: 1000
videoEnd: 6000
*/

/*
title: Area Pieces
titleCN: 折线图区域高亮
category: 'line, visualMap'
since: 6.0.0
*/