报表基本语法

1 基础语法

1.1 关键字

Magic Script 支持以下关键字：

var if else for in while return exit assert instanceof try catch import as new async true false null

1.2 数据类型

类型	字面量示例	说明
int	123	整型
long	123L	长整型
double	3.14	双精度浮点数
float	3.14f	单精度浮点数
BigDecimal	3.14m	高精度小数
boolean	true / false	布尔
string	'hello' / "hello"	字符串
多行字符串	"""多行文本"""	多行文本块
Pattern	/\d+/g	正则表达式
lambda	(a, b) => a + b	Lambda 函数
list	[1, 2, 3]	列表
map	{key: value}	键值对映射

1.3 变量定义

var name = "张三";
var age = 18;
var list = [1, 2, 3];
var map = {name: "张三", age: 18};

1.4 运算符

算术运算符：+ - * / % ++ -- += -= *= /=

比较运算符：== === != !== < <= > >=

逻辑运算符：&& || !

以下值被视为假值（falsy）：null、空集合、空 Map、空数组、数字 0、false

三元运算符：

var result = score >= 60 ? "及格" : "不及格";

1.5 类型转换

使用 ::type 语法进行显式类型转换：

var a = "123"::int;                       // => 123
var b = "abc"::int(0);                    // 转换失败取默认值 0
var c = "3.14"::double;                   // => 3.14
var d = "2024-01-01"::date('yyyy-MM-dd'); // => Date 对象
var e = 123::string;                      // => "123"

1.6 可选链操作符

使用 ?. 访问可能为 null 的属性，遇到 null 时短路返回 null：

var user = null;
var name = user?.name;         // => null（不报错）
var city = order?.address?.city;

1.7 扩展运算符

// 展开到函数参数
var sum = (a, b, c) => a + b + c;
sum(...[1, 2, 3]);  // => 6

// 合并 Map
var a = {x: 1}; var b = {y: 2};
{...a, ...b};       // => {x: 1, y: 2}

2 流程控制

2.1 条件语句

if (score >= 90) {
    return "优秀";
} else if (score >= 60) {
    return "及格";
} else {
    return "不及格";
}

2.2 for 循环

var list = ["苹果", "香蕉", "橙子"];

// 带索引
for (index, item in list) {
    println(index + ": " + item);
}

// 遍历 Map
for (key, value in {name: "张三", age: 18}) {
    println(key + " = " + value);
}

// 循环指定次数
for (i in range(1, 100)) {
    total = total + i;
}

2.3 while 循环

var count = 10; var sum = 0;
while (count) {
    sum = sum + count;
    count = count - 1;
}

2.4 break / continue

for (item in list) {
    if (item == null) continue;  // 跳过 null
    if (item > 100) break;       // 超过 100 停止
    println(item);
}

2.5 return / exit / assert

// return：正常返回值
return formatDate(now(), "yyyy-MM-dd");

// exit：终止脚本并携带状态码
exit 400, "参数不合法";
exit 200, "成功", {data: result};

// assert：断言，不满足则 exit
assert value != null : 400, "值不能为空";

3 Lambda 表达式

// 单表达式（自动 return）
var double = x => x * 2;

// 多参数
var add = (a, b) => a + b;

// 多行（需写 return）
var check = (score) => {
    if (score >= 60) return "及格";
    return "不及格";
};

// 用于集合操作
var nums = [1, 2, 3, 4, 5];
var evens = nums.filter(x => x % 2 == 0);  // [2, 4]
var doubled = nums.map(x => x * 2);         // [2, 4, 6, 8, 10]

4 导入 Java 类

// 导入静态工具类
import 'java.lang.Math' as Math;
Math.sqrt(16);  // => 4.0

// 从 Spring 容器获取 Bean
import 'javax.sql.DataSource' as ds;

// 创建 Java 对象
import 'java.util.Date' as Date;
var d = new Date();

// 通配符导入（1.3.4+）
import 'java.text.*';
var fmt = new SimpleDateFormat("yyyy-MM-dd");
fmt.format(new Date());

---

6 报表公式实战示例

以下为直接填在单元格里的表达式（无 = 前缀、函数小写）。

序号 / 编号

&A2                                  // 扩展序号 1,2,3...
seq()                                // 全局自增
"NO." + concat("0000", seq()).right(4)  // NO.0001

汇总与占比

sum(B2)                              // 子格 B2 所有扩展行求和（写在合计/父格）
avg(B2)   max(B2)   min(B2)
formatNumber(C2 / sum(C2), "0.00%")  // 当前行占总计的比例

同比 / 环比（cellOffset）

// 环比 =（本期 - 上期）/ 上期；上期取上一行同列
var prev = cellOffset("C2", -1, 0);
isNull(prev) || prev == 0 ? "—" : percent((C2 - prev) / prev, 1)

条件标记 / 状态映射

C2 < 0 ? "▼ " + abs(C2) : "▲ " + C2
$$value == 1 ? "已付款" : ($$value == 2 ? "待付款" : "已取消")

金额大写 / 日期 / 季度

numberToRMB(C2)                          // 金额大写
formatDate($$value, "yyyy年MM月dd日")     // 日期格式化
"第 " + quarter(now()) + " 季度"          // 当前季度

取参数（$参数名）

$dept == null ? "全部" : $dept
formatDate($startDate::date('yyyy-MM-dd'), "yyyy/MM/dd")

函数清单见 函数参考，更多脚本写法见 脚本示例。