首页 > 网络编程 > JavaScript > javascript技巧 > JavaScript时间处理插件

基于JavaScript优雅的实现一个时间处理插件

2025-10-29 08:28:23 作者：会联营的陆逊

这篇文章主要介绍了如何优雅地实现一个时间处理插件,包括UMD模式、单例模式的实现,以及插件的初始化、方法（如getDate、setDate、format、parse）的定义和使用,文章还涵盖了格式化标记、解析流程、常见场景和性能优化建议,需要的朋友可以参考下

1. UMD 模式解析

1.1 立即执行函数 (IIFE)

外层是一个立即执行函数，接收 global 和 factory 两个参数。

global 参数说明：

typeof window !== "undefined" ? window : this;

根据不同的运行环境，global 参数会指向：

浏览器环境：window 对象
Node.js 环境：global 对象
其他环境：当前上下文 this

1.2 UMD 模块定义

通过条件判断支持多种模块系统：

if (typeof define === "function" && define.amd) {
  // AMD 模式 (RequireJS)
  define(function () {
    return factory();
  });
} else if (typeof module === "object" && module.exports) {
  // CommonJS 模式 (Node.js)
  module.exports = factory();
} else {
  // 浏览器全局变量模式
  global.SurveyTimezone = factory();
}

支持的模块系统：

AMD：用于 RequireJS 等加载器
CommonJS：用于 Node.js 环境
全局变量：用于直接在浏览器中使用

1.3 工厂函数解析

工厂函数 factory 返回插件的构造函数：

function () {
    'use strict';

    // 构造函数定义
    function SurveyTimezone(options) {
    }

    // 原型方法定义
    SurveyTimezone.prototype = {
        constructor: SurveyTimezone, // 修复 constructor 指向
        version: '1.0.0',
        _init: function () {
        }
    }

    // 返回构造函数
    return SurveyTimezone;
}

核心组成部分：

严格模式：使用 'use strict' 确保代码质量
构造函数：定义 SurveyTimezone 类
原型方法：通过原型链添加共享方法
返回值：导出构造函数供外部使用

1.4 执行流程

UMD 模块的加载和执行流程：

立即执行：代码加载后立即执行 IIFE
环境检测：检测当前支持的模块系统（AMD / CommonJS / 全局变量）
工厂调用：执行 factory() 函数，返回 SurveyTimezone 构造函数
模块导出：根据环境将构造函数导出到相应位置

(function (global, factory) {
    // 环境检测和模块导出逻辑
}(typeof window !== "undefined" ? window : this, function () {
    // 工厂函数：创建并返回构造函数
}));

2. 单例模式实现

2.1 为什么使用单例模式？

在时区处理插件中，我们通常只需要一个全局实例来管理配置和状态：

避免重复实例：防止多次实例化造成的内存浪费
全局状态管理：统一管理时区配置、数据映射表等
配置一致性：确保整个应用使用相同的时区设置

2.2 单例模式实现

2.2.1 私有实例存储

// 闭包中的私有变量，存储单例实例
var instance = null;

2.2.2 构造函数实现

function SurveyTimezone(options) {
    // 1. 如果已存在实例，直接返回
    if (instance) {
        return instance;
    }
    
    // 2. 确保通过 new 调用
    if (!(this instanceof SurveyTimezone)) {
        return new SurveyTimezone(options);
    }
    
    // 3. 初始化配置
    this.options = options || {};
    
    // 4. 保存单例实例
    instance = this;
    
    // 5. 执行初始化
    this._init();
    
    return instance;
}

实现要点：

实例检查：首次检查是否已存在实例，有则直接返回
new 检查：确保即使不用 new 关键字也能正常工作
配置初始化：保存传入的配置选项
实例保存：将当前实例保存到闭包变量中
初始化执行：调用内部初始化方法

2.2.3 静态方法

/**
 * 获取单例实例
 */
SurveyTimezone.getInstance = function (options) {
    if (!instance) {
        instance = new SurveyTimezone(options);
    }
    return instance;
}

/**
 * 重置单例（用于测试）
 */
SurveyTimezone.resetInstance = function () {
    instance = null;
}

2.3 使用方式

方式一：使用 new 关键字

const instance1 = new SurveyTimezone({ timezone: 'Asia/Shanghai' });
const instance2 = new SurveyTimezone({ timezone: 'America/New_York' });

console.log(instance1 === instance2); // true（返回同一个实例）

方式二：使用 getInstance 静态方法

const instance = SurveyTimezone.getInstance({ timezone: 'Asia/Shanghai' });

方式三：不使用 new（自动转换）

const instance = SurveyTimezone({ timezone: 'Asia/Shanghai' });

