日期函数

概述

日期函数分为六组：取当前时间、类型转换与格式化、取日期分量、日期加减、月/季/年的起止、日期差。本篇共 39 个函数。

日期值在表达式里是 Java Date 对象。数据集中的日期、日期时间列传入后即为日期对象；文本形式的日期需要先用 toDate 转换。下文示例中的 toDate(...) 只是为了得到一个确定的日期对象，真实报表里换成单元格或数据集字段引用即可。

所有涉及「年月日」计算的函数使用服务器的默认时区。

功能入口

• 单元格属性面板「数据」标签，内容类型为「公式」时的「内容公式」，点击「编辑」打开「表达式编辑」对话框，在右侧「函数」标签页搜索并插入。
• 报表参数的默认值可选「日期预设」（当天、本月月初、上季度末等），无需手写函数，见 报表参数。

函数列表

分组	函数
当前时间	now、date、time、datetime、timestamp、timestampMillis
转换与格式化	toDate、timestampToDate、dateToNumber、formatDate、formatDateTime、dateFormat
日期分量	year、month、day、week、hour、minute、second、quarter
日期加减	dateOffset、addYears、addMonths、addDays、addHours、addMinutes、addSeconds
起止日期	monthStart、monthEnd、quarterStart、quarterEnd、yearStart、yearEnd
日期差	betweenYears、betweenMonths、betweenDays、betweenDayOfMonth、betweenMonthOfYear、betweenDayOfYear

当前时间

now

语法

now()

无参数。

返回值：Date，当前服务器时间。

示例

formatDate(now(), 'yyyy-MM-dd HH:mm')

结果：当前时间文本，如 "2026-09-29 10:30"

说明

• 与脚本内置的同名函数返回值相同。
• 报表里的「当前时间」在每次求值时取值，不是报表打开时刻固定的值。

date

语法

date()

无参数。

返回值：String，当前日期，格式固定为 yyyy-MM-dd。

示例

date()

结果：如 "2026-09-29"

说明

• 返回的是文本而不是日期对象；需要日期运算时使用 now()。

time

语法

time()

无参数。

返回值：String，当前时间，格式固定为 HH:mm:ss。

示例

time()

结果：如 "10:30:05"

datetime

语法

datetime()

无参数。

返回值：String，当前日期时间，格式固定为 yyyy-MM-dd HH:mm:ss。

示例

datetime()

结果：如 "2026-09-29 10:30:05"

说明

• date、time、datetime 属于报表函数，只在报表表达式环境可用（数据集后处理脚本等非报表渲染环境不保证有）。

timestamp

语法

timestamp()

无参数。

返回值：long，当前时间戳，单位为秒。

示例

timestamp()

结果：如 1790000000

timestampMillis

语法

timestampMillis()

无参数。

返回值：long，当前时间戳，单位为毫秒。

示例

timestampMillis()

结果：如 1790000000000

转换与格式化

toDate

语法

toDate(dateText, format)

参数	类型	必填	说明
dateText	String	是	日期文本；null 或空字符串返回 null
format	String	是	与文本对应的格式，使用 java.time 的格式符，如 yyyy-MM-dd、yyyy-MM-dd HH:mm:ss；为 null 返回 null

返回值：Date。

示例

toDate('2024-01-05', 'yyyy-MM-dd')

结果：2024 年 1 月 5 日 00:00:00 的日期对象

toDate('2024-01-05 08:30:00', 'yyyy-MM-dd HH:mm:ss')

结果：2024 年 1 月 5 日 08:30:00 的日期对象

说明

• format 中不含 HH、mm、ss 时，按日期解析，时间部分为 00:00:00。
• 文本与格式不匹配会报错，而不是返回 null。格式位数要一致：2024-1-5 要用 yyyy-M-d。

timestampToDate

语法

timestampToDate(timestamp)

参数	类型	必填	说明
timestamp	Object	是	毫秒时间戳；null 返回 null

返回值：Date。

示例

timestampToDate(1700000000000L)

结果：2023-11-14 22:13:20 UTC，即东八区 2023-11-15 06:13:20 的日期对象

说明

• 13 位毫秒数超过 int 范围，直接写数字字面量时必须加 L 后缀（1700000000000L），否则报「定义int变量值不合法」；来自单元格或数据集的值不受此限。
• 参数单位是毫秒。传入 10 位的秒级时间戳（如 1700000000）会得到 1970 年 1 月的日期；秒级时间戳请先乘以 1000。

dateToNumber

语法

