# @super-calendar/native 中文文档

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

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

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

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

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

- 包体积（解压后）：970 kB，36 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18，date-fns \>=3，react-native \>=0\.74 \<2，@legendapp/list \>=3，react-native-worklets \>=0\.5，react-native-reanimated \>=4\.0\.0 \<5，react-native-gesture-handler \>=2\.16
- 首次发布：2026-06-29T12:15:27.636Z
- 最新版本发布：2026-11-02T13:56:42.425Z
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

手势驱动，虚拟的月/周/日日历和日期选择器，用于React Native（以及通过React - Native -web）。

## 安装

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

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

## README

# @super-calendar /本机

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

React Native渲染器 [super-calendar](https://github.com/afonsojramos/super-calendar)手势驱动的，虚拟的 **月/周/日** 日历和日期选择器。运行于iOS， Android和web （web via） [react-native-web](https://necolas.github.io/react-native-web/)）。

-   📆月网格加上天/ 3天/周/自定义n时间网格和议程
-   🤏捏缩放周/天网格（UI线程，不重新渲染）
-   ✋拖动以选择、创建和移动：在周/天网格上按时间，在月和年网格上按整天
-   ♾️通过虚拟化的快照分页视图 [`@legendapp/list`](https://legendapp.com/open-source/list/)
-   🧩自带活动类型(`CalendarEvent<T>`)和a `renderEvent` 逃生出口
-   🪝无头 `useMonthGrid` 和 `useDateRange` 用于完全自定义的ui
-   🎨主题表，带 `darkTheme` 预设

## 安装

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

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

同行依赖性: `@legendapp/list` (> = 3), `date-fns` (> = 3), `react` (> = 19), `react-native` (> = 0.74 < 2), `react-native-gesture-handler` (> = 2), `react-native-reanimated` (> = 4), `react-native-worklets` (> = 0.8)。

对于不需要Reanimated的仅选择器包，从 `@super-calendar/native/picker` 子路径。

## 使用

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

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 [mode, setMode] = useState<"month" | "week" | "day">("week");
  const [date, setDate] = useState(new Date());

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

## 移动事件

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

在边缘分页之后，浮动事件的水平中心选择目标 日，其上边选择时间。

设置事件的 `dragHandleColor` 颜色，调整大小 `TimeGrid` 和 `ResourceTimeline` (两个方向)。默认为 `theme.colors.eventText`. `showDragHandle={false}` 仍然隐藏着时间网格。 您可以在安装后切换它，而无需更换 `events` 数组中。

## 顺风造型

每个可样式化的部分都是一个命名槽，它接受一个类（由Tailwind运行时解析），例如 [uniwind](https://docs.uniwind.dev/) 或NativeWind)和/或样式重写。一个类槽丢掉了它内置的主题样式，所以你的类拥有它的外观：

```tsx
<Calendar
  mode="month"
  date={date}
  events={events}
  classNames={{
    title: "text-center text-xl font-bold text-indigo-900",
    weekday: "uppercase tracking-wider text-indigo-400",
  }}
  styles={{ more: { color: "#6366F1" } }}
  onChangeDate={setDate}
  onPressEvent={(event) => console.log(event.id)}
/>
```

看到 [风格指南](https://super-calendar.afonsojramos.me/guides/styling) 用于插槽列表和uniwind设置。

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

## 文档

看到 [完整的文档](https://super-calendar.afonsojramos.me/) 和 [快速入门](https://super-calendar.afonsojramos.me/quickstart)，包括主题、重复事件、时区和无头选择器。

## 许可证

麻省理工学院

## 常见问题

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

手势驱动，虚拟的月/周/日日历和日期选择器，用于React Native（以及通过React - Native -web）。

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

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

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

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

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

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

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

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

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

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