日期函数简介

• 日期时间字段 的返回值为时间戳（timestamp），单位是毫秒；本文中的日期函数的参数均可直接使用日期字段。如，YEAR(日期时间字段)。
• 下面介绍关于日期函数的两个基本概念：
• 时间戳（timestamp）：时间戳是计算机记录时间的一种格式。通常是一个字符序列，唯一地标识某一刻的时间。在搭贝表单中，「日期时间」字段便是由这样的序列来存储的。
• 日期对象：可以理解为年月日时分秒；日期对象的格式为 Sat Aug 01 2015 00:00:00 GMT+0800，即北京时间 2015 年 8 月 1 日 00:00:00，日期对象可以进行各种运算，比如日期加减法等等。

DATE

• DATE 函数可用于将时间戳转换为日期对象。
• 函数用法：
• DATE(timestamp)
• 通过以下公式可将年月日（时分秒）转换为日期对象：
• DATE(year,month,day)
• DATE(year,month,day,hour,minute,second)
• 其中各参数的含义如下：
• 函数示例：如 2023 年 1 月 1 日的日期对象可以用如下公式表示：
• 这三个公式都表示“Sun Jan 01 2023 00:00:00 GMT+0800”。

DAY

• DAY 函数可用于返回日期中的天数， 值是介于 1 到 31 之间的整数。
• 函数用法：
• DAY(timestamp)
• 函数示例：如计算签到日期中对应的天数，可设置公式为DAY(签到日期)，即 2023-01-20 对应的天数为 20。

DAYS

• DAYS 函数可计算两个日期之间的天数。
• 函数用法：
• DAYS(end_timestamp, start_timestamp)
• 其中各参数的含义如下：
• 函数示例：如考勤请假场景中，手动输入请假开始、结束日期，设置公式为DAYS(结束日期,开始日期)，即可计算出请假天数。

DAYS360

• 用法：DAYS360(end_timestamp, start_timestamp, method)
• 说明：按照一年 360 天的算法（每个月以 30 天计，一年共计 12 个月），DAYS360 函数返回两个日期间相差的天数，这在一些会计计算中将会用到。如果财会系统是基于一年 12 个月，每月 30 天，可使用此函数帮助计算支付款项。
• end_timestamp: 必需。结束日期。
• start_timestamp: 必需。起始日期。
• method: 可选。用于指定在计算中是采用美国方法还是欧洲方法。不填或false表示是美国方法，true表示是欧洲方法。
• 注意：1、使用美国方法时，如果起始日期是一个月的第 31 天，则将这一天与同一个月份的第 30 天视为同一天；如果起始日期早于一个月的第 30 天，且终止日期是一个月的第 31 天，则将终止日期视同于下一个月的第 1 天；如果起始日期为一个月的第 30 天，且终止日期是一个月的第 31 天，则将终止日期视同于终止日期所在月的第 30 天。2、使用欧洲方法时，起始日期或终止日期是一个月的第 31 天时，都将其视同于当月的第 30 天。

DATEDIF

• DATEDIF 函数可用于计算两个时间的差值。
• 函数用法：
• DATEDIF(start_timestamp, end_timestamp, [unit])
• 其中各参数的含义如下：
• start_timestamp 必需。一个代表开始时间的日期。
• end_timestamp 必需。一个代表结束时间的日期。
• unit 可选。一个可选参数，默认为 “d”，可以是 “y” 、“M”、“d”、“MD”、“YD”、“YM”，分别代表计算两个日期相差的年数、月数、天数、间隔天数（忽略日期中的月份和年份）、间隔天数（忽略日期中的年份）、间隔月数（忽略日期中的年份）。
• 函数示例：通过 DATEDIF 函数计算时间差的年数、月数、天数等，可应用于计算项目的消耗天数、活动的举办天数等。

HOUR

• HOUR 函数可用于返回日期时间中的小时数。
• 函数用法：
• HOUR(timestamp)
• 函数示例：如计算打卡时间中对应的小时数，可设置公式为HOUR(打卡时间)，即 2023-01-01 14:38:01 对应的小时数为 14。

MINUTE

• MINUTE 函数可用于返回日期时间中的分钟数。
• 函数用法：
• MINUTE(timestamp)
• 函数示例：如计算打卡时间中对应的分钟数，可设置公式为MINUTE(打卡时间)，即 2023-01-05 16:14:24 对应的分钟数为 14。

MONTH

