echarts-wordcloud

Third-party Wordcloud extension based on wordcloud2.js for Apache ECharts.

This is a maintained fork of ecomfe/echarts-wordcloud for ECharts 6, published as @qyperion/echarts-wordcloud. It keeps the option API of the original and fixes how a layout stops when the chart is disposed, resized or updated. It also adds a few options; see the changelog.

Install

npm install echarts @qyperion/echarts-wordcloud

import * as echarts from 'echarts';
import '@qyperion/echarts-wordcloud';

Or

<script src="https://cdn.jsdelivr.net/npm/echarts@6/dist/echarts.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@qyperion/echarts-wordcloud@3/dist/echarts-wordcloud.min.js"></script>

| Package | ECharts | | ------------------------------- | ------- | | @qyperion/echarts-wordcloud@3 | 6 | | echarts-wordcloud@2 | 5 | | echarts-wordcloud@1 | 4 |

Usage

var chart = echarts.init(document.getElementById('main'));

chart.setOption({
    ...
    series: [{
        type: 'wordCloud',

        // The shape of the "cloud" to draw. Can be any polar equation represented as a
        // callback function, or a keyword present. Available presents are circle (default),
        // cardioid (apple or heart shape curve, the most known polar equation), diamond (
        // alias of square), triangle-forward, triangle, (alias of triangle-upright, pentagon, and star.

        shape: 'circle',

        // Keep aspect ratio of maskImage or 1:1 for shapes
        keepAspect: false,

        // A silhouette image which the white area will be excluded from drawing texts.
        // The shape option will continue to apply as the shape of the cloud to grow.
        // The image must be loaded before the option is set; an image that cannot be
        // drawn, such as a broken or cross-origin one, makes setOption throw.

        maskImage: maskImage,

        // Folllowing left/top/width/height/right/bottom are used for positioning the word cloud
        // Default to be put in the center and has 75% x 80% size.

        left: 'center',
        top: 'center',
        width: '70%',
        height: '80%',
        right: null,
        bottom: null,

        // Text size range which the value in data will be mapped to.
        // Default to have minimum 12px and maximum 60px size.

        sizeRange: [12, 60],

        // Text rotation range and step in degree. Text will be rotated randomly in range [-90, 90] by rotationStep 45

        rotationRange: [-90, 90],
        rotationStep: 45,

        // Seed of the random rotations. The same seed lays out the same words the same way
        // in a container of the same size, also after a resize back to it.
        // Without a seed, every layout differs.
        randomSeed: null,

        // size of the grid in pixels for marking the availability of the canvas
        // the larger the grid size, the bigger the gap between words.

        gridSize: 8,

        // set to true to allow word to be drawn partly outside of the canvas.
        // Allow word bigger than the size of the canvas to be drawn
        drawOutOfBound: false,

        // if the font size is too large for the text to be displayed,
        // whether to shrink the text. If it is set to false, the text will
        // not be rendered. If it is set to true, the text will be shrinked.
        shrinkToFit: false,

        // If perform layout animation.
        // NOTE disable it will lead to UI blocking when there is lots of words.
        layoutAnimation: true,

        // Global text style
        textStyle: {
            fontFamily: 'sans-serif',
            fontWeight: 'bold',
            // Color can be a callback function or a color string
            color: function () {
                // Random color
                return 'rgb(' + [
                    Math.round(Math.random() * 160),
                    Math.round(Math.random() * 160),
                    Math.round(Math.random() * 160)
                ].join(',') + ')';
            }
        },
        emphasis: {
            focus: 'self',

            textStyle: {
                textShadowBlur: 10,
                textShadowColor: '#333'
            }
        },

        // Data is an array. Each array item must have name and value property.
        data: [{
            name: 'Farrah Abraham',
            value: 366,
            // Style of single text
            textStyle: {
            }
        }]
    }]
});

The series also takes z and zlevel, and the color and opacity of a visualMap.

TypeScript

The package declares WordCloudSeriesOption and registers the wordCloud series in the option types of ECharts, so EChartsOption accepts it:

import * as echarts from 'echarts';
import '@qyperion/echarts-wordcloud';

const option: echarts.EChartsOption = {
  series: { type: 'wordCloud', data: [{ name: 'ECharts', value: 1 }] }
};