2.4 单例模式的优势

优势	说明
内存优化	只创建一个实例，减少内存占用
状态一致	全局共享同一个实例，避免状态不一致
易于管理	集中管理配置和数据
防止冲突	避免多个实例之间的配置冲突

2.5 完整示例

// 第一次创建实例
const timezone1 = new SurveyTimezone({ 
    timezone: 'Asia/Shanghai',
    locale: 'zh-CN'
});

// 第二次尝试创建（返回第一次的实例）
const timezone2 = new SurveyTimezone({ 
    timezone: 'America/New_York'  // 这个配置会被忽略
});

console.log(timezone1 === timezone2);        // true
console.log(timezone1.options.timezone);     // 'Asia/Shanghai'

// 重置单例后可以创建新实例
SurveyTimezone.resetInstance();
const timezone3 = new SurveyTimezone({ 
    timezone: 'Europe/London'
});

console.log(timezone1 === timezone3);        // false
console.log(timezone3.options.timezone);     // 'Europe/London'

2.6 初始化时传入日期时间

从 v1.0.0 开始，SurveyTimezone 支持在初始化时传入日期时间字符串或时间戳，使其更加灵活实用。

2.6.1 初始化方式

构造函数签名：

new SurveyTimezone(input, format)

参数说明：

参数	类型	必填	说明
`input`	`string\|number\|Date\|Object`	❌	日期时间字符串、时间戳、Date对象或配置对象
`format`	`string`	❌	日期格式（当 input 为字符串时使用）

2.6.2 初始化示例

方式1：传入日期字符串

const tz = new SurveyTimezone('2025-10-28 14:30:45');
console.log(tz.getDate());      // Date 对象
console.log(tz.format());       // '2025-10-28 14:30:45'

方式2：传入时间戳

const tz = new SurveyTimezone(1698484245000);
console.log(tz.getDate());      // Date 对象
console.log(tz.format());       // 对应的日期时间字符串

方式3：传入日期字符串和格式

const tz = new SurveyTimezone('28/10/2025', 'DD/MM/YYYY');
console.log(tz.format('YYYY-MM-DD'));  // '2025-10-28'

方式4：传入 Date 对象

const tz = new SurveyTimezone(new Date());
console.log(tz.format());       // 当前时间

方式5：传入配置对象

const tz = new SurveyTimezone({
    date: '2025-10-28 14:30:45',
    timezone: 'Asia/Shanghai',
    locale: 'zh-CN'
});
console.log(tz.getDate());      // Date 对象
console.log(tz.options);        // { date: '...', timezone: '...', locale: '...' }

方式6：不传参数（默认当前时间）

const tz = new SurveyTimezone();
console.log(tz.format());       // 当前时间

2.6.3 新增实例方法

getDate() - 获取日期对象

const tz = new SurveyTimezone('2025-10-28 14:30:45');
const date = tz.getDate();
console.log(date);  // Date 对象

setDate() - 设置日期（支持链式调用）

const tz = new SurveyTimezone();

// 设置新日期
tz.setDate('2025-12-25 00:00:00');
console.log(tz.format());  // '2025-12-25 00:00:00'

// 链式调用
const result = tz.setDate('2026-01-01').format('YYYY/MM/DD');
console.log(result);  // '2026/01/01'

2.6.4 format 方法增强

现在 format 方法可以在不传参数时格式化实例的日期：

const tz = new SurveyTimezone('2025-10-28 14:30:45');

// 格式化实例日期（无参数）
tz.format();                    // '2025-10-28 14:30:45'（默认格式）

// 格式化实例日期（指定格式）
tz.format('YYYY年MM月DD日');    // '2025年10月28日'

// 格式化指定日期
tz.format(new Date(), 'YYYY-MM-DD');  // 格式化其他日期

2.6.5 完整工作流示例

// 场景：接收用户输入 → 解析 → 处理 → 格式化输出

// 1. 用户输入欧洲格式日期
const userInput = '28/10/2025';

// 2. 创建实例并解析
const tz = new SurveyTimezone(userInput, 'DD/MM/YYYY');

// 3. 验证解析结果
console.log(tz.getDate());  // Date 对象

// 4. 格式化为不同格式输出
console.log(tz.format('YYYY-MM-DD'));      // '2025-10-28'（ISO格式）
console.log(tz.format('YYYY年MM月DD日'));  // '2025年10月28日'（中文）
console.log(tz.format('MMM DD, yyyy'));    // 'Oct 28, 2025'（英文）

// 5. 修改日期并重新格式化
tz.setDate('2025-12-25');
console.log(tz.format('YYYY年MM月DD日'));  // '2025年12月25日'

2.6.6 与单例模式的配合

由于采用单例模式，第一次初始化时传入的日期会被保存，后续创建实例会返回同一个实例：

// 第一次创建，指定日期
const tz1 = new SurveyTimezone('2025-10-28 14:30:45');
console.log(tz1.format());  // '2025-10-28 14:30:45'

// 第二次创建，尝试传入不同日期（但返回的是同一个实例）
const tz2 = new SurveyTimezone('2026-01-01 00:00:00');
console.log(tz2.format());  // '2025-10-28 14:30:45'（仍然是第一次的日期）
console.log(tz1 === tz2);   // true（同一个实例）

// 如果需要新的日期，可以使用 setDate 方法
tz2.setDate('2026-01-01 00:00:00');
console.log(tz2.format());  // '2026-01-01 00:00:00'
console.log(tz1.format());  // '2026-01-01 00:00:00'（tz1 也变了，因为是同一个实例）

// 或者先重置单例
SurveyTimezone.resetInstance();
const tz3 = new SurveyTimezone('2026-01-01 00:00:00');
console.log(tz3.format());  // '2026-01-01 00:00:00'（新实例，新日期）

2.6.7 错误处理

当传入无效日期时，会自动使用当前时间：

// 无效日期字符串
const tz1 = new SurveyTimezone('invalid date');
console.log(tz1.getDate());  // 当前时间的 Date 对象

// 重置单例
SurveyTimezone.resetInstance();

// 无效时间戳
const tz2 = new SurveyTimezone(NaN);
console.log(tz2.getDate());  // 当前时间的 Date 对象

2.6.8 方法对比表

方法	类型	参数	返回值	说明
`new SurveyTimezone(input, format)`	构造函数	日期输入	实例	创建实例并初始化日期
`getDate()`	实例方法	-	Date	获取实例的日期对象
`setDate(input, format)`	实例方法	日期输入	this	设置实例日期，支持链式调用
`format(date, format)`	实例方法	可选	string	格式化日期（无参数时格式化实例日期）
`parse(dateString, format)`	实例方法	必填	Date\|null	解析日期字符串

3. format 方法详解

3.1 方法说明

format 方法用于格式化日期对象，兼容 dayjs 和 laydate 两种流行的日期格式化风格。

方法签名：

// 原型方法
instance.format(date, format)

// 静态方法（向后兼容）
SurveyTimezone.format(date, format)

参数：

参数	类型	必填	默认值	说明
`date`	`Date`	✅	-	要格式化的 JavaScript Date 对象
`format`	`string`	❌	`'YYYY-MM-DD HH:mm:ss'`	格式化模板字符串

返回值：

类型：string
说明：格式化后的日期字符串，无效日期返回空字符串 ''

3.2 支持的格式化标记

3.2.1 年份标记

标记	说明	示例输出	兼容性
`YYYY`	四位年份	2025	dayjs
`yyyy`	四位年份	2025	laydate
`YY`	两位年份	25	dayjs
`y`	两位年份	25	laydate

3.2.2 月份标记

标记	说明	示例输出	兼容性
`MMM`	英文月份缩写	Jan, Feb, Mar...	通用
`MM`	两位月份（补零）	01, 02... 12	通用
`M`	月份（不补零）	1, 2... 12	通用

3.2.3 日期标记

标记	说明	示例输出	兼容性
`DD`	两位日期（补零）	01, 02... 31	dayjs
`dd`	两位日期（补零）	01, 02... 31	laydate
`D`	日期（不补零）	1, 2... 31	dayjs
`d`	日期（不补零）	1, 2... 31	laydate

3.2.4 时间标记

标记	说明	示例输出	兼容性
`HH`	24小时制小时（补零）	00, 01... 23	通用
`H`	24小时制小时（不补零）	0, 1... 23	通用
`mm`	分钟（补零）	00, 01... 59	通用
`m`	分钟（不补零）	0, 1... 59	通用
`ss`	秒（补零）	00, 01... 59	通用
`s`	秒（不补零）	0, 1... 59	通用

3.2.5 毫秒标记

标记	说明	示例输出	兼容性
`SSS`	三位毫秒	000, 001... 999	dayjs

3.3 使用示例

3.3.1 基础用法

const tz = new SurveyTimezone();
const now = new Date('2025-10-28 14:30:45.123');

// 默认格式
tz.format(now);  // '2025-10-28 14:30:45'

// 自定义格式
tz.format(now, 'YYYY/MM/DD');  // '2025/10/28'
tz.format(now, 'HH:mm:ss');    // '14:30:45'

3.3.2 dayjs 风格格式

