From b0a03e48e18dc99b0b3be29b2df4663c04aafd65 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sun, 29 Mar 2026 10:59:23 +0900 Subject: [PATCH 1/2] =?UTF-8?q?=E9=85=8D=E5=90=88=20ScriptCat=201.3.x=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20`@crontab`=20=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/dev/background.md | 66 +++++++++++++++++++++++++++++++++++------- 1 file changed, 56 insertions(+), 10 deletions(-) diff --git a/docs/dev/background.md b/docs/dev/background.md index 06171c7..5475400 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(0) * * * // 每小时仅在 0 分时执行，本小时内不再执行（等效于 0 * * * *，但有 once 保护） +* once(0,30) * * * // 每小时在 0 分或 30 分中，最早命中的那次执行，本小时内不再执行 +``` + ### `once` 所在位置 = 限制的时间周期 -`once` 写在哪一位，就表示“在该时间粒度内只执行一次”。 +`once` / `once(...)` 写在哪一位，就表示"在该时间粒度内只执行一次"。 | `once` 位置 | 行为含义 | | --------- | -------- | @@ -84,13 +101,14 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 示例： ```text -* once * * * // 每小时只执行一次 -* * once * * // 每天只执行一次 +* once * * * // 每小时只执行一次 +* * once * * // 每天只执行一次 +* * once(0) * * // 每天只在 0 时执行一次（即每天 00:00 前后第一次命中） ``` ### `once` 与范围 / 列表 / 步长的组合行为 -`once` 可以与任何 cron 语法组合使用，但规则只有一条： +`once` / `once(...)` 可以与任何 cron 语法组合使用，但规则只有一条： > **在同一周期内，只要成功执行过一次，其余命中的时间点都会被忽略** @@ -130,6 +148,27 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 * 当天第一次执行后 * 其余时间点将不再执行 +#### 示例四：`once(...)` 指定候选时间点 + +```text +* once(0,30) * * * +``` + +含义： + +* 每小时仅 0 分、30 分为候选时间 +* 若 0 分已执行，30 分将被忽略 +* 下一小时重置，再次从 0 分开始判断 + +```text +* * once(9-18) * * +``` + +含义： + +* 每天仅 9 点至 18 点之间为候选时间 +* 当天第一次命中后，18 点前不再执行 + ## `@crontab` 示例 ### 常见 @@ -148,9 +187,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(0) * * * // 每小时仅在整点(0分)时执行一次 +//@crontab * once(0,30) * * * // 每小时在0分或30分中，最早命中的那次执行，本小时内不再执行 +//@crontab * * once(9-18) * * // 每天9点至18点之间只执行一次 ``` ## 使用建议 @@ -173,8 +215,12 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 ## Cron 表达式测试 -测试 cron 表达式时，请将 `once` **临时替换为 `*`**。 -注意测试工具有可能不支持 扩展 6 位格式。 +测试 cron 表达式时，请将 `once` / `once(...)` **临时替换为对应的值**： + +* `once` → `*` +* `once(expr)` → `expr` + +注意测试工具有可能不支持扩展 6 位格式。 推荐工具： From 4851ca2d728a0978cbdb20d7a477a0ed48c818c0 Mon Sep 17 00:00:00 2001 From: cyfung1031 <44498510+cyfung1031@users.noreply.github.com> Date: Sun, 29 Mar 2026 11:42:07 +0900 Subject: [PATCH 2/2] =?UTF-8?q?=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/dev/background.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/dev/background.md b/docs/dev/background.md index 5475400..2d7296a 100644 --- a/docs/dev/background.md +++ b/docs/dev/background.md @@ -81,9 +81,9 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 示例对比： ```text -* once * * * // 每小时任意分钟，第一次命中即执行，本小时内不再执行 -* once(0) * * * // 每小时仅在 0 分时执行，本小时内不再执行（等效于 0 * * * *，但有 once 保护） -* once(0,30) * * * // 每小时在 0 分或 30 分中，最早命中的那次执行，本小时内不再执行 +* once * * * // 每小时任意分钟，第一次命中即执行，本小时内不再执行 +* once(9-17) * * * // 每天 9 时至 17 时期间，每小时执行一次 +0,30 once * * * // 每小时在 0 分或 30 分中，最早命中的那次执行，本小时内不再执行 ``` ### `once` 所在位置 = 限制的时间周期 @@ -101,9 +101,9 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 示例： ```text -* once * * * // 每小时只执行一次 -* * once * * // 每天只执行一次 -* * once(0) * * // 每天只在 0 时执行一次（即每天 00:00 前后第一次命中） +* once * * * // 每小时只执行一次 +* * once * * // 每天只执行一次 +* 9-18 once * * // 每天 9 时至 18 时之间只执行一次 ``` ### `once` 与范围 / 列表 / 步长的组合行为 @@ -151,23 +151,24 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 #### 示例四：`once(...)` 指定候选时间点 ```text -* once(0,30) * * * +* once(9-17) * * * ``` 含义： -* 每小时仅 0 分、30 分为候选时间 -* 若 0 分已执行，30 分将被忽略 -* 下一小时重置，再次从 0 分开始判断 +* 每天 9 时至 17 时为候选小时 +* 每小时周期重置，当小时内第一次命中后不再重复 +* 效果：每天 9 时至 17 时期间，每小时各执行一次，共 9 次 ```text -* * once(9-18) * * +* 9-18 once * * ``` 含义： -* 每天仅 9 点至 18 点之间为候选时间 -* 当天第一次命中后，18 点前不再执行 +* 每天 9:00–18:59 为候选时间 +* 日位 `once` 锁定每天周期 +* 当天第一次命中后，18:59 前不再执行 ## `@crontab` 示例 @@ -190,9 +191,9 @@ DOM 对象。可使用与油猴一致的 GM API 进行开发，对于兼容性 //@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(0) * * * // 每小时仅在整点(0分)时执行一次 -//@crontab * once(0,30) * * * // 每小时在0分或30分中，最早命中的那次执行，本小时内不再执行 -//@crontab * * once(9-18) * * // 每天9点至18点之间只执行一次 +//@crontab * once(9-17) * * * // 每天9时至17时期间，每小时执行一次 +//@crontab 0,30 once * * * // 每小时在0分或30分中，最早命中的那次执行，本小时不再重复 +//@crontab * 9-18 once * * // 每天9时至18时之间只执行一次 ``` ## 使用建议