• MONTH 函数可用于返回日期中的月份， 值是介于 1 到 12 之间的整数。
• 函数用法：
• MONTH(timestamp)
• 函数示例：如计算考勤日期对应的月份，可设置公式为MONTH(考勤时间)，即 2023-01-02 对应的月份为 1。

NETWORKDAYS

• NETWORKDAYS 函数可计算两个日期之间完整的工作日数值，其中，工作日不包括周末和专门指定的假期。
• 函数用法：
• NETWORKDAYS(start_timestamp, end_timestamp, [holidays])
• 其中各参数的含义如下：
• 注：holidays 参数可通过如下两种方式输入：
• 函数示例：如，计算某员工 6 月外包工资时，需将 2023 年 6 月 22 日和 2023 年 6 月 23 日制定为假期，则设置公式为NETWORKDAYS(开始时间,结束时间,[DATE(2023,6,22),DATE(2023,6,23)])，即可根据开始、结束时间计算出对应的工作天数和工资。

SYSTIME

• SYSTIME 函数可返回当前服务器时间。即使客户端的时间被人为调整了，SYSTIME 函数不受影响，获取的仍然是服务器时间。
• 函数用法：
• SYSTIME()
• 函数示例：如签到、打卡等场景中，可通过 SYSTIME 函数完成记录系统时间，有效避免作弊的情况。
• 注：在日期时间字段中使用 SYSTIME 函数时，时间类型可在字段属性中设置。

SECOND

• SECOND 函数可用于返回日期时间中的秒数。
• 函数用法：
• SECOND(timestamp)
• 函数示例：如计算签到时间中对应的秒数，可设置公式为SECOND(签到时间)，即 2023-02-03 08:49:44 对应的秒数为 44。

TIMESTAMP

• TIMESTAMP 函数可将日期对象转换成时间戳。
• 函数用法：
• TIMESTAMP(date)
• 函数示例：在日期时间字段自定义时间时，可通过 TIMESTAMP 函数将日期对象转换为时间戳格式，以便于字段生成具体时间。

TODAY

• TODAY 函数可用于获取当前系统的日期，可精确到秒。
• 函数用法：
• TODAY()
• 函数示例：
• 1）TODAY 函数可直接在日期时间字段中使用，显示的日期精度由日期时间字段的「字段属性 >> 类型」决定：
• 如，当设置日期时间字段类型为「年-月-日-时-分-秒」时，TODAY 函数的使用效果如下：
• 2）也可搭配 TEXT 函数 将获取的日期转换为文本格式，如设置公式为TEXT(TODAY(),"yyyyMMddhhmmss")，即可获取日期的年月日时分秒。
• 注：日期与文本格式的相互转换，可参考文档：文本与日期格式相互转换。

WEEKDAY

• WEEKDAY 函数可用于计算日期的星期数，返回 1到 7 之间的数值。
• 函数用法：
• WEEKDAY(日期时间)
• 函数示例：如计算签到日期对应的星期数，可设置公式为WEEKDAY(签到日期)，即 2023-05-26 对应的星期数为 6（星期五），2023-05-28 对应的星期数为 1（星期日）。

WEEKNUM

• 返回该日期在一年中的第几周。例如，包含 1 月 1 日的周为该年的第 1 周，其编号为第 1 周。
• date: 必需。代表一周中的日期。手写时需要增加引号。
• return_type: 可选。 一数字，确定星期从哪一天开始。 默认值为 1。当 return_type 为 1 或省略时，则周日被视为一周的第一天（美国习惯）；当其为 2 时，则周一被视为一周的第一天。
• 此函数所用机制：包含 1 月 1 日的周为该年的第 1 周，其编号为第 1 周。
• 示例：
• WEEKNUM("2012-3-9")，2012-3-9 所在一年中的周数，一周开始于星期日（默认值），返回 10。
• WEEKNUM("2012-3-9",2)，2012-3-9 所在一年中的周数，一周开始于星期一（第二个参数 2），返回 11。
• 注意：
• 如果 date 小于 1970 年 1 月 1 日时，则返回空。
• 如果 return_type 超过指定的范围，则返回空。

WORKDAY

• WORKDAY 函数可计算在某日期（起始日期）之前或之后、与该日期相隔指定工作日的某一日期的日期值。 工作日不包括周末和专门指定的假日。
• 函数用法：
• WORKDAY(start_timestamp, days, holidays)
• 其中各参数的含义如下：
• 注：holidays 参数可通过如下两种方式输入：
• 函数示例：如，计算交货时间时，需将 2023 年 4 月 5 日制定为假期，则设置公式为WORKDAY(下单时间,处理工作日,HOLIDAYS(2023,4,5))，扣除周末和设置的假期，即可根据下单时间计算出对应的交货时间。

