# charts-springt-boot
**Repository Path**: LevelCoder/charts-springt-boot
## Basic Information
- **Project Name**: charts-springt-boot
- **Description**: 基于ECharts和HighCharts的SpringBoot starter封装
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 3
- **Created**: 2024-09-29
- **Last Updated**: 2024-09-29
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 图表组件
## 目录
[一、简介](#一简介)
[二、部署](#二部署)
[三、安装](#三安装)
[四、架构](#四架构)
[五、结构](#五结构)
[六、使用](#六使用)
## 正文
## 一、简介
“charts-spring-boot-starter”组件是对目前较常用的前端图表组件进行统一的后台封装（如ECharts、HighCharts等），目的是降低各类图表组件的学习和使用成本。
组件的内部封装以“ECharts”为主、“HighCharts”（开发中）为次，其他“图表组件”（陆续增加）为辅。
下图为组件实际使用时的后台样例和图表效果（ECharts）：
## 二、部署
| Version | Repository | Author | Date |
| :-----: | :--------: | :----: | :--: |
| [0.0.1.RELEASE](http://180.168.156.212:2905/#browse/browse:maven-releases:com%2Fcesgroup%2Fzw%2Fspring%2Fboot%2Fcharts-spring-boot-starter) | [Sonatype Nexus Repository](http://180.168.156.212:2905/#browse/browse) | chanlong | Thu Jun 13 2019 |
## 三、安装
> maven pom.xml
>
> 1. 添加maven私服仓库
>```xml
>
>
> maven-releases
> http://180.168.156.212:2905/repository/maven-releases/
>
>
>
> maven-snapshots
> http://180.168.156.212:2905/repository/maven-snapshots/
>
>
>```
> 2. 添加组件依赖
>```xml
>
>
> com.cesgroup.zw.spring.boot
> charts-spring-boot-starter
> 0.0.1.RELEASE
>
>
>```
## 四、架构
### Compile Dependencies (4)
| Category/License | Group / Artifact | Version | Updates |
| :--------------: | :--------------- | :------ | :------ |
| Apache 2.0 | org.yaml >> snakeyaml | 1.19 | 1.24 |
| Apache 2.0 | cn.hutool >> hutool-all | 4.5.11 | ✔ |
| Apache 2.0 | io.spring.platform >> platform-bom | Cairo-RELEASE | ✔ |
| MIT | org.projectlombok >> lombok | 1.16.22 | 1.18.8 |
## 五、结构
```
charts-springt-boot -------------------------[maven parent]
├──charts-spring-boot-api ---------------- [组件的封装层，含各种图表的接口定义、封装以及构造器]
├──charts-spring-boot-library ------------ [组件的实现库，含各种图表配置项的预置实现，由中台开发人员维护]
├──charts-spring-boot-starter ------------ [组件的启动器]
├──charts-spring-boot-autoconfigure ------ [组件的自动装配模块]
charts-spring-boot-example ----------------- [独立于组件的样例项目及测试用例]
```
```
charts-springt-boot-library -----------------[组件的实现库]
├──com
├──cesgroup
├──zw
├──spring
├──boot
├──library
├──echarts
├──annular -------------------------------- [环形图]
├──simple ------------------------------- [简单环形图]
├──SimpleAnnularOption ---------------- [配置项]
├──SimpleAnnularParam ---------------- [参数]
├──SimpleAnnularSeries ---------------- [系列]
├──bar ------------------------------------ [柱状图]
├──simple ------------------------------- [简单柱状图]
├──SimpleBarOption -------------------- [配置项]
├──SimpleBarParam -------------------- [参数]
├──SimpleBarSeries -------------------- [系列]
├──graph ---------------------------------- [关系图]
├──simple ------------------------------- [简单关系图]
├──SimpleGraphOption ------------------ [配置项]
├──SimpleGraphParam ------------------ [参数]
├──SimpleGraphSeries ------------------ [系列]
├──line ----------------------------------- [折线图]
├──simple ------------------------------- [简单折线图]
├──SimpleLineOption ------------------- [配置项]
├──SimpleLineParam ------------------- [参数]
├──SimpleLineSeries ------------------- [系列]
├──rose ----------------------------------- [玫瑰图]
├──simple ------------------------------- [简单玫瑰图]
├──SimpleRoseOption ------------------- [配置项]
├──SimpleRoseParam ------------------- [参数]
├──SimpleRoseSeries ------------------- [系列]
├──scatter -------------------------------- [散点图]
├──simple ------------------------------- [简单散点图]
├──SimpleScatterOption ---------------- [配置项]
├──SimpleScatterParam ---------------- [参数]
├──SimpleScatterSeries ---------------- [系列]
```
## 六、使用
### 1、简单使用 —— 直接使用预置配置（library项目，需不断迭代完善）构造图表
#### 以绘制“简单柱状图”为例：
```
1）以二维数组结构，构造数据，如下：
Object[][] dataset = new Object[][] {
{ "product", "2017", "2018", "2019" },
{ "产品一", 43.3, 85.8, 93.7 },
{ "产品二", 83.1, 73.4, 55.1 },
{ "产品三", 86.4, 65.2, 82.5 },
{ "产品四", 72.4, 53.9, 39.1 }
};
// 二维数组中，第一行（除第一个元素外，第一个元素可以是任意值，目的只是为了保持数组结构的统一）为系列（此处为2017、2018、2019，三个系列，即三根柱子）
// 从第二行开始，即为具体的数据项，每一行的第一个元素为数据项的名称，后面的数值对应每个系列
// 因此根据上面的数据结构，可推算得出，系列“2017”，包含数据为“{产品一：43.3, 产品二：83.1, 产品三：46.4, 产品四：72.4}”，其余系列以此类推
2）构造图表的参数项
SimpleBarParam param = SimpleBarParam.builder().dataset(dataset).build();
// SimpleBarParam 为简单柱状图的参数模型，用于设置图表的动态参数，如dataset(数据集)等
3）构造EChartsOptionBuilder
EChartsOptionBuilder builder = EChartsOptionBuilderFactory.build(param, new SimpleBarOption());
// 与构造参数项不同，此处“EChartsOptionBuilderFactory”的调用方式，相对固定，仅传入的参数不同；
// 此语句的作用是，利用“EChartsOptionBuilderFactory”工厂类，通过“参数项”和“配置项”构造“EChartsOptionBuilder”
// “SimpleBarOption”为“简单柱状图”的配置项
4）通过EChartsOptionBuilder获取用于返回给前端的“图表配置项”
IOption option = builder.getOption();
5）通过Json将“图表配置项”返回给前端，参见“[正文 一、简介]”
```
### 2、扩展library项目的图表库
#### 以绘制“简单环形图”为例：
```
1）每个图表均由三个基本对象要素组成，分别为“配置项、参数项和系列项”。
配置项，即图表的基本配置，如标题、边距、图例等图表组件的配置；
参数项，即图表的参数设置，用于存放图表的动态参数，如数据集、数据项等动态内容；
系列项，即图表的系列配置，用于设置各系列中具备共性的配置；
2）扩展“EChartsOption”，创建自定义的“图表配置项”
@SuppressWarnings("serial")
public class SimpleAnnularOption extends EChartsOption {
// 在构造函数中设置配置项
public SimpleAnnularOption(SimpleAnnularParam param) { // 注1
this.setTitle(new Title() {{ // 注2
this.setText("总数");
this.setSubtext(param.getTotal()); // 注3
this.setTextStyle(new RichTextStyle() {{this.setFontSize(40);}});
this.setSubtextStyle(new RichTextStyle() {{this.setFontSize(30);}});
this.setTop("44%");
this.setLeft(Align.center);
}});
this.setLegend(new Legend() {{
this.setTop(Align.top);
this.setRight("5%");
this.setOrient(Orient.vertical);
this.setTextStyle(new RichTextStyle() {{this.setFontSize(18);}});
}});
// 配置项中的具体配置，参照ECharts官网
}
// 注1：设置配置项时，如需要动态数据，可通过参数项“SimpleAnnularParam”传入
// 注2: 此处是“new 匿名内部类对象，同时设置属性”的一种写法
// 注3: 此处即从“参数项”中获取动态数据
}
3）实现“IChartsParam”接口，创建自定义的“参数项”
@Data @Builder @SuppressWarnings("serial")
public class SimpleAnnularParam implements IChartsParam {
private String title;
private String total;
private Object[][] dataset;
@Override
public IComponent[] getSeries() {
return new SimpleAnnularSeries[] {new SimpleAnnularSeries(this)};
}
}
// 此处title、total、dataset即创建图表时所需的动态数据
// 泛型中，第一个参数用于指定系列（xxx series）的类型，第二个参数用于指定数据集（dataset）的类型
// 实现“getSeries”接口，此接口会被“EChartsOptionBuilderFactory”的build方法调用，用于设置图表的系列组件
// “参数项”中，应至少包含一个“dataset”属性，用于设置图表的数据集，有关数据集的结构，参见ECharts官方文档
4）继承对应的系列组件，创建自定义的“系列项”
@SuppressWarnings("serial")
public class SimpleAnnularSeries extends Pie {
public SimpleAnnularSeries(SimpleAnnularParam param) {
this.setRadius(new String[] {"35%","60%"});
this.setLabel(new LabelStyle() {{
this.setShow(true);
this.setFontSize(16);
}});
this.setLabelLine(new LabelLine() {{
this.setShow(true);
this.setLength(30);
this.setLength2(35);
}});
this.setName(param.getTitle());
}
// 此处设置各项配置的方式同“步骤2）”
}
5）扩展上述三个基本对象后，既可以按照以下方式创建图表
@Autowired
private ObjectMapper mapper;
@Test
public void test() throws JsonProcessingException {
// 构造数据（根据业务情况动态获取）
Object[][] dataset = new Object[][] {
{ "红名单查询", 410 },
{ "黑名单查询", 285 },
{ "法人行政处罚", 274 },
{ "其它查询", 235 }
};
// 构造参数（根据业务情况设置动态参数）
SimpleAnnularParam param = SimpleAnnularParam.builder().title("查询总量").total("7789").dataset(dataset).build();
// 构造配置，SimpleAnnularOption 即“步骤2）”创建的“图表配置项”
EChartsOptionBuilder builder = EChartsOptionBuilderFactory.build(param, new SimpleAnnularOption(param));
// 获取配置（对应前端图表组件的配置项，如ECharts）
IOption option = builder.getOption();
// 输出调试日志，“mapper”为SpringBoot自带的JSON解析器“Jackson”
log.info("The SimpleAnnular's option is: \n{}", mapper.writerWithDefaultPrettyPrinter().writeValueAsString(option));
}
```