本教程详细介绍了如何在 fullcalendar 3 中有效地集成来自 php 后端的多个事件数据。我们将探讨 fullcalendar 期望的事件数据格式，演示如何正确构建和转换 php 数组，并通过 `json_encode` 直接注入 javascript。更进一步，文章推荐并详细说明了使用 fullcalendar 的 json feed 机制，以实现更灵活、可扩展的事件数据管理。

FullCalendar 事件数据格式理解

FullCalendar 是一个功能强大的 JavaScript 日历库，用于在网页上显示事件。为了正确渲染事件，FullCalendar 期望事件数据以特定的 JSON 数组格式提供，其中每个元素都是一个事件对象。一个基本的事件对象至少需要包含 title（事件标题）和 start（事件开始日期/时间）属性。

例如，一个包含多个事件的 JavaScript 数组示例如下：

events: [
  {
    title: '全天事件',
    start: '2025-12-02'
  },
  {
    title: '长期事件',
    start: '2025-12-02',
    end: '2025-12-04'
  },
  {
    title: '点击跳转谷歌',
    url: 'https://google.com/',
    start: '2025-12-24'
  }
]

可以看到，events 选项接收的是一个数组，数组的每个元素都是一个 JavaScript 对象，代表一个独立的事件。

PHP 数组的构建与转换

当我们需要从 PHP 后端获取事件数据时，关键在于将 PHP 数组转换为 FullCalendar 能够理解的 JSON 格式。

最初，如果 PHP 数组的结构是键值对形式，例如：

$arrayDate = [
  "2025-12-02" => "SG-12345-0 : xx, yy",
  "2025-12-03" => "SG-156645-0 : aa, bb",
  "2025-12-02" => "SG-13435-0 : cc, dd", // 注意：PHP 数组键不能重复，此例中第二个 "2025-12-02" 会覆盖第一个
  "2025-12-04" => "SG-76864-0 : ee, ff"
];

这种结构无法直接用于 FullCalendar，因为它的键是日期，值是标题，而不是 FullCalendar 期望的包含 title 和 start 属性的对象数组。此外，PHP 数组的键不能重复，如果存在重复日期，则后面的值会覆盖前面的。

为了符合 FullCalendar 的要求，PHP 数组必须构建成一个包含多个关联数组（代表事件对象）的索引数组。每个关联数组应包含 start 和 title 等 FullCalendar 事件对象属性。

以下是正确的 PHP 数组结构示例：

 "2025-12-02", "title" => "SG-12345-0 : xx, yy"],
  ["start" => "2025-12-03", "title" => "SG-156645-0 : aa, bb"],
  ["start" => "2025-12-02", "title" => "SG-13435-0 : cc, dd"],
  ["start" => "2025-12-04", "title" => "SG-76864-0 : ee, ff"]
];
?>

将 PHP 数据注入 FullCalendar

有了正确结构的 PHP 数组后，我们可以使用 json_encode() 函数将其转换为 JSON 字符串，并直接在 HTML/JavaScript 中输出。

在 FullCalendar 配置中，将 events 选项设置为 json_encode() 后的 PHP 数组：

这种方法适用于事件数量不多且页面加载时一次性获取所有事件的场景。

推荐方案：使用 FullCalendar JSON Feed

对于更复杂、数据量更大或需要动态加载事件的场景，FullCalendar 提供了更高级的 JSON Feed 机制。这种方法允许 FullCalendar 在需要时（例如用户切换月份）通过 AJAX 请求从指定 URL 获取事件数据。

工作原理：

1. 在 FullCalendar 配置中，将 events 选项设置为一个 URL。
2. 当 FullCalendar 初始化或用户导航到新的日期范围时，它会向该 URL 发送一个 AJAX 请求。
3. FullCalendar 会自动在请求中包含 start 和 end 参数（通常是 Unix 时间戳或 ISO 8601 格式），表示当前视图的开始和结束日期。
4. 服务器端的 PHP 脚本接收这些参数，查询数据库或数据源，并返回一个 JSON 格式的事件数组。

前端配置示例：

$(document).ready(function() {
  $('#calendar').fullCalendar({
    defaultDate: '2025-12-02',
    eventLimit: true,
    events: 'your-events-feed.php' // 指定事件数据源的 URL
    // 或者，如果需要传递额外参数：
    // events: {
    //   url: 'your-events-feed.php',
    //   type: 'POST', // 或 'GET'
    //   data: {
    //     custom_param: 'some_value'
    //   },
    //   error: function() {
    //     alert('加载事件时发生错误！');
    //   }
    // }
  });
});

后端 your-events-feed.php 脚本示例：

 "2025-12-01", "title" => "月度会议"],
  ["start" => "2025-12-02", "title" => "项目启动", "end" => "2025-12-03"],
  ["start" => "2025-12-05", "title" => "客户演示"],
  ["start" => "2025-12-08", "title" => "团队建设"],
  ["start" => "2025-12-15", "title" => "季度回顾"],
  ["start" => "2025-12-24", "title" => "节日派对"],
  ["start" => "2025-01-05", "title" => "新年计划"]
];

$filteredEvents = [];
// 简单过滤逻辑（实际应用中应使用数据库查询优化）
foreach ($allEvents as $event) {
    // 假设 start 和 end 都是 YYYY-MM-DD 格式
    if ($start && $end) {
        if ($event['start'] >= date('Y-m-d', $start) && $event['start'] <= date('Y-m-d', $end)) {
             $filteredEvents[] = $event;
        }
    } else {
        $filteredEvents[] = $event; // 如果没有 start/end 参数，则返回所有事件
    }
}


echo json_encode($filteredEvents);
?>

使用 JSON Feed 的优点是：

• 性能优化： 只加载当前视图所需的事件，减少数据传输量。
• 可伸缩性： 适用于大量事件，避免一次性加载所有数据导致的性能问题。
• 灵活性： 后端可以根据需要动态生成事件数据，例如根据用户权限、筛选条件等。

总结与注意事项

正确地将 PHP 后端数据集成到 FullCalendar 3 中，关键在于理解 FullCalendar 期望的事件数据格式。无论是直接注入还是通过 JSON Feed，PHP 数组都必须转换成一个包含事件对象的 JSON 数组。

• 数据格式是核心： 确保 PHP 数组的结构与 FullCalendar 的事件对象规范一致（即一个包含关联数组的索引数组）。
• json_encode() 不可或缺： 使用 json_encode() 是将 PHP 数组转换为 JavaScript 可理解的 JSON 格式的标准方法。
• 选择合适的集成方式： 对于小型、静态数据集，直接注入是简便的选择。对于大型、动态或需要按需加载的数据集，强烈推荐使用 FullCalendar 的 JSON Feed 机制，它提供了更好的性能和可维护性。
• 错误处理： 在实际项目中，无论是前端的 AJAX 请求还是后端的 PHP 脚本，都应加入适当的错误处理机制，以提升用户体验和系统健壮性。
• FullCalendar 版本： 本教程基于 FullCalendar 3。如果您使用 FullCalendar 4 或更高版本，其 API 和事件源配置可能有所不同，请查阅相应版本的官方文档。