TOAST UI Calendar v2 迁移指南：从概念到实践-优快云博客

TOAST UI Calendar v2 迁移指南：从概念到实践

前言

TOAST UI Calendar 作为一款功能强大的日历组件，在 v2 版本中进行了重大架构升级。本文将深入解析 v2 版本的核心变化，帮助开发者顺利完成迁移工作。我们将从技术架构、API 设计、性能优化等多个维度进行全面剖析。

架构升级解析

渲染引擎革命

v2 版本最显著的改变是采用了 Preact 作为渲染引擎，取代了 v1 版本的直接 DOM 操作。这一变化带来了三大优势：

虚拟 DOM 机制：通过差异比对算法减少不必要的 DOM 操作
渲染性能提升：复杂场景下的操作流畅度显著提高
未来扩展性：为服务端渲染(SSR)奠定了基础

包管理变更

命名规范调整

v2 版本对包名称和文件命名进行了标准化处理：

| 版本 | 包名称 | CSS 文件 | JS 文件 | |------|--------|----------|---------| | v1 | tui-calendar | tui-calendar.css | tui-calendar.js | | v2 | @toast-ui/calendar | toastui-calendar.css | toastui-calendar.js |

安装方式对比

# v1 版本安装
npm install tui-calendar@1.15.0

# v2 版本安装
npm install @toast-ui/calendar

CDN 结构调整

v2 版本重新组织了 CDN 目录结构，新旧版本对比：

cdn.toast.com/
├─ tui-calendar/  # v1 专用目录
│  └─ latest/     # v1 最新版本
└─ calendar/      # v2+ 目录
   └─ latest/     # 最新稳定版
      ├─ toastui-calendar.min.css
      ├─ toastui-calendar.min.js
      └─ toastui-calendar.ie11.min.js # IE11 专用包

浏览器兼容性策略

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

| 版本 | 支持范围 | 特别说明 | |------|----------|----------| | v1 | IE9+ | 广泛兼容 | | v2 | IE11+ | 默认包不含 polyfill |

对于需要支持 IE11 的项目，需特别引入兼容包：

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

注意：IE11 专用包体积比默认包大约 30%，请按需使用。

API 迁移详解

术语标准化

v2 版本对核心术语进行了统一规范：

| v1 术语 | v2 术语 | 说明 | |---------|---------|------| | schedule | event | 统一使用"事件"概念 | | currentTimeIndicator/currentTimeLine | nowIndicator | 当前时间指示器 | | creationGuide | gridSelection | 日期/时间选择区域 | | vpanelSplitter | panelResizer | 面板调节器 |

功能增强

主题系统升级

v2 的主题系统采用了更合理的嵌套对象结构：

// v1 平面结构
calendar.setTheme({
  'common.dayName.color': '#333'
});

// v2 嵌套结构
calendar.setTheme({
  common: {
    dayName: {
      color: '#333'
    }
  }
});

视图类型强化

v2 明确了三种视图类型：

month - 月视图
week - 周视图
day - 日视图

相关 API 的类型定义更加严格，如 changeView() 和 getViewName() 方法。

任务/事件视图配置

周/日视图的显示配置更加直观：

const calendar = new Calendar('#calendar', {
  week: {
    taskView: ['milestone', 'task'], // 任务视图配置
    eventView: ['allday', 'time']    // 事件视图配置
  }
});

重要变更点

选项调整

部分选项位置或名称发生变化：

| v1 选项 | v2 变更位置 | 备注 | |---------|-------------|------| | disableDblClick | gridSelection.enableDblClick | 默认值反转 | | month.isAlways6Week | month.isAlways6Weeks | 拼写修正 | | timezone.offsetCalculator | timezone.customOffsetCalculator | 更名 |

方法变更

关键方法更新：

// 事件表单弹窗
v1: calendar.openCreationPopup(schedule);
v2: calendar.openFormPopup(event);

// 日历可见性控制
v1: calendar.toggleSchedules('cal1', true);
v2: calendar.setCalendarVisibility('cal1', false);