本文旨在解决 FullCalendar 应用中常见的两个问题：`refetchEvents()` 方法因变量作用域错误导致未定义，以及事件时间显示与实际存储时间存在偏差。通过调整 FullCalendar 实例的声明方式和配置 `timeZone` 选项，我们将详细阐述如何确保事件数据能够正确刷新并在用户界面上准确显示时间，从而提升日历功能的稳定性和用户体验。
FullCalendar 是一个功能强大的 JavaScript 日历库，广泛应用于日程管理和事件调度。然而，在实际开发中，开发者可能会遇到一些常见的挑战，例如事件数据无法正确刷新或时间显示不一致。本教程将深入探讨这两个问题的原因及其解决方案，并提供清晰的代码示例。
1. 解决 refetchEvents() 未定义错误
当尝试在事件添加或更新后调用 calendario1.refetchEvents() 刷新日历事件时，可能会遇到 Uncaught TypeError: Cannot read properties of undefined (reading 'refetchEvents') 错误。这通常是由于 JavaScript 变量作用域问题导致的。
1.1 问题分析
在提供的代码中，calendario1 变量在 document.addEventListener('DOMContentLoaded', function() { ... }); 回调函数内部使用 var 关键字声明：
document.addEventListener('DOMContentLoaded', function() {
var calendarEl = document.getElementById('calendario1');
// ... 其他配置
var calendario1 = new FullCalendar.Calendar(calendarEl, {
// ... 配置选项
});
// ...
});这意味着 calendario1 是一个局部变量，其作用域仅限于 DOMContentLoaded 回调函数内部。当在外部函数 agregarRegistro 中尝试访问 calendario1.refetchEvents() 时：
function agregarRegistro(registro) {
$.ajax({
// ...
success: function(msg) {
calendario1.refetchEvents(); // 此时 calendario1 在此作用域中是 undefined
},
// ...
});
}由于 agregarRegistro 函数无法访问 DOMContentLoaded 内部的局部变量 calendario1，因此会抛出 TypeError。
1.2 解决方案
要解决此问题，需要确保 calendario1 变量在 agregarRegistro 函数的调用范围内是可访问的。最直接的方法是将 calendario1 声明为全局变量，或者至少在两者共同的父级作用域中声明。
步骤：
- 在 DOMContentLoaded 回调函数外部声明 calendario1，使其成为一个全局变量。
- 在 DOMContentLoaded 回调函数内部初始化 calendario1 时，移除 var 关键字，表示是对已声明的全局变量进行赋值，而不是声明一个新的局部变量。
修改后的代码示例：
// 在全局作用域声明 calendario1
var calendario1;
document.addEventListener('DOMContentLoaded', function() {
var calendarEl = document.getElementById('calendario1');
// ... 其他配置
// 初始化 calendario1，不再使用 var 关键字
calendario1 = new FullCalendar.Calendar(calendarEl, {
timeZone: 'UTC', // 注意：此处的 timeZone 稍后会讨论
schedulerLicenseKey: 'CC-Attribution-NonCommercial-NoDerivatives',
initialView: 'resourceTimelineDay',
aspectRatio: 1.5,
locale: 'es',
headerToolbar: {
left: 'prev,next',
center: 'title',
right: 'resourceTimelineDay,resourceTimelineWeek,resourceTimelineMonth'
},
editable: true,
resourceAreaHeaderContent: 'Rooms',
resources: 'datoseventos.php?accion=listarempleados&taller=' + taller + '&user=' + user + '&user_filtro=' + userfiltro,
events: 'datoseventos.php?accion=listar&taller=' + taller + '&user=' + user + '&user_filtro=' + userfiltro,
// ... 其他 FullCalendar 配置
});
// 渲染日历
calendario1.render();
});
// 现在 agregarRegistro 函数可以正确访问全局的 calendario1 变量
function agregarRegistro(registro) {
$.ajax({
type: 'POST',
url: 'datoseventos.php?accion=agregar',
data: registro,
success: function(msg) {
calendario1.refetchEvents(); // 正常调用
},
error: function(error) {
// alert("Hay un problema:" + error);
calendario1.refetchEvents(); // 正常调用
}
});
}通过这种修改，calendario1 变量在整个脚本中都是可访问的，从而解决了 refetchEvents() 未定义的问题。
2. 修正 FullCalendar 事件时间显示偏差
另一个常见问题是 FullCalendar 显示的事件时间与数据库中存储的时间不一致。例如，数据库存储 2023-06-16T07:00:00Z (UTC 时间上午 7 点)，但在模态框或控制台输出中却显示为 09:00。
2.1 问题分析
这种时间偏差通常与时区处理有关。FullCalendar 提供了 timeZone 选项来控制日历如何解释和显示事件时间。
- 数据库存储： 您的数据库将事件时间存储为 2023-06-16T07:00:00Z。这里的 Z 表示 Zulu time，即 UTC (协调世界时)。
- FullCalendar 配置： 原始 FullCalendar 配置中设置了 timeZone: 'UTC'。这意味着 FullCalendar 会将所有事件时间视为 UTC 时间。
- 用户本地时区： 如果用户浏览器所在的本地时区比 UTC 晚（例如，UTC+2），那么当 FullCalendar 内部处理或使用 moment.js 等库将 UTC 时间转换为本地时间显示时，就会出现偏差。例如，UTC 上午 7 点在 UTC+2 时区就是上午 9 点。
在 eventClick 回调中，moment(info.event.start).format("HH:mm") 这行代码会根据当前浏览器环境的本地时区来格式化时间，如果 FullCalendar 本身已经将 UTC 事件时间转换成了本地时间，或者 moment 默认进行转换，就会出现这种偏差。
2.2 解决方案
要使 FullCalendar 显示与用户本地时区一致的时间，最简单的方法是将 timeZone 选项设置为 'local'。
修改 FullCalendar 配置：
将 FullCalendar 配置中的 timeZone: 'UTC' 修改为 timeZone: 'local'：
document.addEventListener('DOMContentLoaded', function() {
var calendarEl = document.getElementById('calendario1');
// ...
calendario1 = new FullCalendar.Calendar(calendarEl, {
timeZone: 'local', // 将时区设置为本地时区
schedulerLicenseKey: 'CC-Attribution-NonCommercial-NoDerivatives',
initialView: 'resourceTimelineDay',
aspectRatio: 1.5,
locale: 'es',
headerToolbar: {
left: 'prev,next',
center: 'title',
right: 'resourceTimelineDay,resourceTimelineWeek,resourceTimelineMonth'
},
editable: true,
resourceAreaHeaderContent: 'Rooms',
resources: 'datoseventos.php?accion=listarempleados&taller=' + taller + '&user=' + user + '&user_filtro=' + userfiltro,
events: 'datoseventos.php?accion=listar&taller=' + taller + '&user=' + user + '&user_filtro=' + userfiltro,
// ... 其他 FullCalendar 配置
});
calendario1.render();
});通过将 timeZone 设置为 'local'，FullCalendar 会自动将从服务器获取的事件时间（即使是 UTC 格式）转换为用户浏览器所在的本地时区进行显示。这样，数据库中的 07:00:00Z 就会在 UTC+2 的环境中被正确地显示为 09:00，与 moment 格式化后的结果一致。
2.3 注意事项与最佳实践
-
timeZone 选项：
- 'UTC'：所有事件时间都按照 UTC 进行解释和显示。
- 'local'：所有事件时间都按照用户浏览器的本地时区进行解释和显示。
- 特定时区字符串（如 'America/New_York'）：所有事件时间都按照指定的时区进行解释和显示。
- 选择哪个选项取决于您的应用需求。如果您的用户分布在全球各地，并且希望每个人都看到其本地时间，那么 'local' 是一个好的选择。如果希望所有用户都看到统一的某个特定时区的时间，则应指定该时区。
- 后端与前端一致性： 确保后端在存储和发送时间数据时也遵循一致的时区策略。通常，将所有时间在后端存储为 UTC 是一个最佳实践，然后在前端根据用户偏好进行转换。
- moment.js 或 Luxon： 在处理日期和时间时，使用像 moment.js (如示例所示) 或 Luxon 这样的库非常有用，它们提供了强大的时区处理和格式化功能。确保在获取和设置日期/时间输入字段时，也考虑时区转换。例如，当从 info.event.start 获取时间并填充到模态框的输入字段时，如果 FullCalendar 已经处理了时区，那么 moment() 应该直接使用该时间，而不是再次进行不必要的时区转换。
总结
通过正确管理 JavaScript 变量的作用域，可以避免 refetchEvents() 等方法未定义的错误，确保 FullCalendar 实例在需要时始终可访问。同时，合理配置 FullCalendar 的 timeZone 选项，能够有效解决事件时间显示不准确的问题，为用户提供准确且符合其本地习惯的日程视图。在开发 FullCalendar 应用时，理解并应用这些原则对于构建健壮且用户友好的日历功能至关重要。
