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

    قيمة منطقية

    Chrome 150+

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

  • scheduledTime

    الرقم

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

AlarmCreateInfo

الخصائص

  • delayInMinutes

    number اختياري

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

  • الاسم

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

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

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

  • periodInMinutes

    number اختياري

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

  • persistAcrossSessions

    boolean اختياري

    Chrome 150+

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

  • متى

    number اختياري

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

الطُرق

clear()

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

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

المعلمات

  • الاسم

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

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

المرتجعات

  • 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 على مرة واحدة كل 30 ثانية على الأكثر، ولكن قد يتم تأخيرها لمدة عشوائية إضافية. أي أنّ ضبط delayInMinutes أو periodInMinutes على قيمة أقل من 0.5 لن يتم تنفيذه وسيؤدي إلى ظهور تحذير. يمكن ضبط قيمة when على أقل من 30 ثانية بعد "الآن" بدون تحذير، ولكن لن يتم تشغيل المنبّه فعليًا لمدة 30 ثانية على الأقل.

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

المعلمات

  • الاسم

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

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

  • alarmInfo

    AlarmCreateInfo

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

المرتجعات

  • Promise<void>

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

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

get()

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

تعرض هذه الطريقة تفاصيل حول المنبّه المحدّد.

المعلمات

  • الاسم

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

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

المرتجعات

  • 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