const tz = new SurveyTimezone();
const now = new Date('2025-10-28 14:30:45.123');

tz.format(now, 'YYYY-MM-DD HH:mm:ss');      // '2025-10-28 14:30:45'
tz.format(now, 'YYYY-MM-DD HH:mm:ss.SSS');  // '2025-10-28 14:30:45.123'
tz.format(now, 'YY/M/D H:m:s');             // '25/10/28 14:30:45'
tz.format(now, 'MMM DD, YYYY');             // 'Oct 28, 2025'

3.3.3 laydate 风格格式

const tz = new SurveyTimezone();
const now = new Date('2025-10-28 14:30:45');

tz.format(now, 'yyyy-MM-dd HH:mm:ss');  // '2025-10-28 14:30:45'
tz.format(now, 'yyyy年MM月dd日');        // '2025年10月28日'
tz.format(now, 'y-M-d H:m:s');          // '25-10-28 14:30:45'
tz.format(now, 'dd/MM/yyyy');           // '28/10/2025'

3.3.4 中文日期格式

const tz = new SurveyTimezone();
const now = new Date('2025-10-28 14:30:45');

tz.format(now, 'YYYY年MM月DD日');               // '2025年10月28日'
tz.format(now, 'YYYY年MM月DD日 HH时mm分ss秒');   // '2025年10月28日 14时30分45秒'
tz.format(now, 'yyyy年MM月dd日 HH:mm');         // '2025年10月28日 14:30'

3.3.5 静态方法调用（无需实例化）

const now = new Date('2025-10-28 14:30:45');

// 直接使用静态方法
SurveyTimezone.format(now, 'YYYY-MM-DD');      // '2025-10-28'
SurveyTimezone.format(now, 'yyyy年MM月dd日');  // '2025年10月28日'
SurveyTimezone.format(now, 'MMM DD, yyyy');    // 'Oct 28, 2025'

3.4 常用格式模板

格式模板	输出示例	使用场景
`YYYY-MM-DD`	2025-10-28	标准日期格式
`YYYY-MM-DD HH:mm:ss`	2025-10-28 14:30:45	完整日期时间
`yyyy年MM月dd日`	2025年10月28日	中文日期
`MMM DD, yyyy`	Oct 28, 2025	英文日期
`YYYY/MM/DD HH:mm`	2025/10/28 14:30	简短日期时间
`HH:mm:ss`	14:30:45	仅时间
`YY-M-D`	25-10-28	简短日期
`YYYY-MM-DD HH:mm:ss.SSS`	2025-10-28 14:30:45.123	带毫秒

3.5 错误处理

const tz = new SurveyTimezone();

// 无效日期返回空字符串
tz.format(null);                    // ''
tz.format(undefined);               // ''
tz.format(new Date('invalid'));     // ''
tz.format('2025-10-28');            // ''（字符串不是 Date 对象）

// 有效日期
tz.format(new Date());              // '2025-10-28 14:30:45'（当前时间）

3.6 实现原理

format 方法采用正则替换策略实现格式化：

标记解析：将格式字符串中的标记（如 YYYY、MM）识别出来
长度优先：按标记长度从长到短处理，避免 YYYY 被 YY 误替换
顺序处理：依次替换每个标记为对应的日期值
类型转换：使用 JavaScript Date 对象的原生方法获取年、月、日等值

关键代码逻辑：

// 标记处理顺序（长的在前，短的在后）
var tokens = ['YYYY', 'yyyy', 'MMM', 'SSS', 'MM', 'DD', 'dd', 'HH', 'mm', 'ss', 'YY', 'M', 'D', 'd', 'H', 'm', 's', 'y'];

// 依次替换每个标记
for (var i = 0; i < tokens.length; i++) {
    var token = tokens[i];
    if (result.indexOf(token) !== -1) {
        result = result.replace(new RegExp(token, 'g'), matches[token]());
    }
}

3.7 原型方法 vs 静态方法

特性	原型方法	静态方法
调用方式	`instance.format()`	`SurveyTimezone.format()`
是否需要实例化	✅ 需要	❌ 不需要
访问实例属性	✅ 可以	❌ 不可以
推荐使用场景	面向对象编程	工具函数调用
性能	略优	略低（多一层调用）

关系说明：

静态方法内部调用原型方法实现
两种方式返回结果完全一致
静态方法保证向后兼容性

// 静态方法实现（调用原型方法）
SurveyTimezone.format = function (date, format) {
    return SurveyTimezone.prototype.format.call(null, date, format);
}

4. parse 方法详解

4.1 方法说明

parse 方法用于将日期时间字符串解析为 JavaScript Date 对象，支持多种常见格式的自动识别。