chrome.alarms

الوصف

استخدِم واجهة برمجة التطبيقات chrome.alarms لجدولة تنفيذ الرمز بشكل دوري أو في وقت محدّد في المستقبل.

الأذونات

alarms

البيان

لاستخدام واجهة برمجة التطبيقات chrome.alarms، عليك الإعلان عن إذن "alarms" في البيان:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

أمثلة

توضّح الأمثلة التالية كيفية استخدام المنبّه والردّ عليه. لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال Alarm API من مستودع chrome-extension-samples.

ضبط منبّه

يضبط المثال التالي منبّهًا في مشغّل الخدمات عند تثبيت الإضافة:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

الردّ على منبّه

يضبط المثال التالي رمز شريط الأدوات للإجراء استنادًا إلى اسم المنبّه الذي تم تشغيله.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

الأنواع

Alarm

الخصائص

  • name

    سلسلة

    اسم هذا المنبّه.

  • periodInMinutes

    رقم (اختياري)

    إذا لم تكن القيمة خالية، يكون المنبّه متكررًا وسيتم تشغيله مرة أخرى بعد periodInMinutes دقيقة.

  • persistAcrossSessions

    قيمة منطقية

    Chrome 150 والإصدارات الأحدث

    تحديد ما إذا كان يجب أن يبقى المنبّه نشطًا خلال الجلسات (إعادة تشغيل المتصفّح)

  • scheduledTime

    الرقم

    الوقت الذي تم فيه ضبط المنبّه ليتم تشغيله، بالملّي ثانية منذ بداية الحقبة (مثلاً Date.now() + n). لأسباب متعلّقة بالأداء، قد يكون المنبّه قد تأخّر بمقدار عشوائي يتجاوز هذا الوقت.

AlarmCreateInfo

الخصائص

  • delayInMinutes

    رقم (اختياري)

    المدة بالدقائق التي يجب بعدها تشغيل الحدث onAlarm

  • name

    سلسلة اختيارية

    في انتظار المراجعة

    اسم هذا المنبّه.

  • periodInMinutes

    رقم (اختياري)

    إذا تم ضبط هذه القيمة، يجب تشغيل الحدث onAlarm كل periodInMinutes دقيقة بعد الحدث الأولي المحدّد من خلال when أو delayInMinutes. إذا لم يتم ضبط هذه القيمة، سيتم تشغيل المنبّه مرة واحدة فقط.

  • persistAcrossSessions

    قيمة منطقية اختيارية

    Chrome 150 والإصدارات الأحدث

    تحديد ما إذا كان يجب أن يبقى المنبّه نشطًا خلال الجلسات (إعادة تشغيل المتصفّح) في Chrome، يتم ضبط هذه القيمة تلقائيًا على "صحيح" لتتطابق مع السلوك السابق، ولكن عليك ضبطها بشكل صريح لتحقيق أقصى قدر من التوافق مع المتصفّحات المختلفة.

  • when

    رقم (اختياري)

    الوقت الذي يجب فيه تشغيل المنبّه، بالملّي ثانية منذ بداية الحقبة (مثلاً Date.now() + n)

الطُرق

clear()

Promise 
chrome.alarms.clear(
  name?: string,
  callback?: function,
): Promise<boolean>

يزيل المنبّه بالاسم المحدّد.

المعلمات

  • name

    سلسلة اختيارية

    اسم المنبّه الذي تريد إزالته. القيمة التلقائية هي السلسلة الفارغة.

  • callback

    دالة (اختيارية)

    تبدو مَعلمة callback على النحو التالي: 

    (wasCleared: boolean) => void

    • wasCleared

      قيمة منطقية

المرتجعات

  • Promise<boolean>

    Chrome 91 والإصدارات الأحدث

    لا تتوافق الوعود إلا مع Manifest V3 والإصدارات الأحدث، بينما تحتاج الأنظمة الأساسية الأخرى إلى استخدام دوال ردّ الاتصال.

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

يزيل جميع المنبّهات.

المعلمات

  • callback

    دالة (اختيارية)

    تبدو مَعلمة callback على النحو التالي: 

    (wasCleared: boolean) => void

    • wasCleared

      قيمة منطقية

