异常教程

JavaScript toLocaleDateString() 方法（一文讲透）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

在 JavaScript 开发中，日期格式化是一个高频需求。无论是显示用户的注册时间、订单创建日期，还是展示天气预报的日期信息，开发者都需要将日期对象转化为符合本地习惯的字符串。然而，由于不同国家和地区对日期的表示方式存在显著差异（例如，美国使用 "MM/DD/YYYY"，而中国使用 "YYYY年MM月DD日"），直接使用基础的 Date 对象方法可能无法满足国际化场景的需求。此时，toLocaleDateString() 方法便成为了解决这一问题的核心工具。本文将从零开始，系统讲解这一方法的用法、参数配置、实际案例及常见问题，帮助开发者在项目中高效应用它。

一、从基础到进阶：理解 toLocaleDateString() 的核心逻辑

1.1 为什么需要 toLocaleDateString()？

JavaScript 的原生 Date 对象提供了一系列方法，例如 toString() 和 toDateString()，但它们的输出格式固定且不支持本地化。例如：

const date = new Date();  
console.log(date.toString()); // "Fri, 22 Sep 2023 14:30:00 GMT"  
console.log(date.toDateString()); // "Fri Sep 22 2023"

这些格式既不符合大多数中文用户的阅读习惯，也无法满足多语言需求。而 toLocaleDateString() 的核心优势在于：

  • 本地化适配：根据浏览器或环境的区域设置自动调整日期格式。
  • 可配置性：通过参数自定义显示的日期部分（如年、月、日）和语言。

1.2 基础语法与默认行为

toLocaleDateString() 的基本语法如下：

dateObj.toLocaleDateString([locales[, options]])
  • dateObj：必须是一个 Date 对象。
  • locales（可选）：指定目标语言和区域，例如 "zh-CN" 表示简体中文。
  • options（可选）：进一步控制格式细节，如显示时分秒或使用 24 小时制。

默认行为示例：

const today = new Date();  
console.log(today.toLocaleDateString());  
// 输出可能为 "2023/9/22"（取决于浏览器区域设置）

若未指定 locales，方法会使用用户设备的区域设置。例如，中文环境下通常显示为 "YYYY/MM/DD"，而英文环境可能显示为 "MM/DD/YYYY"。

二、深入参数配置：locales 与 options 的使用技巧

2.1 locales 参数：控制语言与区域

locales 是一个字符串或字符串数组，用于指定目标区域。例如：

// 指定中文简体（中国大陆）  
console.log(today.toLocaleDateString("zh-CN")); // "2023年9月22日"  

// 指定英文（美国）  
console.log(today.toLocaleDateString("en-US")); // "9/22/2023"  

// 同时指定多个区域（按优先级排序）  
console.log(today.toLocaleDateString(["zh-TW", "zh-CN"])); // "2023年9月22日"（若支持 zh-CN）

注意：若指定的区域不存在，浏览器会回退到默认区域。

2.2 options 参数：精细化控制日期格式

options 对象包含 weekday、year、month、day 等属性，用于选择显示的日期部分。例如：

const options = {  
  weekday: "long", // 显示完整星期名称（如 "星期五"）  
  year: "numeric",  
  month: "long", // 显示完整月份名称（如 "九月"）  
  day: "numeric"  
};  

console.log(today.toLocaleDateString("zh-CN", options));  
// 输出 "2023年9月22日 星期五"

以下是 options 的关键属性及取值说明：

属性取值类型取值范围及效果
weekday字符串"narrow"（如 "5"）、"short"（如 "周五"）、"long"（如 "星期五"）
era字符串"narrow"（如 "公元"）、"short"、"long"（如 "公元纪年"）
year字符串"numeric"（如 "2023"）、"2-digit"（如 "23"）
month字符串"numeric"（如 "9"）、"2-digit"、"narrow"（如 "9"）、"short"（如 "9月"）
day字符串"numeric"（如 "22"）、"2-digit"（如 "22"）
hour字符串控制是否显示小时（需结合 timeZone 使用）
minute字符串控制是否显示分钟（需结合 timeZone 使用）

2.3 动态适配与兼容性

2.3.1 动态区域适配

通过结合 navigator.language，可以自动检测用户区域：

