الوصف
استخدِم chrome.alarms API لجدولة تشغيل الرمز بشكل دوري أو في وقت محدّد في المستقبل.
الأذونات
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();
أمثلة
توضّح الأمثلة التالية كيفية استخدام منبّه والاستجابة له. لتجربة واجهة برمجة التطبيقات هذه، تثبيت مثال على واجهة برمجة تطبيقات Alarm من 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
});
});
الاستجابة لمنبّه
يحدد المثال التالي رمز شريط أدوات الإجراء استنادًا إلى اسم المنبه الذي انطلق.
service-worker.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
منطقي
-
المرتجعات
-
Promise<boolean>
الإصدار 91 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
يمحو هذا الزر جميع المنبّهات.
المعلمات
-
رد الاتصال
الدالة اختيارية
تظهر المَعلمة
callbackعلى النحو التالي:(wasCleared: boolean) => void
-
wasCleared
منطقي
-
المرتجعات
-
Promise<boolean>
الإصدار 91 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار 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. -
رد الاتصال
الدالة اختيارية
الإصدار 111 من Chrome أو الإصدارات الأحدثتظهر المَعلمة
callbackعلى النحو التالي:() => void
المرتجعات
-
وعود <باطلة>
الإصدار 111 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
لاسترداد التفاصيل حول المنبّه المحدد.
المعلمات
المرتجعات
-
Promise<Alarm | غير محددة>
الإصدار 91 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.
getAll()
chrome.alarms.getAll(
callback?: function,
)
الحصول على مجموعة من جميع المنبّهات
المعلمات
المرتجعات
-
التعهد<المنبّه[]>
الإصدار 91 من Chrome أو الإصدارات الأحدثتتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.