The CommonJS types of ECharts keep their series registry private. With CommonJS module resolution, compose the option instead:

import type { ComposeOption, PieSeriesOption } from 'echarts';
import type { WordCloudSeriesOption } from '@qyperion/echarts-wordcloud';

type Option = ComposeOption<WordCloudSeriesOption | PieSeriesOption>;

Layout lifecycle

A layout runs on an offscreen canvas after the option is set and places the words one by one. An integration that has to wait for resources, or to know when the words are drawn, can control each layout with setLayoutLifecycle:

import { setLayoutLifecycle } from '@qyperion/echarts-wordcloud';

setLayoutLifecycle(function (seriesModel, api, canvas) {
  canvas.addEventListener('wordcloudstop', function () {
    // Every word is placed.
  });
  canvas.addEventListener('wordcloudabort', function (event) {
    // The layout failed with event.detail.error.
  });
  return {
    // Starts the layout once fonts are ready; cleanupFailure disposes it.
    run: function (start, cleanupFailure) {
      document.fonts.ready.then(start).catch(cleanupFailure);
    },
    // The series was replaced or removed.
    retire: function () {},
    // The layout was disposed after a failure.
    cancel: function () {},
    // Drawing a word threw error.
    fail: function (error) {}
  };
});

The factory is called before each series layout; returning null starts the layout at once. setLayoutLifecycle(null) restores the default.

Development

npm ci
npx playwright install chromium
npm run lint
npm run typecheck
npm test

npm test builds dist/ and runs the tests in Chromium. To see the examples, build and serve the repository root with any static file server, then open example/wordCloud.html.

A v* tag that matches the version in package.json publishes the package to npm from .github/workflows/release.yml, through npm trusted publishing.

Changelog

3.0.0

• [breaking] Published as @qyperion/echarts-wordcloud. Requires ECharts 6.1 (peerDependencies.echarts: ^6.1.0)
• [breaking] Built with Rollup as an ES module and UMD bundles; the UMD global that holds the exports is echartsWordcloud. dist/ is no longer in the repository
• [breaking] WordCloudSeriesOption is exported from this package and registered in the option types of ECharts 6; sizeRange and rotationRange are [min, max] tuples, and shape takes the presets or a function
• [breaking] An invalid mask image throws instead of logging and laying out without the mask
• [fix] Disposing, resizing or updating the chart stops the running layout; a disposed layout no longer places the remaining words on its offscreen canvas, and the layout removes its listeners
• [fix] Without layoutAnimation, the layout iterates instead of recursing once per word, so large data no longer overflows the stack
• [fix] An error thrown while placing a word, for example by a shape callback, stops the layout with wordcloudabort instead of escaping from a timer
• [fix] Disposing a chart whose first render failed no longer throws
• [fix] The brush action keeps the drawn words instead of clearing them
• [fix] The words are drawn on the z and zlevel of the series
• [fix] The opacity of a visualMap is applied (ecomfe/echarts-wordcloud#158)
• [fix] wordcloudstart and wordclouddrawn are cancelable as documented (from modernized-js/echarts-wordcloud)
• [fix] Importing without a DOM, as during server-side rendering, no longer throws (ecomfe/echarts-wordcloud#173)
• [feature] Add randomSeed for a repeatable layout (ecomfe/echarts-wordcloud#160)
• [feature] Add setLayoutLifecycle to defer, cancel and observe layouts
• [chore] Sync with wordcloud2.js 1.2.3
• [chore] Browser tests with Vitest and Chromium, CI, and releases with npm provenance

2.1.0

• [chore] Update Apache ECharts version
• [chore] Sync with the latest wordcloud2.js and use prettier to format the code
• [feature] Add keepAspect option to keep aspect ratio of maskImage or 1:1 for shapes
• [feature] Add drawOutOfBound option to allow words to be drawn partly outside of the canvas
• [feature] Add shrinkToFit option to shrink the text if the font size is too large for the text to be displayed

License

ISC. The layout in src/layout.js is based on wordcloud2.js, under the MIT License. See LICENSE.

Notice

The Apache Software Foundation Apache ECharts, ECharts, Apache, the Apache feather, and the Apache ECharts project logo are either registered trademarks or trademarks of the Apache Software Foundation.