返回探索
指南VibeFix 内容整理更新于 2026年11月20日

同一时刻,世界各地几点?Intl 日期时间格式化实战指南

同一个时间点,美国写 12/20/2020,英国写 20/12/2020,韩国写 2012. 12. 19.。本文按 MDN 的 Intl.DateTimeFormat 与 Intl 总览讲清楚:locale、时区、12/24 小时制、历法与数字系统、formatToParts 与格式化器复用。

真实照片:成田机场二号航站楼的精工世界时钟,世界地图分昼夜两色,右侧一列显示达拉斯、圣地亚哥、巴黎、伊斯坦布尔、内罗毕、台北、新加坡的时间

先把这篇的边界说清楚。站里已经有《Promise 与 async/await 实战指南》,讲的是等一个结果回来有几种写法;还有《事件循环实战指南》,讲的是代码排队执行的顺序;还有《闭包与作用域实战指南》,讲的是变量谁能看见。这篇不讲等结果、不讲排队、不讲变量,只讲一件事:一个时间点,在页面上该写成什么样子。时间显示错了,顾客会以为订单丢了,店主会以为系统坏了,客服对账更是对不上。下面用到的“青石咖啡馆”还是那个虚构的练手项目:一个帮街边咖啡馆做点单的网页小工具。这回它接了线上订单,顾客可能在世界各地,下单时间要按顾客自己的习惯显示。本文所有以它为例的操作、代码和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于日期时间格式化的语法和行为,都来自 MDN 的《Intl.DateTimeFormat》参考页与《Intl》总览页,来源见每篇的 meta 信息与 evidence 记录。MDN 文档里的例子,比如 2012 年 12 月 20 日那个时间点、达拉斯和台北的世界时钟,都是文档自带的示例,不是真实用户数据。

第一步:时间点只有一个,写法却有无数种

JavaScript 里的时间,先要分清两样东西:时间点和写法。时间点就是一个瞬间,用 new Date 存下来,本质上是从 1970 年 1 月 1 日开始算的毫秒数,跟人在哪个国家没有关系。写法则是把这个瞬间变成人能看懂的字符串,这一步才跟语言和地区有关。同一个瞬间,美国人习惯写成 12/20/2020,英国人习惯写成 20/12/2020,韩国人习惯写成 2012. 12. 19.,阿拉伯语的埃及人习惯用阿拉伯数字写成 ١٩/١٢/٢٠١٢。MDN 的原话是:DateTimeFormat 在不指定语言环境时,使用默认语言环境和默认选项。也就是说,你不告诉它按谁的习惯写,它就按运行这台机器的习惯写,同一行代码在不同人的电脑上跑出不同的字符串,这是最常见的第一坑。

青石咖啡馆的线上点单页就踩过这个坑:订单详情页直接用 new Date().toLocaleString() 显示下单时间,店主的电脑是中文系统,显示“2026/11/19 08:30:00”;一位在伦敦的顾客打开同一页,看到的却是“19/11/2026, 08:30:00”。两个人看的是同一个订单,说的却是两种写法,对账的时候差点以为是两个订单。记住第一句话:时间点是客观的,写法是本地的;写法不写死,页面就人人不同。

第二步:locale 参数,就是“按谁的习惯写”

Intl.DateTimeFormat 的第一个参数 locales,就是用来回答“按谁的习惯写”的。你可以传一个字符串,比如 en-US,也可以传一个数组,比如 ["ban", "id"],表示先按巴厘语写,巴厘语不支持就退到印尼语。MDN 的例子很直观:同一个时间点 new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738)),用 en-US 格式化得到 12/20/2020,用 ["ban", "id"] 得到 20/12/2020。顺序、分隔符、甚至数字长什么样,全跟着 locale 走。

