diff --git a/docs/dev/background.md b/docs/dev/background.md index 06171c7..2d7296a 100644 --- a/docs/dev/background.md +++ b/docs/dev/background.md @@ -15,7 +15,7 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发,对于兼容性 > 定时脚本属于后台脚本的一种,适用于**按时间周期重复执行**的任务。 -定时脚本通过 `@crontab` 属性声明,支持分钟级与秒级调度,并提供脚本猫扩展语法 `once`,用于避免在同一时间周期内重复执行。 +定时脚本通过 `@crontab` 属性声明,支持分钟级与秒级调度,并提供脚本猫扩展语法 `once` / `once(...)`,用于避免在同一时间周期内重复执行。 ⚠️ 注意事项: @@ -69,9 +69,26 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发,对于兼容性 即使在同一周期内,后续时间点仍然符合 cron 规则,也不会再次执行。 +### `once` 与 `once(...)` 的区别 + +| 写法 | 该字段对应的 cron 值 | 说明 | +| ----------- | ------------- | ------------------------------- | +| `once` | `*`(任意值) | 周期内第一次命中时执行,不限定具体时间点 | +| `once(expr)` | `expr` | 周期内仅在 `expr` 匹配的时间点执行,且只执行一次 | + +`once(expr)` 允许在限制"每周期只执行一次"的同时,精确指定候选时间点。括号内支持所有标准 cron 语法(数字、范围、步长、列表)。 + +示例对比: + +```text +* once * * * // 每小时任意分钟,第一次命中即执行,本小时内不再执行 +* once(9-17) * * * // 每天 9 时至 17 时期间,每小时执行一次 +0,30 once * * * // 每小时在 0 分或 30 分中,最早命中的那次执行,本小时内不再执行 +``` + ### `once` 所在位置 = 限制的时间周期 -`once` 写在哪一位,就表示“在该时间粒度内只执行一次”。 +`once` / `once(...)` 写在哪一位,就表示"在该时间粒度内只执行一次"。 | `once` 位置 | 行为含义 | | --------- | -------- | @@ -84,13 +101,14 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发,对于兼容性 示例: ```text -* once * * * // 每小时只执行一次 -* * once * * // 每天只执行一次 +* once * * * // 每小时只执行一次 +* * once * * // 每天只执行一次 +* 9-18 once * * // 每天 9 时至 18 时之间只执行一次 ``` ### `once` 与范围 / 列表 / 步长的组合行为 -`once` 可以与任何 cron 语法组合使用,但规则只有一条: +`once` / `once(...)` 可以与任何 cron 语法组合使用,但规则只有一条: > **在同一周期内,只要成功执行过一次,其余命中的时间点都会被忽略** @@ -130,6 +148,28 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发,对于兼容性 * 当天第一次执行后 * 其余时间点将不再执行 +#### 示例四:`once(...)` 指定候选时间点 + +```text +* once(9-17) * * * +``` + +含义: + +* 每天 9 时至 17 时为候选小时 +* 每小时周期重置,当小时内第一次命中后不再重复 +* 效果:每天 9 时至 17 时期间,每小时各执行一次,共 9 次 + +```text +* 9-18 once * * +``` + +含义: + +* 每天 9:00–18:59 为候选时间 +* 日位 `once` 锁定每天周期 +* 当天第一次命中后,18:59 前不再执行 + ## `@crontab` 示例 ### 常见 @@ -148,9 +188,12 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发,对于兼容性 ### 进阶 ```js -//@crontab * 1,3,5 once * * // 每天1点3点5点中运行一次(假设当1点时运行了一次,3,5点将不会再运行) -//@crontab * 10-23 once * * // 每天10点-23:59中运行一次(假设当10:04时运行了一次,10:05-23:59的后续时间将不会再运行) -//@crontab * once 13 * * // 每个月的13号的每小时运行一次 +//@crontab * 1,3,5 once * * // 每天1点3点5点中运行一次(假设当1点时运行了一次,3,5点将不会再运行) +//@crontab * 10-23 once * * // 每天10点-23:59中运行一次(假设当10:04时运行了一次,10:05-23:59的后续时间将不会再运行) +//@crontab * once 13 * * // 每个月的13号的每小时运行一次 +//@crontab * once(9-17) * * * // 每天9时至17时期间,每小时执行一次 +//@crontab 0,30 once * * * // 每小时在0分或30分中,最早命中的那次执行,本小时不再重复 +//@crontab * 9-18 once * * // 每天9时至18时之间只执行一次 ``` ## 使用建议 @@ -173,8 +216,12 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发,对于兼容性 ## Cron 表达式测试 -测试 cron 表达式时,请将 `once` **临时替换为 `*`**。 -注意测试工具有可能不支持 扩展 6 位格式。 +测试 cron 表达式时,请将 `once` / `once(...)` **临时替换为对应的值**: + +* `once` → `*` +* `once(expr)` → `expr` + +注意测试工具有可能不支持扩展 6 位格式。 推荐工具: