# @gentleduck/calendar 中文文档

规范地址：https://npmcn.com/package/%40gentleduck/calendar/

版本：0\.5\.1
npm 元数据更新时间：2026-10-12T23:11:25.279Z
中文译文更新时间：2026-11-16T04:09:21.388Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gentleduck/calendar
原文对照：https://npmcn.com/package/%40gentleduck/calendar/?lang=original
项目主页：https://gentleduck.org/duck-ui
源码仓库：https://github.com/gentleeduck/gentleduck

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：121 kB，139 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：dayjs \>=1\.11\.0，luxon \>=3\.0\.0，react \>=18\.0\.0，date-fns \>=3\.0\.0
- 首次发布：2026-03-20T13:40:34.121Z
- 最新版本发布：2026-10-12T23:11:25.015Z
- 近 30 天下载量：3129（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

无头,框架不可知日历引擎有日期适配器模式.

## 安装

```sh
npm install @gentleduck/calendar
```

也可以使用：`pnpm add @gentleduck/calendar`、`yarn add @gentleduck/calendar`、`bun add @gentleduck/calendar`

## README

![@gentleduck/calendar](https://npmcn.com/package/public/logo-dark.svg)

# @ gentleduck/ 日历

无头型,框架-不可知日历引擎有日期适配器模式,反应钩和复合组件.

[麻省理工学院](https://npmcn.com/package/LICENSE) - 说吧 [更改日志](https://npmcn.com/package/CHANGELOG.md) - 说吧 [捐款](https://npmcn.com/package/CONTRIBUTING.md) - 说吧 [文档](https://gentleduck.org/duck-ui)

[![npm](https://img.shields.io/npm/v/@gentleduck/calendar.svg)](https://www.npmjs.com/package/@gentleduck/calendar) [![downloads](https://img.shields.io/npm/dm/@gentleduck/calendar.svg)](https://www.npmjs.com/package/@gentleduck/calendar) [![MIT](https://img.shields.io/npm/l/@gentleduck/calendar.svg)](https://npmcn.com/package/LICENSE)

* * *

**75%小于每日采集反应器** - ~5 KB克齐比特对~20 KB. 零从属. 全键盘导航和ARIA合规.

## 基准

| 图书馆 | 大小( gzip) | 依赖关系 |
| --- | --- | --- |
| **@ gentleduck/ 日历** | **~5 KB 键** | **0 个** |
| 反应日选择器 | ~20 KB 键 | 日期 - fns |
| 反应-日历 | ~18 KB 键 | 0 个 |
| 反应- 日期选择器 | ~38 KB (韩语) | 日期fns,反应-流行 |
| 反应-aria (DatePicker) | ~45 KB (英语) | @ 国际化/日期+5 |

4个历法系统(希腊语,伊斯兰教,波斯语,希伯来语). 7个日期适配器(Native, date-fns, dayjs, luxon + 3个日历专用). 见 [全部基准](https://gentleduck.org/docs/packages/duck-calendar/benchmarks) 用于特性比较.

```bash
bun run benchmark
```

## 快速启动

```tsx
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>
  )
}
```

## 特征

-   **日期适应器模式** - 插入任何日期库(日期、日期、日期、时间)
-   **选择模式** - 单一、范围、多选择和类型安全条件类型
-   **多月数** - 并列显示1至12个月
-   **时间选择器** - 使用带有自旋按钮的TimePicker钩ARIA
-   **约会时间拾取器** - 使用DateTime编译日历+时间
-   **键盘导航** - 箭头密钥、页上/下、主/端、输入/空间、逃逸
-   **屏幕阅读器** - 关于导航和选择的线活性公告
-   **正在移动 TabIndex** - 与DOM焦点同步进行适当的重点管理
-   **无 CSS** - 使用 Tailwind、 CSS 模块或 vanilla CSS 的带有数据\* 属性的样式
-   **可树动** - 说吧 `sideEffects: false`,只导入您使用的东西

## 建筑

```
@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
```

## 文档

完整文件时间 [greatduck.org/docs/packages/duck-日历](https://gentleduck.org/docs/packages/duck-calendar)

## 许可证

麻省理工学院

## 常见问题

### @gentleduck/calendar 是什么？

无头,框架不可知日历引擎有日期适配器模式\.

### 如何安装 @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 和提交记录判断。

