TOAST UI Calendar v2 迁移指南：从v1升级到v2的最佳实践

TOAST UI Calendar v2 迁移指南：从v1升级到v2的最佳实践

tui.calendar 🍞📅A JavaScript calendar that has everything you need. 项目地址: https://gitcode.com/gh_mirrors/tu/tui.calendar

前言

TOAST UI Calendar 是一款功能强大的JavaScript日历组件，广泛应用于各类Web应用中。随着v2版本的发布，该组件在性能、功能和开发体验上都有了显著提升。本文将详细介绍如何从v1版本平滑迁移到v2版本，帮助开发者理解变更内容并顺利完成升级。

安装变更

包名和文件名变更

v2版本对包名和文件命名进行了标准化调整：

1. npm包名变更：

   # v1版本安装方式
   npm install tui-calendar@1.15.0
   
   # v2版本安装方式
   npm install @toast-ui/calendar
   

2. 模块导入变更：

   // v1版本导入方式
   import Calendar from 'tui-calendar';
   import "tui-calendar/dist/tui-calendar.min.css";
   
   // v2版本导入方式
   import Calendar from '@toast-ui/calendar';
   import '@toast-ui/calendar/dist/toastui-calendar.min.css';
   

3. CDN引用变更：

   <!-- v1版本CDN引用 -->
   <link rel="stylesheet" href="//uicdn.toast.com/tui-calendar/latest/tui-calendar.min.css"/>
   <script src="//uicdn.toast.com/tui-calendar/latest/tui-calendar.min.js"></script>
   
   <!-- v2版本CDN引用 -->
   <link rel="stylesheet" href="//uicdn.toast.com/calendar/latest/toastui-calendar.min.css"/>
   <script src="//uicdn.toast.com/calendar/latest/toastui-calendar.min.js"></script>
   

CDN目录结构调整

v2版本对CDN目录结构进行了优化，现在所有v2及以上版本的文件都存放在/calendar/目录下，而v1版本的文件则保留在/tui-calendar/目录中。

浏览器支持变更

v2版本调整了浏览器支持策略：

• 最低支持版本：Internet Explorer 11+
• 现代浏览器：支持最新两个版本的Chrome、Firefox、Safari和Edge

对于IE11用户，需要特别引入兼容版本：

import Calendar from '@toast-ui/calendar/ie11';

注意：IE11专用包体积比标准包大约30%，请根据实际需求选择。

API迁移指南

术语变更

1. Schedule → Event： v2版本中将"schedule"统一改为"event"，所有相关API都进行了相应调整。

2. 时间指示器命名统一：

   • currentTimeIndicator → nowIndicator
   • currentTimeLine → nowIndicator

3. 其他术语变更：

   • creationGuide → gridSelection
   • vpanelSplitter → panelResizer
   • 视图名称统一为dayGrid、timeGrid等

功能改进

渲染优化

v2版本采用Preact进行虚拟DOM渲染，带来了显著的性能提升：

• 移除了force、silent等渲染控制参数
• 自动优化渲染流程，减少不必要的重绘
• 为未来支持SSR奠定了基础

主题系统改进

v2版本的主题系统进行了重构：

1. 配置方式变更：

   // v1版本主题设置
   calendar.setTheme({
     'common.dayName.color': '#333',
   });
   
   // v2版本主题设置
   calendar.setTheme({
     common: {
       dayName: {
         color: '#333',
       },
     },
   });
   

2. 移除的主题属性：

   • 大部分尺寸和布局相关属性
   • 字体相关属性
   • 颜色属性保留，其他样式建议通过CSS控制

类型系统增强

v2版本对类型系统进行了多项改进：

1. 视图类型明确化：

   type ViewType = 'month' | 'week' | 'day';
   

2. 任务和事件视图类型优化：

   const calendar = new Calendar('#calendar', {
     week: {
       taskView: ['task'],  // 显示任务面板
       eventView: ['time'], // 仅显示时间面板
     },
   });
   

API变更详情

选项变更

| v1选项 | v2选项 | 变更说明 | |--------|--------|----------| | taskView | week.taskView | 移动到week配置项下 | | disableDblClick | gridSelection.enableDblClick | 默认值从false改为true | | month.isAlways6Week | month.isAlways6Weeks | 拼写修正 | | month.daynames | month.dayNames | 命名规范化 |

方法变更

1. 表单弹窗方法：

   // v1
   calendar.openCreationPopup(schedule);
   
   // v2
   calendar.openFormPopup(event);
   

2. 日历可见性控制：

   // v1
   calendar.toggleSchedules('1', true);
   
   // v2
   calendar.setCalendarVisibility('1', false);
   

事件变更

// v1
calendar.on('clickMore', callback);

// v2
calendar.on('clickMoreEventsBtn', callback);

模板变更

timegridCurrentTime模板更名为timegridNowIndicatorLabel。

移除的功能

1. 不再支持：

   • Bower包管理
   • jQuery插件形式
   • IE9/IE10支持

2. 移除的渲染参数：

   • force
   • silent
   • immediately

迁移建议

1. 逐步迁移：

   • 先更新包引用
   • 然后处理术语变更
   • 最后调整主题和样式

2. 测试重点：

   • 事件处理逻辑
   • 自定义模板
   • 浏览器兼容性

3. 性能优化：

   • 利用v2的自动渲染优化
   • 减少手动DOM操作

通过遵循本指南，开发者可以顺利完成从v1到v2版本的迁移，并充分利用v2版本的新特性和性能改进。如果在迁移过程中遇到问题，建议参考官方文档或社区讨论获取更多帮助。

tui.calendar 🍞📅A JavaScript calendar that has everything you need. 项目地址: https://gitcode.com/gh_mirrors/tu/tui.calendar