chenx/qhmes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
SCADA系统测试
qhmes/.trae/skills/jimureport/references/components.md

9.4 KiB
Raw Permalink Blame History

报表组件参考

积木报表支持 4 种图层组件（Layer），它们以独立数组存储在 jsonStr 顶层，与 rows/cols 平级。

组件类型总览

组件 jsonStr 字段 类型标识 用途
图片 imgList img 外部图片/Logo/背景图
图表 chartList chart ECharts 可视化图表
条形码 barcodeList barcode CODE128/EAN 等一维码
二维码 qrcodeList qrcode QR Code 二维码

所有组件共享以下基础属性：

{
    "row": 0,           # 起始行号（从0开始）
    "col": 0,           # 起始列号（从0开始）
    "colspan": 0,       # 列跨度
    "rowspan": 0,       # 行跨度
    "width": 300,       # 宽度（像素，图表必须是字符串如"300"）
    "height": 200,      # 高度（像素，图表必须是字符串如"200"）
    "layer_id": "唯一ID",  # 唯一标识，对应 virtual cell
    "offsetX": 0,       # X偏移
    "offsetY": 0,       # Y偏移
    "virtualCellRange": [[row,col], ...]  # 占据的所有单元格坐标
}

1. 图片组件 (imgList)

JSON 结构

img_item = {
    "row": 0,
    "col": 1,
    "colspan": 0,
    "rowspan": 0,
    "width": 315,           # 数字
    "height": 151,          # 数字
    "src": "/jmreport/img/upload/xxx.png",  # 图片路径（相对或绝对）
    "isBackend": False,     # 是否作为前置遮罩
    "isBackendImg": False,  # 是否作为背景图
    "commonBackend": None,  # 共享遮罩/背景属性
    "layer_id": "img_xxx",
    "offsetX": 0,
    "offsetY": 0,
    "virtualCellRange": [[0,1],[0,2],[1,1],[1,2]]
}

图片路径说明

类型 示例
上传图片 /jmreport/img/upload/xxx.png
外部URL https://example.com/logo.png
数据绑定 ${dbCode.imgField} — 字段值为图片URL

2. 图表组件 (chartList)

详见 chart-config.md，这里列出关键结构。

JSON 结构

chart_item = {
    "row": 5,
    "col": 1,
    "colspan": 0,
    "rowspan": 0,
    "width": "650",          # 必须是字符串！
    "height": "350",         # 必须是字符串！
    "config": json.dumps(echarts_option),  # ECharts 配置 JSON 字符串
    "url": "",               # 外部数据 URL（通常为空）
    "extData": {
        "chartType": "bar.simple",  # 图表类型
        "dataType": "sql",          # 数据来源: "sql"/"api"/"json"/"javabean"/"files"
        "dataId": "数据集ID",       # saveDb 返回的 id
        "dbCode": "数据集编码",     # 数据集编码
        "axisX": "name",           # 固定值
        "axisY": "value",          # 固定值
        "series": "type",          # 固定值
        "xText": "",
        "yText": "",
        "apiStatus": "1"
    },
    "layer_id": "chart_xxx",
    "offsetX": 0,
    "offsetY": 0,
    "backgroud": {"enabled": False, "color": "#fff", "image": ""},
    "virtualCellRange": [[5,1],[5,2],...]
}

3. 条形码组件 (barcodeList)

JSON 结构

barcode_item = {
    "row": 3,
    "col": 0,
    "colspan": 0,
    "rowspan": 0,
    "width": 300,
    "height": 200,
    "layer_id": "barcode_xxx",
    "offsetX": 0,
    "offsetY": 0,
    "jsonString": json.dumps({
        "barcodeContent": "jmreport",   # 条码内容（支持 ${dbCode.field} 动态绑定）
        "format": "CODE128",            # 条码格式
        "width": 2,                     # 条线宽度
        "height": 100,                  # 条码高度
        "displayValue": False,          # 是否显示文字
        "text": "jmreport",             # 显示文字内容
        "fontOptions": "",              # 字体选项（bold/italic）
        "font": "monospace",            # 字体
        "textAlign": "center",          # 文字对齐
        "textPosition": "bottom",       # 文字位置
        "textMargin": 2,               # 文字间距
        "fontSize": 20,                # 字体大小
        "background": "#fff",          # 背景色
        "lineColor": "#000",           # 条线颜色
        "margin": 10                   # 边距
    }),
    "virtualCellRange": [[3,0],[3,1],[4,0],[4,1]]
}

支持的条码格式

format 说明
CODE128 Code 128（默认，最常用）
CODE39 Code 39
EAN13 EAN-13
EAN8 EAN-8
UPC UPC-A
ITF14 ITF-14

动态数据绑定

条码内容支持表达式：${dbCode.fieldName}，运行时替换为数据集字段值。

4. 二维码组件 (qrcodeList)

JSON 结构

qrcode_item = {
    "row": 5,
    "col": 0,
    "colspan": 0,
    "rowspan": 0,
    "width": 128,
    "height": 128,
    "layer_id": "qrcode_xxx",
    "offsetX": 0,
    "offsetY": 0,
    "jsonString": json.dumps({
        "text": "http://jimureport.com/",  # 二维码内容（支持 ${dbCode.field}）
        "width": 128,
        "height": 128,
        "colorDark": "#000000",            # 前景色
        "colorLight": "#ffffff"            # 背景色
    }),
    "virtualCellRange": [[5,0],[5,1],[6,0],[6,1]]
}

