Hapio Calendar 正式发布：我们为预约应用打造的开源日历组件

Hapio 采用无头架构。我们为您提供预订和排程 API——包括服务、资源、日程表和可预订时段——由您来构建客户所见的用户体验。这种方式对于预订流程本身效果很好，但大多数项目迟早都需要一个真正的日历：员工可以在周视图中拖动预订；日视图会显示空闲时段；月视图则用于整体概览。

到目前为止，这意味着要么使用现成的日历库，要么从头开始构建一个。当您的数据模型已经存在于 Hapio 中时，这两种选择都不太理想。

今天，我们发布了Hapio Calendar——一款适用于 React 19 和 shadcn/ui 的开源全尺寸日历组件。它支持周视图、日视图、月视图和列表视图，具备拖动和调整大小的功能，支持按日历设置时区以及重复事件，并且开箱即用即可与 Hapio API 对接。该组件采用 MIT 许可证，且不设高级版。

周视图。营业时间以阴影标出，预约显示在网格上，红色线条标示当前时间。

功能介绍

Hapio Calendar 是一个功能齐全的日历，而非日期选择器。开箱即用，它为您提供：

四种视图：周视图、日视图、月视图和列表视图。视图和日期可选地包含在URL中，以便链接可分享。
拖拽、调整大小和键盘编辑。可以使用鼠标移动和调整事件的大小，也可以通过每个事件上的“操作”菜单使用键盘进行操作。您还可以从日历外部将项目拖入日历，例如从未分配的预订列表中。
时区处理得当。每个日历都有自己的时区，且无需重新挂载即可切换。23小时或25小时的日子显示布局正确，因此夏令时转换不会破坏网格布局。
预订规则。开放时间、时间冲突检查以及您自定义的检查项。当预订被拒绝时，日历会向用户说明原因。
乐观保存。更改会立即显示，在 API 保存期间处于待处理状态，如果保存失败则会回滚。
周期性事件。RFC 5545 系列编辑，包括当服务器已知时区和日期时的服务器端展开。
内置无障碍功能。键盘移动、实时语音提示，以及每个示例的无障碍检查。
本地化。支持多种语言（包括瑞典语）以及从右向左的排版。
服务器端渲染。支持 SSR 和 React 服务器端组件，并附带一份内容安全策略指南。

月视图，包含ISO周号、多日活动，以及在繁忙日子出现的“+N个”溢出提示。

专为 Hapio 打造

日历是一个通用组件，但其设计是基于 Hapio 项目实际的工作方式。该集成主要涉及三个回调函数：

加载。事件源会从您服务器上的某条路线中，为每个可见日期范围获取预订信息。
预订。Hapio 中的可预订时段显示为“空闲时间”。当客户或员工选择其中一个时段时，您的应用会生成预订。
重新安排时间。 拖拽和键盘移动调用 onEventChange. 如果 Hapio 拒绝该更改（资源不可用、时段不在开放时间内），日历会将其恢复原状并显示原因。

通过拖拽操作重新安排预订。在您的服务员确认更改之前，原时段将保持灰色不可选状态。

与我们的管理面板一样，您的 API 令牌绝不会传输到浏览器。您的服务器通过 hapio-sdk 包，且日历仅与您的服务器进行通信。令牌的权限由 Hapio 照常进行管控。

代码归您所有

我们不想再推出一款“黑匣子”式的日历。Hapio Calendar 分为三个层次，您可以自行决定要深入到什么程度：

@hapio/calendar-core — 无框架的逻辑：布局、时区计算、规则、递归。不使用 React。
@hapio/calendar-react — 核心层上的无头钩子。请自行提供标记语言和样式。
该 @hapio shadcn 注册表 — 经过样式设置、可直接使用的组件。它通过 shadcn CLI 安装，并被复制到你的项目，因此您可以像编辑其他 shadcn 组件一样编辑这些文件。

大多数项目都会从注册表组件开始，只有在需要处理特殊情况时才会转而使用钩子。无论哪种方式，都没有什么是你无法修改的。

入门指南

您需要 React 19.2 或更高版本，以及基于 Tailwind CSS 4（Radix 或 Base UI 基础框架）的 shadcn/ui 应用。若要进行服务器端渲染，则需要 Node 22.12 或更高版本。

首先，添加 @hapio 注册表到您的 components.json:

{
  "registries": {
    "@hapio": "https://calendar.hapio.io/r/{name}.json"
  }
}

然后添加日历：

npx shadcn@latest add @hapio/hapio-calendar

这会将该组件复制到 components/hapio-calendar/, 拉进鲱鱼 button, popover 和 scroll-area 组件，并进行安装 @hapio/calendar-react 和 temporal-polyfill. 在应用程序的根目录下加载一次该 polyfill，然后指定高度和时区来渲染日历：

<HapioCalendar
  events={events}
  timeZone="Europe/Stockholm"
  className="h-[36rem]"
/>

基础组件为只读。添加 calendar-selection 以便让用户选择时间， calendar-editing 移动和调整事件大小，以及 calendar-external-draggable 从外面往里投放物品。该安装指南详细讲解了每个步骤，并且你的第一本日历接下来就由他接手了。

Hapio Calendar 基于 React 19、shadcn/ui、TypeScript、Tailwind CSS 和 Temporal polyfill 构建，并采用 MIT 许可证发布。每个示例都经过自动无障碍性检查，测试套件随源代码一并发布。非常欢迎提交问题和拉取请求。

浏览示例，请阅读文档，或者运行 npx shadcn@latest add @hapio/hapio-calendar 今天就在您自己的项目中试一试吧。

链接：calendar.hapio.io·GitHub 代码库·Hapio 文档·Hapio 门户

介绍 Hapio Calendar：我们为预约应用开发的开源日历组件

功能介绍

专为 Hapio 打造

代码归您所有

入门指南

JSON

壳牌

TSX

帕特里克