الوصف
استخدِم واجهة برمجة تطبيقات chrome.alarms
لجدولة الرموز ليتم تشغيلها بشكل دوري أو في وقت محدّد في المستقبل.
الأذونات
alarms
لاستخدام واجهة برمجة تطبيقات chrome.alarms
، عليك تعريف إذن ""alarms"
" في البيان:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
المفاهيم والاستخدام
لفهم سلوك واجهة برمجة التطبيقات بشكل موثوق، من المفيد فهمها.
سكون الجهاز
يستمر تشغيل المنبّهات عندما يكون الجهاز في وضع السكون. ومع ذلك، لن يستيقظ المنبه الجهاز. عندما يتم تنشيط الجهاز، سيتم إطلاق أي منبّهات فائتة. سيتم إطلاق المنبّهات المتكررة مرة واحدة على الأكثر ثم يُعاد جدولتها وفقًا للمدة المحدّدة، بدءًا من وقت تنشيط الجهاز، بدون مراعاة أي وقت انقضى منذ ضبط الإنذار في الأصل.
الإصرار
تستمر المنبّهات عادةً إلى أن يتم تحديث الإضافة. ومع ذلك، لا يمكن ضمان ذلك، وقد يتم محو التنبيهات عند إعادة تشغيل المتصفح. وبالتالي، ننصحك بضبط قيمة لمساحة التخ��ين عند إنشاء تنبيه والتأكّد من أنّه متوفّر في كل مرة يبدأ فيها تشغيل عامل الخدمة. مثلاً:
const STORAGE_KEY = "user-preference-alarm-enabled";
async function checkAlarmState() {
const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);
if (alarmEnabled) {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create({ periodInMinutes: 1 });
}
}
}
checkAlarmState();
أمثلة
توضّح الأمثلة التالية كيفية استخدام منبّه والاستجابة له. لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت مثال 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 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
سيتم محو كل المنبّهات.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(wasCleared: boolean) => void
-
wasCleared
boolean
-
المرتجعات
-
Promise<boolean>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار 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 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
لاسترداد تفاصيل حول التنبيه المحدد.
المَعلمات
المرتجعات
-
Promise<Alarm | undefined>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getAll()
chrome.alarms.getAll(
callback?: function,
)
تلقّي مجموعة من المنبّهات
المَعلمات
المرتجعات
-
وعد<منبه[]>
Chrome 91 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.