const userLocale = navigator.language; // 获取浏览器语言设置，如 "zh-CN"  
console.log(today.toLocaleDateString(userLocale));

2.3.2 兼容性处理

虽然现代浏览器广泛支持 toLocaleDateString()，但旧版浏览器（如 IE 11）可能不支持 locales 参数。可通过 try...catch 或 polyfill 库（如 Intl polyfill）确保兼容性：

try {  
  // 尝试使用现代语法  
  return date.toLocaleDateString("zh-TW", { year: "numeric" });  
} catch (e) {  
  // 回退到基础方法  
  return date.toLocaleDateString();  
}

三、实战案例：从简单到复杂的应用场景

3.1 基础场景：显示当前日期

function displayCurrentDate() {  
  const date = new Date();  
  const formattedDate = date.toLocaleDateString();  
  document.getElementById("date-display").innerText = formattedDate;  
}

3.2 中文环境下的完整日期显示

const options = {  
  year: "numeric",  
  month: "long",  
  day: "numeric",  
  weekday: "long"  
};  

console.log(new Date().toLocaleDateString("zh-CN", options));  
// 输出 "2023年9月22日 星期五"

3.3 多语言切换

在国际化项目中，可基于用户选择动态切换区域：

function formatForLanguage(language) {  
  const date = new Date();  
  let formattedDate;  

  switch (language) {  
    case "en":  
      formattedDate = date.toLocaleDateString("en-US", { month: "long", day: "numeric" });  
      break;  
    case "zh":  
      formattedDate = date.toLocaleDateString("zh-CN", { year: "numeric", month: "numeric", day: "numeric" });  
      break;  
    default:  
      formattedDate = date.toLocaleDateString();  
  }  

  return formattedDate;  
}  

console.log(formatForLanguage("zh")); // "2023/9/22"

四、常见问题与解决方案

4.1 时区问题：日期显示与服务器时间不一致

toLocaleDateString() 默认使用本地时区，若需强制使用特定时区，需结合 options.timeZone：

// 使用 UTC 时间  
const utcDate = new Date().toLocaleDateString("en-US", { timeZone: "UTC" });

注意：并非所有浏览器都支持 timeZone 参数，需谨慎使用。

4.2 参数传递错误导致的意外输出

若 locales 或 options 参数格式错误，可能导致方法返回原始格式。例如：

// 错误写法：locales 参数应为字符串而非对象  
const invalidLocale = { language: "zh" };  
console.log(new Date().toLocaleDateString(invalidLocale)); // 可能输出默认格式

4.3 中文环境下的特殊符号处理

部分区域设置会使用特殊符号（如顿号），可通过自定义 options 调整：

// 强制使用斜杠分隔  
const customOptions = {  
  year: "numeric",  
  month: "2-digit",  
  day: "2-digit",  
  formatMatcher: "basic" // 可能影响分隔符，具体效果因浏览器而异  
};  

console.log(new Date().toLocaleDateString("zh-CN", customOptions)); // 可能输出 "2023/09/22"

五、对比与替代方案

5.1 与 toLocaleString() 的区别

toLocaleDateString() 仅格式化日期部分，而 toLocaleString() 会包含时间：

console.log(new Date().toLocaleDateString()); // "2023/9/22"  
console.log(new Date().toLocaleString());     // "2023/9/22 下午2:30:00"

5.2 手动格式化 vs 使用第三方库

对于复杂需求（如自定义格式字符串），可考虑使用 date-fns 或 moment.js：

// 使用 date-fns 的 format 函数  
import { format } from "date-fns";  
console.log(format(new Date(), "yyyy年MM月dd日")); // "2023年09月22日"

但 toLocaleDateString() 的优势在于无需依赖库且更贴近浏览器本地化能力。

结论

toLocaleDateString() 方法是 JavaScript 开发中处理日期本地化的利器。通过合理配置 locales 和 options 参数，开发者可以轻松适配不同地区的日期格式需求，提升用户体验。无论是构建多语言网站、国际化应用，还是处理用户输入的日期数据，掌握这一方法都能显著简化开发流程。建议在实际项目中结合用户区域设置动态调整格式，并注意浏览器兼容性问题。随着对 Intl API 的深入学习，开发者将能更灵活地应对复杂的国际化场景。

最新发布

查看更多文章