使用Google Calendar API计算员工本地时区空闲时间的JS问题

1. IANA时区转含夏令时的动态偏移量 #

直接用编程语言的时区处理库自动适配夏令时，不用手动维护偏移规则：

• Python（3.9+）：

from zoneinfo import ZoneInfo
from datetime import datetime

user_tz = ZoneInfo("America/Denver")
current_dt = datetime.now(user_tz)
offset_str = current_dt.strftime("%z")  # 输出如-0600（夏令时）或-0700（冬令时）

• JavaScript：

const { DateTime } = require('luxon');
const userTz = 'America/Denver';
const offsetMinutes = DateTime.now().setZone(userTz).offset; // 如-360对应-06:00
const offsetStr = `${offsetMinutes >= 0 ? '+' : '-'}${Math.abs(Math.floor(offsetMinutes/60)).toString().padStart(2, '0')}${(offsetMinutes%60).toString().padStart(2, '0')}`;

这些库会根据当前日期自动切换夏令时/冬令时偏移。

2. 获取日历当前时区偏移量 #

Google Calendar API没有直接返回偏移量的接口，必须通过calendars/get拿到IANA时区后，用上面的方法计算当前偏移量。本质和问题1一致，无需额外API调用。

3. 能否用IANA时区直接调用API #

Freebusy和events.list不支持直接用IANA时区作为时间参数，但可以：

• 在请求参数中添加timeZone（IANA格式），这样API返回的事件时间会自动转换为该时区
• 但请求的timeMin/timeMax仍需传入带偏移的RFC3339格式时间，比如把用户时区的8:00转换为2024-05-20T08:00:00-06:00

4. 更优实现思路 #

• 优先用Freebusy API：直接返回忙碌时段，比遍历events.list计算空闲高效，还能批量查询多用户日历，同时通过status=accepted过滤已接受的事件
• 标准化时间转换流程：
  1. 从calendars/get获取用户IANA时区
  2. 针对目标日期，在用户时区生成当天8:00和17:00的时间对象
  3. 将这两个时间转换为带偏移的RFC3339格式，作为API的timeMin/timeMax
  4. 请求时带上timeZone参数，确保返回结果对齐用户时区
• 缓存优化：缓存用户的IANA时区信息，每日更新一次偏移量（夏令时切换是固定日期，无需实时计算）
• 处理夏令时切换日：跨切换日查询时，要单独处理每天的时间范围，避免因当天时长异常（23/25小时）导致的时间计算错误

内容的提问来源于stack exchange，提问作者JCarrier