# @rencomputer/rencal-sdk 中文文档

规范地址：https://npmcn.com/package/%40rencomputer/rencal-sdk/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T06:54:40.984Z
中文译文更新时间：2026-11-02T08:13:54.628Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40rencomputer/rencal-sdk
原文对照：https://npmcn.com/package/%40rencomputer/rencal-sdk/?lang=original
项目主页：https://rencal.org/
源码仓库：https://github.com/t4t5/rencal

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

- 包体积（解压后）：39.1 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：6 个
- peer 依赖：@types/react ^19\.2\.0，@types/react-dom ^19\.2\.0
- 首次发布：2026-10-15T18:05:54.949Z
- 最新版本发布：2026-11-02T06:54:40.818Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

为renCal构建视图插件：插件API，设计令牌和零配置构建。

## 安装

```sh
npm install @rencomputer/rencal-sdk
```

也可以使用：`pnpm add @rencomputer/rencal-sdk`、`yarn add @rencomputer/rencal-sdk`、`bun add @rencomputer/rencal-sdk`

## README

# renCal SDK

构建视图插件 [renCal](https://rencal.org/)． 视图是一个React组件，它与内置的周视图、月视图和年视图一起显示。这个包有插件API、renCal的Tailwind设计令牌和一个不需要配置的构建命令。

## 设置

```sh
pnpm add -D @rencomputer/rencal-sdk @types/react @types/react-dom
```

将脚本添加到 `package.json`：

```json
{
  "scripts": {
    "build": "rencal-sdk build",
    "dev": "rencal-sdk dev"
  }
}
```

扩展共享的 `tsconfig.json`：

```json
{ "extends": "@rencomputer/rencal-sdk/tsconfig.json" }
```

## 声明视图

视图是在插件的 `rencal-plugin.toml`：

```toml
id = "alice.upcoming"
name = "Upcoming"
description = "The next seven days as a list."
min_rencal_version = "0.9.1"

[[contributes.views]]
id = "upcoming"
name = "Upcoming"
script = "dist/upcoming.js"
css = "dist/upcoming.css"
```

`css` 是可选的;如果视图没有样式，则将其省略。看到 [创建一个插件](https://rencal.org/docs/plugins/create/) 其余的舱单。

## 编写视图

默认情况下，导出组件 `src/index.tsx`，或from `src/<view-id>.tsx` 当插件有几个视图时：

```tsx
import {
  type CalendarEvent,
  useEventProps,
  useEventsInRange,
  useToday,
} from "@rencomputer/rencal-sdk"

export default function UpcomingView() {
  const today = useToday()
  const events = useEventsInRange(today, today.add({ days: 7 }))

  return (
    <ul className="flex flex-col gap-1 p-4">
      {events.map((event) => (
        <EventItem key={event.key} event={event} />
      ))}
    </ul>
  )
}

function EventItem({ event }: { event: CalendarEvent }) {
  return (
    <li {...useEventProps(event)} className="rounded-md px-2 py-1">
      {event.summary}
    </li>
  )
}
```

顺风类开箱即用并使用renCal的主题，因此视图与用户安装的任何主题匹配。当用户在标题中键入新事件时，renCal将淡入事件和集合 `data-dimmed` 环视；其他部分也跟着褪色，比如 `in-data-dimmed:opacity-50`.

## API

| 出口 |  |
| --- | --- |
| `useEventsInRange(start, end)` | 可见日历中的事件 `start` 直至，但不包括， `end`，加上正在创建的事件和拖动事件的预览，标记为 `event.transient` |
| `useEventProps(event, { drag })` | 使元素表现得像一个renCal事件的道具：日历颜色、选择、RSVP和拖动状态、单击打开、右键单击菜单和with `drag`，拖动可重新安排 |
| `useEventState(event)` | 事件是否被选中、显示其菜单或被拖动 |
| `dayProps(date, zone)` | 将元素标记为日：将事件拖放到那里，拖拽、双击或右键单击它将创建一个事件 |
| `useDayGrid()` | 正在绘制以创建事件的范围，以及是否正在拖动任何东西 |
| `selectionProps()` | 标记一个元素绘制该范围的一部分，因此new-event弹出窗口将在其旁边打开 |
| `useToday()` | 今天的日期，保持当前午夜和时区的变化 |
| `useViewerTzid()` | 用户的时区，当它改变时保持当前 |
| `useNavigation()` | 活动日期，以及转到另一个日期的函数 |
| `useOnNavigate(onNavigate)` | 调用 `onNavigate` 每次经过深思熟虑的导航，甚至到活动日期，把它带入视野 |
| `useCalendars()` | 用户的日历 |
| `useDisplaySettings()` | 用户的时间格式、一周的第一天以及是否显示周数 |
| `useEventAppearance(event)` | 事件的颜色和RSVP，对于非事件元素的标记 |
| `Temporal` | 临时API用于日期和时间 |
| `eventsByDay(events, start, end)` | 事件分组成一个条目，每天从 `start` 直至，但不包括， `end`包括空虚的日子 |
| `layoutAllDay(items, start, dayCount)`， `layoutTimed(items)`， `isSpanning(event)` | renCal的布局是：将活动安排在车道上，并将一天的活动重叠在一起 |
| `dateInViewerZone`， `toViewerZonedDateTime`， `isAllDay`， `isSameDay`， `startOfWeek`， `isoWeekNumber`， `epochDay` | 日期助手 |
| `formatTime`， `formatWallclockTime`， `formatShortDate`， `formatLongDate`， `formatWeekday`， `formatMonth`， `getRelativeDayLabel` | 遵循renCal的格式 |
| `Button`， `Tooltip`， `cn`， `ChevronLeftIcon`， `ChevronRightIcon`， `UntitledEventText` | 来自renCal UI的组件和实用程序 |

React、Temporal和这个包是由renCal在运行时提供的。其他依赖项被捆绑到视图中。

## 构建

`pnpm build` 类型检查插件并将每个视图写入 `script` 和 `css` 路径在它的manifest中。 `pnpm dev` 重建每一个变化。

要尝试该插件，请将其目录添加到 `~/.config/rencal/plugins.toml`． renCal在每次重建时重新加载它：

```toml
plugins = ["~/dev/rencal-upcoming"]
```

本地插件不需要其他任何东西。保持 `dist/` Out of git：它是构建输出。

## 发布

renCal从最新的GitHub版本安装视图插件，下载每个插件 `script` 和 `css` 具有相同文件名的来自发布资产的文件。添加一个构建插件和附加的工作流 `dist/*` 当您按下一个版本标记时，就会生成一个版本 `.github/workflows/release.yml`：

```yaml
name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
      attestations: write
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: 24

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Attest build provenance
        uses: actions/attest@v4
        with:
          subject-path: dist/*

      - name: Create release
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --generate-notes dist/*
```

然后推送一个标签，比如 `v0.1.0` 发布新闻稿标签是renCal显示的版本。看到 [rencal-view-board](https://github.com/t4t5/rencal-view-board) 对于使用pnpm设置的插件，和 [发布插件](https://rencal.org/docs/plugins/publish/) 在插件目录中列出你的。

## 来源

SDK是在 [renCal库](https://github.com/t4t5/rencal/tree/main/packages/sdk).

## 常见问题

### @rencomputer/rencal-sdk 是什么？

为renCal构建视图插件：插件API，设计令牌和零配置构建。

### 如何安装 @rencomputer/rencal-sdk？

在项目目录运行 npm install @rencomputer/rencal-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@types/react（^19\.2\.0）、@types/react-dom（^19\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 rencal-sdk，可以用 npx rencal-sdk 直接运行。

### @rencomputer/rencal-sdk 支持 TypeScript 吗？

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

### @rencomputer/rencal-sdk 支持 ESM 还是 CommonJS？

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

### @rencomputer/rencal-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @rencomputer/rencal-sdk 可以商用吗？

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

### @rencomputer/rencal-sdk 还在维护吗？

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