qhmes/.trae/skills/jimureport/references/constraints.md

积木报表重要约束

1. 数据集编码 db_code 不能重复且只支持英文字符 — 同一个报表内的多个数据集，每个的 db_code 必须唯一。编码只能使用英文字母、数字和下划线，不能包含中文或特殊字符。重复会导致数据覆盖或查询异常。
2. is_page 分页只能有一个 — 一个报表中只能有一个数据集设置 is_page=1（启用分页），其余数据集必须为 is_page=0。多个数据集同时分页会导致分页冲突。

数据绑定语法

语法	说明	场景
${db.field}	单值绑定	主表字段、固定值
#{db.field}	列表绑定	明细行、循环数据
#{db.group(field)}	纵向分组	按字段分组汇总
#{db.groupRight(field)}	横向分组	按字段横向展开
#{db.dynamic(field)}	动态聚合	交叉表数据
#{db.customGroup(field)}	自定义分组	横向自定义展开
=SUM(D7)	Excel 公式	列汇总

单元格属性

属性	说明	值
merge	合并	[行数,列数]，如 [0,2] 向右合并2列
style	样式索引	引用 styles 数组下标
loopBlock	循环块标记	1=属于循环块
zonedEdition	分版标记	1/2/... 分版编号
fixedHead	固定表头	1=固定
fixedTail	固定表尾	1=固定
aggregate	聚合类型	见下方分组配置
subtotal	小计配置	见下方分组配置
funcname	聚合函数	见下方分组配置
subtotalText	小计行文本	"合计" / "小计"
direction	展开方向	见下方分组配置
sort	排序	见下方分组配置
rendered	渲染标记	""
config	配置标记	""
decimalPlaces	小数位	"0"/"1"/"4"
display	显示格式	见下方 display 值表
fillForm	填报组件	组件配置对象

分组相关配置

aggregate 聚合方式（polyWayList）

值	说明
select	列表（普通列，不分组）
group	分组（相同值合并单元格）

subtotal 是否启用小计

值	说明
"-1"	否（不显示小计行）
"groupField"	是（分组切换时显示小计/合计行）

funcname 聚合函数（aggregateList）

值	说明	用于
"-1"	无（不计算，仅显示 subtotalText 文本）	分组字段（地区、销售员等）
"SUM"	求和	数值字段（金额、数量等）
"MAX"	最大值	数值字段
"MIN"	最小值	数值字段
"AVERAGE"	平均值	数值字段
"COUNT"	计数	任意字段

direction 展开方向（directionList）

值	说明
"down"	纵向（默认）
"right"	横向

sort 排序（sortType）

值	说明
"default"	默认（不排序）
"asc"	正序
"desc"	倒序

aggregate 高级模式（advancedList）

值	说明
"default"	普通属性
"dynamic"	动态属性（交叉表）

分组单元格配置示例

分组字段（地区，一级分组 — 合计）：

{
    "text": "#{sales.group(region)}",
    "style": 4,
    "aggregate": "group",
    "subtotal": "groupField",
    "funcname": "-1",
    "subtotalText": "合计",
    "rendered": "",
    "config": ""
}

分组字段（销售员，二级分组 — 小计）：

{
    "text": "#{sales.group(salesman)}",
    "style": 4,
    "aggregate": "group",
    "subtotal": "groupField",
    "funcname": "-1",
    "subtotalText": "小计"
}

数值字段（销售额，小计/合计行自动求和）：

{
    "text": "#{sales.amount}",
    "style": 4,
    "funcname": "SUM",
    "subtotal": "-1",
    "display": "number",
    "rendered": "",
    "config": ""
}

注意： 数值字段的 subtotal 为 "-1"（不是 "groupField"），funcname 为 "SUM"。含义是：该字段不触发分组切换，但在分组切换产生的小计/合计行中自动按 SUM 聚合。

display 显示格式（JmConst.CELL_FORMAT_*）

display 值	说明	示例
normal	默认文本	—
number	数值（数值类型字段默认）	58000
percent	百分比	85%
rmb	人民币	¥58,000.00
usd	美元	$58,000.00
eur	欧元	€58,000.00
date	日期	2026-03-20
date2	日期(斜杠)	2026/03/20
time	时间	12:30:00
datetime	日期时间	2026-03-20 12:30:00
year	年	2026
month	月	03
base64Img	Base64图片	—
img	图片	—
qrcode	二维码	—
barcode	条形码	—
richText	富文本	—

顶层配置

字段	说明
loopBlockList	循环块定义（含 loopTime 分栏次数）
zonedEditionList	分版区域定义
fixedPrintHeadRows	固定打印表头
fixedPrintTailRows	固定打印表尾
groupField	分组字段
isGroup	是否启用分组
submitHandlers	填报提交处理器
background	背景图配置
imgList	图片列表
displayConfig	二维码/条码显示配置
dicts	引用的字典编码列表
printConfig	打印配置（纸张/方向/边距）
merges	合并单元格列表（如 "B1:H1")