表达式与函数
最后更新: 2026/2/27
报表表达式语法和内置函数参考
概述
Magic Report 的表达式引擎基于 Magic Script，支持在单元格中直接编写计算逻辑。语法类似 JavaScript，比 Excel 公式更强大，支持变量、循环、Lambda，并可访问报表数据行和参数。
⚠️ 注意：所有内置函数均为小写，如 sum(B2)、if(x, a, b)、now()，而非 Excel 中的大写形式。
两种表达式形式
| 形式 | 说明 | 示例 |
|---|
| 单行表达式 | 直接写表达式，其值即为单元格显示内容 | sum(B2)、if(A2 > 0, "正", "负") |
| 多行脚本 | 使用 var、if、return 等关键字编写复杂逻辑 | var v = A2 * 1.1; return round(v, 2); |
内置变量
| 变量 | 说明 | 示例 |
|---|
$$value | 当前单元格的原始值，用于格式化表达式或条件渲染中 | $$value > 0 ? "盈利" : "亏损" |
$$record | 当前数据行（Map），可访问任意字段 | $$record.dept_name |
$参数名 | 报表参数（$ 前缀） | $startDate、$dept |
$$config.key | 管理员在「脚本配置」中定义的自定义键值对 | $$config.companyName |
单元格引用
| 写法 | 说明 |
|---|
A1 | 引用单元格 A1 的当前值 |
sum(B2) | B2 所有扩展行的总和 |
avg(B2)、count(B2)、max(B2) | 平均值、计数、最大值 |
sum(B2:B10) | 区域引用求和 |
&A2 | A2 当前扩展迭代的序号（1, 2, 3…） |
父子关系约束：父格表达式中不能引用子格（含 sum(子格)），否则报错。总计行应在报表底部单独一行，并设 enabledParentCellFilter=false。
函数速查
数学与统计
| 函数 | 说明 | 示例 |
|---|
sum(v1, v2, ...) | 求和 | sum(10, 20, 30) → 60 |
avg(v1, v2, ...) | 平均值 | avg(B2) |
max(v1, v2, ...) | 最大值 | max(B2) |
min(v1, v2, ...) | 最小值 | min(B2) |
count(v1, v2, ...) | 计数 | count(B2) |
round(n, digits) | 四舍五入 | round(3.456, 2) → 3.46 |
abs(n) | 绝对值 | abs(-100) → 100 |
percent(n, digits) | 转百分比字符串 | percent(0.856, 1) → "85.6%" |
formatNumber(n, pattern) | 数字格式化 | formatNumber(1234567.89, "#,##0.00") |
字符串
| 函数 | 说明 | 示例 |
|---|
concat(s1, s2, ...) | 拼接（忽略 null） | concat("部门：", dept) |
left(str, n) / right(str, n) | 左/右截取 | left("hello", 3) → "hel" |
length(str) | 字符串长度 | length("hello") → 5 |
upper(str) / lower(str) | 大/小写转换 | upper("hello") → "HELLO" |
trim(str) | 去首尾空格 | |
replace(str, old, new) | 替换（支持正则） | |
numberToRMB(n) | 数字转人民币大写 | numberToRMB(1234.56) |
日期
| 函数 | 说明 | 示例 |
|---|
now() | 当前日期时间 | |
formatDate(d, pattern) | 格式化日期 | formatDate(now(), "yyyy年MM月dd日") |
year(d) / month(d) / day(d) | 提取年/月/日 | year(now()) → 2026 |
addDays(d, n) / addMonths(d, n) | 日期加减 | addDays(now(), -7) → 一周前 |
monthStart() / monthEnd() | 本月第一天/最后一天 | |
betweenDays(d1, d2) | 相差天数 | |
逻辑与空值处理
| 函数 | 说明 | 示例 |
|---|
if(cond, trueVal, falseVal) | 条件判断（函数式，推荐） | if(A1 > 60, "及格", "不及格") |
isNull(v) / isNotNull(v) | null 判断 | |
isEmpty(v) / isNotEmpty(v) | 空值/空集合判断 | |
ifNull(v, default) | 为 null 时返回默认值 | ifNull(remark, "—") |
ifEmpty(v, default) | 为空时返回默认值 | ifEmpty(dept, "未分配") |
joinIfNotEmpty(sep, v1, v2, ...) | 非空值用分隔符拼接 | joinIfNotEmpty(" / ", dept, team) |
报表专属
| 函数 | 说明 |
|---|
seq() | 全局唯一自增序号（1, 2, 3…） |
seq("key") | 分组内自增序号，同一 key 共享计数 |
row() / rows() | 当前行号 / 报表总行数 |
page() / pageCount() | 当前页码 / 总页数 |
dataset(name, field) | 获取指定数据集中某字段的所有值（返回列表） |
相关文档
