اسکریپت پس‌زمینه

اسکریپت‌های پس‌زمینه برای اسکریپت‌هایی مناسب هستند که باید به طور مداوم در حال اجرا بمانند. اسکریپت‌های پس‌زمینه یک نوع اسکریپت مخصوص ScriptCat هستند؛ آن‌ها در یک sandbox اجرا می‌شوند و نمی‌توانند به DOM دسترسی پیدا کنند. آن‌ها را می‌توان با همان APIهای GM مانند تامپرمانکی توسعه داد و نکات سازگاری در مستندات ذکر شده است.

اسکریپت پس‌زمینه (@background)

یک اسکریپت پس‌زمینه با ویژگی @background اعلام می‌شود. این اجازه می‌دهد اسکریپت پس از فعال شدن اسکریپت یا شروع مرورگر در پس‌زمینه به کار خود ادامه دهد.

اسکریپت زمان‌بندی‌شده (@crontab)

یک اسکریپت زمان‌بندی‌شده نوعی اسکریپت پس‌زمینه است که برای کارهایی مناسب است که باید به طور مکرر در یک چرخه زمانی اجرا شوند.

یک اسکریپت زمان‌بندی‌شده با ویژگی @crontab اعلام می‌شود. از زمان‌بندی در سطح دقیقه و ثانیه پشتیبانی می‌کند و نحو توسعه‌یافته once / once(...) را برای جلوگیری از اجرای بیش از یک بار در همان چرخه زمانی ارائه می‌دهد.

⚠️ نکات:

• در یک اسکریپت، فقط اولین @crontab اثر می‌کند
• توصیه می‌شود زمان اجرای تکی + زمان تلاش مجدد اسکریپت از فاصله cron تجاوز نکند، در غیر این صورت ممکن است اجراها همپوشانی داشته باشند

نکات عبارت Cron

پیاده‌سازی cron در ScriptCat بر اساس node-cron است، با یک افزونه کوچک بر روی نحو استاندارد cron.

قالب عبارت

قالب استاندارد ۵ فیلدی (توصیه‌شده)

minute hour day month weekday

قالب توسعه‌یافته ۶ فیلدی (توصیه نمی‌شود)

second minute hour day month weekday

⚠️ قالب ۶ فیلدی توصیه نمی‌شود محیط‌های مرورگر نمی‌توانند دقت در سطح ثانیه را تضمین کنند و سربار عملکرد را افزایش می‌دهد — صفحه پس‌زمینه ممکن است در زمان‌بندی تأخیر داشته باشد.

نحو موجود برای هر فیلد

نحو	معنی	مثال
*	هر مقدار	* (هر دقیقه/ساعت)
عدد	مقدار خاص	5 (دقیقه پنجم)
a,b,c	چند مقدار گسسته	1,15,30
a-b	بازه پیوسته	10-23
*/n	هر n واحد	*/5
a-b/n	بازه با گام	10-50/10

قوانین روز هفته

• 1–6: دوشنبه تا شنبه
• 0 یا 7: یکشنبه

نحو توسعه once

معنی once

استفاده از once در عبارت cron به این معنی است:

در چرخه زمانی فعلی، فقط یک اجرای موفق مجاز است

حتی اگر نقاط زمانی بعدی در همان چرخه همچنان با قانون cron مطابقت داشته باشند، اسکریپت دوباره اجرا نمی‌شود.

once در برابر once(...)

نحو	مقدار cron زیربنایی برای این فیلد	توضیحات
once	* (هر مقدار)	در اولین تطبیق در چرخه اجرا می‌شود، بدون زمان خاص
once(expr)	expr	فقط در زمان‌هایی که در چرخه با expr مطابقت دارند اجرا می‌شود، و فقط یک بار

once(expr) به شما امکان می‌دهد نقاط زمانی کاندید را دقیقاً مشخص کنید در حالی که همچنان «فقط یک بار در هر چرخه اجرا» را اعمال می‌کنید. تمام نحو استاندارد cron (اعداد، بازه‌ها، گام‌ها، فهرست‌ها) در داخل پرانتز پشتیبانی می‌شود.

مقایسه مثال:

* once * * *          // هر دقیقه از هر ساعت؛ در اولین تطبیق اجرا می‌شود، بدون اجرای بیشتر در آن ساعت
* once(9-17) * * *    // بین 9:00 و 17:59 هر روز، یک بار در ساعت اجرا می‌شود
0,30 once * * *       // هر کدام از دقیقه 0 یا 30 که اول تطبیق داده شود در آن ساعت اجرا می‌شود؛ بدون اجرای بیشتر در آن ساعت

موقعیت once = چرخه زمانی که محدود می‌کند

هرجا once / once(...) قرار گیرد، به این معنی است که «فقط یک بار در آن دانه‌بندی زمانی اجرا شو.»

موقعیت once	رفتار
فیلد دقیقه	فقط یک بار در دقیقه اجرا می‌شود
فیلد ساعت	فقط یک بار در ساعت اجرا می‌شود
فیلد روز	فقط یک بار در روز اجرا می‌شود
فیلد ماه	فقط یک بار در ماه اجرا می‌شود
فیلد روز هفته	فقط یک بار در هفته اجرا می‌شود