locale 标识符本身也有结构,MDN 的《Intl》总览页讲得很清楚:它由语言子标签、书写文字子标签、地区子标签等用连字符连起来,比如 zh-Hans-CN 就是中文、简体字、中国大陆;de-AT 是德语、在奥地利使用;hi 就是印地语。大小写不敏感,但习惯上书写文字首字母大写、地区全大写、其余小写。写 locale 的时候别凭感觉拼,拼错了可能被当成不认识的语言直接忽略,悄悄退回默认设置,页面不报错,但显示的却不是你想要的习惯。

第三步:不传 locale,就等于把决定权交给别人的电脑

MDN 明确提醒:不带参数的 toLocaleString 依赖于实现、默认语言环境和默认时区。这句话翻译成人话就是:你不传 locale,浏览器就按用户电脑的设置来。店主的电脑是中文,顾客的电脑是英文,同一行代码跑出两种结果,测试的时候在自己电脑上看着好好的,上线就变样。

正确的做法是:显示给用户看的时间,永远显式传 locale。能拿到用户偏好的语言,就用 navigator.language;想给用户留退路,就用 navigator.languages 传一个按偏好排好序的列表,让运行时按顺序协商出一个最合适的。MDN 的例子是:const formattedDate = new Intl.DateTimeFormat(navigator.language).format(date),用浏览器报告的用户首选语言来格式化。咖啡馆的点单页改成这样之后,伦敦顾客看到 19/11/2026,美国顾客看到 11/19/2026,各看各的习惯,谁也不用再猜。

第四步:写错的 locale 会怎样——三种不同的下场

locale 传错了,有三种下场,要分清。第一种,传的不是字符串也不是对象,比如传了个数字,MDN 说会抛 TypeError。第二种,传的字符串语法上就不合格,比如乱拼的标识符,会抛 RangeError。第三种,语法合格但运行时不认识这门语言,比如 MDN 举的例子 new Intl.DateTimeFormat("default"),default 语法上没问题,但不是任何语言,运行时就忽略它,退回系统默认语言环境。第三种最阴险:不报错、不崩溃,只是悄悄用了默认写法,等你发现的时候,页面已经按错误的习惯显示了很久。

所以 locale 列表要当作优先级来写:把最想要的放前面,兜底的放后面。MDN 的 ["ban", "id"] 就是这个意思:巴厘语可能不支持,那就用印尼语。咖啡馆的做法是:先传用户在页面上自己选的语言,再传 navigator.languages,最后什么都不传也行——因为不传就等于用默认的,兜底总在最后。写代码的时候顺手做一件事:把最终生效的 locale 用 resolvedOptions() 读出来打到日志里,出问题的时候一眼就能看到底按谁的习惯写的。

第五步:dateStyle 和 timeStyle——先定长短,再定细节

定了按谁的习惯写,下一步是定写多长。Intl.DateTimeFormat 提供了 dateStyle 和 timeStyle,取值都是 full、long、medium、short 四档。MDN 的例子是:en-GB、dateStyle 是 full、timeStyle 是 long、时区 Australia/Sydney,格式化 2020 年 12 月 20 日那个时间点,得到 Sunday, 20 December 2020 at 14:23:16 GMT+11。星期、月、日、时、分、秒、时区全写出来了,一眼就能对上。

选哪一档,看场景。订单列表里每一行空间有限,用 short 就够了;订单详情页要让人一眼确认时间,用 long 或者 full 更稳。咖啡馆的规矩是:列表页只显示日期 short,详情页显示日期 long 加时间 short,客服电话里念给顾客听的时候再用 full。档位是写给人看的,不是写给机器看的;机器之间传时间,永远传时间戳或者 ISO 字符串,别传格式化好的字符串,解析回来会丢时区、丢精度。

第六步:weekday、month、hour 这些细选项,想写什么就点什么

dateStyle 和 timeStyle 是套餐,weekday、year、month、day、hour、minute、second 这些是单点。MDN 的例子是:weekday 是 long、year 是 numeric、month 是 long、day 是 numeric,德语环境下格式化 2012 年 12 月 20 日,得到 Donnerstag, 20. Dezember 2012。想让星期几出现,就加 weekday;想让月份写全名,就把 month 设成 long;想让月份只写数字,就设成 numeric。

