使用Intl.DateTimeFormat自动获取本地化星期名称

作者:木棉

时间:2026-11-17

浏览:512

介绍如何使用 JavaScript 内置的 Intl.DateTimeFormat 自动获取本地化星期名称,涵盖 weekday 参数选择、七天表头生成、实例复用差异及常见时区问题处理。

文章目录
使用Intl.DateTimeFormat自动获取本地化星期名称
图 0:Intl.DateTimeFormat 根据语言标签与 weekday 参数自动输出对应星期名称

在 JavaScript 中获取本地化星期名称,最直接的方式是使用内置的 Intl.DateTimeFormat 构造函数,并在配置对象中指定 weekday 选项(如 'long'、'short' 或 'narrow')。只要传入符合标准的语言标签(例如 'zh-CN'、'en-US')和有效的 Date 实例,就可以直接输出对应地区的星期文本,不必自己维护多个语言的数组映射。

一、基础用法:获取单个日期的本地化星期名称

Intl.DateTimeFormat 接收两个参数:语言环境标识 locales 和格式选项 options。只获取星期名称时,在 options 中仅保留 weekday 属性即可,随后调用实例的 format(date) 方法完成转换。

下面的代码适用于现代浏览器控制台或 Node.js 环境。以 2026 年 3 月 16 日(星期一)为例,分别传入中文、英文和日文语言标签:

// 运行环境:现代浏览器或 Node.js
const targetDate = new Date(2026, 2, 16); // 月份从 0 开始,2 表示 3 月

const zhWeekday = new Intl.DateTimeFormat('zh-CN', { weekday: 'long' }).format(targetDate);
const enWeekday = new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(targetDate);
const jaWeekday = new Intl.DateTimeFormat('ja-JP', { weekday: 'long' }).format(targetDate);

console.log({ zhWeekday, enWeekday, jaWeekday });
示例输出(实际文字受运行环境内置语言数据影响)
{ zhWeekday: '星期一', enWeekday: 'Monday', jaWeekday: '月曜日' }

关于第一个参数 locales,实际开发中有三种常见传法:

  • 固定语言标签:传入如 'zh-CN'、'zh-TW'、'en-GB' 等 BCP 47 字符串,输出语言与站点语言保持一致。
  • 回退数组:传入如 ['fr-CA', 'fr', 'en-US'],运行环境会按顺序匹配首个受支持的语言规则。
  • 省略或传 undefined:自动采用当前运行环境的默认语言(在浏览器中通常跟随用户系统或浏览器设置,也可显式传入 navigator.language)。

二、weekday 选项的三种粒度与适用场景

options.weekday 支持三个取值:'long'、'short' 和 'narrow'。它们决定了输出文本的完整程度,在不同语言中的缩略方式也不一样。

选项值 zh-CN(示例输出) en-US(示例输出) ja-JP(示例输出) 常见界面位置
'long' 星期二 / 星期四 Tuesday / Thursday 火曜日 / 木曜日 文章日期行、详情页摘要、无障碍读屏
'short' 周二 / 周四 Tue / Thu 火 / 木 周视图表头、表格列、日程卡片
'narrow' 二 / 四 T / T 火 / 木 空间极窄的迷你月历单元格
使用Intl.DateTimeFormat自动获取本地化星期名称
图 1:weekday 三种格式选项在多语言下的表现差异与选型依据

选择参数时要看界面语境是否具备“连续七天”的上下文。在英文环境下,'narrow' 会把 Tuesday 和 Thursday 都缩略成 "T",把 Saturday 和 Sunday 都缩略成 "S"。如果只是单独显示某一条日程的星期,使用 'narrow' 会让用户无法分辨是周几,此时应选用 'short' 或 'long'。

三、批量生成一周七天的本地化表头

制作日历组件或排班表时,经常需要一次性拿到按周一起始或按周日起始的七天名称数组。只要选定历史上任意一个已知星期几的日期作为基准日,再连续偏移 0 到 6 天并复用同一个格式化器,就能生成完整的七天表头。

下面按步骤实现一个支持指定每周起始日(周一或周日)的辅助函数:

  1. 确定基准日:2024 年 1 月 1 日是星期一,2024 年 1 月 7 日是星期日。用 Date.UTC(2024, 0, startDay + i) 构造日期可以跨月自动进位。
  2. 对齐格式化器时区:因为日期是由 Date.UTC 按零时区构造的,创建 Intl.DateTimeFormat 时必须显式传入 timeZone: 'UTC',防止负时区环境下日期被回拨一天。
  3. 循环生成数组:复用同一个 formatter 实例调用 7 次 format(),返回本地化星期数组。
使用Intl.DateTimeFormat自动获取本地化星期名称
图 2:从基准日选取到 UTC 对齐生成七天本地化表头的操作流程
// 运行环境:现代浏览器或 Node.js
function getLocalizedWeekdays(locale, { weekday = 'short', weekStartsOn = 'monday' } = {}) {
  const formatter = new Intl.DateTimeFormat(locale, {
    weekday,
    timeZone: 'UTC',
  });

  // 2024-01-01 为周一,2024-01-07 为周日
  const startDay = weekStartsOn === 'sunday' ? 7 : 1;

  return Array.from({ length: 7 }, (_, index) => {
    const date = new Date(Date.UTC(2024, 0, startDay + index));
    return formatter.format(date);
  });
}

console.log(getLocalizedWeekdays('zh-CN', { weekday: 'short', weekStartsOn: 'monday' }));
console.log(getLocalizedWeekdays('en-US', { weekday: 'short', weekStartsOn: 'sunday' }));
示例输出
['周一', '周二', '周三', '周四', '周五', '周六', '周日']
['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']

