chrome.alarms

الوصف

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

الأذونات

alarms

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

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

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

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

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

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

الاستمرارية

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

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

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

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

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

checkAlarmState();

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

أمثلة

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

ضبط منبّه

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

service-worker.js:

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

الاستجابة لمنبّه

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

service-worker.js:

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

الأنواع

Alarm

الخصائص

  • name

    سلسلة

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

  • periodInMinutes

    رقم (اختياري)

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

  • persistAcrossSessions

    قيمة منطقية

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

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

  • scheduledTime

    الرقم

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

AlarmCreateInfo

الخصائص

  • delayInMinutes

    رقم (اختياري)

    طول المدة بالدقائق التي يجب بعدها تشغيل الحدث onAlarm

  • name

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

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

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

  • periodInMinutes

    رقم (اختياري)

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

  • persistAcrossSessions

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

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

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

  • when

    رقم (اختياري)

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

الطُرق

clear()

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

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

المعلمات

  • name

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

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

المرتجعات

  • Promise<boolean>

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

clearAll()

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

يزيل جميع المنبّهات.

المرتجعات

  • Promise<boolean>

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

create()

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

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

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

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

المعلمات

  • name

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

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

  • alarmInfo

    AlarmCreateInfo

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

المرتجعات

  • Promise<void>

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

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

get()

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

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

المعلمات

  • name

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

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

المرتجعات

  • Promise<Alarm | undefined>

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

getAll()

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

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

المرتجعات

  • Promise<Alarm[]>

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

الفعاليات

onAlarm

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

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

المعلمات

  • callback

    دالة

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

    (alarm: Alarm) => void