时间也一样:hour、minute、second 各设 numeric,再配 timeZoneName,就能写出带时区缩写的完整时间。MDN 的例子里,同一个时间点,时区设成 UTC、时区名设成 short,英文环境下得到 Thursday, December 20, 2012, GMT;时区设成 Australia/Sydney,澳大利亚英文环境下得到 2:00:00 pm AEDT;再把 fractionalSecondDigits 设成 3,得到 2:00:00.200 pm AEDT,毫秒都写出来了。咖啡馆的厨房出单打印机上,时间精确到秒就够了;对账单上,精确到毫秒也没用,反而看不清。细选项的原则是:页面上每多一个字段,就要问一句“用户真的需要看它吗”,不需要就别加。

第七步:12 小时还是 24 小时,别让用户猜

同一个时间点,12 小时制和 24 小时制写出来完全不一样,混用就是事故。MDN 的例子是:把 hour12 设成 false,时区设成 America/Los_Angeles,英文环境下 2012 年 12 月 19 日那个时间点写成 12/19/2012, 19:00:00;hour12 不设,同一个时间点在澳大利亚英文环境下写成 2:00:00 pm。19 点和下午 2 点,说的是同一个瞬间在不同时区的墙上时间,写法一换,读的人很容易以为是两个时间。

更微妙的是 dayPeriod:MDN 的例子里,options 只写 hour 是 numeric、dayPeriod 是 short,英文环境下 2012 年 12 月 20 日凌晨 3 点那个时间点,结果是 10 at night——注意,这不是 3 点,是晚上 10 点的时段说法,MDN 用它来说明 dayPeriod 会按时间段给出一句本地化的说法。咖啡馆的教训是:给顾客看的时间,要么写清楚是上午还是下午,要么直接用 24 小时制,别只写一个光秃秃的 2:00,让人猜是凌晨 2 点还是下午 2 点。hour12 这个选项要显式写出来,别依赖默认值,因为默认值跟着 locale 走,en-US 默认 12 小时制,de-DE 默认 24 小时制,同一个页面换个语言就变了。

第八步:timeZone——同一个瞬间,各地墙上的钟不一样

时间点是唯一的,墙上的钟却各地不同。MDN 的例子把这一点算得很清楚:同一个瞬间,悉尼是 2020 年 12 月 20 日星期天 14:23:16,洛杉矶是 2012 年 12 月 19 日 19:00:00。timeZone 参数就是用来指定“按哪里的墙上时间写”的,取值是 IANA 时区名,比如 Australia/Sydney、America/Los_Angeles、Asia/Shanghai。

不传 timeZone,用的就是运行这台机器的本地时区。咖啡馆的订单存的是 UTC 时间戳,显示的时候必须显式传 timeZone:给顾客看,用顾客所在地的时区;给店主看,用 Asia/Shanghai;给客服对账看,用 UTC,并且把时区名写出来,让人一眼知道这串数字是按哪个时区算的。MDN 还提醒:options 里可以同时传 timeZone 和 timeZoneName,比如 timeZoneName 是 short,英文环境下就会在末尾写上 GMT、AEDT 这样的缩写。只写时间不写时区,等于只报数字不报单位,对账的时候一定会出事。

第九步:历法和数字系统——同一种语言,也有不同的写法

定了语言和时区,还没完:同一种语言,还可能用不同的历法和数字。MDN 的例子是:options 里 calendar 设成 chinese、numberingSystem 设成 arab,resolvedOptions() 读出来 calendar 就是 chinese、numberingSystem 就是 arab、timeZone 是运行机器的默认时区,比如 America/New_York。历法和数字系统可以独立指定,也可以在 locale 后面用 -u- 扩展写,比如 ja-JP-u-ca-japanese,意思是日语、日本历法,2012 年在日本历法里是平成 24 年,格式化出来就是 24/12/19。

