函数参考

最后更新: 2026/6/17

Sight Report 内置全局函数速查：数学、字符串、日期、工具及报表专属函数

所有内置函数均可在表达式中直接调用，无需任何前缀。

5.1 数学函数

函数	说明	示例
`round(n, digits?)`	四舍五入，默认 0 位	`round(3.456, 2)` → `3.46`
`ceil(n)`	向上取整	`ceil(3.1)` → `4`
`floor(n)`	向下取整	`floor(3.9)` → `3`
`abs(n)`	绝对值	`abs(-5)` → `5`
`pow(n, e)`	指数运算	`pow(2, 10)` → `1024`
`log(n, base)`	对数	`log(100, 10)` → `2`
`percent(n, digits?)`	转百分比字符串	`percent(0.856, 1)` → `"85.6%"`
`formatNumber(value, fmt)`	格式化数字	`formatNumber(1234567.89, "#,##0.00")` → `"1,234,567.89"`
`sum(v1, v2, ...)`	多参数求和	`sum(10, 20, 30)` → `60`
`avg(v1, v2, ...)`	多参数平均值	`avg(10, 20, 30)` → `20`
`max(v1, v2, ...)`	多参数最大值	`max(3, 1, 4, 1, 5)` → `5`
`min(v1, v2, ...)`	多参数最小值	`min(3, 1, 4, 1, 5)` → `1`
`count(v1, v2, ...)`	参数个数（含 null）	`count(1, null, 3)` → `3`

5.2 字符串函数

函数	说明	示例
`concat(s1, s2, ...)`	拼接（忽略 null）	`concat("Hello", " World")` → `"Hello World"`
`upper(str)`	转大写	`upper("hello")` → `"HELLO"`
`lower(str)`	转小写	`lower("HELLO")` → `"hello"`
`trim(str)`	去两端空格	`trim(" hi ")` → `"hi"`
`length(str)`	字符串长度	`length("hello")` → `5`
`substring(str, start, end?)`	截取子串	`substring("hello", 1, 3)` → `"el"`
`left(str, n)`	左起截取 n 位	`left("hello", 3)` → `"hel"`
`right(str, n)`	右起截取 n 位	`right("hello", 3)` → `"llo"`
`replace(str, old, new)`	替换（支持正则）	`replace("a1b2", "\\d", "X")` → `"aXbX"`
`indexOf(str, find)`	查找位置（-1=未找到）	`indexOf("hello", "ll")` → `2`
`contains(str, sub)`	是否包含子串	`contains("hello", "ell")` → `true`
`startsWith(str, prefix)`	是否以前缀开头	`startsWith("hello", "he")` → `true`
`endsWith(str, suffix)`	是否以后缀结尾	`endsWith("hello", "lo")` → `true`
`isBlank(str)`	是否为空白字符串	`isBlank(" ")` → `true`
`isNotBlank(str)`	是否不为空白	`isNotBlank("hi")` → `true`
`numberToRMB(n)`	数字转人民币大写	`numberToRMB(1234.56)` → `"壹仟贰佰叁拾肆圆伍角陆分"`

5.3 日期函数

获取日期

函数	说明	示例
`now()`	当前日期时间（Date 对象）	`now()`
`date()`	当前日期 yyyy-MM-dd	`date()` → `"2024-03-15"`
`time()`	当前时间 HH:mm:ss	`time()` → `"14:30:00"`
`toDate(str, fmt)`	字符串解析为 Date	`toDate("2024-03-15", "yyyy-MM-dd")`

格式化日期

函数	说明	示例
`formatDate(val)`	格式化为 yyyy-MM-dd	`formatDate(now())`
`formatDate(val, pattern)`	自定义格式	`formatDate(now(), "yyyy年MM月dd日")`
`formatDateTime(val)`	格式化为 yyyy-MM-dd HH:mm:ss	`formatDateTime(now())`

提取日期分量

函数	说明
`year(date?)`	年份
`month(date?)`	月份（1~12）
`day(date?)`	日（1~31）
`hour(date?)`	小时（0~23）
`minute(date?)`	分钟（0~59）
`second(date?)`	秒（0~59）

