echarts6-liquidfill
v1.1.1
Published
Liquid fill chart plugin for Apache ECharts 6, which is usually used to represent data in percentage
Downloads
362
Maintainers
gf85712921Readme
echarts6-liquidfill
Liquid Fill Chart plugin for Apache ECharts 6.x, which is usually used to represent data in percentage.
项目背景
本项目 fork 自 ecomfe/echarts-liquidfill(v3.1.0)。
Apache ECharts 发布 6.x 之后,原插件 [email protected] 声明的 peerDependencies 仍是 echarts@^5.0.1,在 echarts 6.x 项目中安装时会遇到依赖冲突(以下均为实测复现):
npm(v7 及以上):依赖解析直接失败并报错,无法正常安装:
npm error ERESOLVE unable to resolve dependency tree npm error peer echarts@"^5.0.1" from [email protected]必须追加
--force或--legacy-peer-deps才能装上;强装之后npm ls也会把 echarts 标记为invalid(peer 版本不满足)。pnpm:每次安装/更新都会持续输出警告(这也正是本项目 fork 的直接动因):
└─┬ echarts-liquidfill 3.1.0 └── ✕ unmet peer echarts@^5.0.1: found 6.x.x
本项目的处理方式(插件渲染逻辑与 [email protected] 保持一致,API 向下兼容,升级只需替换包名):
- 将 peerDependencies 升级为
echarts@^6.0.0,包名变更为echarts6-liquidfill,echarts 6 项目可正常安装、无冲突报错与警告; - 构建产物瘦身:插件源码不再深引用
echarts/lib/util/number等内部模块,改用 echarts 入口导出的number命名空间,避免打包器将 echarts/zrender 内部代码混入插件 dist(开发版 dist 由 69KB 降至 28KB,压缩版由 10.8KB 降至 7.6KB); - 适配 zrender 6 的文本样式键变更:echarts 6 下
textAlign/textVerticalAlign已更名为align/verticalAlign,旧键会被静默忽略,本插件已改用新键名,label.align与垂直对齐配置恢复正常生效; - label 支持 echarts 5/6 标准写法
verticalAlign(旧的baseline写法仍然兼容,同时设置时以verticalAlign为准); - 新增 TypeScript 类型声明(
index.d.ts),并通过 echarts 6 官方提供的RegisteredSeriesOption声明合并注册liquidFill系列,series: [{ type: 'liquidFill', ... }]可直接通过EChartsOption类型检查(echarts 6 的类型文件中已不包含 liquidFill 声明)。
插件渲染逻辑与 [email protected] 保持一致,API 完全向下兼容,升级只需替换包名。
安装
# install echarts as peer dependency
npm install echarts
npm install echarts6-liquidfill版本对应关系:
| echarts6-liquidfill | echarts | | ------------------- | ------- | | 1.x | 6.x | | echarts-liquidfill 3.x(上游) | 5.x | | echarts-liquidfill 2.x(上游) | 4.x |
在 npm/打包工具中使用
import * as echarts from "echarts";
import "echarts6-liquidfill";或按需引入 echarts 核心:
import * as echarts from "echarts/core";
import "echarts6-liquidfill";TypeScript 用户无需额外引入类型,插件导入后 EChartsOption 即支持 liquidFill 系列。
通过 <script> 使用
在 echarts 之后引入插件:
<script src="echarts.js"></script>
<script src="echarts6-liquidfill.js"></script>ECharts 可从 GitHub dist 目录 或 官网下载页 获取;插件文件见本仓库 dist 目录。
NOTE
Liquid Fill Chart 最低可运行于 echarts.simple.js。如需 tooltip 等组件,请使用完整版 echarts。
快速开始
创建一个 type 为 'liquidFill' 的 series 即可:
var option = {
series: [
{
type: "liquidFill",
data: [0.6],
},
],
};
常见用法:
Examples
A Simple Example
Multiple Waves
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
},
],
};This creates a chart with waves at position of 60%, 50%, 40%, and 30%.
Color and Opacity
To set colors for liquid fill chart series, set color to be an array of colors. To set opacity, use itemStyle.opacity and itemStyle.emphasis.opacity for normal style and hover style.
var option = {
series: [
{
type: "liquidFill",
data: [0.5, 0.4, 0.3],
color: ["red", "#0f0", "rgb(0, 0, 255)"],
itemStyle: {
opacity: 0.6,
},
emphasis: {
itemStyle: {
opacity: 0.9,
},
},
},
],
};
You may also set the color and opacity of a single data item by:
var option = {
series: [
{
type: "liquidFill",
data: [
0.5,
0.4,
{
value: 0.3,
itemStyle: {
color: "red",
opacity: 0.6,
},
emphasis: {
itemStyle: {
opacity: 0.9,
},
},
},
],
},
],
};
Static Waves
To prevent the waves from moving left or right, you may simply set waveAnimation to be false. To disable the animation of waves raising, set animationDuration and animationDurationUpdate to be 0.
var option = {
series: [
{
type: "liquidFill",
waveAnimation: false,
animationDuration: 0,
animationDurationUpdate: 0,
data: [0.6, 0.5, 0.4, 0.3],
},
],
};
Still Water
You may set the amplitude to be 0 to make still waves.
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
amplitude: 0,
waveAnimation: false,
},
],
};It is recommended to set waveAnimation to be false in this case to disable animation for performance consideration.
Change A Single Wave
To change a single wave, overwrite the options in data item.
var option = {
series: [
{
type: "liquidFill",
data: [
0.6,
{
value: 0.5,
direction: "left",
itemStyle: {
color: "red",
},
},
0.4,
0.3,
],
},
],
};
Background Style
You can use backgroundStyle option to set the stroke, fill style of background shape.
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
backgroundStyle: {
borderWidth: 5,
borderColor: "red",
color: "yellow",
},
},
],
};
Outline Style
To hide the outline, just set outline.show to be false.
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
outline: {
show: false,
},
},
],
};
Shape
Shape of water fill chart. It can be:
- one of the default symbols:
'circle','rect','roundRect','triangle','diamond','pin','arrow'; 'container': a shape that fully fills the container.- an SVG path starting with
'path://'.
var options = [
{
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
shape: "diamond",
},
],
},
];
option = {
series: [{
type: 'liquidFill',
data: [0.5, 0.4, 0.3, 0.2],
shape: 'container',
outline: {
show: false
}
}]
};
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.55, 0.4, 0.25],
radius: "60%",
outline: {
show: false,
},
backgroundStyle: {
borderColor: "#156ACF",
borderWidth: 1,
shadowColor: "rgba(0, 0, 0, 0.4)",
shadowBlur: 20,
},
shape:
"path://M367.855,428.202c-3.674-1.385-7.452-1.966-11.146-1.794c0.659-2.922,0.844-5.85,0.58-8.719 c-0.937-10.407-7.663-19.864-18.063-23.834c-10.697-4.043-22.298-1.168-29.902,6.403c3.015,0.026,6.074,0.594,9.035,1.728 c13.626,5.151,20.465,20.379,15.32,34.004c-1.905,5.02-5.177,9.115-9.22,12.05c-6.951,4.992-16.19,6.536-24.777,3.271 c-13.625-5.137-20.471-20.371-15.32-34.004c0.673-1.768,1.523-3.423,2.526-4.992h-0.014c0,0,0,0,0,0.014 c4.386-6.853,8.145-14.279,11.146-22.187c23.294-61.505-7.689-130.278-69.215-153.579c-61.532-23.293-130.279,7.69-153.579,69.202 c-6.371,16.785-8.679,34.097-7.426,50.901c0.026,0.554,0.079,1.121,0.132,1.688c4.973,57.107,41.767,109.148,98.945,130.793 c58.162,22.008,121.303,6.529,162.839-34.465c7.103-6.893,17.826-9.444,27.679-5.719c11.858,4.491,18.565,16.6,16.719,28.643 c4.438-3.126,8.033-7.564,10.117-13.045C389.751,449.992,382.411,433.709,367.855,428.202z",
label: {
position: ["38%", "40%"],
formatter: function () {
return "ECharts\nLiquid Fill";
},
fontSize: 40,
color: "#D94854",
},
},
],
};
Animation
Generally speaking, there are two types of animations in liquid fill charts.
The first type is initial animation, which has the effect of wave raising. The easing method of this animation is controlled with animationEasing and its duration with animationDuration.
The second type is the update animation, which is usually used when data changes and wave height changes. They are controlled with animationEasingUpdate and animationDurationUpdate.
For example, to disable the raising animation and set update animation time to be two seconds with cubicOut easing, you can use the following option:
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
animationDuration: 0,
animationDurationUpdate: 2000,
animationEasingUpdate: "cubicOut",
},
],
};
chart.setOption(option);
setTimeout(function () {
chart.setOption({
series: [
{
type: "liquidFill",
data: [0.8, 0.6, 0.4, 0.2],
},
],
});
}, 3000);
Change Text
By default, the text label of liquid fill chart displays percentage of the first data. For example, for a chart with data [0.6, 0.5, 0.4, 0.3], default text is 60%.
To change the text, you may use label.formatter, which can be set to a string or function.
If it is a string, {a} refers to series name, {b} to data name, and {c} to data value.
var option = {
series: [
{
type: "liquidFill",
name: "Liquid Fill",
data: [
{
name: "First Data",
value: 0.6,
},
0.5,
0.4,
0.3,
],
label: {
formatter: "{a}\n{b}\nValue: {c}",
fontSize: 28,
},
},
],
};Label text of this example is 'Liquid Fill\nFirst Data\nValue: 0.6'.
This has the same result as using formatter as a function:
var option = {
series: [
{
type: "liquidFill",
name: "Liquid Fill",
data: [
{
name: "First Data",
value: 0.6,
},
0.5,
0.4,
0.3,
],
label: {
formatter: function (param) {
return (
param.seriesName + "\n" + param.name + "\n" + "Value:" + param.value
);
},
fontSize: 28,
},
},
],
};Text position is at the center by default. label.position can be set to be 'inside', 'left', 'right', 'top', 'bottom', or horizontal and vertical positions like ['10%', '20%'], which means '10%' to the left (controlled by label.align, which can be 'left', 'center', or 'right') and '20%' to the top (controlled by label.verticalAlign, which can be 'top', 'middle', or 'bottom').
注:
label.verticalAlign是 echarts 5 起的标准写法;旧文档中的label.baseline仍被兼容,两者同时设置时以verticalAlign为准。
Shadow
By default, waves and outline have shadow on them. Here's how to change them.
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
itemStyle: {
shadowBlur: 0,
},
outline: {
borderDistance: 0,
itemStyle: {
borderWidth: 5,
borderColor: "#156ACF",
shadowBlur: 20,
shadowColor: "rgba(255, 0, 0, 1)",
},
},
},
],
};
Tooltip
To add tooltip:
var option = {
series: [
{
type: "liquidFill",
data: [0.6],
name: "Liquid Fill",
},
],
tooltip: {
show: true,
},
};
Click Event
To add click event on waves:
chart.setOption(option);
chart.on("click", function () {
console.log(arguments);
// do something useful here
});Like any other chart types, the above code will only trigger events on waves. If you want to track events on the whole canvas or specific elements, you may add listener to zrender like:
chart.getZr().on("click", function () {
console.log(arguments);
});Non-interactable
To make an element (e.g., a wave) non-interactable, simply set silent to be true.
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
silent: true,
},
],
};API
Default option for liquid fill charts are:
{
data: [],
color: ['#294D99', '#156ACF', '#1598ED', '#45BDFF'],
center: ['50%', '50%'],
radius: '50%',
amplitude: '8%',
waveLength: '80%',
phase: 'auto',
period: 'auto',
direction: 'right',
shape: 'circle',
waveAnimation: true,
animationEasing: 'linear',
animationEasingUpdate: 'linear',
animationDuration: 2000,
animationDurationUpdate: 1000,
outline: {
show: true,
borderDistance: 8,
itemStyle: {
color: 'none',
borderColor: '#294D99',
borderWidth: 8,
shadowBlur: 20,
shadowColor: 'rgba(0, 0, 0, 0.25)'
}
},
backgroundStyle: {
color: '#E3F7FF'
},
itemStyle: {
opacity: 0.95,
shadowBlur: 50,
shadowColor: 'rgba(0, 0, 0, 0.4)'
},
label: {
show: true,
color: '#294D99',
insideColor: '#fff',
fontSize: 50,
fontWeight: 'bold',
align: 'center',
verticalAlign: 'middle',
position: 'inside'
},
emphasis: {
itemStyle: {
opacity: 0.8
}
}
}data {(number|Object)[]}
Value of each data item should be between 0 and 1.
The data item can also be an object to configure the option for a single item.
var option = {
series: [
{
type: "liquidFill",
data: [
0.6,
{
value: 0.5,
itemStyle: {
color: "red",
},
},
0.4,
0.3,
],
},
],
};This defines a chart with the second wave of red color.
color {string[]}
Wave colors.
shape {string}
Shape of water fill chart. It can be one of the default symbols: 'circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow', or 'container'. Or, an SVG path starting with 'path://'.
center {string[]}
Position of the chart. The first value is x position, the second one is the y position. Each of the values can be a relative value like '50%', which is relative to the smaller value of container width and height, or an absolute value like 100px.
radius {string}
Radius of the chart, which can be a relative value like '50%', which is relative to the smaller value of container width and height, or an absolute value like 100px.
amplitude {number}
Amplitude of the wave, in pixels or percentage. If it is in percentage, it's relative to the diameter.
waveLength {string|number}
Wave length of the wave, which can be a relative value like '50%', which is relative to the diameter, or an absolute value like '100px' or 100.
phase {number}
Phase of wave, in radian system. By default, it is set to be 'auto', when each wave has a phase of Math.PI / 4 larger than the previous one.
period {number|'auto'|function}
Milliseconds that it takes to move forward a wave-length. By default, it is set to be 'auto', when the wave at the front has a greater speed.
It can also be a formatter function.
var option = {
series: [
{
type: "liquidFill",
data: [0.6, 0.5, 0.4, 0.3],
radius: "70%",
phase: 0,
period: function (value, index) {
// This function is called four times, each for a data item in series.
// `value` is 0.6, 0.5, 0.4, 0.3, and `index` is 0, 1, 2, 3.
return 2000 * index + 1000;
},
},
],
};direction {string}
Direction that the waves moving in, which should either be 'right', or 'left'.
waveAnimation {boolean}
Whether to enable wave from moving left or right.
animationEasing {string}
Easing methods for initial animation, when waves raise from the bottom at the beginning.
animationEasingUpdate {string}
Easing methods for other animation, for example, when data value changes and wave position changes.
animationDuration {number}
Initial animation duration, in milliseconds.
animationDurationUpdate {number}
Other animation duration, in milliseconds.
outline.show {boolean}
Whether to display outline.
outline.borderDistance {number}
Distance between border and inner circle.
outline.itemStyle.borderColor {string}
Border color.
outline.itemStyle.borderWidth {number}
Border width.
outline.itemStyle.shadowBlur {number}
Outline shadow blur size.
outline.itemStyle.shadowColor {string}
Outline shadow color.
backgroundStyle.color {string}
Background fill color.
backgroundStyle.borderWidth {number}
Background stroke line width.
backgroundStyle.borderColor {string}
Background stroke line color.
backgroundStyle.shadowBlur {number}
Background shadow blur size.
backgroundStyle.shadowColor {string}
Background shadow color.
itemStyle.opacity {number}
Wave opacity.
itemStyle.shadowBlur {number}
Wave shadow width.
itemStyle.shadowColor {string}
Wave shadow color.
emphasis.itemStyle.opacity {number}
Wave opacity when hover.
label.show {boolean}
Whether to display label text.
label.color {string}
Color of text when display on background.
label.insideColor {string}
Color of text when display on wave.
label.fontSize {number}
Label font size.
label.fontWeight {string}
Label font weight.
label.align {string}
Text align, which should be 'left', 'center', or 'right'.
label.verticalAlign {string}
Text vertical align, which should be 'top', 'middle', or 'bottom'. The legacy name label.baseline is still supported.
label.position {string|string[]}
Text position is at the center by default. label.position can be set to be 'inside', 'insideTop', 'insideBottom', 'insideLeft', 'insideRight', 'left', 'right', 'top', 'bottom', or horizontal and vertical positions like ['10%', '20%'], which means '10%' to the left and '20%' to the top.
Note that label.verticalAlign aligns the text box relative to its anchor point (for 'inside', the center of the shape), not to the container edge. To place text near the top or bottom edge of the shape, prefer 'insideTop' / 'insideBottom'.
构建
npm install
# development build (dist/echarts6-liquidfill.js)
npm run build
# production + development build (dist/echarts6-liquidfill.min.js / .js)
npm run release
# watch mode
npm run dev
# TypeScript declaration check (requires type-check.ts)
npm run check-types
# headless smoke test (echarts 6 SSR, no browser needed)
npm test示例页面
example/ 目录下提供了多个示例,可直接用静态服务器打开(如 npx http-server 后访问 http://127.0.0.1:8000/example/echarts6.html):
echarts6.html— 基于 echarts 6 的综合示例index.html/test.html/fill-container.html— 原有示例(已升级为 echarts 6)
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.
更新日志
各版本变更详见 CHANGELOG.md。
License
本项目基于 BSD 3-Clause License 开源(版权所有 © 2020, Baidu Inc.),fork 自 ecomfe/echarts-liquidfill,原作者与主要贡献者见上游仓库。按 BSD-3-Clause 条款,本项目允许修改、商用与再分发,前提是随分发保留上述版权声明、许可文本与免责声明;Baidu Inc. 及原贡献者不为衍生项目背书。