《Intl》总览页还给了更多例子:th-TH-u-nu-thai 用泰语数字 ๐๑๒๓๔๕๖๗๘๙;de-DE-u-co-phonebk 用德语电话簿排序;en-GB-u-ca-islamic-umalqura 用伊斯兰乌姆古拉历,公历 2017 年 10 月 14 日对应伊斯兰历 1439 年穆哈兰姆月 24 日。咖啡馆用不上伊斯兰历,但道理是一样的:日期格式化不是“把数字拼成字符串”,而是“按一套完整的本地规矩写出来”,历法、数字、排序、时区,全是这套规矩的一部分。做海外顾客的页面,历法和数字系统要跟着 locale 走,别自己硬拼。

第十步:formatToParts——想自己排版,就先拆成零件

有时候,设计稿要求的排版是格式化函数给不出来的:年份要加粗、星期几要换颜色、时区要单独放一行。这时候不要自己拼字符串,要用 formatToParts。它返回一个零件数组,每个零件带 type 和 value,比如 year、month、day、weekday、literal,literal 就是中间的分隔符和空格。拿到零件数组,你想怎么拼就怎么拼,年份加粗、星期变色,都只是把零件重新组装一遍。

同理,显示一段时间范围的时候,别自己格式化两个日期再用横杠连起来,要用 formatRange。它会按 locale 的习惯把范围写成最简洁的样子,比如同一个月里的两天,英文环境下可能只写一次月份。对应的 formatRangeToParts 则把范围也拆成零件,方便自定义排版。咖啡馆的会员有效期就是这么写的:formatRange 显示“2026 年 11 月 1 日 – 2026 年 11 月 30 日”,月份只出现该出现的地方,不会写成两段重复的完整日期。记住判断句:要改排版,先拆零件;要写范围,用 formatRange;别自己拼字符串。

第十一步:格式化器只建一次,别放在循环里

new Intl.DateTimeFormat() 是有成本的:每次创建都要协商 locale、解析选项、准备本地化数据。订单列表有几百行,每行都 new 一个格式化器,页面会明显变慢。正确的做法是:格式化器只建一次,存在外面,循环里只调 format。MDN 的例子也是这么写的:先 const dateFormat = new Intl.DateTimeFormat(undefined, options),后面反复用它 format。

还有两个顺手的做法。第一,Date 自带的 toLocaleString、toLocaleDateString、toLocaleTimeString 底层走的也是同一套 Intl 引擎,写一次性的代码可以直接用它们,写列表渲染还是显式建格式化器复用更稳。第二,格式化器的选项定下来之后,用 resolvedOptions() 读一遍,确认最终生效的 locale、calendar、numberingSystem、timeZone 是不是你想要的——locale 协商可能悄悄退回默认值,读一遍才放心。咖啡馆的列表页改成复用格式化器之后,几百行订单的渲染时间肉眼可见地变快了,改动的只是一行代码的位置。

传 timeZone 之前,还可以先问一句“这个时区到底支不支持”。MDN 的《Intl》总览页讲了 Intl.supportedValuesOf():传 "timeZone" 进去,返回运行环境支持的时区名排好序的数组;传 "calendar"、"numberingSystem"、"currency"、"unit"、"collation" 也一样,各自返回支持的取值清单。咖啡馆上线新城市之前,先用它查一遍目标时区在不在清单里,不在就早点换写法,别等到顾客下单那天才发现时区名不认。配套的还有 Intl.getCanonicalLocales(),把用户传进来的 locale 字符串规范化成标准写法,比如大小写写乱了也能纠回来。这两个都是“先查再传”的工具,和 resolvedOptions() 的“传完再确认”正好一头一尾。

第十二步:96 次日期显示事故,先对着图自查

虚构青石咖啡馆项目一周 96 次日期显示相关事故的原因分布条形图