日期运算

函数	说明	示例
`addDays(date, n)`	增减天数	`addDays(now(), 7)` → 一周后
`addMonths(date, n)`	增减月数	`addMonths(now(), -3)` → 三个月前
`addYears(date, n)`	增减年数	`addYears(now(), 1)` → 一年后
`monthStart(date?)`	月初（00:00:00）	`monthStart()`
`monthEnd(date?)`	月末（23:59:59.999）	`monthEnd()`
`yearStart(date?)`	年初（1月1日 00:00:00）	`yearStart()`
`yearEnd(date?)`	年末（12月31日 23:59:59）	`yearEnd()`
`betweenDays(d1, d2)`	相差完整天数	`betweenDays(d1, d2)` → `1920L`
`betweenMonths(d1, d2)`	相差完整月数	`betweenMonths(d1, d2)`
`betweenYears(d1, d2)`	相差完整年数	`betweenYears(d1, d2)`

5.4 工具函数

函数	说明	示例
`isNull(v)`	是否为 null	`isNull(null)` → `true`
`isNotNull(v)`	是否不为 null	`isNotNull("")` → `true`
`isEmpty(v)`	是否为空（null/空字符串/空集合）	`isEmpty([])` → `true`
`isNotEmpty(v)`	是否不为空	`isNotEmpty("a")` → `true`
`ifNull(v, default)`	为 null 时返回默认值	`ifNull(null, "N/A")` → `"N/A"`
`ifEmpty(v, default)`	为空时返回默认值	`ifEmpty("", "默认")` → `"默认"`
`joinIfNotEmpty(sep, v1, v2, ...)`	非空值用分隔符拼接	`joinIfNotEmpty("-", "a", null, "b")` → `"a-b"`
`uuid()`	生成 UUID 字符串	`uuid()`
`range(from, to)`	生成整数区间迭代器（含两端）	`range(1, 5)` → `[1,2,3,4,5]`
`userAccount()`	当前登录用户账号	`userAccount()` → `"admin"`
`username()`	当前登录用户姓名	`username()` → `"管理员"`
`println(v)`	向控制台打印（调试用）	`println("debug: " + value)`

5.5 报表专属函数

以下函数仅在报表表达式上下文中可用（依赖报表运行时）：

位置信息

函数	说明
`row()`	当前单元格的行号（从 1 开始）
`rows()`	报表计算后的总行数
`column()`	当前单元格的列号（从 1 开始）
`columns()`	报表计算后的总列数

分页信息

函数	说明
`page()`	当前页码（从 1 开始）
`pageCount()`	分页后总页数

序列与计数

函数	说明	示例
`seq()`	全局唯一自增序号	`seq()` → `1, 2, 3...`
`seq(key)`	同一 key 共享的自增序号	`seq("group1")`

数据集访问

函数	说明	示例
`dataset(name)`	获取指定数据集（返回列表）	`dataset("ds1")`
`dataset(name, field)`	获取数据集中某字段的所有值	`dataset("ds1", "amount")`

// 示例：对数据集中某字段求和
var amounts = dataset("sales", "amount");
sum(...amounts)

// 示例：获取完整数据集并过滤
var rows = dataset("employees");
rows.filter(r => r.dept == "技术部").map(r => r.name).join("、")

5.6 季度与高级日期函数（补充）

函数	说明	示例
`quarter(date?)`	季度（1~4）	`quarter(toDate("2026-05-15","yyyy-MM-dd"))` → 2
`quarterStart(date?)`	季度第一天 00:00:00	`quarterStart(...05-15)` → 2026-04-01
`quarterEnd(date?)`	季度最后一天 23:59:59	`quarterEnd(...05-15)` → 2026-06-30
`week(date?)`	星期几（1=周日 … 7=周六）	`week(now())`
`datetime()`	当前日期时间 yyyy-MM-dd HH:mm:ss	`datetime()` → "2026-06-17 14:30:00"
`addHours/addMinutes/addSeconds(date, n)`	增减时 / 分 / 秒	`addHours(now(), -2)`
`dateOffset(date, n, unit)`	通用增减；unit：`year/年`、`month/月`、`day/天`、`hh/时`、`mm/分`、`ss/秒`	`dateOffset(now(), -7, "day")` → 一周前
`timestampToDate(ts)`	时间戳转 Date	`timestampToDate(1700000000000)`