مثال‌ها:

* once * * *       // فقط یک بار در ساعت اجرا می‌شود
* * once * *       // فقط یک بار در روز اجرا می‌شود
* 9-18 once * *    // فقط یک بار بین 9:00 و 18:59 هر روز اجرا می‌شود

once ترکیب با بازه‌ها / فهرست‌ها / گام‌ها

once / once(...) را می‌توان با هر نحو cron ترکیب کرد، اما فقط یک قانون وجود دارد:

در همان چرخه، پس از موفقیت یک اجرا، تمام نقاط زمانی مطابق بعدی نادیده گرفته می‌شوند

مثال ۱: بازه

* 10 once * *

معنی:

• هر روز، 10:00–10:59 زمان‌های کاندید هستند
• پس از اولین تطبیق روز
• 10:05–10:59 دیگر اجرا نمی‌شوند

مثال ۲: فهرست

* 1,3,5 once * *

معنی:

• هر روز، 1:00، 3:00 و 5:00 زمان‌های کاندید هستند
• اگر 1:00 قبلاً اجرا شده باشد
• 3:00 و 5:00 رد می‌شوند

مثال ۳: گام

* */4 once * *

معنی:

• هر روز، 0:00، 4:00، 8:00، 12:00، 16:00 و 20:00 زمان‌های کاندید هستند
• پس از اولین اجرای روز
• هیچ نقطه زمانی دیگری اجرا نمی‌شود

مثال ۴: once(...) مشخص‌کردن نقاط زمانی کاندید

* once(9-17) * * *

معنی:

• هر روز، 9:00 تا 17:00 ساعت‌های کاندید هستند
• چرخه هر ساعت بازنشانی می‌شود؛ در یک ساعت، اولین تطبیق اجراهای بعدی را متوقف می‌کند
• اثر: یک بار در ساعت بین 9:00 و 17:00 هر روز، در مجموع ۹ بار اجرا می‌شود

* 9-18 once * *

معنی:

• هر روز، 9:00–18:59 زمان‌های کاندید هستند
• once در فیلد روز چرخه را به یک بار در روز قفل می‌کند
• پس از اولین تطبیق روز، هیچ چیز دیگری قبل از 18:59 اجرا نمی‌شود

مثال‌های @crontab

رایج

//@crontab * * * * *        // یک بار در دقیقه اجرا می‌شود
//@crontab * * * * * *      // یک بار در ثانیه اجرا می‌شود (توصیه نمی‌شود)
//@crontab 0 */6 * * *      // هر ۶ ساعت بر روی ساعت اجرا می‌شود
//@crontab 15 */6 * * *     // در دقیقه ۱۵ هر ۶ ساعت اجرا می‌شود
//@crontab * once * * *     // حداکثر یک بار در ساعت اجرا می‌شود
//@crontab * * once * *     // حداکثر یک بار در روز اجرا می‌شود
//@crontab * 10 once * *    // فقط یک بار در ساعت 10:00 هر روز اجرا می‌شود (مثلاً اگر در 10:04 اجرا شد، از 10:05-10:59 دوباره اجرا نمی‌شود)
//@crontab * */4 once * *   // حداکثر یک بار هر ۴ ساعت هر روز بررسی می‌کند (مثلاً اگر در 4:00 اجرا شد، در 8، 12، 16، 20، 24 و غیره دوباره اجرا نمی‌شود)

پیشرفته

//@crontab * 1,3,5 once * *       // یک بار در 1:00، 3:00 یا 5:00 هر روز اجرا می‌شود (مثلاً اگر در 1:00 اجرا شد، در 3:00 یا 5:00 دوباره اجرا نمی‌شود)
//@crontab * 10-23 once * *       // یک بار بین 10:00 و 23:59 هر روز اجرا می‌شود (مثلاً اگر در 10:04 اجرا شد، از 10:05-23:59 دوباره اجرا نمی‌شود)
//@crontab * once 13 * *          // یک بار در ساعت در روز ۱۳ هر ماه اجرا می‌شود
//@crontab * once(9-17) * * *     // یک بار در ساعت بین 9:00 و 17:00 هر روز اجرا می‌شود
//@crontab 0,30 once * * *        // هر کدام از دقیقه 0 یا 30 که اول تطبیق داده شود در آن ساعت اجرا می‌شود؛ بدون تکرار در آن ساعت
//@crontab * 9-18 once * *        // فقط یک بار بین 9:00 و 18:00 هر روز اجرا می‌شود

توصیه‌های استفاده

موارد مناسب برای once

• کارهایی که فقط یک بار باید اجرا شوند در هر روز/ساعت

• اسکریپت‌های بررسی وضعیت، همگام‌سازی و گزارش

• اجتناب از مشکلات زیر:

  • مرورگر برای مدت طولانی باز نشده است
  • تأخیرهای زمان‌بندی صفحه پس‌زمینه
  • اجرای تکراری ناشی از راه‌اندازی مجدد مرورگر

