JavaScript怎么封装支持自定义模板的当前时间格式化函数

一、占位符规范与核心设计

设计自定义模板函数的首要步骤是制定统一、清晰的占位符规范。占位符既要符合主流使用习惯（如国际标准与社区开源库标准），又要能区分“是否自动补齐前导零”以及“24小时制与12小时制”。

下表列出了本函数支持的标准占位符定义及其映射规则：

二、核心实现步骤剖析

实现该函数主要分为四个步骤：

1. 实例化当前时间：通过 new Date() 初始化时间对象。为保证函数的通用性，还可以允许调用方选择性传入已有 Date 对象或时间戳，若不传则默认取当前时间。
2. 提取时间分量并对齐：调用原生方法提取分量。需要格外注意 getMonth() 返回值是 0 ~ 11，在日常展示时必须加上 1；24小时与12小时制的换算可通过 hours % 12 || 12 实现。
3. 构建占位符字典：将提取出的分量以字符串形式存入对象中，其中 MM、DD、HH、mm、ss 等长标记使用 String.prototype.padStart(2, '0') 填充为两位。
4. 正则一次性查表替换：使用统一的正则表达式同时匹配所有标记，在 replace 回调中查表替换。这一步至关重要，能彻底避免链式替换造成的二次污染。

三、为什么必须使用“正则单次查表替换”

初学者在封装格式化函数时，经常容易写出类似下面的错误模式：

// 错误示例：连续链式替换（存在二次替换污染风险）
template
  .replace('YYYY', year)
  .replace('MM', month)
  .replace('DD', day)
  .replace('HH', hour)
  .replace('mm', minute)
  .replace('ss', second);

这种链式 replace 方式有严重隐患：前面的替换结果可能会引入后续占位符相同的字母。例如，若年份替换为了 2026 没什么问题，但如果是处理自定义格式或者含其他字母的模板时，前面的替换结果一旦碰巧包含了后续占位符（如 M、D、s 等），就会导致原本已经替换完成的内容被再次篡改。

正规解法是利用 全局正则表达式分支匹配（/YYYY|MM|.../g）并结合回调函数查表。因为 JavaScript 的正则引擎会对目标字符串进行单向线性扫描，已经被替换的文本不会被再次扫入正则匹配队列，从而确保原子性与绝对安全。

四、完整封装代码实现

下面给出生产可用的完整封装代码。该实现默认格式化当前时间（new Date()），默认模板为 "YYYY-MM-DD HH:mm:ss"，同时支持传入自定义模板以及特定时间对象：

/**
 * 格式化时间函数
 * @param {string} [template='YYYY-MM-DD HH:mm:ss'] - 目标格式模板
 * @param {Date|number|string} [targetDate=new Date()] - 目标时间，默认当前时间
 * @returns {string} 格式化后的时间字符串
 */
function formatTime(template = 'YYYY-MM-DD HH:mm:ss', targetDate = new Date()) {
  // 1. 规范化 Date 实例
  const date = targetDate instanceof Date ? targetDate : new Date(targetDate);

  // 2. 检查日期有效性
  if (Number.isNaN(date.getTime())) {
    throw new TypeError('formatTime: 提供的时间参数无效');
  }

  // 3. 提取各个时间分量
  const year = date.getFullYear();
  const month = date.getMonth() + 1;
  const day = date.getDate();
  const hours24 = date.getHours();
  const hours12 = hours24 % 12 || 12;
  const minutes = date.getMinutes();
  const seconds = date.getSeconds();
  const milliseconds = date.getMilliseconds();

  // 4. 构建占位符映射字典
  const tokens = {
    YYYY: String(year),
    YY: String(year).slice(-2),
    MM: String(month).padStart(2, '0'),
    M: String(month),
    DD: String(day).padStart(2, '0'),
    D: String(day),
    HH: String(hours24).padStart(2, '0'),
    H: String(hours24),
    hh: String(hours12).padStart(2, '0'),
    h: String(hours12),
    mm: String(minutes).padStart(2, '0'),
    m: String(minutes),
    ss: String(seconds).padStart(2, '0'),
    s: String(seconds),
    SSS: String(milliseconds).padStart(3, '0')
  };

  // 5. 按照“长标记优先”的原则构造全局匹配正则
  // 避免 MM 被先行误匹配为 M，或者 YYYY 被误匹配为 YY
  const tokenRegex = /YYYY|SSS|YY|MM|DD|HH|hh|mm|ss|M|D|H|h|m|s/g;

  // 6. 查表替换并返回
  return template.replace(tokenRegex, (match) => tokens[match]);
}

/**
 * 专用于当前时间的快捷调用函数
 * @param {string} [template='YYYY-MM-DD HH:mm:ss'] - 目标格式模板
 * @returns {string} 当前时间的格式化字符串
 */
function formatNow(template = 'YYYY-MM-DD HH:mm:ss') {
  return formatTime(template, new Date());
}

五、实际使用与场景验证

完成封装后，可以在各种常见的业务场景下直接调用 formatNow()。以下给出不同模板下的运行效果示例：

// 场景 1：默认标准完整时间（未传参）
console.log(formatNow());
// 输出示例："2026-11-11 01:50:55"

// 场景 2：仅获取当前年月日（常用于报表归档、文件命名）
console.log(formatNow('YYYY-MM-DD'));
// 输出示例："2026-11-11"

// 场景 3：中文语义化日期（常用于页面顶部抬头展示）
console.log(formatNow('YYYY年MM月DD日 HH时mm分ss秒'));
// 输出示例："2026年11月11日 01时50分55秒"

// 场景 4：紧凑型时间戳（常用于订单流水号前缀）
console.log(formatNow('YYYYMMDDHHmmss'));
// 输出示例："20261111015055"

// 场景 5：包含高精度毫秒（常用于系统日志追踪）
console.log(formatNow('HH:mm:ss.SSS'));
// 输出示例："01:50:55.042"

// 场景 6：不补零的极简展示与12小时制
console.log(formatNow('M月D日 上午/下午 hh:mm'));
// 输出示例："11月11日 上午/下午 01:50"

六、细节提醒与进阶拓展

七、总结

封装一个支持自定义模板的时间格式化函数并不复杂，核心在于不引入过重第三方库的前提下，保证代码的准确性与防御性。通过规范化的占位符命名、原生的 padStart 补零以及基于“长标记优先”的正则单次替换，开发者只需几十行轻量代码就能满足绝大多数前端与服务端关于时间展示的格式化诉求。