@gentleduck/calendar

中文文档
0.5.1发布于 2026/10/13MITTypeScriptES Module零依赖近 30 天下载 3129

Headless, framework-agnostic calendar engine with date adapter pattern.

原始使用文档
文档目录6 节
  1. Benchmarks
  2. Quick Start
  3. Features
  4. Architecture
  5. Documentation
  6. License

@gentleduck/calendar

@gentleduck/calendar

Headless, framework-agnostic calendar engine with date adapter pattern, React hooks, and compound components.

MIT - Changelog - Contributing - Docs

npm downloads MIT


75% smaller than react-day-picker - ~5 KB gzipped vs ~20 KB. Zero dependencies. Full keyboard navigation and ARIA compliance.

Benchmarks

LibrarySize (gzipped)Dependencies
@gentleduck/calendar~5 KB0
react-day-picker~20 KBdate-fns
react-calendar~18 KB0
react-datepicker~38 KBdate-fns, react-popper
react-aria (DatePicker)~45 KB@internationalized/date + 5 more

4 calendar systems (Gregorian, Islamic, Persian, Hebrew). 7 date adapters (Native, date-fns, dayjs, luxon + 3 calendar-specific). See the full benchmarks for feature comparisons.

bun run benchmark

Quick Start

import { NativeAdapter, useCalendar } from '@gentleduck/calendar'

const adapter = new NativeAdapter()

function MyCalendar() {
  const { state, getDayProps, getGridProps } = useCalendar({
    adapter,
    mode: 'single',
  })

  return (
    <div {...getGridProps()}>
      {state.weeks.map(week =>
        week.days.map(day => (
          <button key={day.date.getTime()} {...getDayProps(day)}>
            {day.date.getDate()}
          </button>
        ))
      )}
    </div>
  )
}

Features

  • Date Adapter Pattern - Plug in any date library (native Date, dayjs, date-fns, Temporal)
  • Selection Modes - Single, range, multi-select with type-safe conditional types
  • Multi-Month - Display 1-12 months side by side
  • Time Picker - useTimePicker hook with spinbutton ARIA
  • DateTime Picker - useDateTime composing calendar + time
  • Keyboard Navigation - Arrow keys, Page Up/Down, Home/End, Enter/Space, Escape
  • Screen Reader - aria-live announcements for navigation and selection
  • Roving TabIndex - Proper focus management with DOM focus sync
  • Zero CSS - Style with data-* attributes using Tailwind, CSS modules, or vanilla CSS
  • Tree-Shakeable - sideEffects: false, import only what you use

Architecture

@gentleduck/calendar
├── adapter/      -  DateAdapter<TDate> interface + NativeAdapter
├── grid/         -  buildCalendarMonth, buildMultiMonth, year/decade views
├── selection/    -  selectDay, applySelection, range/multi logic
├── navigation/   -  navigate, canNavigate, month/year jumping
├── time/         -  TimeValue, clampTime, incrementField, formatters
└── react/        -  useCalendar, useTimePicker, useDateTime, useKeyboard, useAnnouncer

Documentation

Full docs at gentleduck.org/docs/packages/duck-calendar

License

MIT

版本与发布记录

@gentleduck/calendar 共发布 9 个版本,首次发布于 2026/03/20;过去 12 个月发布了 9 个版本。

版本发布日期距今
0.5.1latest2026/10/131 个月前
0.5.02026/10/111 个月前
0.4.02026/05/305 个月前
0.3.22026/05/205 个月前
0.3.12026/05/066 个月前
0.3.02026/04/196 个月前

关于 @gentleduck/calendar 的常见问题

@gentleduck/calendar 是什么?

Headless, framework-agnostic calendar engine with date adapter pattern.

如何安装 @gentleduck/calendar?

在项目目录运行 npm install @gentleduck/calendar,或使用 pnpm add / yarn add / bun add。

@gentleduck/calendar 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gentleduck/calendar 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gentleduck/calendar 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gentleduck/calendar 可以商用吗?

@gentleduck/calendar 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gentleduck/calendar 的下载量有多少?

根据 npm 官方下载统计,@gentleduck/calendar 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,129 次,日均约 104 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gentleduck/calendar 还在维护吗?

最新版本 0.5.1 发布于 2026/10/13(1 个月前);至今共发布 9 个版本,其中过去 12 个月发布了 9 个;首次发布于 2026/03/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。