برای once توصیه نمی‌شود

• کارهایی که باید در یک لحظه دقیق اجرا شوند
• اسکریپت‌هایی که زمان اجرای آن‌ها ممکن است به طور قابل توجهی از فاصله cron تجاوز کند
• کارهایی با الزامات سازگاری سخت‌گیرانه بر تعداد اجراها

تست عبارت‌های Cron

هنگام تست یک عبارت cron، لطفاً به طور موقت once / once(...) را با مقدار زیربنایی آن‌ها جایگزین کنید:

• once → *
• once(expr) → expr

توجه داشته باشید که ابزارهای تست ممکن است از قالب توسعه‌یافته ۶ فیلدی پشتیبانی نکنند.

ابزارهای توصیه‌شده:

• crontab.guru
• ماشین حساب cron tool.lu

در صفحه فهرست اسکریپت، روی ستون وضعیت اجرا هاور کنید تا زمان اجرای زمان‌بندی‌شده بعدی اسکریپت را ببینید.

لاگ‌ها

در صفحه فهرست اسکریپت، هاور کردن روی «ستون وضعیت اجرا» یک tooltip با وضعیت اجرای اسکریپت نشان می‌دهد؛ کلیک روی آن محتوای لاگ چاپ‌شده از طریق GM_log را باز می‌کند.

اشکال‌زدایی اسکریپت

اسکریپت‌های پس‌زمینه را می‌توان مستقیماً از صفحه ویرایشگر اسکریپت اشکال‌زدایی کرد، اما این محدودیت‌های زیر را دارد:

• value به درستی همگام‌سازی نمی‌شود
• منوهای registerMenu به درستی فعال نمی‌شوند

برای اشکال‌زدایی محیط اجرای واقعی، حالت توسعه‌دهنده را در تنظیمات افزونه فعال کنید، سپس صفحه background.html افزونه را برای اشکال‌زدایی باز کنید.

خطاهای مطرح‌شده در زمان اجرا را نیز می‌توان در لاگ اجرا مشاهده کرد.

Promise

الگوی زیر به شدت توصیه می‌شود، زیرا همچنین به مدیر اسکریپت اجازه می‌دهد اجرای اسکریپت را نظارت کند. اگر اسکریپت هر عملیات ناهمگامی انجام دهد، باید یک Promise برگرداند.

// ==UserScript==
// @name         اسکریپت پس‌زمینه
// @namespace    wyz
// @version      1.0.0
// @author       wyz
// @background
// ==/UserScript==
return new Promise((resolve, reject) => {
  if (Math.round((Math.random() * 10) % 2)) {
    resolve("ok"); // موفق
  } else {
    reject("error"); // ناموفق، با دلیل خطا
  }
});

// ==UserScript==
// @name         اسکریپت زمان‌بندی‌شده که یک بار در روز اجرا می‌شود
// @namespace    wyz
// @version      1.0.0
// @author       wyz
// @crontab      * * once * *
// ==/UserScript==
return new Promise((resolve, reject) => {
  if (Math.round((Math.random() * 10) % 2)) {
    resolve("ok"); // موفق
  } else {
    reject("error"); // ناموفق، با دلیل خطا
  }
});

// ==UserScript==
// @name         فراخوانی یک API
// @namespace    wyz
// @version      1.0.0
// @author       wyz
// @crontab      * * once * *
// ==/UserScript==
return new Promise((resolve, reject) => {
  GM_xmlhttpRequest({
    url: "https://bbs.tampermonkey.net.cn/",
    onload() {
      resolve("ok"); // موفق
    },
    onerror() {
      reject("error"); // ناموفق، با دلیل خطا
    },
  });
});

لطفاً مطمئن شوید که resolve / reject را فقط پس از پایان واقعی منطق اسکریپت فراخوانی می‌کنید. پس از فراخوانی، مدیر اجرای اسکریپت را کامل در نظر می‌گیرد و هر عملیات GM بعدی دیگر اثری نخواهد داشت.

تلاش مجدد خطا

اسکریپت‌های پس‌زمینه ScriptCat از تلاش مجدد خطا پشتیبانی می‌کنند. هنگامی که یک اسکریپت ناموفق باشد، می‌تواند با CATRetryError یک reject انجام دهد تا تلاش مجدد فعال شود.

• حداقل فاصله تلاش مجدد: ۵ ثانیه
• از تداخل با زمان اجرای خود اسکریپت خودداری کنید، در غیر این صورت ممکن است اجرای تکراری رخ دهد

// ==UserScript==
// @name         مثال تلاش مجدد
// @namespace    https://bbs.tampermonkey.net.cn/
// @version      0.1.0
// @description  تلاش برای تسخیر جهان!
// @author       شما
// @crontab      * * once * *
// @grant        GM_notification
// ==/UserScript==

return new Promise((resolve, reject) => {
  GM_notification({
    title: "retry",
    text: "تلاش مجدد تا ۱۰ ثانیه دیگر",
  });
  reject(new CATRetryError("xxx error", 10));
});