四、复用 Intl.DateTimeFormat 与调用 toLocaleDateString 的差异

日常代码中还会见到另一种写法:直接调用日期对象上的 date.toLocaleDateString(locale, { weekday: 'long' })。从结果来看,当参数相同时,两种写法返回的星期名称是一致的,因为 toLocaleDateString 在规范底层也是委托给 Intl.DateTimeFormat 处理的。

两者在工程使用上的关键差异在于状态是否复用以及能否拆分输出词素:

  • 实例解析开销:每次调用 date.toLocaleDateString(locale, options),引擎通常需要重新解析语言标签与配置项;而预先创建一次 const fmt = new Intl.DateTimeFormat(...),在循环中反复调用 fmt.format(date) 时,区域规则已经提前解析完成,更适合渲染日历网格或长列表。
  • 词素拆分能力:当你想同时格式化完整日期并单独提取(或高亮)星期部分时,toLocaleDateString 只返回拼接好的字符串;Intl.DateTimeFormat 实例则提供 formatToParts(date) 方法,可以把年、月、日与星期拆成结构化数组。
使用Intl.DateTimeFormat自动获取本地化星期名称
图 3:toLocaleDateString 与复用 Intl.DateTimeFormat 实例的解析时机差异

如果页面需要在完整日期中单独给星期名称加样式(例如把日期和星期分别放进不同的标签),用 formatToParts() 比用正则表达式或 split() 截取字符串更稳妥,因为不同语言的标点和词序并不相同:

// 运行环境:现代浏览器或 Node.js
const fullFormatter = new Intl.DateTimeFormat('zh-CN', {
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  weekday: 'short',
});

const parts = fullFormatter.formatToParts(new Date(2026, 2, 16));
const weekdayPart = parts.find((part) => part.type === 'weekday');

console.log(parts);
console.log('提取到的星期:', weekdayPart?.value);
示例输出
[
  { type: 'year', value: '2026' },
  { type: 'literal', value: '/' },
  { type: 'month', value: '03' },
  { type: 'literal', value: '/' },
  { type: 'day', value: '16' },
  { type: 'weekday', value: '周一' }
]
提取到的星期: 周一

五、常见错误与边界情况处理

把 Intl.DateTimeFormat 接入真实业务时,有四类边界情况最容易引发显示错位或运行时异常,建议在封装工具函数时一并处理。

1. ISO 纯日期字符串引发的时区错天

执行 new Date('2026-03-16') 时,JavaScript 会把不带时间部分的标准日期字符串按 UTC 零点(2026-03-16T00:00:00.000Z)解析。如果用户的电脑处于西半球负时区(例如 America/New_York),Intl.DateTimeFormat 默认会换算成本地时间 2026-03-15 20:00,从而返回前一天的星期名称。

处理方式有两种:如果输入的字符串本身代表纯粹的日历日期(不涉及具体时刻),创建格式化器时传入 timeZone: 'UTC';如果代表用户所在时区的本地日期,改用 new Date(2026, 2, 16) 构造本地零点,或明确传入业务约定的 timeZone。

2. 无效 Date 对象抛出 RangeError

向 format() 传入 new Date('invalid-date')(即内部时间戳为 NaN 的无效日期)时,Intl.DateTimeFormat 不会返回空字符串,而是直接抛出 RangeError: Invalid time value。因此格式化前应先校验 date instanceof Date && !Number.isNaN(date.getTime())。

3. 非法语言标签与环境兼容回退

当语言标签来自用户输入或外部接口时,诸如 'zh_CN'(使用了下划线而非连字符)或空字符串 '' 会触发 RangeError: Incorrect locale information provided。可以在传入前将下划线替换为连字符,或先用 Intl.DateTimeFormat.supportedLocalesOf([locale]) 检验后再创建实例:

// 运行环境:现代浏览器或 Node.js
function formatSafeWeekday(input, locale = 'zh-CN', weekday = 'long') {
  const date = input instanceof Date ? input : new Date(input);
  if (Number.isNaN(date.getTime())) {
    return '';
  }

  const normalizedLocale = String(locale).replaceAll('_', '-');
  const supported = Intl.DateTimeFormat.supportedLocalesOf([normalizedLocale]);
  const targetLocale = supported.length > 0 ? supported[0] : 'en-US';

  return new Intl.DateTimeFormat(targetLocale, { weekday }).format(date);
}

console.log(formatSafeWeekday(new Date(2026, 2, 16), 'zh_CN', 'short'));
console.log(formatSafeWeekday('not-a-date', 'zh-CN', 'short'));
示例输出
'周一'
''

4. 服务端渲染(SSR)下的默认语言不一致

如果在服务端渲染组件时省略了第一个参数(或传入 undefined),Node.js 进程会按服务器的系统语言输出星期名称,而浏览器接管页面时又可能按用户浏览器语言重新计算,导致两端文本不匹配。在同构渲染场景中,应从请求头或路由参数中解析出明确的 locale 再传给 Intl.DateTimeFormat。

六、使用要点总结

用 Intl.DateTimeFormat 获取本地化星期名称时,核心在于先确认输入日期与语言标签有效,再依据展示空间挑选 'long' 或 'short'(慎用容易在英文中重名的 'narrow'),并在涉及纯日期字符串或基准周循环时对齐 timeZone。对于表格和日历等高频渲染场景,把实例提取到循环外部复用,既能减少重复解析开销,也能方便地配合 formatToParts() 做细粒度排版。

使用Intl.DateTimeFormat自动获取本地化星期名称
图 4:使用 Intl.DateTimeFormat 获取本地化星期名称的四个核心检查点

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章