chrome.alarms

الوصف

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

الأذونات

alarms

البيان

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

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

أمثلة

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

تعيير منبّه

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

service-work.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-work.js:

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

الأنواع

Alarm

أماكن إقامة

  • اسم

    سلسلة

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

  • periodInMinutes

    الرقم اختياري

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

  • scheduledTime

    الرقم

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

AlarmCreateInfo

أماكن إقامة

  • delayInMinutes

    الرقم اختياري

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

  • periodInMinutes

    الرقم اختياري

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

  • عندما

    الرقم اختياري

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

الطُرق

clear()

وعد 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

سيتم محو المنبّه باستخدام الاسم الذي تم إدخاله.

المَعلمات

  • اسم

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

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

  • معاودة الاتصال

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

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

المرتجعات

  • Promise<boolean>

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

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

clearAll()

وعد 
chrome.alarms.clearAll(
  callback?: function,
)

سيتم محو كل المنبّهات.

المَعلمات

  • معاودة الاتصال

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

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

المرتجعات

  • Promise<boolean>

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

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

create()

وعد 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

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

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

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

المَعلمات

  • اسم

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

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

  • alarmInfo

    AlarmCreateInfo

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

  • معاودة الاتصال

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

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

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

    ()=>void

المرتجعات

  • Promise<void>

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

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

get()

وعد 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

المَعلمات

  • اسم

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

    اسم المنبّه الذي تريد تلقّيه يتم ضبط القيمة التلقائية على السلسلة الفارغة.

  • معاودة الاتصال

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

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

    (alarm?: Alarm)=>void

المرتجعات

  • وعد<منبّه|غير محدّد>

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

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

getAll()

وعد 
chrome.alarms.getAll(
  callback?: function,
)

تلقّي مجموعة من المنبّهات

المَعلمات

  • معاودة الاتصال

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

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

    (alarms: Alarm[])=>void

المرتجعات

  • وعد<منبه[]>

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

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

فعاليات

onAlarm

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

يتم تنشيطها عند انقضاء أحد التنبيهات. وهذه السمة مفيدة لصفحات الفعاليات.

المَعلمات

  • معاودة الاتصال

    الوظيفة

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

    (alarm: Alarm)=>void