chrome.alarms

الوصف

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

الأذونات

alarms

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

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

المفاهيم والاستخدام

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

سكون الجهاز

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

الإصرار

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

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();

أمثلة

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

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

clearAll()

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

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

المَعلمات

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

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

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

المرتجعات

  • 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

المرتجعات

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

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

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

getAll()

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

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

المَعلمات

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

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

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

    (alarms: Alarm[])=>void

المرتجعات

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

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

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

فعاليات

onAlarm

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

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

المَعلمات

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

    الوظيفة

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

    (alarm: Alarm)=>void