qhmes/.trae/skills/jimureport/references/chart-config.md

图表配置参考

图表模板文件位置

src/main/resources/static/jmreport/desreport_/chartjson/

生成图表报表时，应先读取对应的模板 JSON 文件作为 ECharts 配置基础。

可用图表类型

文件名	chartType	说明
bar.simple.json	bar.simple	柱状图（单系列）
bar.multi.json	bar.multi	柱状图（多系列）
bar.stack.json	bar.stack	堆叠柱状图
bar.horizontal.json	bar.horizontal	横向柱状图
bar.multi.horizontal.json	bar.multi.horizontal	横向多系列柱状图
bar.stack.horizontal.json	bar.stack.horizontal	横向堆叠柱状图
bar.negative.json	bar.negative	正负柱状图
bar.background.json	bar.background	带背景柱状图
line.simple.json	line.simple	折线图（单系列）
line.multi.json	line.multi	折线图（多系列）
line.smooth.json	line.smooth	平滑曲线图
line.area.json	line.area	面积图
line.step.json	line.step	阶梯折线图
pie.simple.json	pie.simple	饼图
pie.doughnut.json	pie.doughnut	环形图
pie.rose.json	pie.rose	玫瑰图
mixed.linebar.json	mixed.linebar	柱状+折线混合图
radar.basic.json	radar.basic	雷达图
radar.custom.json	radar.custom	自定义雷达图
scatter.simple.json	scatter.simple	散点图
scatter.bubble.json	scatter.bubble	气泡图
funnel.simple.json	funnel.simple	漏斗图
funnel.pyramid.json	funnel.pyramid	金字塔图
gauge.simple.json	gauge.simple	仪表盘
gauge.simple180.json	gauge.simple180	半圆仪表盘
graph.simple.json	graph.simple	关系图
map.simple.json	map.simple	地图
map.scatter.json	map.scatter	地图散点
pictorial.spirits.json	pictorial.spirits	象形柱图

echartslist.json 主要 key 对照

key	对应图表
bar	单系列柱状图
bar2	dataset 模式柱状图
bar3	多系列柱状图
line	单系列折线图
line3	平滑曲线
line4	多系列折线图
line5	阶梯折线图
pie	饼图
pie1	环形图
pie2	玫瑰图
linebar	柱状+折线混合
map	地图
scatter	散点图

图表在 jsonStr 中的配置

图表通过单元格占位 + chartList 配置实现，不是绝对定位。需要两部分配合：

1. chartList 结构

{
    "chartList": [
        {
            "row": 5,
            "col": 1,
            "colspan": 0,
            "rowspan": 0,
            "width": "500",
            "height": "350",
            "config": "ECharts配置JSON字符串",
            "url": "",
            "extData": {
                "chartType": "bar.simple",
                "dataType": "sql",
                "dataId": "数据集ID",
                "dbCode": "数据集编码",
                "axisX": "name",
                "axisY": "value",
                "series": "type",
                "xText": "",
                "yText": "",
                "apiStatus": "1"
            },
            "layer_id": "唯一层ID",
            "offsetX": 0,
            "offsetY": 0,
            "backgroud": {"enabled": false, "color": "#fff", "image": ""},
            "virtualCellRange": [[5,1],[5,2],[5,3],[6,1],[6,2],[6,3]]
        }
    ]
}

关键字段说明：

字段	类型	说明
row / col	number	图表起始位置（行号/列号），不是 left/top 像素值
width / height	string	图表宽高像素，必须是字符串（如 "500"，不是 500）
virtualCellRange	array	图表占据的所有单元格坐标 [[row,col], ...]
layer_id	string	唯一标识，对应 rows 中 cells 的 virtual 属性
backgroud	object	图表背景（注意拼写是 backgroud 不是 background）
offsetX / offsetY	number	偏移量，通常为 0

2. rows 中的 virtual 占位

图表占据的每个单元格必须在 rows 中声明 "virtual": "layer_id"：

"rows": {
    "5": {
        "cells": {
            "1": {"text": " ", "virtual": "chart_xxx"},
            "2": {"text": " ", "virtual": "chart_xxx"},
            "3": {"text": " ", "virtual": "chart_xxx"}
        }
    },
    "6": {
        "cells": {
            "1": {"text": " ", "virtual": "chart_xxx"},
            "2": {"text": " ", "virtual": "chart_xxx"},
            "3": {"text": " ", "virtual": "chart_xxx"}
        }
    }
}

注意：

