在 TypeScript 中封装 AM/PM 时间格式化方法

🎓 作者简介： 前端领域优质创作者

🚪 资源导航： 传送门=>

🎬 个人主页：  江城开朗的豌豆

🌐 个人网站:    江城开朗的豌豆 🌍

📧 个人邮箱: YANG_TAO_WEB@163.com 📩

💬 个人微信:     y_t_t_t_ 📱

📌  座  右 铭: 生活就像心电图，一帆风顺就证明你挂了。 💔

👥 QQ群:  906392632 (前端技术交流群) 💬

在日常开发中，我们经常需要将时间格式化为用户友好的形式，比如 PM 03:05。本文将介绍如何在 TypeScript 中封装一个通用的时间格式化方法，支持多种输入类型，并具备良好的扩展性和错误处理能力。

---

1. 核心实现代码

以下是核心代码实现：

/**
 * 将时间格式化为 AM/PM 格式（例如 "PM 03:05"）
 * @param input 时间输入（支持 Date 对象、时间戳、ISO 字符串）
 * @returns 格式化后的时间字符串
 * @throws 当输入无效时抛出错误
 */
function formatTimeToAMPM(input: Date | number | string): string {
  // 将输入统一转换为 Date 对象
  const date = input instanceof Date ? input : new Date(input);

  // 验证时间有效性
  if (isNaN(date.getTime())) {
    throw new Error("Invalid date input");
  }

  // 提取小时和分钟
  let hours = date.getHours();
  const minutes = date.getMinutes().toString().padStart(2, "0");

  // 判断 AM/PM
  const ampm = hours >= 12 ? "PM" : "AM";
  
  // 转换为 12 小时制
  hours = hours % 12;
  hours = hours === 0 ? 12 : hours; // 处理 0 点显示为 12

  // 格式化为两位数小时
  const formattedHours = hours.toString().padStart(2, "0");

  return `${ampm} ${formattedHours}:${minutes}`;
}

---

2. 功能特性

• 多类型输入支持：接受 Date 对象、时间戳（number）、ISO 字符串（string）。
• 错误处理：无效输入会抛出明确错误。
• 自动补零：小时和分钟始终显示两位数（如 03:05）。
• 12 小时制：自动转换 24 小时制为 12 小时制（0 点显示为 12）。

---

3. 使用示例

// 示例 1: 使用 Date 对象
const now = new Date("2023-10-10T15:05:00"); // 3:05 PM
console.log(formatTimeToAMPM(now)); // 输出 "PM 03:05"

// 示例 2: 使用时间戳
const timestamp = now.getTime();
console.log(formatTimeToAMPM(timestamp)); // 输出 "PM 03:05"

// 示例 3: 使用 ISO 字符串
console.log(formatTimeToAMPM("2023-10-10T00:05:00")); // 输出 "AM 12:05"
console.log(formatTimeToAMPM("2023-10-10T12:05:00")); // 输出 "PM 12:05"
console.log(formatTimeToAMPM("2023-10-10T13:05:00")); // 输出 "PM 01:05"

---

4. 高级用法（扩展功能）

支持自定义格式

interface FormatOptions {
  showSeconds?: boolean;   // 是否显示秒（如 "PM 03:05:30"）
  uppercase?: boolean;     // AM/PM 是否大写（默认 true）
}

function formatTimeToAMPM(
  input: Date | number | string,
  options: FormatOptions = {}
): string {
  // ...（省略前面的代码）

  // 处理选项
  const ampmDisplay = options.uppercase !== false ? ampm : ampm.toLowerCase();
  let result = `${ampmDisplay} ${formattedHours}:${minutes}`;

  // 添加秒数
  if (options.showSeconds) {
    const seconds = date.getSeconds().toString().padStart(2, "0");
    result += `:${seconds}`;
  }

  return result;
}

// 使用示例
console.log(formatTimeToAMPM(new Date(), { showSeconds: true }));
// 输出 "PM 03:05:30"
console.log(formatTimeToAMPM(new Date(), { uppercase: false }));
// 输出 "pm 03:05"

---

5. 关键逻辑解析

步骤	代码	说明
输入转换	new Date(input)	统一转换为 Date 对象
有效性校验	isNaN(date.getTime())	确保输入是合法时间
12 小时制转换	hours = hours % 12	将 24 小时制转换为 12 小时制
午夜 0 点处理	hours = hours === 0 ? 12 : hours	0 点显示为 12（符合日常习惯）
自动补零	.padStart(2, "0")	确保小时和分钟始终是两位数
AM/PM 判断	hours >= 12 ? "PM" : "AM"	根据小时数判断时段

---

6. 常见问题解决

问题 1：时区不一致

• 现象：输出时间与预期不符。

• 解决：明确函数基于本地时间，如需 UTC 时间，改用以下方法：

  // 使用 UTC 时间
  let hours = date.getUTCHours();
  const minutes = date.getUTCMinutes().toString().padStart(2, "0");
  

问题 2：输入解析失败

• 现象：传入字符串如 "3:05 PM" 导致错误。
• 解决：使用更安全的解析库（如 date-fns 或 moment.js）替代 new Date()。

问题 3：浏览器兼容性

• 现象：旧浏览器不支持 .padStart()。

• 解决：添加 Polyfill 或改用以下代码：

  const padZero = (num: number) => (num < 10 ? `0${num}` : num.toString());
  const minutes = padZero(date.getMinutes());
  

---

7. 总结

通过上述方法，我们实现了一个灵活且可靠的 TypeScript 时间格式化工具。它支持多种输入类型，具备良好的扩展性和错误处理能力，能够满足日常开发中的大部分需求。希望本文对你有所帮助！

---

欢迎在评论区分享你的想法和建议！如果你觉得这篇文章有用，别忘了点赞和收藏哦~