Tempus Dominus版本迁移指南：从v5到v6的平滑过渡

Tempus Dominus是一款功能强大的日期时间选择器插件（Date/time picker widget），v6版本带来了重大改进，包括移除Moment.js、jQuery和Bootstrap依赖，默认使用Font Awesome 5图标，并采用Popper.js v2进行定位。本指南将帮助开发者从v5平稳迁移至v6，避免常见陷阱并充分利用新特性。

核心变更概述

v6版本的核心目标是精简依赖并提升性能，主要变更包括：

• 依赖移除：不再依赖Moment.js、jQuery和Bootstrap，降低项目体积
• 图标系统：默认使用Font Awesome 5（未来将迁移至Font Awesome 6）
• 定位引擎：采用Popper.js v2替代自定义定位逻辑
• API重构：配置项和事件系统全面优化，提升可扩展性

官方迁移文档：src/docs/partials/migration.html

环境准备与安装

依赖安装

v6需要Popper.js v2支持，通过npm安装核心包及必要依赖：

npm install @eonasdan/tempus-dominus popper.js

若使用Font Awesome图标，需单独安装：

npm install @fortawesome/fontawesome-free

目录结构变化

v6的源码结构更加清晰，主要功能模块位于src/js/目录下，按功能划分为：

• 核心逻辑：tempus-dominus.ts
• 日期处理：dates.ts
• 显示组件：display/目录
• 工具函数：utilities/目录

配置方式迁移

从jQuery插件到原生API

v5中通过jQuery初始化的方式已被移除，v6采用原生JavaScript API：

v5（jQuery方式）：

$('#datetimepicker1').datetimepicker({
  format: 'L'
});

v6（原生方式）：

const picker = new tempusDominus.TempusDominus(
  document.getElementById('datetimepicker1'),
  {
    format: 'yyyy-MM-dd'
  }
);

HTML结构调整

v6对HTML标记有明确要求，需包含数据属性指定目标元素：

v6推荐结构：

<div class="input-group" id="datetimepicker1">
  <input type="text" class="form-control" data-td-target="#datetimepicker1" />
  <span class="input-group-text" data-td-target="#datetimepicker1" data-td-toggle="datetimepicker">
    <span class="fas fa-calendar"></span>
  </span>
</div>

数据属性说明：

• data-td-target：指向选择器容器ID
• data-td-toggle：触发显示/隐藏的元素标记

核心功能迁移指南

日期格式化

v6移除了Moment.js依赖，采用自定义日期处理模块dates.ts，格式标记有所调整：

功能	v5（Moment格式）	v6（原生格式）
日期	'L' (MM/DD/YYYY)	'MM/dd/yyyy'
时间	'LT' (h:mm A)	'hh:mm a'
完整日期时间	'L LT'	'MM/dd/yyyy hh:mm a'

事件系统变更

v6重构了事件系统，采用更直观的命名和触发方式：

v5事件绑定：

$('#datetimepicker1').on('dp.change', function(e) {
  console.log(e.date);
});

v6事件绑定：

picker.on('change', (e) => {
  console.log(e.date);
});

完整事件列表可参考命名空间文档

本地化配置

v6的本地化文件位于src/js/locales/目录，支持20+种语言。使用方式如下：

import { fr } from '@eonasdan/tempus-dominus/dist/locales/fr';

const picker = new tempusDominus.TempusDominus(
  document.getElementById('datetimepicker1'),
  {
    localization: fr
  }
);

中文本地化文件：zh-CN.ts

常见问题与解决方案

图标显示异常

若Font Awesome图标无法显示，需检查：

1. 正确引入Font Awesome CSS
2. 使用v6兼容的图标类名（如fas fa-calendar而非fa fa-calendar）

日期范围选择

v6内置日期范围功能，无需额外插件：

const startPicker = new tempusDominus.TempusDominus(
  document.getElementById('startPicker'),
  {
    useCurrent: false
  }
);

const endPicker = new tempusDominus.TempusDominus(
  document.getElementById('endPicker'),
  {
    useCurrent: false
  }
);

startPicker.on('change', (e) => {
  endPicker.updateOptions({ restrictions: { minDate: e.date } });
});

日期范围选择界面：

迁移工具使用

官方提供了配置转换工具，可通过迁移页面在线转换v5配置为v6格式：

1. 粘贴v5配置到输入框
2. 点击转换按钮生成v6配置
3. 在REPL区域测试效果

高级功能与插件

自定义日期格式

v6支持通过插件扩展日期格式化能力，customDateFormat插件允许自定义解析规则：

import { CustomDateFormatPlugin } from '@eonasdan/tempus-dominus/dist/plugins/customDateFormat';

const picker = new tempusDominus.TempusDominus(
  document.getElementById('datetimepicker1'),
  {
    plugins: [new CustomDateFormatPlugin({
      formats: {
        'custom': 'yyyy年MM月dd日'
      }
    })]
  }
);

视图模式控制

v6提供多种日历视图，可通过API动态切换：

// 切换到年份视图
picker.show('years');

// 切换到时间选择视图
picker.show('time');

支持的视图模式包括：

• 日期视图：
• 时间视图：
• 十年视图：

测试与验证

单元测试

v6提供完善的测试用例，位于test/目录，可通过以下命令运行：

npm test

关键测试文件包括：

• dates.test.ts：日期处理测试
• validation.test.ts：输入验证测试

浏览器兼容性

v6支持现代浏览器，包括Chrome、Firefox、Edge最新版本，不支持IE11及以下。可通过浏览器支持文档查看详细兼容列表。

迁移 checklist

完成迁移后，建议按以下清单验证：

• [ ] 所有日期选择器已使用原生API初始化
• [ ] 移除jQuery和Moment.js依赖
• [ ] 验证所有事件处理逻辑正常工作
• [ ] 检查移动端响应式布局
• [ ] 测试本地化显示是否正确

官方变更日志：change-log.html

通过遵循本指南，可实现从Tempus Dominus v5到v6的平滑过渡，充分利用新特性提升应用性能和用户体验。迁移过程中遇到问题，可查阅完整文档或提交issue获取支持。