dateToNumber(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 返回 null

返回值：Long，自 1970-01-01 00:00:00 UTC 起的毫秒数。

示例

(dateToNumber(toDate('2024-01-11', 'yyyy-MM-dd')) - dateToNumber(toDate('2024-01-01', 'yyyy-MM-dd'))) / 86400000

结果：10（相差天数）

说明

• 直接求相差的完整天数可用 betweenDays。

formatDate

语法

formatDate(value)
formatDate(value, pattern)
formatDate(value, pattern, locale)

参数	类型	必填	说明
value	Object	是	日期对象（Date、LocalDate、LocalTime、LocalDateTime）；null 返回 null
pattern	String	否	格式模式，如 yyyy-MM-dd HH:mm:ss；省略时为 yyyy-MM-dd；null 返回 null
locale	String	否	区域，写成 语言:国家，如 zh:CN、en:US

返回值：String。

示例

formatDate(toDate('2024-01-05', 'yyyy-MM-dd'), 'yyyy/MM/dd')

结果："2024/01/05"

formatDate(toDate('2024-01-05', 'yyyy-MM-dd'))

结果："2024-01-05"

formatDate(toDate('2024-01-05', 'yyyy-MM-dd'), 'EEEE', 'zh:CN')

结果："星期五"

说明

• value 是空字符串时返回空字符串；value 不是日期类型（例如文本 "2024-01-05"）时原样返回其文本，不会重新格式化。文本日期请先 toDate。
• locale 用冒号分隔语言与国家（zh:CN），写成 zh_CN 不会被识别为国家。
• pattern 为空字符串会报错「日期格式的格式不能为空！」。

formatDateTime

语法

formatDateTime(value)

参数	类型	必填	说明
value	Object	是	日期对象；null 返回 null

返回值：String，格式固定为 yyyy-MM-dd HH:mm:ss。

示例

formatDateTime(toDate('2024-01-05', 'yyyy-MM-dd'))

结果："2024-01-05 00:00:00"

说明

• 等价于 formatDate(value, 'yyyy-MM-dd HH:mm:ss')。

dateFormat

语法

dateFormat(date)
dateFormat(date, pattern)

参数	类型	必填	说明
date	Date 或 TemporalAccessor	是	日期对象；null 返回 null
pattern	String	否	格式模式；对 Date 省略时为 yyyy-MM-dd HH:mm:ss；参数是 LocalDate 等 java.time 对象时必须提供

返回值：String。

示例

dateFormat(now(), 'yyyy-MM-dd')

结果：当前日期文本，如 "2026-09-29"

说明

• 与 formatDate 的差别：dateFormat 只接受日期对象，不做文本原样返回；没有区域参数。日常使用推荐 formatDate。

日期分量

以下 8 个函数的参数都是 Date。参数为 null 时按当前时间计算，而不是返回 null；日期字段可能为空的地方请先判空。

year

语法

year(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

year(toDate('2024-03-15', 'yyyy-MM-dd'))

结果：2024

month

语法

month(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

month(toDate('2024-03-15', 'yyyy-MM-dd'))

结果：3

说明

• 范围 1 至 12。

day

语法

day(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

day(toDate('2024-03-15', 'yyyy-MM-dd'))

结果：15

week

语法

week(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

week(toDate('2024-03-15', 'yyyy-MM-dd'))

结果：6（星期五）

说明

• 取值 1 至 7，1 表示星期日，2 为星期一，7 为星期六。

hour

语法

hour(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

hour(toDate('2024-03-15 14:25:36', 'yyyy-MM-dd HH:mm:ss'))

结果：14

minute

语法

minute(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

minute(toDate('2024-03-15 14:25:36', 'yyyy-MM-dd HH:mm:ss'))

结果：25

second

语法

second(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

second(toDate('2024-03-15 14:25:36', 'yyyy-MM-dd HH:mm:ss'))

结果：36

quarter

语法

quarter(date)

参数	类型	必填	说明
date	Date	是	日期对象；null 时使用当前时间

返回值：Integer

示例

quarter(toDate('2024-03-15', 'yyyy-MM-dd'))

结果：1

说明

• 取值 1 至 4，按 1-3 月为第 1 季度划分。

日期加减

dateOffset

语法

dateOffset(date, offset, unit)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null
unit	String	是	单位：year 或 年、month 或 月、day 或 天、hh 或 时、mm 或 分、ss 或 秒

返回值：Date。

示例

formatDate(dateOffset(toDate('2024-01-31', 'yyyy-MM-dd'), 1, 'month'), 'yyyy-MM-dd')

结果："2024-02-29"

说明

• 英文单位不区分大小写；中文单位需写成上表的单字。
• unit 不是上表中的任何一个时，不做加减，原样返回 date。
• offset 必须是整数：BigDecimal 会先四舍五入取整；其他类型按文本转整数，1.5 这样的 Double 会报错。
• 月份加减遇到目标月天数不足时落到该月最后一天（如 1 月 31 日加 1 个月得 2 月 29 日或 28 日）。

addYears

语法

addYears(date, offset)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null；须为整数

返回值：Date。

示例

formatDate(addYears(toDate('2024-02-29', 'yyyy-MM-dd'), 1), 'yyyy-MM-dd')

结果："2025-02-28"

说明

• 等价于 dateOffset(date, offset, 'year')。

addMonths

语法

addMonths(date, offset)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null；须为整数

返回值：Date。

示例

formatDate(addMonths(toDate('2024-03-15', 'yyyy-MM-dd'), -2), 'yyyy-MM-dd')

结果："2024-01-15"

说明

• 等价于 dateOffset(date, offset, 'month')。

addDays

语法

addDays(date, offset)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null；须为整数

返回值：Date。

示例

formatDate(addDays(toDate('2024-03-15', 'yyyy-MM-dd'), 30), 'yyyy-MM-dd')

结果："2024-04-14"

说明

• 等价于 dateOffset(date, offset, 'day')。

addHours

语法

addHours(date, offset)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null；须为整数

返回值：Date。

示例

formatDateTime(addHours(toDate('2024-03-15 23:00:00', 'yyyy-MM-dd HH:mm:ss'), 2))

结果："2024-03-16 01:00:00"

说明

• 等价于 dateOffset(date, offset, 'hh')。

addMinutes

语法

addMinutes(date, offset)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null；须为整数

返回值：Date。

示例

formatDateTime(addMinutes(toDate('2024-03-15 10:00:00', 'yyyy-MM-dd HH:mm:ss'), 90))

结果："2024-03-15 11:30:00"

说明

• 等价于 dateOffset(date, offset, 'mm')。

addSeconds

语法

addSeconds(date, offset)

参数	类型	必填	说明
date	Date	是	起始日期；null 返回 null
offset	Object	是	增减量，正数加、负数减；null 返回 null；须为整数

返回值：Date。

示例

formatDateTime(addSeconds(toDate('2024-03-15 10:00:00', 'yyyy-MM-dd HH:mm:ss'), -1))

结果："2024-03-15 09:59:59"

说明

• 等价于 dateOffset(date, offset, 'ss')。

月、季、年的起止

以下 6 个函数都有两种写法：只传日期时返回 Date（起始为当天 00:00:00.000，结束为 23:59:59.999）；再传一个格式模式时直接返回格式化后的文本。参数为 null 时使用当前日期，参数不是 Date 类型时会尝试按文本自动识别日期。

monthStart

语法

monthStart(date)
monthStart(date, format)

参数	类型	必填	说明
date	Object	是	日期对象，也可以是可识别的日期文本；null 使用当前日期
format	String	否	格式模式，如 yyyy-MM-dd；提供后返回文本

返回值：Date（不带 format）或 String（带 format）。

示例

monthStart(toDate('2024-02-10', 'yyyy-MM-dd'), 'yyyy-MM-dd')

结果："2024-02-01"

说明

• 所在月第一天 00:00:00.000。

monthEnd

语法

monthEnd(date)
monthEnd(date, format)

参数	类型	必填	说明
date	Object	是	日期对象，也可以是可识别的日期文本；null 使用当前日期
format	String	否	格式模式，如 yyyy-MM-dd；提供后返回文本

返回值：Date（不带 format）或 String（带 format）。

示例

monthEnd(toDate('2024-02-10', 'yyyy-MM-dd'), 'yyyy-MM-dd')

结果："2024-02-29"

说明

• 所在月最后一天 23:59:59.999。

quarterStart

语法

quarterStart(date)
quarterStart(date, format)

参数	类型	必填	说明
date	Object	是	日期对象，也可以是可识别的日期文本；null 使用当前日期
format	String	否	格式模式，如 yyyy-MM-dd；提供后返回文本

返回值：Date（不带 format）或 String（带 format）。

示例

quarterStart(toDate('2024-05-20', 'yyyy-MM-dd'), 'yyyy-MM-dd')

结果："2024-04-01"

说明

• 所在季度第一天 00:00:00.000。

quarterEnd

语法

quarterEnd(date)
quarterEnd(date, format)

参数	类型	必填	说明
date	Object	是	日期对象，也可以是可识别的日期文本；null 使用当前日期
format	String	否	格式模式，如 yyyy-MM-dd；提供后返回文本

返回值：Date（不带 format）或 String（带 format）。

示例

quarterEnd(toDate('2024-05-20', 'yyyy-MM-dd'), 'yyyy-MM-dd')

结果："2024-06-30"

说明

• 所在季度最后一天 23:59:59.999。

yearStart

语法

yearStart(date)
yearStart(date, format)

参数	类型	必填	说明
date	Object	是	日期对象，也可以是可识别的日期文本；null 使用当前日期
format	String	否	格式模式，如 yyyy-MM-dd；提供后返回文本

返回值：Date（不带 format）或 String（带 format）。

示例

yearStart(toDate('2024-05-20', 'yyyy-MM-dd'), 'yyyy-MM-dd')

结果："2024-01-01"

说明

• 所在年第一天 00:00:00.000。

yearEnd

语法

yearEnd(date)
yearEnd(date, format)

参数	类型	必填	说明
date	Object	是	日期对象，也可以是可识别的日期文本；null 使用当前日期
format	String	否	格式模式，如 yyyy-MM-dd；提供后返回文本

返回值：Date（不带 format）或 String（带 format）。

示例

yearEnd(toDate('2024-05-20', 'yyyy-MM-dd'), 'yyyy-MM-dd')

结果："2024-12-31"

说明

• 所在年最后一天 23:59:59.999。

日期差

以下 6 个函数的两个参数都是 Date，任一为 null 时返回 null，结果不分先后（总是非负数）。

betweenYears

语法

betweenYears(date1, date2)

参数	类型	必填	说明
date1	Date	是	第一个日期
date2	Date	是	第二个日期

返回值：Long，相差的完整年数。

示例

betweenYears(toDate('2020-06-01', 'yyyy-MM-dd'), toDate('2024-06-01', 'yyyy-MM-dd'))

结果：4

说明

• 只计满一整年的部分；不满一年的舍去。

betweenMonths

语法

betweenMonths(date1, date2)

参数	类型	必填	说明
date1	Date	是	第一个日期
date2	Date	是	第二个日期

返回值：Long，相差的完整月数。

示例

betweenMonths(toDate('2024-01-15', 'yyyy-MM-dd'), toDate('2024-03-15', 'yyyy-MM-dd'))

结果：2

说明

• 只计满一整月的部分；如 1 月 15 日到 3 月 14 日为 1。

betweenDays

语法

betweenDays(date1, date2)

参数	类型	必填	说明
date1	Date	是	第一个日期
date2	Date	是	第二个日期

返回值：Long，相差的完整天数。

示例

betweenDays(toDate('2024-01-01', 'yyyy-MM-dd'), toDate('2024-03-01', 'yyyy-MM-dd'))

结果：60

说明

• 计算年龄可用 betweenYears(出生日期, now())。

betweenDayOfMonth

语法

betweenDayOfMonth(date1, date2)

参数	类型	必填	说明
date1	Date	是	第一个日期
date2	Date	是	第二个日期

返回值：Integer，两个日期「当月第几天」之差的绝对值。

示例

betweenDayOfMonth(toDate('2024-01-05', 'yyyy-MM-dd'), toDate('2024-03-20', 'yyyy-MM-dd'))

结果：15

说明

• 只比较日分量，不考虑年月；要相差天数请用 betweenDays。

betweenMonthOfYear

语法

betweenMonthOfYear(date1, date2)

参数	类型	必填	说明
date1	Date	是	第一个日期
date2	Date	是	第二个日期

返回值：Integer，两个日期「月份」之差的绝对值。

示例

betweenMonthOfYear(toDate('2024-01-10', 'yyyy-MM-dd'), toDate('2024-04-20', 'yyyy-MM-dd'))

结果：3

说明

• 只比较月分量，不考虑年份；如 2023 年 11 月与 2024 年 2 月得 9，要相差月数请用 betweenMonths。

betweenDayOfYear

语法

betweenDayOfYear(date1, date2)

参数	类型	必填	说明
date1	Date	是	第一个日期
date2	Date	是	第二个日期

返回值：Integer，两个日期「当年第几天」之差的绝对值。

示例

betweenDayOfYear(toDate('2024-01-10', 'yyyy-MM-dd'), toDate('2024-03-01', 'yyyy-MM-dd'))

结果：51

说明

• 只比较年内序号，不考虑年份；要相差天数请用 betweenDays。

注意事项

注意：year、month、day、week、hour、minute、second、quarter 收到 null 时返回当前时间的对应分量，不返回 null。日期字段可能为空时，先用 isNull 判断。

注意：formatDate 遇到文本形式的日期会原样返回文本；year 等分量函数的参数类型是 Date。文本日期一律先经 toDate(文本, 格式) 转换。

提示：timestampToDate 的参数是毫秒，秒级时间戳需乘以 1000。

相关文档

• 函数参考
• 逻辑与空值函数
• 数学函数
• 报表参数
• 报表基本语法