5. 单元格内嵌组件 (displayConfig)

除了图层组件，单元格本身也可以通过 display 属性渲染为特殊组件：

# 在 rows 的 cell 中设置
cell = {
    "text": "#{dbCode.imgUrl}",
    "display": "img"           # 渲染为图片
}

# 或
cell = {
    "text": "#{dbCode.code}",
    "display": "barcode"       # 渲染为条形码
}

# 或
cell = {
    "text": "#{dbCode.url}",
    "display": "qrcode"        # 渲染为二维码
}

display 可选值：

值 说明
normal 普通文本（默认）
img 图片（text 为图片 URL）
barcode 条形码（text 为条码内容）
qrcode 二维码（text 为二维码内容）
base64Img Base64 图片
richText 富文本/HTML

Virtual Cell 占位规则

所有图层组件都需要在 rows 中声明 virtual 占位：

# 1. 确定组件占据的行列范围
row_start, row_end = 5, 8
col_start, col_end = 1, 4
layer_id = "chart_xxx"

# 2. 构造 virtualCellRange
virtual_cells = []
for r in range(row_start, row_end + 1):
    for c in range(col_start, col_end + 1):
        virtual_cells.append([r, c])

# 3. 在 rows 中添加 virtual 占位
for r in range(row_start, row_end + 1):
    cells = {}
    for c in range(col_start, col_end + 1):
        cells[str(c)] = {"text": " ", "virtual": layer_id}
    rows_data[str(r)] = {"cells": cells}

# 4. 组件中设置 virtualCellRange
component["virtualCellRange"] = virtual_cells

注意事项：

  • virtual 值必须和组件的 layer_id 一致
  • text 必须为 " "（一个空格），不能为空
  • 组件区域不能和数据绑定行重叠
  • 一个组件的 virtual cells 不能和其他组件重叠

Python 构造完整示例

# 构造一个包含 表格 + 柱状图 + 二维码 的报表

layer_chart_id = "chart_" + gen_id()
layer_qr_id = "qrcode_" + gen_id()

rows_data = {
    # 标题行
    "1": {"cells": {"1": {"text": "销售报表", "style": 5}}, "height": 40},
    # 表头
    "2": {"cells": {
        "1": {"text": "产品", "style": 4},
        "2": {"text": "销量", "style": 4},
        "3": {"text": "金额", "style": 4}
    }, "height": 34},
    # 数据行
    "3": {"cells": {
        "1": {"text": "#{ds.name}", "style": 2},
        "2": {"text": "#{ds.qty}", "style": 2},
        "3": {"text": "#{ds.amount}", "style": 2}
    }},
    # 空行
    "4": {"cells": {}, "height": 15},
    "len": 200
}

# 柱状图占位 (row 5-12, col 1-5)
for r in range(5, 13):
    cells = {}
    for c in range(1, 6):
        cells[str(c)] = {"text": " ", "virtual": layer_chart_id}
    rows_data[str(r)] = {"cells": cells}

# 二维码占位 (row 5-8, col 6-7)
for r in range(5, 9):
    cells = rows_data.get(str(r), {"cells": {}})["cells"]
    for c in range(6, 8):
        cells[str(c)] = {"text": " ", "virtual": layer_qr_id}
    rows_data[str(r)] = {"cells": cells}

# 柱状图
chart_config = {
    "title": {"text": "销量统计", "left": "center"},
    "tooltip": {"trigger": "axis"},
    "xAxis": [{"type": "category", "data": []}],
    "yAxis": [{"type": "value"}],
    "series": [{"type": "bar", "data": [], "itemStyle": {"color": "#01b0f1"}}]
}

chart_list = [{
    "row": 5, "col": 1, "colspan": 0, "rowspan": 0,
    "width": "500", "height": "300",
    "config": json.dumps(chart_config, ensure_ascii=False),
    "url": "",
    "extData": {
        "chartType": "bar.simple", "dataType": "sql",
        "dataId": chart_db_id, "dbCode": "saleschart",
        "axisX": "name", "axisY": "value", "series": "type",
        "xText": "", "yText": "", "apiStatus": "1"
    },
    "layer_id": layer_chart_id,
    "offsetX": 0, "offsetY": 0,
    "backgroud": {"enabled": False, "color": "#fff", "image": ""},
    "virtualCellRange": [[r,c] for r in range(5,13) for c in range(1,6)]
}]

# 二维码
qrcode_list = [{
    "row": 5, "col": 6, "colspan": 0, "rowspan": 0,
    "width": 128, "height": 128,
    "layer_id": layer_qr_id,
    "offsetX": 0, "offsetY": 0,
    "jsonString": json.dumps({"text": "https://example.com", "width": 128, "height": 128, "colorDark": "#000000", "colorLight": "#ffffff"}),
    "virtualCellRange": [[r,c] for r in range(5,9) for c in range(6,8)]
}]

# 最终保存数据中包含
save_data = {
    # ... 其他字段
    "chartList": chart_list,
    "qrcodeList": qrcode_list,
    # imgList 和 barcodeList 为空时可省略或传 []
}
Reference in New Issue View Git Blame Copy Permalink