@cron-zen/vue3

@cron-zen/vue3

Vue 3 可视化 Cron 表达式生成器。基于 @cron-zen/core，交互对齐 cron.ren：顶部 Tab + 中部配置 + 底部预览（可选）。

本包需要 Vue 3。 包名中的 vue3 即运行时要求；无 Vue 请用 @cron-zen/core。

默认不依赖 Element / Ant。 推荐只用 CronZen / useCronZen。CronZenPicker 是 Element 可选示例壳；CronZenPlugin 只注册 CronZen，不会全局挂上 Picker。

选包：选哪个包 · 弹层：任意 UI 库集成。

Install

pnpm add @cron-zen/vue3 @cron-zen/core vue

import { createApp } from 'vue';
import { CronZenPlugin } from '@cron-zen/vue3';
import '@cron-zen/vue3/style.css';

createApp(App).use(CronZenPlugin).mount('#app');

也可按需引入 CronZen，不必装插件。只有全站已用 Element Plus 时才需要：

pnpm add element-plus   # 仅 CronZenPicker；不是安装前提

Quick Start

<script setup lang="ts">
import { ref } from 'vue';
import { CronZen } from '@cron-zen/vue3';
import '@cron-zen/vue3/style.css';

/** 空串 = 无值（不注入默认表达式）；有值则回显 */
const cron = ref('');
</script>

<template>
  <CronZen v-model="cron" />
</template>

默认配置态（点「重置」或内部默认）为 6 段：* * * * * ?（年「不指定」省略，对齐 cron.ren）。选「每年 / 周期 / 指定年」后才会带第 7 段。

CronZen

完整可视化编辑器。

Props

Events

示例

<script setup lang="ts">
import { ref } from 'vue';
import { CronZen } from '@cron-zen/vue3';
import type { CronState } from '@cron-zen/vue3';

const cron = ref('0 0/5 * * * ?');
function onChange(state: CronState) {
  console.log(state.minute); // { mode: 'step', ... }
}
</script>

<template>
  <CronZen
    v-model="cron"
    :show-preview="true"
    :next-count="10"
    @change="onChange"
  />
</template>

弹窗内嵌（无预览区）：

<CronZen v-model="draft" :show-preview="false" />

CronZenPicker（可选 · Element 示例壳）

输入框 +「选择」按钮 + Dialog。仅当你已在用 Element Plus 时省胶水；请 import { CronZenPicker } 按需使用（插件不会全局注册）。其它 UI 库请自行包一层 Dialog，见 任意 UI 库集成，不要为了 Picker 专门引入 Element。

Props

Events

Slots

Expose

示例

<script setup lang="ts">
import { ref } from 'vue';
import { CronZenPicker } from '@cron-zen/vue3';
import '@cron-zen/vue3/style.css';
import 'element-plus/dist/index.css';

const cron = ref('');
</script>

<template>
  <CronZenPicker
    v-model="cron"
    readonly
    @confirm="(v) => console.log('ok', v)"
  />

  <!-- 自定义触发器 -->
  <CronZenPicker v-model="cron">
    <template #trigger="{ open, disabled }">
      <el-button type="primary" :disabled="disabled" @click="open">
        配置定时
      </el-button>
    </template>
  </CronZenPicker>
</template>

useCronZen（无 UI）

只拿状态机 / 预览，自己画界面时用。

import { ref } from 'vue';
import { useCronZen } from '@cron-zen/vue3';

const model = ref('0 0 0 * * ?');
const {
  state,
  expression,
  description,
  nextRuns,
  hint,
  weekFormat,
  activeTab,
  updateField,
  setWeekFormat,
  loadExpression,
  reset,
  flush,
} = useCronZen({
  modelValue: model,
  debounceMs: 0,
  nextCount: 10,
  showPreview: true,
});

updateField('minute', { mode: 'step', raw: '0/5', value: '0', secondary: '5' });
setWeekFormat('abbr'); // MON / TUE …
loadExpression('0 15 10 ? * 6L 2024-2030'); // 回显；6L 保持数字写法
reset(); // → * * * * * ?
flush(); // 立刻写回 v-model（跳过防抖）

同时从包入口可再导出 core API：parseCron、generateCron、describeCron、getNextRuns 等。

行为说明（对齐 cron.ren）

• 空 v-model：不注入默认 Cron；UI 用「每秒 / 每分 / …」原始态编辑，确定/生成后再写出表达式
• 年不指定：输出 6 段（如 * * * * * ?），不补尾部 *
• 日 / 周互斥：一侧具体值时，另一侧自动变为 ?，Tab 上有提示
• 周写法：数字 1~7（1=周日）或英文 SUN…SAT；加载 6L 不会误判成 abbr 改写成 FRIL
• 周期倒序：如周「周六→周二」输出 7-3（与 cron.ren 一致）；近 N 次按环形回绕估算
• 主题：覆盖 CSS 变量（见打包后的 style.css / 源码 styles/cron-zen.css）

:root {
  --cz-primary: #2563eb;
  --cz-border: #e5e7eb;
  /* 更多变量见样式文件 */
}

已知差异 / 限制

相对 cron.ren 主路径已对齐；以下为已知差异（非阻塞）：

License

MIT