chrome.alarms

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

alarms

البيان

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

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

أمثلة

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

ملاحظة: اعتبارًا من الإصدار 117 من Chrome، يقتصر عدد التنبيهات النشطة على 500 تنبيه. وعند بلوغ هذا الحدّ، سيتعذّر تنفيذ chrome.alarms.create(). عند استخدام معاودة الاتصال، سيتم ضبط chrome.runtime.lastError. عند استخدام الوعود، سيتم رفض الوعد.

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

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

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.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()

Promise

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

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

المعلمات

• الاسم

  string اختياري

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

• callback

  function اختياري

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

  (wasCleared: boolean) => void

  • wasCleared

    قيمة منطقية

المرتجعات

• Promise<boolean>

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

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

clearAll()

Promise

chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean | undefined>

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

المعلمات

• callback

  function اختياري

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

  (wasCleared?: boolean) => void

  • wasCleared

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

المرتجعات

• Promise<boolean | undefined>

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

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

create()

Promise

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

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

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

المعلمات

• الاسم

  string اختياري

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

• alarmInfo

  AlarmCreateInfo

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

• callback

  function اختياري

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

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

  () => void

المرتجعات

• وعد<فراغ>

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

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

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

get()

Promise

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

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

المعلمات

• الاسم

  string اختياري

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

• callback

  function اختياري

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

  (alarm?: Alarm) => void

  • منبّه

    المنبّه اختياري

المرتجعات

• Promise<Alarm | undefined>

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

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getAll()

Promise

chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

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

المعلمات

• callback

  function اختياري

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

  (alarms: Alarm[]) => void

  • المنبّهات

    المنبّه[]

المرتجعات

• Promise<Alarm[]>

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

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

الفعاليات

onAlarm

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

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

المعلمات

• callback

  دالة

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

  (alarm: Alarm) => void

  • منبّه

    المنبّه