browser.alarms

الوصف

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

الأذونات

alarms

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

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

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

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

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

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

الاستمرارية

يمكنك التحكّم في استمرار المنبّه عند إنشائه باستخدام العلامة persistAcrossSessions. يمكن ضبط هذه السياسة على true (تظل قائمة إلى أن يتم تحديث الإضافة) أو false (يتم محوها في حال إعادة تحميل الإضافة أو إعادة تشغيل المتصفّح، وعند تحديث الإضافة).

المتصفّحات الأخرى والإصدارات الأقدم من Chrome

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

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

إذا تم إنشاء المنبّه ديناميكيًا استنادًا إلى إجراء المستخدم، قد تحتاج إلى تخزين المنبّه الذي تم إنشاؤه في مكان آخر حتى تتمكّن من إعادة إنشائه إذا لزم الأمر.

أمثلة

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

ضبط منبّه

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

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

الردّ على إنذار

يضبط المثال التالي رمز شريط أدوات الإجراءات استنادًا إلى اسم المنبّه الذي رنّ.

service-worker.js:

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

الأنواع

Alarm

الخصائص

  • الاسم

    سلسلة

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

  • periodInMinutes

    number اختيارية

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

  • persistAcrossSessions

    قيمة منطقية

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

    ما إذا كان يجب أن يستمر المنبّه في جميع الجلسات (إعادة تشغيل المتصفّح).

  • scheduledTime

    الرقم

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

AlarmCreateInfo

الخصائص

  • delayInMinutes

    number اختيارية

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

  • الاسم

    string اختياري

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

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

  • periodInMinutes

    number اختيارية

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

  • persistAcrossSessions

    قيمة منطقية اختيارية

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

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

  • متى

    number اختيارية

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

الطُرق

clear()

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

لمحو المنبّه الذي يحمل الاسم المحدّد

المعلمات

  • الاسم

    string اختياري

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

المرتجعات

  • Promise<boolean>

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

clearAll()

chrome.alarms.clearAll(): Promise<boolean | undefined>

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

المرتجعات

  • Promise<boolean | undefined>

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

create()

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

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

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

المعلمات

  • الاسم

    string اختياري

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

  • alarmInfo

    AlarmCreateInfo

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

المرتجعات

  • وعد<فراغ>

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

    وعد يتم حله عند إنشاء المنبّه.

get()

chrome.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

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

المعلمات

  • الاسم

    string اختياري

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

المرتجعات

  • Promise<Alarm | undefined>

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

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

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

المرتجعات

  • Promise<Alarm[]>

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

الفعاليات

onAlarm

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

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

المعلمات

  • callback

    دالة

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

    (alarm: Alarm) => void