5.7 中文 / 金额大写

函数	说明	示例
`toChinese(n)`	数字转中文	`toChinese(123)` → "一百二十三"
`toChineseAmount(n)`	数字转中文大写金额	`toChineseAmount(123.45)` → "壹佰贰拾叁元肆角伍分"
`numberToRMB(n)`	转人民币大写（圆角分）	`numberToRMB(12345.67)` → "壹万贰仟叁佰肆拾伍圆陆角柒分"

5.8 更多工具函数

函数	说明	示例
`coalesce(v1, v2, ...)`	返回第一个非 null 的值	`coalesce(null, "", "默认")` → ""
`find(str, sub)`	查找位置（字符串 / 集合，-1=未找到）	`find("hello", "ll")` → 2

5.9 报表专属函数（补充）

函数	说明	示例
`cellOffset(cellName, rowOffset, colOffset)`	按相对行列偏移取目标格的值（负数向上 / 向左），常用于同比环比	`cellOffset("C2", -1, 0)` → 上一行 C 列值
`rawDataset(name)` / `rawDataset(name, field)`	取数据集原始完整结果（不受当前行扩展过滤影响）	`rawDataset("sales", "amount")`
`fileName()` / `fileId()`	当前报表模板名称 / ID	`fileName()`

以上函数均依据后端源码核对（DateFunctions / StringFunctions / OtherFunctions / ReportFunctions）。

5.10 集合 / LINQ 操作

集合（数组、dataset() 返回的结果）支持链式方法，适合在脚本或数据集表达式中加工数据：

方法	说明	示例
`.map(fn)`	转换	`list.map(r => r.name)`
`.filter(fn)`	过滤	`list.filter(r => r.amount > 0)`
`.find(fn)` / `.findIndex(fn)`	查找元素 / 索引	`list.find(r => r.id == 1)`
`.sort(fn)`	排序（`(a,b)=>a-b` 升序）	`list.sort((a,b) => b.amount - a.amount)`
`.distinct()` / `.distinct(fn)`	去重 / 按键去重	`list.distinct(r => r.dept)`
`.group(keyFn)`	分组为 Map	`list.group(r => r.dept)`
`.group(keyFn, listFn)`	分组并聚合	`list.group(r => r.dept, g => g.sum())`
`.sum() .avg() .max() .min()`	集合聚合（空集合返回 null）	`list.map(r => r.amount).sum()`
`.join(sep?)`	拼接为字符串	`list.join("、")`
`.concat(other)`	合并集合	`a.concat(b)`
`.toMap(keyFn, valFn?)`	转 Map	`list.toMap(r => r.id, r => r.name)`
`.each(fn)`	遍历	`list.each(r => println(r))`
`.reserve() .shuffle() .push(item)`	反转 / 打乱 / 追加	`list.reserve()`

组合示例：

// 各部门金额合计（Map：部门 → 合计）
dataset("sales").group(r => r.dept, g => g.map(x => x.amount).sum())

// 去重部门名，顿号连接
dataset("sales").map(r => r.dept).distinct().join("、")

// 按金额降序取名称（配合取前 N）
dataset("sales").sort((a,b) => b.amount - a.amount).map(r => r.name)

以上方法依据 magic-script StreamExtension 源码核对，均为集合的链式（后缀）调用。

函数参考

5.1 数学函数

5.2 字符串函数

5.3 日期函数

获取日期

格式化日期

提取日期分量

日期运算

5.4 工具函数

5.5 报表专属函数

位置信息

分页信息

序列与计数

数据集访问

5.6 季度与高级日期函数（补充）

5.7 中文 / 金额大写

5.8 更多工具函数

5.9 报表专属函数（补充）

5.10 集合 / LINQ 操作

留言已发送！