chrome.alarms

الوصف

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

الأذونات

alarms

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

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

المفاهيم وطريقة الاستخدام

لضمان السلوك الموثوق، من المفيد فهم سلوك واجهة برمجة التطبيقات.

وضع السكون للجهاز

يستمر تشغيل المنبّهات عندما يكون الجهاز في وضع السكون. ومع ذلك، لن يؤدي المنبّه إلى desperte جهاز. عند تنشيط الجهاز، سيتم تشغيل أي منبّهات لم يتم تفعيلها. سيتم تشغيل المنبّهات المتكرّرة مرة واحدة بحد أقصى، ثم ستتم إعادة جدولتها باستخدام المدّة المحدّدة بدءًا من وقت تنشيط الجهاز، بدون مراعاة أي وقت مضى منذ ضبط المنبّه في الأصل ليعمل.

الاستمرارية

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

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

    if (!alarm) {
      await chrome.alarms.create({ periodInMinutes: 1 });
    }
  }
}

checkAlarmState();

أمثلة

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

    رقم اختياري

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

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

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

clearAll()

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

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

المعلمات

  • ردّ الاتصال

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

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

    (wasCleared: boolean) => void

    • wasCleared

      قيمة منطقية

المرتجعات

  • Promise<boolean>

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

    تتوفّر الوعود في الإصدار 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 والإصدارات الأحدث

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

get()

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

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

المعلمات

  • الاسم

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

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

  • ردّ الاتصال

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

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

    (alarm?: Alarm) => void

المرتجعات

  • Promise<Alarm | undefined>

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

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

getAll()

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

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

المعلمات

  • ردّ الاتصال

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

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

    (alarms: Alarm[]) => void

المرتجعات

  • Promise<Alarm[]>

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

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

الفعاليات

onAlarm

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

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

المعلمات

  • ردّ الاتصال

    دالة

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

    (alarm: Alarm) => void