الوصف
يمكنك استخدام واجهة برمجة التطبيقات chrome.runtime
API لاسترداد مشغِّل الخدمات وعرض تفاصيل ملف البيان والاستماع إلى الأحداث والردّ عليها خلال مراحل نشاط الإضافة. ويمكنك أيضًا استخدام واجهة برمجة التطبيقات هذه لتحويل المسار النسبي لعناوين URL إلى عناوين URL مؤهَّلة بالكامل.
نظرة عامة
توفر واجهة برمجة تطبيقات وقت التشغيل طرقًا لدعم عدد من مجالات الوظائف التي يمكن للإضافات استخدامها:
- تمرير الرسالة
- يمكن للإضافة التواصل باستخدام سياقات مختلفة داخل إضافتك وكذلك مع إضافات أخرى باستخدام هذه الطرق والأحداث: connect()، onConnect، onConnectExternal، sendMessage()، onMessage، onMessageExternal. بالإضافة إلى ذلك، يمكن للإضافة تمرير الرسائل إلى التطبيقات الأصلية على جهاز المستخدم باستخدام connectNative() و sendNativeMessage().
- الوصول إلى البيانات الوصفية للإضافات والنظام الأساسي
- تتيح لك هاتان الطُرق استرداد عدة أجزاء من البيانات الوصفية حول الإضافة والنظام الأساسي. تتضمن الطرق في هذه الفئة getManifest() وgetPlatformInfo().
- إدارة مراحل نشاط الإضافات وخياراتها
- تتيح لك هذه السمات إجراء بعض العمليات الوصفية على الإضافة وعرض صفحة الخيارات. تتضمن الطرق والأحداث في هذه الفئة onInstalled وonStartup وopenOptionsPage() وreload() وrequestUpdateCheck() وsetUninstallURL().
- برامج الخدمات المساعدة
- توفّر هاتان الطُرق فائدة مثل تحويل تمثيلات الموارد الداخلية إلى تنسيقات خارجية. وتشمل الطرق في هذه الفئة getURL().
- الأدوات المساعدة لوضع Kiosk
- لا تتوفّر هذه الطرق إلا على نظام التشغيل ChromeOS، وهي متاحة بشكل أساسي لدعم عمليات تنفيذ Kiosk. تتضمن الطرق ضمن هذه الفئة restart و restartAfterDelay.
الأذونات
لا تتطلّب معظم الطرق في واجهة برمجة تطبيقات وقت التشغيل أي إذن، باستثناء sendNativeMessage وconnectNative اللذَين يتطلّبان إذن nativeMessaging
.
البيان
يوضّح المثال التالي كيفية تعريف إذن nativeMessaging
في ملف البيان:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
حالات الاستخدام
إضافة صورة إلى صفحة ويب
ولكي تتمكّن صفحة ويب من الوصول إلى مادة عرض مستضافة على نطاق آخر، يجب أن تحدد عنوان URL الكامل للمورد
(مثل <img src="https://example.com/logo.png">
). وينطبق الأمر نفسه على تضمين مادة عرض إضافة على صفحة ويب. يتمثّل الاختلافان في أنّه يجب إظهار مواد عرض الإضافة باعتبارها موارد يمكن الوصول إليها على الويب، وأنّ النصوص البرمجية للمحتوى تكون مسؤولة عادةً عن إدخال مواد عرض الإضافات.
في هذا المثال، ستضيف الإضافة logo.png
إلى الصفحة التي يتم إدخال نص المحتوى فيها باستخدام runtime.getURL()
لإنشاء عنوان URL مؤهّل بالكامل. يجب أولاً الإشارة إلى أنّ مادة العرض هي مورد يمكن الوصول إليه من خلال الويب في البيان.
manifest.json:
{
...
"web_accessible_resources": [
{
"resources": [ "logo.png" ],
"matches": [ "https://*/*" ]
}
],
...
}
content.js:
{ // Block used to avoid setting global variables
const img = document.createElement('img');
img.src = chrome.runtime.getURL('logo.png');
document.body.append(img);
}
إرسال البيانات من مشغّل الخدمات إلى نص برمجي للمحتوى
من الشائع أن تحتاج النصوص البرمجية لمحتوى الإضافة إلى بيانات يديرها جزء آخر من الإضافة، مثل عامل الخدمة. مثلما هو الحال مع نافذتي متصفح مفتوحتين على صفحة الويب نفسها، لا يمكن لهذين السياقين الوصول مباشرةً إلى قيم بعضهما البعض. بدلاً من ذلك، يمكن للإضافة استخدام تمرير الرسائل للتنسيق عبر هذه السياقات المختلفة.
في هذا المثال، يحتاج النص البرمجي للمحتوى إلى بعض البيانات من مشغّل خدمات الإضافة لإعداد واجهة المستخدم الخاصة به. للحصول على هذه البيانات، يعمل التطبيق على تمرير رسالة get-user-data
إلى مشغّل الخدمات،
ويستجيب لها بنسخة من معلومات المستخدم.
content.js:
// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
// 3. Got an asynchronous response with the data from the service worker
console.log('received user data', response);
initializeUI(response);
});
background.js:
// Example of a simple user data object
const user = {
username: 'demo-user'
};
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
// 2. A page requested user data, respond with a copy of `user`
if (message === 'get-user-data') {
sendResponse(user);
}
});
جمع الملاحظات حول إلغاء التثبيت
تستخدم العديد من الإضافات استطلاعات بعد إلغاء التثبيت لمعرفة كيف يمكن للإضافة خدمة المستخدمين بشكل أفضل وتحسين معدّل الاحتفاظ بهم. يوضّح المثال التالي كيفية إضافة هذه الوظيفة.
background.js:
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});
أمثلة على الإضافات
يمكنك الاطّلاع على الإصدار 3 من Manifest V3 - العرض التوضيحي للموارد التي يمكن الوصول إليها على الويب للحصول على مزيد من الأمثلة حول Runtime API.
الأنواع
ContextFilter
فلتر للمطابقة مع سياقات إضافات معيّنة يجب أن تتطابق السياقات المطابِقة مع جميع الفلاتر المحدّدة، ويتطابق أيّ فلتر لم يتمّ تحديده مع جميع السياقات المتاحة. وبالتالي، سيتطابق فلتر "{}" مع جميع السياقات المتاحة.
أماكن إقامة
-
contextIds
سلسلة[] اختيارية
-
contextTypes
ContextType[] اختيارية
-
documentIds
سلسلة[] اختيارية
-
documentOrigins
سلسلة[] اختيارية
-
documentUrls
سلسلة[] اختيارية
-
frameIds
number[] اختيارية
-
وضع التصفّح المتخفي
منطقية اختيارية
-
tabIds
number[] اختيارية
-
windowIds
number[] اختيارية
ContextType
التعداد
"TAB"
يحدد نوع السياق كعلامة تبويب.
"POPUP"
يحدد نوع السياق كنافذة منبثقة للإضافة.
"BACKGROUND"
يحدد نوع السياق كمشغّل خدمات.
"OFFSCREEN_DOCUMENT"
يحدد نوع السياق كمستند خارج الشاشة.
"SIDE_PANEL"
يحدد نوع السياق كلوحة جانبية.
ExtensionContext
سياق يستضيف محتوى الإضافة
أماكن إقامة
-
contextId
سلسلة
معرّف فريد لهذا السياق
-
contextType
نوع السياق المتوافق مع هذا المحتوى.
-
documentId
سلسلة اختيارية
معرّف UUID للمستند المرتبط بهذا السياق، أو غير معرَّف إذا تمت استضافته وليس في مستند.
-
documentOrigin
سلسلة اختيارية
إنّ أصل المستند المرتبط بهذا السياق أو غير محدّد إذا لم يكن السياق مستضافًا في مستند.
-
documentUrl
سلسلة اختيارية
تشير هذه السمة إلى عنوان URL للمستند المرتبط بهذا السياق أو غير محدّد إذا لم يكن السياق مستضافًا في مستند.
-
frameId
الرقم
تمثّل هذه السمة رقم تعريف الإطار الخاص بهذا السياق، أو -1 إذا لم تتم استضافة هذا السياق في إطار.
-
وضع التصفّح المتخفي
boolean
ما إذا كان السياق مرتبطًا بملف شخصي في وضع التصفّح المتخفي.
-
tabId
الرقم
تمثّل هذه السمة رقم تعريف علامة التبويب الخاصة بهذا السياق، أو -1 إذا لم تتم استضافة هذا السياق في علامة تبويب.
-
windowId
الرقم
رقم تعريف النافذة لهذا السياق، أو -1 إذا لم تتم استضافة هذا السياق في نافذة.
MessageSender
عنصر يحتوي على معلومات عن سياق النص البرمجي الذي أرسل رسالة أو طلبًا.
أماكن إقامة
-
documentId
سلسلة اختيارية
Chrome 106 والإصدارات الأحدثمعرّف UUID للمستند الذي فتح الاتصال.
-
documentLifecycle
سلسلة اختيارية
Chrome 106 والإصدارات الأحدثتكون دورة حياة المستند الذي فتح الاتصال موجودة في وقت إنشاء المنفذ. يُرجى العلم أنّ حالة دورة حياة المستند قد تغيّرت منذ إنشاء المنفذ.
-
frameId
الرقم اختياري
الإطار الذي فتح عملية الربط 0 للإطارات ذات المستوى الأعلى، وتكون إيجابية للإطارات الفرعية. لن يتم ضبط هذه السياسة إلا عند ضبط "
tab
". -
id
سلسلة اختيارية
رقم تعريف الإضافة التي فتحت الاتصال، إن توفّرت.
-
nativeApplication
سلسلة اختيارية
الإصدار 74 من Chrome والإصدارات الأحدثاسم التطبيق الأصلي الذي فتح عملية الربط، إن توفّرت.
-
الأصل
سلسلة اختيارية
Chrome 80 والإصدارات الأحدثأصل الصفحة أو الإطار الذي فتح الاتصال. يمكن أن يختلف عن خاصية عنوان URL (على سبيل المثال، about:blank) أو يكون غير شفاف (على سبيل المثال، إطارات iframe في وضع الحماية). ويُعدّ هذا الإجراء مفيدًا في تحديد ما إذا كان يمكن الوثوق في المصدر إذا لم نتمكّن من معرفة ذلك على الفور من عنوان URL.
-
Tab اختيارية
تمثّل هذه السمة
tabs.Tab
التي فتحت عملية الربط، في حال توفّرها. لن يكون هذا الموقع متاحًا إلا عند فتح الاتصال من علامة تبويب (بما في ذلك النصوص البرمجية للمحتوى)، وفقط إذا كان المُستلِم إضافة وليس تطبيقًا. -
tlsChannelId
سلسلة اختيارية
معرّف قناة بروتوكول أمان طبقة النقل (TLS) الخاصة بالصفحة أو الإطار الذي فتح الاتصال، إذا طلبته الإضافة، وإذا كان متاحًا.
-
url
سلسلة اختيارية
عنوان URL للصفحة أو الإطار الذي فتح الاتصال. وإذا كان المُرسِل في إطار iframe، سيكون عنوان URL لإطار iframe وليس عنوان URL للصفحة التي تستضيفه.
OnInstalledReason
سبب إرسال هذا الحدث
التعداد
"install"
يحدد هذا الإعداد سبب الحدث كعملية تثبيت.
"update"
يحدِّد سبب الحدث على أنّه تحديث للإضافة.
"chrome_update"
يحدِّد سبب الحدث على أنّه تحديث لمتصفِّح Chrome.
"shared_module_update"
يحدِّد سبب الحدث باعتباره تعديلاً لوحدة مشتركة.
OnRestartRequiredReason
سبب إرسال الحدث يتم استخدام "app_update" عندما تكون إعادة التشغيل مطلوبة لأن التطبيق محدّث إلى إصدار أحدث. يتم استخدام "os_update" عندما تكون إعادة التشغيل مطلوبة لأنّ المتصفِّح/نظام التشغيل يتم تحديثه إلى إصدار أحدث. تُستخدم كلمة "دوري" عندما يعمل النظام لمدة تتجاوز مدة التشغيل المسموح بها والمحددة في سياسة المؤسسة.
التعداد
"app_update"
يحدد سبب الحدث باعتباره تحديثًا للتطبيق.
"os_update"
يحدد سبب الحدث على أنّه تحديث لنظام التشغيل.
"دوري"
يحدد سبب الحدث على أنه إعادة تشغيل دورية للتطبيق.
PlatformArch
بنية معالج الجهاز.
التعداد
"arm"
يحدد هذا الإعداد بنية المعالج كمجموعة تطبيقات.
"arm64"
يحدد هذا الإعداد بنية المعالج على أنّه Arm64.
"x86-32"
يحدد هذا الإعداد بنية المعالج كـ x86-32.
"x86-64"
يحدد هذا الإعداد بنية المعالج على أنّه x86-64.
"mips"
يحدد هذا المقياس بنية المعالج على أنه mips.
"mips64"
يحدد هذا الإعداد بنية المعالج على أنه mips64.
PlatformInfo
كائن يحتوي على معلومات حول النظام الأساسي الحالي.
أماكن إقامة
-
قوس
بنية معالج الجهاز.
-
nacl_arch
بنية العميل الأصلي. قد يكون هذا القوس مختلفًا عن القوس على بعض المنصات.
-
os
نظام التشغيل الذي يعمل عليه Chrome.
PlatformNaclArch
بنية العميل الأصلي. قد يكون هذا القوس مختلفًا عن القوس على بعض المنصات.
التعداد
"arm"
يحدد هذا الإعداد بنية العميل الأصلي كمجموعة تجربة.
"x86-32"
يحدد هذا الإعداد بنية العميل الأصلي على أنّه x86-32.
"x86-64"
يحدد هذا الإعداد بنية العميل الأصلي على أنّه x86-64.
"mips"
يحدد هذا الإعداد بنية العميل الأصلي على أنه mips.
"mips64"
يحدد هذا الإعداد بنية العميل الأصلي على أنه mips64.
PlatformOs
نظام التشغيل الذي يعمل عليه Chrome.
التعداد
"mac"
يحدد نظام التشغيل MacOS.
"win"
يحدد هذا الإعداد نظام التشغيل Windows.
"android"
يحدد نظام التشغيل Android.
"cros"
يحدد نظام التشغيل Chrome.
"linux"
يحدد هذا الإعداد نظام تشغيل Linux.
"openbsd"
يحدد نظام التشغيل OpenBSD.
"fuchsia"
يحدد نظام التشغيل Fuchsia.
Port
يشير ذلك المصطلح إلى كائن يتيح التواصل المتبادل مع الصفحات الأخرى. راجع الاتصالات طويلة الأجل للحصول على مزيد من المعلومات.
أماكن إقامة
-
اسم
سلسلة
اسم المنفذ، كما هو محدّد في المكالمة المرسَلة إلى
runtime.connect
-
onDisconnect
الحدث<functionvitvit>
يتم تنشيطها عند فصل المنفذ عن الأطراف الأخرى. قد يتم ضبط
runtime.lastError
في حال انقطاع اتصال المنفذ بسبب خطأ. إذا كان المنفذ مغلقًا من خلال قطع الاتصال، يتم تنشيط هذا الحدث فقط من الطرف الآخر. يتم تنشيط هذا الحدث مرة واحدة على الأكثر (راجع أيضًا مدة المنفذ منذ الإنشاء).تبدو الدالة
onDisconnect.addListener
على النحو التالي:(callback: function) => {...}
-
onMessage
الحدث<functionvitvit>
يتم تنشيط هذا الحدث عند استدعاء postMessage من خلال الطرف الآخر للمنفذ.
تبدو الدالة
onMessage.addListener
على النحو التالي:(callback: function) => {...}
-
المُرسِل
MessageSender اختياري
لن تتوفّر هذه الخاصية إلا على المنافذ التي تم ضبطها على مستمعي onConnect / onConnectExternal / onConnectNative.
-
إلغاء الربط
void
افصل المنفذ على الفور. ما مِن تأثير لطلب الاتصال بالرقم
disconnect()
من خلال منفذ لم يتم ربطه من قبل. عند إلغاء ربط المنفذ، لن يتم إرسال أحداث جديدة إلى هذا المنفذ.تبدو الدالة
disconnect
على النحو التالي:() => {...}
-
postMessage
void
أرسِل رسالة إلى الطرف الآخر للمنفذ. إذا كان المنفذ غير متصل، سيحدث خطأ.
تبدو الدالة
postMessage
على النحو التالي:(message: any) => {...}
-
رسالة
أي فلتر
Chrome 52 والإصدارات الأحدثالرسالة المطلوب إرسالها. يجب أن يكون هذا الكائن قابلاً للاستجابة بتنسيق JSON.
-
RequestUpdateCheckStatus
نتيجة البحث عن التحديث
التعداد
"throttled"
يحدد أنه تم تقييد عملية التحقق من الحالة. يمكن أن يحدث ذلك بعد عمليات التحقّق المتكرّرة في غضون فترة زمنية قصيرة.
"no_update"
يتم تحديد أنّه لا تتوفّر أي تحديثات لتثبيتها.
"update_available"
تشير إلى توفُّر تحديث للتثبيت.
أماكن إقامة
id
رقم تعريف الإضافة/التطبيق.
النوع
سلسلة
lastError
تتم تعبئة هذا الحقل برسالة خطأ في حال تعذَّر استدعاء إحدى وظائف واجهة برمجة التطبيقات، وإلا فإنّه لم يتم تحديده. يتم تعريف ذلك فقط في نطاق معاودة الاتصال لهذه الدالة. إذا ظهر خطأ ولكن لم يتم الوصول إلى runtime.lastError
ضمن عملية معاودة الاتصال، يتم تسجيل رسالة في وحدة التحكّم تسرد دالة واجهة برمجة التطبيقات التي أدت إلى ظهور الخطأ. لا يتم ضبط هذه السمة من خلال دوال واجهة برمجة التطبيقات التي تعرض الوعود.
النوع
عنصر
أماكن إقامة
-
رسالة
سلسلة اختيارية
تفاصيل حول الخطأ الذي حدث.
الطُرق
connect()
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)
محاولات ربط المستمعين من خلال إضافة (مثل صفحة الخلفية) أو إضافات/تطبيقات أخرى وهذا مفيد للنصوص البرمجية للمحتوى التي تتصل بعمليات الإضافة، والتواصل بين التطبيقات/الإضافات، والمراسلة على الويب. ملاحظة: لا يرتبط هذا الخيار بأي مستمعين في نص برمجي للمحتوى. يمكن أن تتصل الإضافات بالنصوص البرمجية للمحتوى المضمّنة في علامات التبويب من خلال tabs.connect
.
المَعلمات
-
extensionId
سلسلة اختيارية
رقم تعريف الإضافة المطلوب الربط بها. في حال حذفها، ستتم محاولة الاتصال باستخدام إضافتك الخاصة. مطلوب في حال إرسال رسائل من صفحة ويب للمراسلة على الويب.
-
connectInfo
الكائن اختياري
-
includeTlsChannelId
منطقية اختيارية
ما إذا كان سيتم تمرير معرّف قناة بروتوكول أمان طبقة النقل (TLS) إلى onConnectExternal للعمليات التي ترصد حدث الربط.
-
اسم
سلسلة اختيارية
سيتم تمريرها إلى onConnect للعمليات التي تنتظر حدث الاتصال.
-
المرتجعات
-
المنفذ الذي يمكن إرسال الرسائل واستلامها من خلاله. يتم تنشيط حدث onDisconnect للمنفذ إذا لم تكن الإضافة متوفّرة.
connectNative()
chrome.runtime.connectNative(
application: string,
)
يتصل بتطبيق محلي في الجهاز المضيف. تتطلّب هذه الطريقة الحصول على إذن ""nativeMessaging"
". راجع المراسلة الأصلية لمزيد من المعلومات.
المَعلمات
-
التطبيق
سلسلة
اسم التطبيق المسجَّل المطلوب الربط به.
المرتجعات
-
المنفذ الذي يمكن من خلاله إرسال الرسائل واستلامها باستخدام التطبيق
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
لاسترداد كائن "window" لـ JavaScript لصفحة الخلفية التي تعمل داخل الإضافة/التطبيق الحالي. إذا كانت صفحة الخلفية هي صفحة حدث، سيتأكّد النظام من تحميلها قبل استدعاء طلب الاستدعاء. إذا لم تكن هناك صفحة خلفية، سيتم تعيين خطأ.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(backgroundPage?: Window) => void
-
backgroundPage
نافذة اختيارية
كائن "نافذة" في JavaScript لصفحة الخلفية.
-
المرتجعات
-
Promise<Window | undefined>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
لجلب معلومات عن السياقات النشطة المرتبطة بهذه الإضافة
المَعلمات
-
filter
فلتر للعثور على السياقات المطابقة يتطابق السياق في حال تطابُق مع جميع الحقول المحدّدة في الفلتر. ويتطابق أي حقل غير محدّد في الفلتر مع جميع السياقات.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(contexts: ExtensionContext[]) => void
-
السياقات
السياقات المطابِقة، إن توفّرت.
-
المرتجعات
-
Promise<ExtensionContext[]>
لا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getManifest()
chrome.runtime.getManifest()
عرض تفاصيل حول التطبيق أو الإضافة من البيان. الكائن الذي يتم عرضه هو تسلسل لملف البيان الكامل.
المرتجعات
-
عنصر
تفاصيل البيان
getPackageDirectoryEntry()
chrome.runtime.getPackageDirectoryEntry(
callback?: function,
)
تعرض DirectoryEntry (إدخال الدليل) لدليل الحزمة.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
المرتجعات
-
Promise<DirectoryEntry>
Chrome 122 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
عرض معلومات حول المنصة الحالية
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(platformInfo: PlatformInfo) => void
-
platformInfo
-
المرتجعات
-
Promise<PlatformInfo>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getURL()
chrome.runtime.getURL(
path: string,
)
تحوِّل هذه الدالة مسارًا نسبيًا ضمن دليل تثبيت تطبيق أو إضافة إلى عنوان URL مؤهَّل بالكامل.
المَعلمات
-
المسار
سلسلة
مسار إلى مورد داخل تطبيق أو إضافة يتم التعبير عنها بالنسبة إلى دليل التثبيت الخاص به.
المرتجعات
-
سلسلة
تمثّل هذه السمة عنوان URL المؤهّل بالكامل للمصدر.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
افتح صفحة خيارات الإضافة، إن أمكن.
وقد يعتمد السلوك الدقيق على مفتاح [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)
أو [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)
في البيان، أو على ما يتوافق مع متصفِّح Chrome في ذلك الوقت. على سبيل المثال، قد يتم فتح الصفحة في علامة تبويب جديدة، أو ضمن chrome://extensions، أو داخل أحد التطبيقات، أو قد يتم التركيز فقط على صفحة خيارات مفتوحة. ولن يتسبب ذلك مطلقًا في إعادة تحميل صفحة المتصل.
إذا لم تعلن الإضافة عن صفحة خيارات، أو تعذّر على Chrome إنشاء صفحة لسبب آخر، سيتم ضبط lastError
لمعاودة الاتصال.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
reload()
chrome.runtime.reload()
إعادة تحميل التطبيق أو الإضافة لا تتوفر هذه الطريقة في وضع Kiosk. في وضع Kiosk، استخدِم أسلوب chrome.runtime.restart() .
requestUpdateCheck()
chrome.runtime.requestUpdateCheck(
callback?: function,
)
تطلب إجراء فحص فوري للتحديث لهذا التطبيق/الإضافة.
ملاحظة مهمة: يجب ألا تستخدم معظم الإضافات/التطبيقات هذه الطريقة، لأنّ Chrome يُجري عمليات تحقّق تلقائية كل بضع ساعات، ويمكنك رصد حدث runtime.onUpdateAvailable
بدون الحاجة إلى طلب requestUpdateCheck.
هذه الطريقة مناسبة فقط لطلبها في حالات محدودة جدًا، مثلاً إذا كانت الإضافة تتواصل مع إحدى خدمات الخلفية، وتبيّن لخدمة الخلفية أن إصدار إضافة العميل قديم جدًا وتريد أن تطلب من المستخدم إجراء التحديث. معظم الاستخدامات الأخرى لـ requestUpdateCheck، مثل طلبه بدون شرط بناءً على موقّت متكرر، قد يؤدي على الأرجح إلى إهدار موارد العميل والشبكة والخادم.
ملاحظة: عند استدعاء هذه الدالة باستخدام معاودة الاتصال، بدلاً من عرض كائن، ستعرض هذه الدالة الخاصيتين كوسيطات منفصلة يتم تمريرها إلى رد الاتصال.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: object) => void
-
نتيجة
عنصر
Chrome 109 والإصدارات الأحدثعنصر RequestUpdateCheckResult الذي يحمل حالة البحث عن التحديثات وأي تفاصيل للنتيجة في حال توفر تحديث
-
status
نتيجة البحث عن التحديث
-
إصدار
سلسلة اختيارية
في حال توفُّر تحديث، سيتضمّن هذا الرقم إصدار التحديث المتاح.
-
-
المرتجعات
-
Promise<object>
Chrome 109 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
restart()
chrome.runtime.restart()
أعِد تشغيل جهاز ChromeOS عند تشغيل التطبيق في وضع Kiosk. خلاف ذلك، الأمر لا بيئة.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
عليك إعادة تشغيل جهاز ChromeOS عندما يتم تشغيل التطبيق في وضع Kiosk بعد مرور الثواني المحدّدة. وإذا تم الاتصال مرة أخرى قبل انتهاء الوقت، سيتم تأجيل إعادة التشغيل. إذا تم طلب البيانات بقيمة -1، سيتم إلغاء إعادة التشغيل. إنها ميزة بيئة مستقلة بدون استخدام Kiosk. ولا يُسمح إلا بطلب البيانات هذا بشكل متكرّر من الإضافة الأولى لاستدعاء واجهة برمجة التطبيقات هذه.
المَعلمات
-
ثانية
الرقم
حان وقت الانتظار بالثواني قبل إعادة تشغيل الجهاز، أو -1 لإلغاء عملية إعادة تشغيل مجدوَلة.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
لإرسال رسالة واحدة إلى أدوات معالجة الأحداث داخل إضافتك أو إضافة/تطبيق مختلفَين. يشبه runtime.connect
، ولكنه يرسل رسالة واحدة فقط مع ردّ اختياري. في حال الإرسال إلى الإضافة، سيتم تنشيط الحدث runtime.onMessage
في كل إطار في الإضافة (باستثناء إطار المُرسِل) أو runtime.onMessageExternal
في حال إضافة إضافة مختلفة. تجدر الإشارة إلى أنّ الإضافات لا يمكنها إرسال رسائل إلى النصوص البرمجية للمحتوى باستخدام هذه الطريقة. لإرسال رسائل إلى النصوص البرمجية للمحتوى، استخدِم tabs.sendMessage
.
المَعلمات
-
extensionId
سلسلة اختيارية
رقم تعريف الإضافة المطلوب إرسال الرسالة إليها. في حال حذفها، سيتم إرسال الرسالة إلى الإضافة أو التطبيق الخاص بك. تكون هذه الرسالة مطلوبة عند إرسال رسائل من صفحة ويب للمراسلة على الويب.
-
رسالة
أي فلتر
الرسالة المطلوب إرسالها. ويجب أن تكون هذه الرسالة كائن JSON قابلاً للقياس.
-
الخيارات
الكائن اختياري
-
includeTlsChannelId
منطقية اختيارية
ما إذا كان سيتم تمرير معرّف قناة بروتوكول أمان طبقة النقل (TLS) إلى onMessageExternal للعمليات التي تستمع إلى حدث الربط.
-
-
معاودة الاتصال
الدالة اختيارية
Chrome 99 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:(response: any) => void
-
رد
أي فلتر
تمثّل هذه السمة كائن استجابة JSON الذي يرسله معالج الرسالة. وإذا حدث خطأ أثناء الاتصال بالإضافة، سيتم استدعاء الإجراء بدون وسيطات، وسيتم ضبط
runtime.lastError
على رسالة الخطأ.
-
المرتجعات
-
وعد<any>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
يمكنك إرسال رسالة واحدة إلى تطبيق أصلي. تتطلّب هذه الطريقة الحصول على إذن ""nativeMessaging"
".
المَعلمات
-
التطبيق
سلسلة
اسم مضيف المراسلة مع التطبيقات الأصلية
-
رسالة
عنصر
الرسالة التي سيتم تمريرها إلى مضيف المراسلة مع التطبيقات الأصلية
-
معاودة الاتصال
الدالة اختيارية
Chrome 99 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:(response: any) => void
-
رد
أي فلتر
رسالة الرد التي أرسلها مضيف المراسلة مع التطبيقات الأصلية وإذا حدث خطأ أثناء الاتصال بمضيف المراسلة مع التطبيقات الأصلية، سيتم طلب معاودة الاتصال بدون وسيطات وسيتم ضبط
runtime.lastError
على رسالة الخطأ.
-
المرتجعات
-
وعد<any>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setUninstallURL()
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)
تحدِّد هذه السياسة عنوان URL الذي سيتم الانتقال إليه عند إلغاء التثبيت. يمكن استخدام هذه البيانات لتنظيف البيانات من جهة الخادم وإجراء الإحصاءات وتنفيذ الاستطلاعات. الحد الأقصى لعدد الأحرف هو 1023 حرفًا.
المَعلمات
-
url
سلسلة
عنوان URL الذي سيتم فتحه بعد إلغاء تثبيت الإضافة. يجب أن يحتوي عنوان URL هذا على مخطط http: أو https:. اضبط سلسلة فارغة على عدم فتح علامة تبويب جديدة بعد إلغاء التثبيت.
-
معاودة الاتصال
الدالة اختيارية
Chrome 45 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 99 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
فعاليات
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
يُرجى استخدام runtime.onRestartRequired
.
يتم تنشيطها عند توفّر تحديث لمتصفِّح Chrome، ولكن لا يتم تثبيتها على الفور لأن إعادة تشغيل المتصفِّح مطلوبة.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
يتم تنشيطها عند إجراء اتصال من عملية إضافة أو نص برمجي للمحتوى (من خلال runtime.connect
).
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(port: Port) => void
-
المنفذ
-
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
يتم تنشيطها عند إجراء اتصال من إضافة أخرى (من خلال runtime.connect
) أو من موقع إلكتروني يمكن ربطه خارجيًا.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(port: Port) => void
-
المنفذ
-
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
يتم تنشيطها عند إجراء اتصال من تطبيق أصلي. يتطلّب هذا الحدث إذن ""nativeMessaging"
". ولا تتوفّر هذه الميزة إلا على نظام التشغيل Chrome.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(port: Port) => void
-
المنفذ
-
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
يتم تنشيطها عند تثبيت الإضافة لأول مرة، وعند تحديثها إلى إصدار جديد، وعند تحديث Chrome إلى إصدار جديد.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(details: object) => void
-
التفاصيل
عنصر
-
id
سلسلة اختيارية
يشير إلى رقم تعريف إضافة الوحدة المشتركة المستورَدة التي تم تعديلها. ولا ينطبق ذلك إلا إذا كان "reason" هو "shared_ أمّا_update".
-
previousVersion
سلسلة اختيارية
يشير إلى الإصدار السابق من الإضافة، والذي تم تحديثه للتو. ولا ينطبق ذلك إلا إذا كانت قيمة "السبب" هي "تعديل".
-
السبب
سبب إرسال هذا الحدث
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
يتم تنشيطها عند إرسال رسالة من عملية إضافة (من خلال runtime.sendMessage
) أو نص برمجي للمحتوى (عن طريق tabs.sendMessage
).
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
رسالة
أي فلتر
-
المُرسِل
-
sendResponse
الوظيفة
تبدو معلَمة
sendResponse
على النحو التالي:() => void
-
returns
منطقية | غير محدّدة
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
يتم تنشيطها عند إرسال رسالة من إضافة أخرى (من قِبل runtime.sendMessage
)، ولا يمكن استخدامها في نص برمجي للمحتوى.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
رسالة
أي فلتر
-
المُرسِل
-
sendResponse
الوظيفة
تبدو معلَمة
sendResponse
على النحو التالي:() => void
-
returns
منطقية | غير محدّدة
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
يتم تنشيطها عندما تكون هناك حاجة إلى إعادة تشغيل التطبيق أو الجهاز الذي يتم تشغيله. من المفترض أن يغلق التطبيق جميع نوافذه في أقرب وقت مناسب للسماح بإعادة التشغيل. في حال عدم اتخاذ أي إجراء، سيتم فرض إعادة تشغيل التطبيق بعد مرور فترة سماح مدتها 24 ساعة. لا يتم تنشيط هذا الحدث حاليًا إلا لتطبيقات Kiosk لنظام التشغيل Chrome.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(reason: OnRestartRequiredReason) => void
-
السبب
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
يتم تنشيطها عند بدء تشغيل ملف شخصي تم تثبيت هذه الإضافة عليه. لا يتم تنشيط هذا الحدث عند بدء ملف شخصي في وضع التصفح المتخفي، حتى إذا كانت هذه الإضافة تعمل في وضع التصفح المتخفي "التقسيم".
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
يتم إرساله إلى صفحة الحدث قبل إلغاء تحميله مباشرةً. يمنح ذلك الإضافة فرصة لإجراء بعض التعديلات. يُرجى العلم أنّه بما أنّه يتم إلغاء تحميل الصفحة، لا يمكن ضمان اكتمال أي عمليات غير متزامنة بدأت أثناء معالجة هذا الحدث. وفي حال حدوث المزيد من الأنشطة على صفحة الحدث قبل إلغاء تحميلها، سيتم إرسال الحدث onPauseCanceled ولن يتم إلغاء تحميل الصفحة.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
يتم إرساله بعد onPending للإشارة إلى أنّه لن يتم إلغاء تحميل التطبيق في نهاية الأمر.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
يتم إطلاقه عند توفُّر تحديث، ولكن لا يتم تثبيته على الفور لأن التطبيق قيد التشغيل حاليًا. في حال عدم اتخاذ أي إجراء، سيتم تثبيت التحديث في المرة التالية التي يتم فيها إلغاء تحميل صفحة الخلفية، وإذا كنت تريد تثبيتها في وقت أقرب، يمكنك الاتصال بشكل صريح بـ chrome.runtime.reload(). إذا كانت الإضافة تستخدم صفحة خلفية دائمة، فلن يتم إلغاء تحميل صفحة الخلفية مطلقًا، لذا ما لم يتم استدعاء chrome.runtime.reload() يدويًا استجابةً لهذا الحدث، لن يتم تثبيت التحديث حتى المرة التالية التي تتم فيها إعادة تشغيل Chrome نفسه. إذا لم يتم رصد أي معالِجات لهذا الحدث، وكانت الإضافة تتضمّن صفحة خلفية ثابتة، سيكون سلوكها كما لو تم استدعاء chrome.runtime.reload() كاستجابة لهذا الحدث.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(details: object) => void
-
التفاصيل
عنصر
-
إصدار
سلسلة
رقم إصدار التحديث المتاح.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
يتم تنشيطها عند إجراء اتصال من نص برمجي للمستخدم من هذه الإضافة.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(port: Port) => void
-
المنفذ
-
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
يتم تنشيطها عند إرسال رسالة من نص برمجي للمستخدم مرتبط بالإضافة نفسها.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
رسالة
أي فلتر
-
المُرسِل
-
sendResponse
الوظيفة
تبدو معلَمة
sendResponse
على النحو التالي:() => void
-
returns
منطقية | غير محدّدة
-