المرتجعات

  • Promise<boolean>

    Chrome 91 والإصدارات الأحدث

    لا تتوافق الوعود إلا مع Manifest V3 والإصدارات الأحدث، بينما تحتاج الأنظمة الأساسية الأخرى إلى استخدام دوال ردّ الاتصال.

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

ينشئ منبّهًا. في الأوقات المحدّدة من خلال alarmInfo، يتم تشغيل الحدث onAlarm. إذا كان هناك منبّه آخر بالاسم نفسه (أو بدون اسم إذا لم يتم تحديد اسم)، سيتم إلغاؤه واستبداله بهذا المنبّه.

لتقليل الحمل على جهاز المستخدم، يقتصر Chrome على تشغيل المنبّهات مرة واحدة على الأكثر كل 30 ثانية، ولكن قد يؤخّرها بمقدار عشوائي إضافي. أي أنّه لن يتم تنفيذ ضبط delayInMinutes أو periodInMinutes على أقل من 0.5 وسيؤدي ذلك إلى ظهور تحذير. يمكن ضبط when على أقل من 30 ثانية بعد "الآن" بدون ظهور تحذير، ولكن لن يؤدي ذلك فعليًا إلى تشغيل المنبّه لمدة 30 ثانية على الأقل.

لمساعدتك في تصحيح أخطاء تطبيقك أو إضافتك، لا يوجد حدّ لعدد مرات تشغيل المنبّه عند تحميله بدون ضغطه.

المعلمات

  • name

    سلسلة اختيارية

    اسم اختياري لتحديد هذا المنبّه. القيمة التلقائية هي السلسلة الفارغة.

  • alarmInfo

    AlarmCreateInfo

    يصف هذا النوع الوقت الذي يجب فيه تشغيل المنبّه. يجب تحديد الوقت الأولي من خلال when أو delayInMinutes (وليس كلاهما). إذا تم ضبط periodInMinutes، سيتكرّر المنبّه كل periodInMinutes دقيقة بعد الحدث الأولي. إذا لم يتم ضبط when أو delayInMinutes لمنبّه متكرّر، يتم استخدام periodInMinutes كقيمة تلقائية لـ delayInMinutes.

  • callback

    دالة (اختيارية)

    Chrome 111 والإصدارات الأحدث

    تبدو مَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

    Chrome 111 والإصدارات الأحدث

    وعد يتم تنفيذه عند إنشاء المنبّه

    لا تتوافق الوعود إلا مع Manifest V3 والإصدارات الأحدث، بينما تحتاج الأنظمة الأساسية الأخرى إلى استخدام دوال ردّ الاتصال.

get()

Promise 
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

يستردّ تفاصيل حول المنبّه المحدّد.

المعلمات

  • name

    سلسلة اختيارية

    اسم المنبّه الذي تريد الحصول عليه. القيمة التلقائية هي السلسلة الفارغة.

  • callback

    دالة (اختيارية)

    تبدو مَعلمة callback على النحو التالي: 

    (alarm?: Alarm) => void

    • alarm

      Alarm اختياري

المرتجعات

  • Promise<Alarm | undefined>

    Chrome 91 والإصدارات الأحدث

    لا تتوافق الوعود إلا مع Manifest V3 والإصدارات الأحدث، بينما تحتاج الأنظمة الأساسية الأخرى إلى استخدام دوال ردّ الاتصال.

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

يحصل على مصفوفة تضم جميع المنبّهات.

المعلمات

  • callback

    دالة (اختيارية)

    تبدو مَعلمة callback على النحو التالي: 

    (alarms: Alarm[]) => void

المرتجعات

  • Promise<Alarm[]>

    Chrome 91 والإصدارات الأحدث

    لا تتوافق الوعود إلا مع Manifest V3 والإصدارات الأحدث، بينما تحتاج الأنظمة الأساسية الأخرى إلى استخدام دوال ردّ الاتصال.

الفعاليات

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

يتم تشغيله عند انتهاء المنبّه. مفيد لصفحات الأحداث

المعلمات

  • callback

    دالة

    تبدو مَعلمة callback على النحو التالي: 

    (alarm: Alarm) => void