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

الخصائص

  • الاسم

    سلسلة

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

  • periodInMinutes

    number اختياري

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

  • scheduledTime

    الرقم

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

AlarmCreateInfo

الخصائص

  • delayInMinutes

    number اختياري

    تمثّل هذه السمة المدة الزمنية بالدقائق التي يجب أن يتم بعدها تنشيط الحدث onAlarm.

  • periodInMinutes

    number اختياري

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

  • متى

    number اختياري

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

الطُرق

clear()

الوعد 
chrome.alarms.clear(
  name?: string,
  callback?: function,
): Promise<boolean>

يمحو هذا الإجراء المنبّه الذي يحمل الاسم المحدّد.

المعلمات

  • الاسم

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

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

  • callback

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

    تظهر المَعلمة callback على النحو التالي: 

    (wasCleared: boolean) => void

    • wasCleared

      قيمة منطقية

المرتجعات

  • Promise<boolean>

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

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

clearAll()

الوعد 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

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

المعلمات

  • callback

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

    تظهر المَعلمة callback على النحو التالي: 

    (wasCleared: boolean) => void

    • wasCleared

      قيمة منطقية

المرتجعات

  • Promise<boolean>

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

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

create()

الوعد 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

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

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

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

المعلمات

  • الاسم

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

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

  • alarmInfo

    AlarmCreateInfo

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

  • callback

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

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

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

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

get()

الوعد 
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

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

المعلمات

  • الاسم

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

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

  • callback

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

    تظهر المَعلمة callback على النحو التالي: 

    (alarm?: Alarm) => void

المرتجعات

  • Promise<Alarm | undefined>

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

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

getAll()

الوعد 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

تعرض هذه الطريقة مصفوفة تتضمّن جميع المنبّهات.

المعلمات

  • callback

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

    تظهر المَعلمة callback على النحو التالي: 

    (alarms: Alarm[]) => void

    • المنبّهات

      Alarm[]

المرتجعات

  • Promise<Alarm[]>

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

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

الفعاليات

onAlarm

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

يتم إطلاقه عند انتهاء مدة المنبّه. تكون هذه السمة مفيدة لصفحات الأحداث.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (alarm: Alarm) => void