JavaScript Temporal 怎样处理跨时区日期计算

JavaScript Temporal 处理跨时区日期计算时，先区分两件事：同一个时刻换到另一地区显示，用 Instant 或 ZonedDateTime 换时区；“当地明天同一钟点”则保留业务时区，用 ZonedDateTime 加日历日。不要把一天一律换成 24 小时，也不要把没有时区的日期字符串直接当作全球唯一时刻。

假设预约表单同时服务上海和纽约用户，我会先问“用户约的是一个确定时刻，还是某地区每天固定钟点”。这个选择比换一个日期库更关键。下面围绕这两类预约给出写法，示例用于说明语义，并非本机运行记录。

Temporal 官方文档：https://tc39.es/proposal-temporal/docs/

本文兼容层仓库：https://github.com/js-temporal/temporal-polyfill

跨时区时应该保存什么对象

我倾向于把接口字段的含义写清楚再选类型。Instant 表示一个确定时刻，不带业务时区；ZonedDateTime 同时关联时刻、时区和日历；PlainDateTime 只有当地年月日与钟点，尚不能回答它对应哪个确定时刻。生日、账期日期这类纯日期通常另用 PlainDate，不要为了统一字段强行补上零点。

America/New_York 是一套地区规则；-05:00 只是一个偏移量。固定偏移不能替代地区未来或历史的夏令时规则。本文采用 ISO 日历语义。

同一场会议怎样换成另一时区

下面统一显式导入兼容层，避免示例依赖某一浏览器的原生支持。项目安装依赖后，在模块文件中使用：

# 在当前项目安装示例所用兼容层
npm install @js-temporal/polyfill

import { Temporal } from '@js-temporal/polyfill';

// 先确定上海的预约时间，拒绝不能唯一映射的当地输入
const meeting = Temporal.ZonedDateTime.from({
  timeZone: 'Asia/Shanghai',
  year: 2025, month: 11, day: 12, hour: 9, minute: 0
}, { disambiguation: 'reject' });

// 换区只改变当地表示，会议的确定时刻保持相同
const newYork = meeting.withTimeZone('America/New_York');
const instant = meeting.toInstant();
console.log(newYork.toString());
console.log(instant.equals(newYork.toInstant())); // 语义上应为 true

按这一天的地区规则，纽约当地表示应是前一天 20:00，UTC 表示是当天 01:00。跨区后日期变化是正常现象。withTimeZone 不会把上海 09:00 改成纽约 09:00；后者是一场另约时间的会议。

若后端已经返回带 Z 的时刻，可通过 Temporal.Instant.from(value).toZonedDateTimeISO(viewerZone) 取得观看者当地表示。排序和是否同时发生的判断保留在 Instant 层，避免比较展示字符串。

明天同一时间为什么不是加24小时

我会把“每天当地 09:00”与“24 小时后到期”做成两个明确选项。以纽约春季切换前的预约为例：

// 纽约这段日期包含春季夏令时切换
const start = Temporal.ZonedDateTime.from(
  '2025-03-08T09:00:00-05:00[America/New_York]'
);

// 日历加日适合保持当地钟点；小时加法表示实际时长
const nextLocalDay = start.add({ days: 1 });
const after24Hours = start.add({ hours: 24 });
const elapsed = start.toInstant().until(
  nextLocalDay.toInstant(), { largestUnit: 'hours' }
);
console.log(nextLocalDay.toString()); // 当地日期推进到次日，仍为 09:00
console.log(after24Hours.toString()); // 该例次日当地钟点为 10:00
console.log(elapsed.toString()); // 该例的实际间隔为 PT23H

这些是按示例规则推导的结果，不是性能测量。秋季回拨可能出现相反的日长度变化，其他地区也不一定只改变一小时。因此不要把 23 或 25 小时写死在通用业务里。

对只计算实际耗时的需求，先转为 Instant 再求差更直观；Instant 本身不适合直接加一个依赖地区规则的日历日。Duration 记录单位数量，但把日历单位解释成实际小时需要具体日期与时区上下文。每周固定预约还应保存地区、当地钟点和重复规则，不能仅把第一次的 UTC 时刻不断加固定秒数。

不存在或重复的当地时间怎样处理

当地钟点向确定时刻映射时，春季跳时可能没有对应时刻，秋季回拨可能对应两个时刻。我偏向预约提交时先用 disambiguation: 'reject'，让用户重新选择或明确确认，而不是静默挪动预约。

// 此例中的纽约当地 02:30 落在春季跳时缺口内
try {
  const appointment = Temporal.ZonedDateTime.from({
    timeZone: 'America/New_York',
    year: 2025, month: 3, day: 9, hour: 2, minute: 30
  }, { disambiguation: 'reject' });
  console.log(appointment.toInstant().toString());
} catch (error) {
  if (!(error instanceof RangeError)) throw error;
  // 提示用户重选；不要在捕获后自动保存一个替代时刻
  console.log('日期、时区或当地钟点不可接受，请重新确认');
}

RangeError 不只代表夏令时歧义，也可能来自非法时区或日期，因此上面的反馈保留较宽的错误含义。若业务允许自动调整，再明确采用 earlier、later 或 compatible：重复钟点时 earlier 取较早时刻，later 取较晚时刻；缺口时分别向前或向后移过缺口。compatible 对重复钟点按 earlier、对缺口按 later 处理。

另一个容易混淆的选项是 offset。当输入字符串同时包含偏移量和地区名，而两者不一致时，处理的是“偏移与地区规则的冲突”；这与单纯当地钟点的歧义不同。表单优先传日期字段和地区名，已有带偏移字符串则另行明确冲突处理策略。

接口存储与兼容性怎样安排

确定的一次性事件可保存 UTC 时刻及原业务时区。下面对象仅表示接口设计建议，不意味着必须采用特定数据库类型：

// 确定时刻方便排序，地区信息保留用户预约的业务含义
const payload = {
  startsAt: meeting.toInstant().toString(),
  timeZone: meeting.timeZoneId
};
console.log(JSON.stringify(payload));

服务端接收后仍需按业务处理非法输入。长期重复预约还应另存当地钟点、日期规则及歧义策略；地区规则更新后，未来安排是否重算由业务决定。只存 Instant 无法恢复“原来按哪个地区钟点预约”的意图。

兼容层不会自动创建全局 Temporal。本文从模块导入命名空间；若项目选择原生实现，应在自己的目标环境明确支持后统一入口，不要一部分代码取全局、一部分代码取兼容层后随意混用对象。这里只给兼容方案，不承诺所有浏览器已原生支持。

几个容易混淆的延伸问题

PlainDateTime 能直接换时区吗？不能把它当作已确定时刻。先确认它属于哪个地区，再按所需歧义策略关联时区，才有跨区展示的依据。

只存 +08:00 够吗？对明确固定偏移的需求可以；若含义是某地区未来的预约，保留 IANA 地区名更能表达规则需求。

两个地区日期不同还能算同一场会议吗？可以。判断是否同一时刻可比较各自的 Instant，不要求当地日期和钟点一致。

我的取舍是：一次性会议优先确定时刻，按地区每天发生的预约优先当地日历语义。Temporal 把两种含义分开表达，业务仍需要决定日期缺口、重复钟点和地区规则变化时如何处理。

相关原始资料：https://tc39.es/proposal-temporal/docs/zoneddatetime.html；https://tc39.es/proposal-temporal/docs/timezone.html；https://tc39.es/proposal-temporal/docs/instant.html；https://tc39.es/proposal-temporal/docs/duration.html。