الوصف
استخدِم واجهة برمجة تطبيقات chrome.alarms
لجدولة الرموز ليتم تشغيلها بشكل دوري أو في وقت محدّد في المستقبل.
الأذونات
alarms
البيان
لاستخدام واجهة برمجة تطبيقات chrome.alarms
، عليك تعريف إذن ""alarms"
" في البيان:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
أمثلة
توضّح الأمثلة التالية كيفية استخدام منبّه والاستجابة له. لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت مثال 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 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
سيتم محو كل المنبّهات.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(wasCleared: boolean) => void
-
wasCleared
boolean
-
المرتجعات
-
Promise<boolean>
Chrome 91 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
تعمل على إنشاء منبّه. بالقرب من الأوقات التي يحدِّدها alarmInfo
، يتم تنشيط حدث onAlarm
. إذا كان هناك منبه آخر بالاسم نفسه (أو لم يتم تحديد أي اسم إذا لم يتم تحديد أي اسم)، فسيتم إلغاؤه واستبداله بهذا التنبيه.
لتقليل العبء على جهاز المستخدم، يعمل Chrome على تقييد المنبّهات بحد أقصى مرة واحدة كل 30 ثانية، إلا أنّه قد يؤخّرها بشكل عشوائي أكثر. وهذا يعني أنّه لن يتم قبول ضبط القيمة delayInMinutes
أو periodInMinutes
على أقل من 0.5
وسيؤدي ذلك إلى إرسال تحذير. يمكن ضبط "when
" على أقل من 30 ثانية بعد "الآن" بدون تحذير، إلا أنّ ذلك لن يؤدي إلى إطلاق الإنذار لمدة 30 ثانية على الأقل.
لمساعدتك في تصحيح أخطاء التطبيق أو الإضافة، لن يكون هناك حدّ لعدد مرات تشغيل المنبّه عند تحميل التطبيق أو الإضافة بعد فك ضغطه.
المَعلمات
-
اسم
سلسلة اختيارية
اسم اختياري لتحديد هذا المنبّه. يتم ضبط القيمة التلقائية على السلسلة الفارغة.
-
alarmInfo
تصف هذه السمة متى يجب إطلاق الإنذار. يجب تحديد الوقت الأولي من خلال
when
أوdelayInMinutes
(وليس كليهما). إذا تم ضبطperiodInMinutes
، سيتم تكرار المنبّه كلperiodInMinutes
دقيقة بعد الحدث الأوليّ. إذا لم يتم ضبطwhen
أوdelayInMinutes
على منبّه متكرّر، سيتم استخدامperiodInMinutes
كإعداد تلقائي لمدّةdelayInMinutes
. -
معاودة الاتصال
الدالة اختيارية
Chrome 111 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 111 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
لاسترداد تفاصيل حول التنبيه المحدد.
المَعلمات
المرتجعات
-
Promise<Alarm | undefined>
Chrome 91 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getAll()
chrome.alarms.getAll(
callback?: function,
)
تلقّي مجموعة من المنبّهات
المَعلمات
المرتجعات
-
وعد<منبه[]>
Chrome 91 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.