cron-kit-vue

cron-kit-vue

Vue 3 版 Cron 表达式可视化组件。零运行时依赖，支持 v-model，样式自动注入，可直接嵌进表单弹窗并回传表达式。

对标 cron.ciding.cc：可视化配置、表达式互转、中文描述、最近运行时间、时区、模板、特殊字符说明。引擎在 cron-kit-core。

安装

npm i cron-kit-vue

vue 是 peer 依赖（>=3.2），不随包安装。仅支持 Vue 3。

快速上手

嵌进表单（最常用）

CronInput = 输入框 + 配置按钮 + 弹窗，用 v-model 绑表达式。弹窗内容通过 Teleport 挂到 body，不受父容器 overflow: hidden 影响。

<script setup lang="ts">
import { ref } from 'vue';
import { CronInput } from 'cron-kit-vue';

const form = ref({ cron: '0 0 9 ? * MON-FRI *' });
const rules = { cron: [{ required: true, message: '请配置执行时间' }] };
</script>

<template>
  <el-form :model="form" :rules="rules">
    <el-form-item label="执行时间" prop="cron">
      <CronInput v-model="form.cron" />
    </el-form-item>
  </el-form>
</template>

• 默认 apply-mode="confirm"：弹窗里点「确定」才回传；
• 想边改边同步传 apply-mode="live"；
• 不需要按钮、只想手写表达式传 hide-button。

只用面板

<script setup lang="ts">
import { ref } from 'vue';
import { CronPanel } from 'cron-kit-vue';

const cron = ref('0 0 9 ? * MON-FRI *');
</script>

<template>
  <CronPanel v-model="cron" time-zone="Asia/Shanghai" theme="light" />
</template>

组件

按需引入：

import { CronInput } from 'cron-kit-vue';

Props 与事件

受控 / 非受控

所有涉及表达式的组件都支持 v-model，同时也接受 value / defaultValue 别名：

interface CronChangeInfo {
  expression: string;
  valid: boolean;
  issues: CronIssue[];
  summary: string;          // 自然语言描述
  nextRuns: NextRunItem[];
  syntax: CronSyntax;
  timeZone?: string;
}

<CronPanel v-model="cron" @change="(expr, info) => console.log(expr, info.valid)" />

通用

CronInput 额外

CronPanel 额外

面板还支持 tabChange 事件，默认插槽渲染在底部。

CronBuilder 额外

<CronBuilder v-model="cron" v-model:active-field="field" />

CronExpression 额外

CronExpression 下方会常驻一行字段提示，如「共 7 个字段：秒 分 时 日 月 周 年」。

CronNextRuns 额外

time-zone 会直接影响算出来的时间。

CronExplain 额外

CronTemplates 额外

注意 CronTemplates 不接收 timeZone，模板本身与时区无关。

CronModal 额外

<CronModal :open="open" @ok="confirm" @cancel="open = false">
  <CronPanel v-model="draft" flat :title="null" />
  <template #footer>
    <button type="button" class="ck-btn ck-btn--primary" @click="confirm">就用这个</button>
  </template>
</CronModal>

弹窗通过 Teleport 挂到 body，不受父级 overflow: hidden 影响；Esc 与点遮罩都会触发 cancel。

字段配置模式

每个字段的「指定」模式会把该字段的全部候选值铺成可点选栅格 —— 秒 / 分是 0-59，时是 0-23，日是 1-31，月带月份名，周带星期名，年是当前年份往后 10 年。选中的值会实时汇总（如「已选 3 个：0、15、30」），值多的字段限高滚动。

支持鼠标滑动框选：在某个数值上按住左键横向 / 纵向划过，划过的格子会跟着切换。起手那一格决定本次是「填入」还是「取消」——在未选中的格子上起手就是一路填入，在已选中的格子上起手就是一路取消，两种方向互不干扰，可以放心迭加多段。划过滚动区上下边缘时会自动滚动，方便一次框完 0-59；松手才把结果一次性提交（触发 update:modelValue），不会划一格触发一次。键盘用户按 Enter / 空格仍可单个切换。

下拉一律是自绘面板：月 / 周的「范围」、第几个星期几、时区这几处的下拉都不使用原生 <select> —— 原生弹层由浏览器按系统配色绘制，暗色界面里会弹出一块纯白面板，而且圆角、悬停高亮、内边距都无法定制。改成自绘浮层后，配色跟随 light / dark，当前项带钩，支持键盘 ↑↓ 选择、Enter 确认、Esc 或点击外部关闭，下方空间不足时自动向上弹。时区下拉额外支持输入筛选（输入「上海」或 Asia 都能筛出来）。

以秒为例，四个基础模式是：

日与周额外有「最后一天 / 最后一个工作日 / 最近的工作日 / 第几个星期几」，仅在该语法支持时才出现。

组合式函数

想自己拼 UI 时，可以直接用内部的 composable —— 它封装了表达式、语法、时区三个状态以及派生出的校验、描述与运行时间：

import { useCronState } from 'cron-kit-vue';
import { computed } from 'vue';

const props = defineProps<{ modelValue?: string }>();
const emit = defineEmits<{ (e: 'update:modelValue', v: string): void }>();

const { expression, parsed, described, nextRuns, syntax, setExpression } = useCronState(props, emit);

// expression 为 computed ref；parsed.valid / described.summary / nextRuns 都是响应式派生
const invalid = computed(() => !parsed.value.valid);

样式

样式随组件自动注入（幂等，整个页面只注入一次），一般不用管。

需要 SSR、想自己控制注入时机，或者要做覆盖：

import { ensureCronKitStyles, removeCronKitStyles, CRON_KIT_CSS } from 'cron-kit-vue';

ensureCronKitStyles();   // 手动注入
removeCronKitStyles();   // 移除

也可以直接引 CSS 文件：

import 'cron-kit-vue/style.css';

所有类名带 ck- 前缀，不会污染宿主页面。主题变量集中在 .ck-root / .ck-root[data-ck-theme] 上，覆盖 CSS 变量即可换肤。

支持的语法

支持 * ? , - / L W # 与 JAN–DEC、SUN–SAT 别名。

TypeScript

包内自带类型声明（vue-tsc 生成），CronSyntax / CronIssue / NextRunItem 等核心类型会从 cron-kit-core 透出，无需重复安装。

License

MIT