封装一个通用的JS时间格式化函数支持自定义占位符

作者:小括号时间:2026-11-18 11:24:12浏览:618

本文详细讲解如何使用原生JavaScript封装一个高通用、高可靠的时间格式化函数,支持YYYY、MM、DD、HH、mm、ss、SSS等自定义占位符,分析单正则替换与链式替换的机制差异及避坑指南。

封装一个通用的JS时间格式化函数支持自定义占位符

图:通用时间格式化函数的核心设计与转换效果示例

在日常的前端与 Node.js 业务开发中,将时间对象转化为指定格式的字符串是一项基础而高频的需求。尽管原生 JavaScript 提供了 toISOString() 和 toLocaleDateString(),但它们要么输出固定格式,要么受运行环境本地化配置的影响,难以直接满足类似 YYYY-MM-DD HH:mm:ss 这种灵活的自定义模版需求。本文的目标是封装一个体积轻量、零第三方依赖、兼容多种输入参数的时间格式化函数 formatDate,并深入剖析自定义占位符替换机制中的核心原理与边界处理。

一、核心思路与解析流水线

时间格式化的本质是“模版变量替换”,其核心流程可以划分为四个清晰的阶段:输入归一化、时间分量提取与补齐、模版占位符扫描、映射值组装。整个过程需要确保不论外部传入的是原生 Date 对象、毫秒时间戳还是日期字符串,都能得到稳定、一致的格式化结果。

封装一个通用的JS时间格式化函数支持自定义占位符

图1:时间格式化解析与替换流水线架构

如上图所示,当用户传入待格式化的时间和格式字符串(例如 "YYYY年MM月DD日 HH:mm")后,函数会先将参数安全包装为一个标准的 Date 实例,并通过 getTime() 判断其是否为合法日期。随后,调用原生的 getFullYear()、getMonth()、getDate() 等方法获取年、月、日、时、分、秒的分量数值,并根据位数规则进行前导补零(Pad),最后通过单次正则词法扫描完成匹配与内容填充。

二、占位符设计规范与规则定义

为了让该工具函数具备通用的适应性,我们参考主流库(如 Day.js、date-fns)的常用命名惯例,制定一套直观且语义清晰的占位符规则。占位符主要区分“双字母补零”与“单字母不补零”两种形态:

封装一个通用的JS时间格式化函数支持自定义占位符

图2:常用占位符定义与映射规范表

在具体使用中,读者需要特别关注以下几个占位符的差异:

  • 年份标识:YYYY 输出完整的4位年份(如 2026),而 YY 仅截取后2位(如 26)。
  • 月份与日期的补零差异:MM 与 DD 统一采用 2 位数字显示,个位数前导补 0(如 05月09日);而 M 与 D 则保持原始数值(如 5月9日)。
  • 时制与秒数:HH 代表 24 小时制且补齐两位(00-23),而 mm 与 ss 分别代表分与秒;如果需要毫秒,可通过 SSS 输出 3 位数(000-999)。
  • 星期标识:W 支持直接输出中文星期(如 二 或 周二)。

三、两种实现方案的对比:为什么必须使用单正则匹配

在很多初学者尝试编写时间格式化函数时,最容易写出的代码是“链式连续替换”,即针对每个占位符依次调用 replace 方法。这里我们将链式替换与单正则词法替换在相同运行条件下的表现进行详细对比:

对比维度 方案 A:多次链式 replace 方案 B:单全局正则词法映射(推荐)
核心实现机制 str.replace(/YYYY/g, y).replace(/MM/g, m)... str.replace(/(YYYY|YY|...)/g, token => map[token])
级联污染隐患 存在严重污染风险。前序替换产出的数字可能与后续占位符产生误触 完全免疫。仅扫描原始字符串一次,各词法单元互不干扰
字符长短竞争 若先替换单字母 M,会破坏原有的 MM 模版标记 通过正则中长词优先分支(YYYY|YY、MM|M)天然保证精准匹配
字符串遍历开销 N 个占位符需要对字符串完整扫描并分配内存 N 次 仅对模版字符串进行一次单遍(Single-pass)扫描与构建
警惕级联污染的致命场景

假设用户传入自定义模版 "HH时mm分ss秒",若采用多次替换,先将 HH 替换为数字 12,若后续规则中有支持数字或者误将替换出的内容二次识别,或者当模版中包含其他字母时,前序生成的文本会成为后序替换的扫描目标,造成不可预测的乱码与数据破坏。单次全局正则扫描则完全运行在只读模版之上,从根源上杜绝了这类连环误判。

封装一个通用的JS时间格式化函数支持自定义占位符

图3:formatDate 核心执行与边界判定流程图

四、完整函数封装与步骤详解

按照上述设计原则,下面给出完整可直接运行的函数实现。代码包含入参类型校验、自动补零计算以及基于正则表达式的词法驱动替换。

1. 完整源码实现

/**
 * 通用时间格式化函数
 * @param {Date|number|string} time - 待格式化的时间(Date实例/时间戳/日期字符串)
 * @param {string} [formatStr='YYYY-MM-DD HH:mm:ss'] - 目标格式化模板
 * @returns {string} 格式化后的字符串,若入参无效则返回空字符串
 */
