chrome.alarms

الوصف

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

الأذونات

alarms

البيان

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

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

أمثلة

توضّح الأمثلة التالية كيفية استخدام منبّه والاستجابة له. لتجربة واجهة برمجة التطبيقات هذه، تثبيت مثال على واجهة برمجة تطبيقات Alarm من 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

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

    إذا لم يكن صفرًا، هذا يعني أنّ المنبّه هو إنذار متكرّر وسيتم تشغيله مرة أخرى خلال 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

      منطقي

المرتجعات

  • Promise<boolean>

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

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

clearAll()

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

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

المعلمات

  • رد الاتصال

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

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

    (wasCleared: boolean) => void

    • wasCleared

      منطقي

المرتجعات

  • Promise<boolean>

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

    لا تتوفّر الوعود إلا مع إصدار 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.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

get()

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

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

المعلمات

  • الاسم

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

    اسْمِ الْمُنَبِّهْ الْمَطْلُوبْ. إعداد القيمة التلقائية على السلسلة الفارغة.

  • رد الاتصال

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

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

    (alarm?: Alarm) => void

المرتجعات

  • Promise&lt;Alarm | غير محددة>

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

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

getAll()

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

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

المعلمات

  • رد الاتصال

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

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

    (alarms: Alarm[]) => void

المرتجعات

  • التعهد<المنبّه[]>

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

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

فعاليات

onAlarm

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

يتم إطلاقها عند انقضاء وقت المنبّه. ويكون ذلك مفيدًا لصفحات الفعاليات.

المعلمات

  • رد الاتصال

    دالة

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

    (alarm: Alarm) => void