Intl.DateTimeFormat 的 hourCycle 和 hour12 怎样确定优先级

在时间选择器里，产品往往只想提供“12 小时制/24 小时制”两个选项，但 Intl.DateTimeFormat 同时提供了 hour12 和 hourCycle。两者一起写时，如果不知道优先级，就会出现配置看似是 24 小时制，结果却仍带上午/下午标记的情况。

直接结论：当 hour12 被明确设置为 true 或 false 时，它决定最终采用 12 小时还是 24 小时制，hourCycle 不再参与这次解析；只有没有设置 hour12 时，hourCycle 才直接决定具体循环。可以用 resolvedOptions() 读取最终结果。

官方地址：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat

先把两个选项分成“模式”和“循环”

hour12 只回答一个问题：要不要使用 12 小时制。true 表示使用 12 小时制，false 表示使用 24 小时制。

hourCycle 则是更细的循环选择：h11 与 h12 是 12 小时循环，h23 与 h24 是 24 小时循环。它们的区别主要在午夜如何显示：h11/h23 从 0 开始，h12/h24 从 1 开始，因此 h24 可能把午夜显示为 24。

同时设置时，hour12 覆盖 hourCycle

最容易误判的代码是同时传入两个选项。规范的解析顺序是：如果 hour12 有值，就先把它转换成 12 小时或 24 小时对应的循环；只有 hour12 没有值时，才使用 hourCycle 或 locale 的默认小时循环。

const sample = new Date("2026-01-02T13:05:00Z");

function inspectHourOptions(options) {
  // 固定 locale 和时区，避免示例被运行环境的默认时区干扰。
  const formatter = new Intl.DateTimeFormat("en-US", {
    hour: "numeric",
    minute: "2-digit",
    timeZone: "UTC",
    ...options,
  });

  // resolvedOptions() 返回的是构造器最终解析后的配置。
  return {
    text: formatter.format(sample),
    hourCycle: formatter.resolvedOptions().hourCycle,
    hour12: formatter.resolvedOptions().hour12,
  };
}

// hour12=false 生效，hourCycle 的 h12 被忽略。
console.log(inspectHourOptions({ hour12: false, hourCycle: "h12" }));

// 没有 hour12 时，hourCycle=h23 才直接决定结果。
console.log(inspectHourOptions({ hourCycle: "h23" }));

上面的输出是静态示意：第一组的有效配置应属于 24 小时制，第二组应属于 h23。实际显示文本仍由 locale、时区和字段组合共同决定，所以工程代码应优先检查解析后的选项，而不是硬编码某种字符串。

用 resolvedOptions() 找到真正生效的值

调试“配置没有生效”时，最短路径是分别测试三种情况：只设 hour12、只设 hourCycle、两个都设。重点观察 hourCycle 与 hour12 的返回值。

const cases = [
  { name: "只指定 12 小时制", options: { hour12: true } },
  { name: "只指定 h23", options: { hourCycle: "h23" } },
  { name: "冲突配置", options: { hour12: false, hourCycle: "h12" } },
];

for (const item of cases) {
  // 每个 formatter 都独立创建，避免复用旧实例造成误判。
  const formatter = new Intl.DateTimeFormat("en-US", {
    hour: "numeric",
    minute: "numeric",
    timeZone: "UTC",
    ...item.options,
  });
  const resolved = formatter.resolvedOptions();
  console.log(item.name, {
    hourCycle: resolved.hourCycle,
    hour12: resolved.hour12,
  });
}

如果冲突配置返回的是 hour12: false，就说明最终是 24 小时制；不要再根据传入对象里的 hourCycle 推断显示结果。resolvedOptions() 还会告诉你 locale、timeZone 等其他最终值，适合把配置问题收敛到具体字段。

不要把 locale 默认值当成固定规则

两个选项都不写时，小时制可能来自请求的 locale 及其 Unicode 扩展。比如 locale 可以携带 -u-hc-h23 这样的小时循环偏好，但显式的 hour12 仍然优先。跨地区界面如果必须稳定显示 24 小时制，应明确传入 hour12: false，而不是依赖用户浏览器的区域设置。

反过来，如果产品需要尊重用户地区习惯，就不要无条件覆盖它；可以把 locale 作为输入，仅在用户主动切换显示模式时传入 hour12。涉及午夜显示的场景，再决定使用 h23 还是 h24，不要只写“24 小时制”四个字就结束。

Intl.DateTimeFormat 小时制的常见疑问

hour12=false 后为什么 hourCycle 不是我写的 h23？

因为 hour12=false 只要求 24 小时制，具体使用 h23 还是 h24 仍由 locale 数据和格式化实现选择。需要确认时读取 resolvedOptions().hourCycle。

hourCycle 能替代 hour12 吗？

可以，但两者表达层级不同。只需要 12/24 两种模式时使用 hour12 更直观；需要明确午夜显示 0 还是 24 时，再使用 hourCycle。

为什么不能直接用正则判断上午或下午？

不同 locale 的标记、顺序和数字系统都可能变化。应读取解析选项，或用 formatToParts() 按字段处理，而不是依赖某个语言的显示字符串。