# @super-calendar/dom 中文文档

规范地址：https://npmcn.com/package/%40super-calendar/dom/

版本：2\.15\.0
npm 元数据更新时间：2026-11-02T13:56:16.218Z
中文译文更新时间：2026-11-02T14:57:30.812Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40super-calendar/dom
原文对照：https://npmcn.com/package/%40super-calendar/dom/?lang=original
项目主页：https://super-calendar.afonsojramos.me/
源码仓库：https://github.com/afonsojramos/super-calendar

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

- 包体积（解压后）：638 kB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18，date-fns \>=3，react-dom \>=18，@legendapp/list \>=3
- 首次发布：2026-06-29T12:15:25.874Z
- 最新版本发布：2026-11-02T13:56:15.805Z
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

用于react-dom的虚拟月/周/日日历和日期选择器。没有React Native，就没有React - Native -web。

## 安装

```sh
npm install @super-calendar/dom
```

也可以使用：`pnpm add @super-calendar/dom`、`yarn add @super-calendar/dom`、`bun add @super-calendar/dom`

## README

# @super-calendar / dom

[![npm](https://img.shields.io/npm/v/@super-calendar/dom?style=flat-square&color=1F6FEB)](https://www.npmjs.com/package/@super-calendar/dom) [![JSR](https://img.shields.io/jsr/v/@super-calendar/dom?style=flat-square&label=JSR&color=F7DF1E)](https://jsr.io/@super-calendar/dom) [![npmx](https://img.shields.io/badge/npmx-view-8A2BE2?style=flat-square)](https://npmx.dev/package/@super-calendar/dom)

的react-dom渲染器 [super-calendar](https://github.com/afonsojramos/super-calendar)：虚拟化 **月/周/日** 日历和日期选择器由真正的DOM组件构建。没有React Native，就没有React - Native -web。

它是建立在无头的 [`@super-calendar/core`](https://www.npmjs.com/package/@super-calendar/core) 和Legend List的DOM渲染器。

## 安装

```sh
npm install @super-calendar/dom
```

也在 [JSR](https://jsr.io/@super-calendar/dom)： `deno add jsr:@super-calendar/dom`.

同行依赖性: `@legendapp/list` (> = 3), `date-fns` (> = 3), `react` (> = 19) `react-dom` (> = 19)。

## 使用

```tsx
import { useState } from "react";
import { Calendar, type CalendarEvent } from "@super-calendar/dom";

type MyEvent = { id: string; color: string };

const events: CalendarEvent<MyEvent>[] = [
  {
    id: "1",
    color: "#1F6FEB",
    title: "Lecture",
    start: new Date(2026, 5, 19, 10, 0),
    end: new Date(2026, 5, 19, 11, 30),
  },
];

export function MyCalendar() {
  const [date, setDate] = useState(new Date());

  return (
    <Calendar
      mode="week"
      date={date}
      events={events}
      weekStartsOn={1}
      onPressDay={setDate}
      onPressEvent={(event) => console.log(event.id)}
    />
  );
}
```

对于自定义拾取器，配对无头钩子(`useDateRange`， `useMonthGrid`), `MonthList` 和 `TimeGrid`，全部从此包中重新导出。

## 触摸事件手势

触摸和笔 `TimeGrid` 在拖拽之前，在8像素内等待300毫秒。 轻击从点击中按下事件；垂直滑动可以滚动网格。 其他联系人取消挂起的保持，不能接管活动拖动。 集 `touchDragDelay` 和 `touchDragThreshold` 在 `TimeGrid` 或者 `Calendar` 调整 持有。鼠标拖动和调整大小保留其现有行为。看到 [拖动指南](https://super-calendar.afonsojramos.me/guides/dragging).

## 移动事件

通过 `onDragEvent` 并使用返回的 `start` 和 `end`.

时间网格边缘分页需要鼠标拖动。触摸和笔保持在 可见周期，因此在边缘附近休息不能重复改变日期。 看到 [拖动指南](https://super-calendar.afonsojramos.me/guides/dragging).

在时间网格上，拖动多日事件的任何片段都可以预览整个事件 范围一起移动并保持其持续时间。拖动“调整大小”手柄以进行更改 只有开始或结束。看到 [拖动指南](https://super-calendar.afonsojramos.me/guides/dragging).

## 月芯片尺寸

`chipHeight` 和 `chipGap` 配置月通道和溢出行 `Calendar`， `MonthView`, `MonthList`． 本地的 `MonthPager` 也转发它们。DOM违约 保持18像素的高度和2像素的间距；原生高度保持其主题默认值。 更改任何一个维度都会更新已挂载的列表和寻呼机月份。 看到 [月指南](https://super-calendar.afonsojramos.me/guides/month-view).

## 样式

开箱即用的日历完全按照主题设计样式，不需要样式表。来重新设计特定部件的样式 **顺风** 或者你自己的CSS，每个元素都是一个命名的slot: pass `classNames` (或 `styles`)，并使用 `data-*` 状态变体 `data-[today]:`.

```tsx
<Calendar
  mode="month"
  date={date}
  classNames={{
    title: "text-center text-xl font-bold",
    dayBadge: "rounded-full data-[today]:bg-indigo-600 data-[today]:text-white",
  }}
/>
```

始终保持槽的结构布局；只有它的主题外观为您的类保留，因此类胜过内联默认值。看到 [风格指南](https://super-calendar.afonsojramos.me/guides/styling).

在时间网格上，一个空槽的触屏会发出呼叫 `onPressCell` 从专栏的 点击。滑动和取消的联系人不按槽。鼠标和笔保留 drag-to-create行为。看到 [DOM指南](https://super-calendar.afonsojramos.me/guides/dom).

## 文档

看到 [完整的文档](https://super-calendar.afonsojramos.me/), [快速入门](https://super-calendar.afonsojramos.me/quickstart)，和 [API参考](https://super-calendar.afonsojramos.me/reference/api).

## 许可证

麻省理工学院

## 常见问题

### @super-calendar/dom 是什么？

用于react-dom的虚拟月/周/日日历和日期选择器。没有React Native，就没有React - Native -web。

### 如何安装 @super-calendar/dom？

在项目目录运行 npm install @super-calendar/dom，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、date-fns（\>=3）、react-dom（\>=18）、@legendapp/list（\>=3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @super-calendar/dom 支持 TypeScript 吗？

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

### @super-calendar/dom 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @super-calendar/dom 可以商用吗？

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

### @super-calendar/dom 还在维护吗？

最新版本 2\.15\.0 发布于 2026/11/02（今天）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/06/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。