# @cron-zen/core 中文文档

规范地址：https://npmcn.com/package/%40cron-zen/core/

版本：0\.2\.5
npm 元数据更新时间：2026-11-02T02:20:54.736Z
中文译文更新时间：2026-11-13T05:57:41.018Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cron-zen/core
原文对照：https://npmcn.com/package/%40cron-zen/core/?lang=original
项目主页：https://jaskon-io.github.io/cron-zen/api/core
源码仓库：https://github.com/jaskon-io/cron-zen

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

- 包体积（解压后）：257 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-23T02:08:56.709Z
- 最新版本发布：2026-11-02T02:20:54.521Z
- 近 30 天下载量：2163（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

框架不可知克特兹/克龙.ren Cron 剖析器、 生成器、 验证器、 描述和下运行的估计数

## 安装

```sh
npm install @cron-zen/core
```

也可以使用：`pnpm add @cron-zen/core`、`yarn add @cron-zen/core`、`bun add @cron-zen/core`

## README

# @cron-zen/core

`cron-zen` 核心逻辑层：Cron 表达式解析、生成与校验。**无框架依赖**——原生 JS、Node、非 Vue 前端都应优先用本包。

需要可视化时另装 `vanilla` / `react` / `vue2` / `vue3`（不能用 UI 包替代 core）。

**完整函数说明（参数 / 返回 / 示例）** → [文档 · API · core](https://jaskon-io.github.io/cron-zen/api/core)  
**在线引擎沙箱** → [examples/core.html](https://jaskon-io.github.io/cron-zen/examples/core.html)  
选包：[选哪个包](https://jaskon-io.github.io/cron-zen/guide/choose-package)

## Install

```bash
npm install @cron-zen/core
# or
pnpm add @cron-zen/core
```

## API (当前)

### `parseCron(expression: string): ParseResult`

解析 5 / 6 / 7 段 Cron 表达式为可视化状态。

```ts
import { parseCron } from '@cron-zen/core';

const res = parseCron('0 0 2 * * ? *');
if (res.success) {
  console.log(res.state);
} else {
  console.error(res.error);
}
```

### `validateCronState(state): ValidateResult`

校验范围、日周互斥、非法日期（如 2 月 31 日）。

```ts
import { validateCronState, createDefaultCronState } from '@cron-zen/core';

const res = validateCronState(createDefaultCronState());
console.log(res.valid, res.errors, res.warnings);
```

### `generateCron(state, options?): GenerateResult`

由可视化状态生成 7 段表达式（默认自动日周互斥）。

```ts
import { generateCron, createDefaultCronState } from '@cron-zen/core';

const res = generateCron(createDefaultCronState());
// { success: true, expression: '* * * * * ? *' }
```

### `getNextRuns` / `getPrevRuns`

估算最近 N 次触发（未来）与已触发（新→旧）。已覆盖日 `L` / `LW` / `nW`、周 `nL` / `n#m` / 裸 `L`，以及倒序区间回绕。

```ts
import { getNextRuns, getPrevRuns, parseCron, formatRunTime } from '@cron-zen/core';

const { state } = parseCron('0 0 9 ? * 6#3');
const from = new Date('2026-01-01');
console.log(getNextRuns(state!, 3, from).map(formatRunTime));
console.log(getPrevRuns(state!, 3, from).map(formatRunTime));
```

### `getCronPresets` / `listCronPresetDefs`

常用模板（每分钟 / 工作日 9 点 / 月末…）；`getCronPresets(locale)` 带中英标签。

### 其他导出

-   `parseField` / `stringifyField` — 单字段解析 / 序列化
-   `escapeCronPercent` / `unescapeCronPercent` — `%` 转义
-   `enforceDayWeekMutex` / `assertDayWeekMutex` — 日周互斥
-   `describeCron` / `formatRunTime` / `getUiMessages` — 自然语言与 UI 文案
-   `lastDayOfMonth` / `lastWeekdayOfMonth` / `nearestWeekdayOfMonth` — 日日历
-   `lastQuartzWeekdayOfMonth` / `nthQuartzWeekdayOfMonth` — 周日历（nL / #）
-   `QUARTZ_MONTH_LABELS` / `quartzMonthLabel` — 月标签
-   `getCronTabs` — UI Tab 元数据
-   `createDefaultCronState` — 默认 UI 状态
-   `generateCronOrThrow` — 生成失败时抛错

## Build

```bash
pnpm --filter @cron-zen/core build
```

产物：`dist/`（ESM / CJS + `.d.ts`），仅 `dist` 会随 npm 包发布。

## License

MIT

## 常见问题

### @cron-zen/core 是什么？

框架不可知克特兹/克龙\.ren Cron 剖析器、 生成器、 验证器、 描述和下运行的估计数

### 如何安装 @cron-zen/core？

在项目目录运行 npm install @cron-zen/core，或使用 pnpm add / yarn add / bun add。

### @cron-zen/core 支持 TypeScript 吗？

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

### @cron-zen/core 支持 ESM 还是 CommonJS？

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

### @cron-zen/core 可以商用吗？

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

### @cron-zen/core 的下载量有多少？

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

### @cron-zen/core 还在维护吗？

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