YEAR

• YEAR 函数可用于返回日期时间中的年份。
• 函数用法：
• YEAR(timestamp)
• 函数示例：如计算生产时间中对应的秒年份，可设置公式为YEAR(生产日期)，即 2023-02-10 对应的年份为 2023。

ADDDAY

• 用法：ADDDAY(date,days)
• 说明：将指定日期加/减指定天数，date 为指定日期，days 为指定天数，当为负数时在 date 上减去此天数
• 场景：录入【任务开始时间】、【任务预计天数】，通过 ADDDAY 函数自动填入【任务预计完成时间】。
• 注意：此函数如果使用在单行文本、多行文本组件中，需要搭配 TEXT 函数转换为文本使用，不然会输出时间戳格式的文本。

ADDMONTH

• 用法：ADDMONTH(date,months)
• 说明：将指定日期加/减指定月数，date 为指定日期，months 为指定月数，当为负数时在此 date 上减去此月数。
• 场景：录入【项目开始时间】、【项目预计月数】，通过 ADDMONTH 函数自动填入【项目预计完成时间】。
• 注意：此函数如果使用在单行文本、多行文本组件中，需要搭配 TEXT 函数转换为文本使用，不然会输出时间戳格式的文本。

ADDYEAR

• 用法：ADDYEAR(date,years)
• 说明：将指定日期加/减指定年数，date 为指定日期，years 为指定年数，当为负数时在此 date 上减去此年数。
• 场景：录入【合同开始时间】、【合同有效年限】，通过 ADDYEAR 函数自动填入【合同到期时间】。
• 注意：此函数如果使用在单行文本、多行文本组件中，需要搭配 TEXT 函数转换为文本使用，不然会输出时间戳格式的文本。

HOLIDAYS

• 用法：HOLIDAYS(时间1，时间2，时间3)
• 说明：当需要从工作日历中排除一个或多个日期的时候，可使用此函数，例如各种省/市/自治区和国家/地区的法定假日及非法定假日。该参数可以是由日期所构成的数组常量。
• 示例：HOLIDAYS("2012-11-22","2012-12-4","2013-1-21")
• 注意：此函数必须与 「NETWORKDAYS」「WORKDAY」函数搭配使用。

ADDHOUR

• 用法：ADDHOUR(日期,整数)
• 说明：此函数返回指定日期增加指定小时后的日期-时间值。
• 示例：ADDHOUR( 2023-2-1 19:23:34,3)得出结果为 2023-2-1 22:23:34。

EOMONTH

• 用法：EOMONTH(start_date, number)
• 说明：Start_date 必需。 表示开始日期的日期。 如果日期以文本形式输入，则会出现问题。number 必需。 start_date 之前或之后的月份数。 number 为正值将生成未来日期；为负值将生成过去日期；为0则生成当月日期。
• 注意：如果 number 不是整数，将截尾取整。
• 示例：EOMONTH(2023-04-23, 0)=2023-04-30扩展用法：获取本月第一天：ADDDAY(EOMONTH(2023-04-23, -1),1)获取上月第一天：ADDDAY(EOMONTH(2023-04-23, -2),1)获取下月第一天：ADDDAY(EOMONTH(2023-04-23, 0),1)

CALCWEEK

• 用法：CALCWEEK(data, week)
• 说明：获取周的开始日期文本和结束日期文本,week 填写的是第几周 例如:第一周或第二周或第三周等。
• 场景：CALCWEEK(排期时间,"第一周")，【排期时间】是2024年6月10号的话，输出的六月第一周的结果是6.3--6.9号，5月27号-6月2号算五月最后一周。

NETWORKDAYS.INTL

• 用法：NETWORKDAYSINTL(start_date, end_date, weekend, holidays)
• 说明：返回参数 start_date 和 end_date 之间完整的工作日数值。工作日不包括周末和专门指定的假期。可以使用函数 NETWORKDAYS，根据某一特定时期内雇员的工作天数，计算其应计的报酬。
• start_date：必需。代表开始日期。手写时需要增加引号。
• end_date：必需。代表终止日期。手写时需要增加引号。
• holidays：可选。一个可选参数，其中包含需要从工作日历中排除的一个或多个日期，例如各种省/市/自治区和国家/地区的法定假日及非法定假日。该参数可以是由日期所构成的数组常量。
• 如：开始日期 (2012-10-1) 和终止日期 (2013-3-1) 之间工作日的天数，返回 110。