329 lines
9.4 KiB
Markdown
329 lines
9.4 KiB
Markdown
# 报表组件参考
|
||
|
||
积木报表支持 4 种图层组件（Layer），它们以独立数组存储在 jsonStr 顶层，与 rows/cols 平级。
|
||
|
||
## 组件类型总览
|
||
|
||
| 组件 | jsonStr 字段 | 类型标识 | 用途 |
|
||
|------|-------------|---------|------|
|
||
| 图片 | `imgList` | `img` | 外部图片/Logo/背景图 |
|
||
| 图表 | `chartList` | `chart` | ECharts 可视化图表 |
|
||
| 条形码 | `barcodeList` | `barcode` | CODE128/EAN 等一维码 |
|
||
| 二维码 | `qrcodeList` | `qrcode` | QR Code 二维码 |
|
||
|
||
所有组件共享以下基础属性：
|
||
|
||
```python
|
||
{
|
||
"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 结构
|
||
|
||
```python
|
||
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 结构
|
||
|
||
```python
|
||
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 结构
|
||
|
||
```python
|
||
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 结构
|
||
|
||
```python
|
||
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` 属性渲染为特殊组件：
|
||
|
||
```python
|
||
# 在 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 占位：
|
||
|
||
```python
|
||
# 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 构造完整示例
|
||
|
||
```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 为空时可省略或传 []
|
||
}
|
||
```
|