• virtual 的值必须和 chartList[].layer_id 一致
• text 设为 " "（一个空格），不能为空字符串
• 图表区域的行数 × 列数 = virtualCellRange 的元素数量
• 图表区域不能和列表数据行重叠

extData 关键字段

字段	说明
chartType	图表类型（如 bar.simple, line.multi, pie.simple）
dataType	数据来源："sql" / "api" / "json" / "javabean" / "files"（前端文本值，与 dbType 数字不同）
dataId	数据集ID（saveDb 返回的 id）
dbCode	数据集编码
axisX	X轴/分类字段名，固定为 name
axisY	Y轴/数值字段名，固定为 value
series	系列/分组字段名，固定为 type（单系列也要传 "type"）
apiStatus	API 数据集是否启用（"1" = 启用）
dataId1	第二数据集ID（关系图 graph.simple 使用）
isCustomPropName	是否自定义字段映射（默认不填，使用 name/value/type）

图表字段映射规则

重要：图表数据绑定使用固定的三个字段名，不是数据集的原始字段名。

extData 字段	固定值	含义	示例
axisX	name	X轴/分类	产品名称
axisY	value	Y轴/数值	销售额
series	type	系列/分组（多系列）	月份、类别

前端渲染时会将数据集查询结果按 name/value/type 进行映射：

• 单系列图表：series 也传 "type"（数据中 type 字段可为空字符串）
• 多系列图表：series = "type"，按 type 值分组生成多条系列

SQL 数据集示例（需要 AS 别名映射到 name/value）：

SELECT product_name AS name, sales_amount AS value FROM sales_table

多系列 SQL 示例（加 type 字段）：

SELECT month AS name, amount AS value, category AS type FROM sales_table

JSON 数据集示例：

{"data": [
    {"name": "螺丝钉", "value": 5000, "type": ""},
    {"name": "电阻器", "value": 3200, "type": ""}
]}

使用流程

1. 根据需求确定 chartType
2. 读取对应的 chartjson/{chartType}.json 文件作为 ECharts 配置模板
3. 修改模板中的 title.text、series 等，data 留空（由数据集驱动）
4. 将配置 JSON 字符串化后放入 chartList[].config
5. 配置 extData：axisX=name，axisY=value，series=type
6. 数据集字段必须包含 name 和 value（SQL 用 AS 别名，JSON 直接命名）
7. 确定图表占位区域（起始 row/col，占几行几列）
8. 在 rows 中为每个占位 cell 添加 "virtual": "layer_id"
9. 构造 virtualCellRange（所有占位坐标数组）
10. 将 chartList 放入 jsonStr 顶层

完整示例（列表 + 柱状图）

数据集配置

列表和图表使用两个独立数据集（db_code 唯一）：

数据集	dbCode	dbType	用途	字段
进库列表	stocklist	3(JSON)	列表展示	name, quantity, stock_time
进库图表	stockchart	3(JSON)	柱状图	name, value

Python 生成图表占位的关键代码

layer_id = "chart_" + gen_id()

# 图表占据 row5~row14, col1~col5
chart_row_start, chart_row_end = 5, 14
chart_col_start, chart_col_end = 1, 5

# 1. 构造 virtualCellRange
virtual_cell_range = []
for r in range(chart_row_start, chart_row_end + 1):
    for c in range(chart_col_start, chart_col_end + 1):
        virtual_cell_range.append([r, c])

# 2. 构造 rows 中的 virtual 占位 cells
chart_rows = {}
for r in range(chart_row_start, chart_row_end + 1):
    cells = {}
    for c in range(chart_col_start, chart_col_end + 1):
        cells[str(c)] = {"text": " ", "virtual": layer_id}
    chart_rows[str(r)] = {"cells": cells}

# 3. 合并到 all_rows
all_rows.update(chart_rows)

# 4. chartList 配置
chart_item = {
    "row": chart_row_start,
    "col": chart_col_start,
    "colspan": 0,
    "rowspan": 0,
    "width": "500",      # 字符串！
    "height": "350",     # 字符串！
    "config": json.dumps(chart_config, ensure_ascii=False),
    "url": "",
    "extData": {
        "chartType": "bar.simple",
        "dataType": "json",
        "dataId": chart_db_id,
        "dbCode": "stockchart",
        "axisX": "name",
        "axisY": "value",
        "series": "type",
        "xText": "",
        "yText": "",
        "apiStatus": "1"
    },
    "layer_id": layer_id,
    "offsetX": 0,
    "offsetY": 0,
    "backgroud": {"enabled": False, "color": "#fff", "image": ""},
    "virtualCellRange": virtual_cell_range
}