function formatDate(time, formatStr = 'YYYY-MM-DD HH:mm:ss') {
  // 步骤一:输入归一化与有效性校验
  if (time === null || time === undefined || time === '') {
    return '';
  }

  let date;
  if (time instanceof Date) {
    date = time;
  } else if (typeof time === 'number') {
    // 处理10位秒级时间戳兼容转化为13位毫秒
    date = new Date(time.toString().length === 10 ? time * 1000 : time);
  } else if (typeof time === 'string') {
    // 兼容 iOS 环境下部分日期字串 "YYYY-MM-DD" 需要转换为 "YYYY/MM/DD" 解析的问题
    const normalizedStr = time.trim().replace(/-/g, '/');
    date = new Date(normalizedStr);
    // 若转换后依然无效,尝试直接解析原字符串(兼容带T的标准ISO格式)
    if (isNaN(date.getTime())) {
      date = new Date(time);
    }
  } else {
    return '';
  }

  // 验证是否为合法有效日期
  if (isNaN(date.getTime())) {
    return '';
  }

  // 步骤二:提取基础时间分量
  const year = date.getFullYear();
  const month = date.getMonth() + 1;
  const day = date.getDate();
  const hours = date.getHours();
  const minutes = date.getMinutes();
  const seconds = date.getSeconds();
  const milliseconds = date.getMilliseconds();
  const weekDay = date.getDay();
  const weekDays = ['日', '一', '二', '三', '四', '五', '六'];

  // 辅助补零函数
  const padZero = (val, len = 2) => String(val).padStart(len, '0');

  // 步骤三:构建占位符字典映射表
  const tokenMap = {
    'YYYY': String(year),
    'YY': String(year).slice(-2),
    'MM': padZero(month),
    'M': String(month),
    'DD': padZero(day),
    'D': String(day),
    'HH': padZero(hours),
    'H': String(hours),
    'hh': padZero(hours % 12 || 12),
    'h': String(hours % 12 || 12),
    'mm': padZero(minutes),
    'm': String(minutes),
    'ss': padZero(seconds),
    's': String(seconds),
    'SSS': padZero(milliseconds, 3),
    'W': weekDays[weekDay]
  };

  // 步骤四:通过最长优先匹配的单次正则执行全局替换
  // 注意:长字符占位符必须置于短字符前面,以保证贪婪长词匹配
  const tokenRegex = /(YYYY|YY|MM|M|DD|D|HH|H|hh|h|mm|m|ss|s|SSS|W)/g;

  return formatStr.replace(tokenRegex, (match) => {
    return tokenMap[match] !== undefined ? tokenMap[match] : match;
  });
}

2. 调用示例与预期输出

以下示例展示了在不同业务场景下的调用方法及返回结果:

const targetDate = new Date('2026-11-17T08:05:03.045');

// 1. 标准年月日时分秒(示例输出: "2026-11-17 08:05:03")
console.log(formatDate(targetDate));

// 2. 自定义中文日期与星期(示例输出: "2026年11月17日 星期二")
console.log(formatDate(targetDate, 'YYYY年MM月DD日 星期W'));

// 3. 精确到毫秒的日志打印(示例输出: "2026-11-17 08:05:03.045")
console.log(formatDate(targetDate, 'YYYY-MM-DD HH:mm:ss.SSS'));

// 4. 非补零简写展示(示例输出: "26/11/17 8:5:3")
console.log(formatDate(targetDate, 'YY/M/D H:m:s'));

// 5. 支持时间戳输入(示例输出: "2026-11-17")
console.log(formatDate(targetDate.getTime(), 'YYYY-MM-DD'));

// 6. 异常输入防崩兜底(示例输出: "")
console.log(formatDate('invalid-date-string'));

五、注意事项与落地细节

虽然上述实现已经能够满足绝大部分日常业务需求,但在生产环境落地时,仍有以下几个重要细节值得注意:

  1. 正则中的长词分支顺序:构建正则时,YYYY 必须位于 YY 之前,MM 必须位于 M 之前。如果顺序写反,正则引擎在遇到 YYYY 时会优先匹配前两个字符为 YY,导致原本完整的年份被拆散识别,输出错误的内容。
  2. 月份从 0 开始的坑:date.getMonth() 返回值为 0-11,在填充字典时必须显式 + 1。
  3. 时区与本地时间:上述函数中的 getFullYear()、getHours() 均基于运行设备的“本地时区”。如果你的项目需要输出 UTC 时间或服务端统一时区的时间,可类似地替换为 getUTCFullYear()、getUTCHours(),或在入参处增加一个 isUTC 标识布尔值来切换取值策略。
  4. 字面量转义场景:如果格式模版中包含形如 [Today is] YYYY-MM-DD 这种本不希望被替换的英文字符(例如 is 中的 s 可能会被匹配为秒数),在高级场景下可以在正则前先将 \[(.*?)\] 提取为占位符缓存,完成替换后再还原文本。
封装一个通用的JS时间格式化函数支持自定义占位符

图4:时间格式化技术方案选型与全景评估

六、总结

封装一个通用的 JavaScript 时间格式化函数并不复杂,但要做到“轻量、健壮且无副作用”,关键在于理解词法解析机制。通过将输入规范为 Date 对象、提取对应时间维度、并在正则中采用长词优先策略实施单遍替换,既规避了多次链式替换带来的级联误伤缺陷,又避免了引入庞大的第三方库包袱,非常适合在工具库、中后台管理系统及移动端微应用中直接集成使用。

作者最新文章
相关文章
更多