上图是虚构的青石咖啡馆项目一周的统计:和日期时间显示相关的事故一共 96 次。没传 locale、全凭运行机器的默认习惯 34 次,占 35.4%,是最多的;没传 timeZone、两地对不上同一个时间点 26 次,占 27.1%;12 小时制和 24 小时制混用、顾客看错上下午 16 次,占 16.7%;自己拼字符串、年月日顺序写错 12 次,占 12.5%;历法和数字系统没管、海外顾客看不懂 8 次,占 8.3%。34 加 26 加 16 加 12 加 8 等于 96,账是平的。这些数字是编出来的例子,目的是让你一眼看到:前两类加起来超过六成,而它们都是同一个根源的不同写法——显示给人看的时间,没有显式写清楚“按谁的习惯、按哪个时区”。

自查清单:写完显示时间的代码,逐条打勾

第一,时间点和写法分开存:机器之间传时间戳或者 ISO 字符串,显示给人看的时候再格式化。第二,显示给用户看的时间,永远显式传 locale,别依赖运行机器的默认设置。第三,locale 列表按优先级写,最想要的放前面,兜底的放后面,写错的 locale 要分清是 TypeError、RangeError 还是悄悄回退。第四,dateStyle 和 timeStyle 先定长短,weekday、month、hour 这些细选项再单点,不需要的字段别加。第五,hour12 显式写出来,12 小时制就要写清楚上午下午,或者直接用 24 小时制。第六,timeZone 显式传 IANA 时区名,时间后面把时区名也写出来,只报数字不报单位等于没报。第七,历法和数字系统跟着 locale 走,别自己硬拼字符串。第八,要改排版用 formatToParts,要写范围用 formatRange,别自己拼。第九,格式化器只建一次、循环里只调 format,选项定下来用 resolvedOptions() 读一遍确认;新城市上线之前,先用 supportedValuesOf() 查一遍时区在不在支持清单里。九条里任何一条答不上来,回到对应的章节再读一遍,比多背十个 API 都有用。

阅读 1评论 0

评论 (0)

ME
0/1000
评论加载中...

原始来源

浏览项目广场发布你的项目

相关文章

真实照片:一排浅灰色金属档案柜,其中一个抽屉拉开,露出里面一排排悬挂的文件夹
指南
浏览器里也能用数据库:IndexedDB 本地存取实战指南

localStorage 只能存字符串、没有索引。IndexedDB 是浏览器里真正的数据库:能存结构化数据、容量大得多、能建索引、能用事务。本文按 MDN 的《Using IndexedDB》《IDBDatabase》《IDBObjectStore》三篇官方文档讲清楚:五步套路、开库、升级、主键、索引、事务、add 与 put、get、游标、范围与多标签页升级。

工具技巧数据工作流前端工程
真实照片:一双手在 MacBook Pro 上打字,屏幕显示改写 HTML 内容的 JavaScript 代码,白色桌面上有白色鼠标、纸张和文件夹
指南
别让函数把你绕晕:JavaScript 函数、参数与箭头函数实战指南

函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。

工具技巧前端工程AI 编程实践
真实照片:木桌上的卡西欧科学计算器,屏幕显示 123456789 + 987654321 = 1111111110,旁边是写满手写数学公式的笔记本、钢笔、咖啡杯和笔记本电脑一角
指南
别让 0.1 + 0.2 坑了你的账单:JavaScript 数字与 Math 实战指南

JavaScript 里数字只有一种类型 Number,存成 64 位浮点数,所以 0.1 + 0.2 等于 0.30000000000000004。本文按 MDN 的《Basic math in JavaScript》《Math》《Number》三篇官方文档讲清楚:一种数字类型、浮点误差、钱改成分算、字符串转数字、NaN 与 Infinity、安全整数、四种取整、Math.random、Math 工具箱与显示格式化。

工具技巧前端工程AI 编程实践