时间加减

📖 节点概述

在指定的基准时间上增加或减少一定的时间量。基准时间可以是一个字符串（格式 YYYY-MM-DD HH:MM:SS），留空则使用当前系统时间。支持的时间单位包括秒、分、时、天、周、月、年。偏移量为整数，正数表示向后（未来）推移，负数表示向前（过去）推移。输出为格式化的时间字符串。该节点为纯数据节点，无执行端口。

💡 使用场景：

• 定时任务调度：在当前时间基础上增加一定时间，计算出任务的下次执行时间。
• 有效期计算：从给定日期起，计算 N 天/月/年后的过期时间。
• 回溯日志：将基准时间向前偏移，查找过去某段时间的记录。
• 周期计算：根据起始时间和周期长度，计算下一周期的时间点。
• 时区无关的简单计算：在不需要处理复杂时区的情况下进行日期算术。

🎮 实战连线指南：如何正确使用它？

节点有三个主要输入端口：基准时间（字符串）、单位（下拉选择）、偏移量（整数），输出端口 新时间（格式化的字符串）。

场景案例：计算当前时间 7 天后的日期

1. 基准时间：留空（使用当前系统时间）。
2. 单位：选择 天。
3. 偏移量：输入 7。
4. 获取结果：新时间 输出当前时间 +7 天的日期时间字符串，如 "2025-06-05 14:30:00"。
5. 后续使用：将该时间用于定时任务或显示。

向前偏移示例：

• 基准时间 2025-01-01 12:00:00，单位 月，偏移量 -3 → 输出 "2024-10-01 12:00:00"。

单位年/月注意事项：

• 月份加减时会自动处理跨年和不同月份天数（例如从 1 月 31 日减 1 个月，结果为 12 月 31 日；从 3 月 31 日减 1 个月，结果为 2 月 28/29 日）。
• 年份加减直接修改年份，若涉及闰年 2 月 29 日，则可能变为 2 月 28 日（如 2024-02-29 加 1 年 → 2025-02-28）。

⚙️ 引脚与参数说明

📥 输入引脚

⚙️ 控件参数

📤 输出引脚

🔧 计算规则

• 基准时间解析使用 datetime.strptime(raw, "%Y-%m-%d %H:%M:%S")。若解析失败或基准时间为空时，使用当前时间 datetime.now()。
• 根据单位执行不同的加法：
  • 秒、分、时、天、周：使用 timedelta 对象进行算术。
  • 月：先将月份数加上偏移量，再调整年份和月份（通过取模运算），最后替换日期。如果目标日期不存在（如 1 月 31 日加 1 个月 → 2 月 31 日不存在），Python 不会自动调整，节点未做特殊处理，可能导致错误。实际使用时建议避免不存在的日期（如1月31日加1个月会出现问题）。更严谨的实现会使用 dateutil.relativedelta，但本节点采用简单替换，请注意。
  • 年：直接替换年份。闰年 2 月 29 日加减年份时，如果目标年不是闰年，会变为 2 月 28 日（Python 的 replace 行为会自动调整）。

⚠️ 注意事项

• 月份/年份的边界行为：对于月份和年份的加减，本节点的实现较为简单，可能产生非预期结果（如 1 月 31 日 + 1 个月 → 3 月 3 日？实际测试：Python 的 replace 遇到无效日期会抛出 ValueError，节点未捕获）。实际上本节点代码中使用 dt.replace(month=month) 时若月份超出 1-12 范围会报错，但前面计算 month 时用了模运算，可能不会超出范围。但对于月份天数不匹配（如 1 月 31 日 + 1 个月 → 2 月 31 日）也会报错。故建议月份和年运算时避免使用月末不存在的日期。
• 时区：所有时间均视为本地时间（无时区信息），计算时不考虑时区转换。
• 基准时间格式：必须严格遵循 YYYY-MM-DD HH:MM:SS，否则解析失败将导致使用当前时间。
• 错误处理：若基准时间无效，返回 "无效时间" 字符串。
• 浮点偏移量：虽然输入控件支持小数（双精度），但节点内部将偏移量转为整数（int(delta_val)），因此不支持非整数偏移。界面上的 double_spin_box 但 decimals=0 实际限制了整数输入。

💎 小贴士：

• 对于精确的月、年加减（如合同到期日），建议使用专门的日期库或分步计算；此节点适用于简单场景。
• 偏移量为 0 时，输出与基准时间相同（或当前时间）。
• 配合【日期差计算】节点，可以实现周期推算和间隔验证。
• 由于是纯数据节点，无需执行信号，可在数据流中直接使用。