تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

chrome.runtime

الوصف

استخدِم واجهة برمجة التطبيقات chrome.runtime لاسترداد عامل الخدمة وعرض تفاصيل عن البيان والاستماع إلى الأحداث في دورة حياة الإضافة والاستجابة لها. يمكنك أيضًا استخدام واجهة برمجة التطبيقات هذه لتحويل المسار النسبي لعناوين URL إلى عناوين URL مؤهَّلة بالكامل.

نظرة عامة

توفّر Runtime API طرقًا لتلبية عدد من مجالات الوظائف التي يمكن لإضافة استخدامها:

تمرير الرسائل: يمكن لإضافتك التواصل مع سياقات مختلفة داخل إضافتك ومع إضافات أخرى باستخدام هذه الطرق والأحداث: connect()‎ و onConnect و onConnectExternal و sendMessage() و onMessage و onMessageExternal. بالإضافة إلى ذلك، يمكن لإضافة Chrome تمرير الرسائل إلى التطبيقات الأصلية على جهاز المستخدم باستخدام علامتَي الترميز connectNative() و sendNativeMessage().

الوصول إلى البيانات الوصفية للإضافات والمنصات: تتيح لك هذه الطرق استرداد عدة أجزاء محدّدة من البيانات الوصفية عن الإضافة والمنصة. تشمل الطرق في هذه الفئة methods getManifest() و getPlatformInfo().
إدارة دورة حياة الإضافة وخياراتها: تسمح لك هذه السمات بتنفيذ بعض العمليات الوصفية على الإضافة وعرض صفحة الخيارات. تشمل الطرق والأحداث في هذه الفئة methods and events in this category onInstalled، onStartup، openOptionsPage()، reload()‎، requestUpdateCheck()، و setUninstallURL()‎.
أدوات مساعدة: توفّر هذه الطرق أدوات مفيدة، مثل تحويل تمثيلات الموارد الداخلية إلى تنسيقات خارجية. تشمل الطرق في هذه الفئة getURL()‎.
أدوات وضع Kiosk: لا تتوفّر هذه الطرق إلا على نظام التشغيل ChromeOS، وهي مخصّصة بشكل أساسي لدعم عمليات تنفيذ تطبيقات نقاط البيع. تشمل الطرق في هذه الفئة restart و restartAfterDelay.

الأذونات

لا تتطلّب معظم الطرق في Runtime API أي إذن، باستثناء 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);
}

إرسال البيانات من الخدمة العاملة إلى نص محتوى

من الشائع أن تحتاج نصوص برمجية المحتوى في إحدى الإضافات إلى بيانات تديرها جزء آخر من الإضافة، مثل الخدمة العاملة. تمامًا مثل نافذتَي متصفّح تم فتحهما لعرض صفحة الويب نفسها، لا يمكن لهما الوصول مباشرةً إلى قيم بعضهما البعض. بدلاً من ذلك، يمكن للإضافة استخدام message passing للتنسيق على مستوى هذه السياقات المختلفة.

في هذا المثال، يحتاج نص المحتوى البرمجي إلى بعض البيانات من الخدمة العاملة للإضافات لبدء واجهة المستخدم. للحصول على هذه البيانات، يُرسِل الرمز البرمجي رسالة 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 - عرض توضيحي للموارد القابلة للوصول إليها من الويب للاطّلاع على المزيد من أمثلة Runtime API.

الأنواع

ContextFilter

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

فلتر لمطابقة سياقات إضافية معيّنة يجب أن تتطابق السياقات المطابقة مع جميع الفلاتر المحدّدة، ويتوافق أي فلتر غير محدّد مع جميع السياقات المتاحة. وبالتالي، سيتطابق فلتر "{}" مع جميع السياقات المتاحة.

أماكن إقامة

contextIds

سلسلة اختيارية
contextTypes

ContextType[] اختياري
documentIds

سلسلة اختيارية
documentOrigins

سلسلة اختيارية
documentUrls

سلسلة اختيارية
frameIds

عدد اختياري
وضع التصفّح المتخفي

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

عدد اختياري
windowIds

عدد اختياري

ContextType

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

التعداد

"TAB"
تُحدِّد نوع السياق كعلامة تبويب

‫"POPUP"
تُحدِّد نوع السياق كنافذة منبثقة لمعلومات إضافية

‫"BACKGROUND"
يحدد نوع السياق كعامل خدمة.

‫"OFFSCREEN_DOCUMENT"
تُحدِّد نوع السياق كمستند خارج الشاشة.

‫"SIDE_PANEL"
تُحدِّد نوع السياق على أنّه لوحة جانبية.

‫"DEVELOPER_TOOLS"
يحدد نوع السياق على أنّه أدوات المطوّرين.

ExtensionContext

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

سياق يستضيف محتوى إضافة

أماكن إقامة

contextId

سلسلة

معرّف فريد لهذا السياق
contextType

ContextType

نوع السياق الذي يتوافق معه هذا العنصر
documentId

سلسلة اختيارية

معرّف UUID للمستند المرتبط بهذا السياق، أو غير محدّد إذا لم يكن هذا السياق مستضافًا في مستند
documentOrigin

سلسلة اختيارية

مصدر المستند المرتبط بهذا السياق، أو غير محدّد إذا لم يكن السياق مستضافًا في مستند
documentUrl

سلسلة اختيارية

عنوان URL للمستند المرتبط بهذا السياق، أو غير محدّد إذا لم يكن السياق مستضافًا في مستند
frameId

الرقم

رقم تعريف الإطار لهذا السياق، أو -1 إذا لم يكن هذا السياق مستضافًا في إطار.
وضع التصفّح المتخفي

قيمة منطقية

ما إذا كان السياق مرتبطًا بملف شخصي في وضع التصفّح المتخفي
tabId

الرقم

رقم تعريف علامة التبويب لهذا السياق، أو -1 إذا لم يكن هذا السياق مستضافًا في علامة تبويب.
windowId

الرقم

رقم تعريف النافذة لهذا السياق، أو -1 إذا لم يكن هذا السياق مستضافًا في نافذة

MessageSender

عنصر يحتوي على معلومات عن سياق النص البرمجي الذي أرسل رسالة أو طلبًا.

أماكن إقامة

documentId

سلسلة اختيارية

Chrome 106 والإصدارات الأحدث

معرّف UUID للمستند الذي فتح الاتصال
documentLifecycle

سلسلة اختيارية

Chrome 106 والإصدارات الأحدث

دورة الحياة التي كان عليها المستند الذي فتح الاتصال في وقت إنشاء المنفذ يُرجى العِلم أنّه قد تغيّرت حالة دورة حياة المستند منذ إنشاء المنفذ.
frameId

رقم اختياري

الإطار الذي فتح الاتصال 0 للإطارات من المستوى الأعلى، وقيمة موجبة للإطارات الفرعية. لن يتم ضبط هذا الإعداد إلا عند ضبط tab.
id

سلسلة اختيارية

رقم تعريف الإضافة التي فتحت الاتصال، إن توفّرت.
nativeApplication

سلسلة اختيارية

Chrome 74 والإصدارات الأحدث

اسم التطبيق الأصلي الذي فتح الاتصال، إن توفّر
الأصل

سلسلة اختيارية

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

مصدر الصفحة أو الإطار الذي فتح الاتصال. ويمكن أن يختلف عن سمة عنوان URL (مثل about:blank) أو أن يكون غير شفاف (مثل إطارات iframe في وضع الحماية). ويُعدّ ذلك مفيدًا لتحديد ما إذا كان المصدر موثوقًا به أم لا إذا لم نتمكّن من معرفة ذلك على الفور من عنوان URL.
tab

علامة تبويب اختيارية

tabs.Tab الذي فتح الاتصال، إن توفّر لن يظهر هذا السمة إلا عند فتح الاتصال من علامة تبويب (بما في ذلك نصوص برمجة المحتوى)، وفقط إذا كان المستلِم إضافة وليس تطبيقًا.
tlsChannelId

سلسلة اختيارية

معرّف قناة بروتوكول أمان طبقة النقل (TLS) للصفحة أو الإطار الذي فتح الاتصال، إذا طلبت الإضافة ذلك، وإذا كان متاحًا.
url

سلسلة اختيارية

عنوان URL للصفحة أو الإطار الذي فتح الاتصال. إذا كان المُرسِل في إطار iframe، سيكون عنوان URL الخاص بإطار iframe وليس عنوان URL للصفحة التي تستضيفه.

OnInstalledReason

Chrome 44 والإصدارات الأحدث

سبب إرسال هذا الحدث.

التعداد

‫"install"
تُحدِّد سبب الحدث على أنّه عملية تثبيت.

‫"update"
تُحدِّد سبب الحدث على أنّه تحديث إضافة.

‫"chrome_update"
تُحدِّد سبب الحدث على أنّه تحديث Chrome.

‫"shared_module_update"
تُحدِّد سبب الحدث على أنّه تعديل على وحدة مشترَكة.

OnRestartRequiredReason

Chrome 44 والإصدارات الأحدث

سبب إرسال الحدث يتم استخدام "app_update" عند الحاجة إلى إعادة التشغيل بسبب تحديث التطبيق إلى إصدار أحدث. يتم استخدام os_update عند الحاجة إلى إعادة التشغيل بسبب تحديث المتصفّح أو نظام التشغيل إلى إصدار أحدث. يتم استخدام "مُنتظم" عندما يعمل النظام لفترة أطول من وقت التشغيل المسموح به المحدَّد في سياسة المؤسسة.

التعداد

‫"app_update"
يحدد سبب الحدث على أنّه تحديث للتطبيق.

‫"os_update"
تُحدِّد سبب الحدث على أنّه تحديث لنظام التشغيل.

‫"periodic"
يُحدِّد سبب الحدث على أنّه إعادة تشغيل التطبيق بشكل دوري.

PlatformArch

Chrome 44 والإصدارات الأحدث

بنية المعالج في الجهاز

التعداد

‫"arm"
تُحدِّد بنية المعالج على أنّها arm.

‫"arm64"
تُحدِّد بنية المعالج على أنّها arm64.

‫"x86-32"
تُحدِّد بنية المعالج على أنّها x86-32.

‫"x86-64"
تُحدِّد بنية المعالج على أنّها x86-64.

‫"mips"
تُحدِّد بنية المعالج على أنّها mips.

"mips64"
تُحدِّد بنية المعالج على أنّها mips64.

PlatformInfo

عنصر يحتوي على معلومات عن النظام الأساسي الحالي

أماكن إقامة

قوس

PlatformArch

بنية المعالج في الجهاز
nacl_arch

PlatformNaclArch

بنية البرنامج المتوافق مع الأجهزة قد يختلف هذا عن arch في بعض المنصات.
os

PlatformOs

نظام التشغيل الذي يعمل عليه Chrome

PlatformNaclArch

Chrome 44 والإصدارات الأحدث

بنية البرنامج المتوافق مع الأجهزة قد يختلف هذا عن arch في بعض المنصات.

التعداد

‫"arm"
تُحدِّد بنية العميل الأصلية على أنّها arm.

‫"x86-32"
تُحدِّد بنية العميل الأصلية على أنّها x86-32.

‫"x86-64"
تُحدِّد بنية العميل الأصلية على أنّها x86-64.

‫"mips"
تُحدِّد بنية العميل الأصلية على أنّها mips.

‫"mips64"
تُحدِّد بنية العميل الأصلية على أنّها mips64.

PlatformOs

Chrome 44 والإصدارات الأحدث

نظام التشغيل الذي يعمل عليه Chrome

التعداد

‫"mac"
تُحدِّد نظام التشغيل MacOS.

‫"win"
تُستخدَم لتحديد نظام التشغيل Windows.

‫"android"
تُحدِّد نظام التشغيل Android.

‫"cros"
تُحدِّد نظام التشغيل Chrome.

‫"linux"
تُحدِّد نظام التشغيل Linux.

‫"openbsd"
تُحدِّد نظام التشغيل OpenBSD.

‫"fuchsia"
تُحدِّد نظام التشغيل Fuchsia.

Port

عنصر يسمح بالتواصل في الاتجاهين مع الصفحات الأخرى اطّلِع على عمليات الربط التي تستمر لفترة طويلة للحصول على مزيد من المعلومات.

أماكن إقامة

الاسم

سلسلة

اسم المنفذ، كما هو محدّد في طلب runtime.connect.
onDisconnect

الحدث<functionvoidvoid>

يتم تشغيله عند انقطاع اتصال المنفذ بالطرف الآخر. قد يتم ضبط runtime.lastError إذا انقطع الاتصال بالمنفذ بسبب خطأ. إذا تم إغلاق المنفذ من خلال قطع الاتصال، يتم تشغيل هذا الحدث فقط على الطرف الآخر. يتم تشغيل هذا الحدث مرة واحدة بحد أقصى (راجِع أيضًا مدة صلاحية المنفذ).

تبدو الدالة onDisconnect.addListener على النحو التالي:
```
(callback: function) => {...}
```
- ردّ الاتصال
  
  دالة
  
  تظهر المَعلمة callback على النحو التالي:
```
(port: Port) => void
```
  - المنفذ
    
    المنفذ
onMessage

الحدث<functionvoidvoid>

يتم تنشيط هذا الحدث عند استدعاء postMessage من الطرف الآخر من المنفذ.

تبدو الدالة onMessage.addListener على النحو التالي:
```
(callback: function) => {...}
```
- ردّ الاتصال
  
  دالة
  
  تظهر المَعلمة callback على النحو التالي:
```
(message: any, port: Port) => void
```
  - رسالة
    
    أي واحد
  - المنفذ
    
    المنفذ
المُرسِل

MessageSender اختياري

لن يكون هذا السمة متوفّرًا إلّا في المنافذ التي يتم تمريرها إلى مستمعي onConnect / onConnectExternal / onConnectNative.
إلغاء الربط

غير صالح

عليك فصل المنفذ على الفور. لن يكون للاتصال بـ disconnect() على منفذ سبق أن تم فصله أي تأثير. عند إلغاء ربط منفذ، لن يتم إرسال أي أحداث جديدة إليه.

تبدو الدالة disconnect على النحو التالي:
```
() => {...}
```
postMessage

غير صالح

أرسِل رسالة إلى الطرف الآخر من المنفذ. إذا انقطع الاتصال بالمنفذ، يتم طرح خطأ.

تبدو الدالة postMessage على النحو التالي:
```
(message: any) => {...}
```
- رسالة
  
  أي واحد
  
  Chrome 52 والإصدارات الأحدث
  
  الرسالة المطلوب إرسالها يجب أن يكون هذا العنصر قابلاً للتحويل إلى ملف JSON.

RequestUpdateCheckStatus

Chrome 44 والإصدارات الأحدث

نتيجة التحقّق من التحديث

التعداد

"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
  
  نافذة اختيارية
  
  كائن "window" في JavaScript للصفحة التي تعمل في الخلفية

المرتجعات

Promise<Window | undefined>

Chrome 99 والإصدارات الأحدث

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

getContexts()

Promise Chrome 116 والإصدارات الأحدث MV3 والإصدارات الأحدث

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

يسترجع معلومات عن السياقات النشطة المرتبطة بهذه الإضافة.

المعلمات

تصفية

ContextFilter

فلتر للعثور على السياقات المطابِقة يتطابق السياق إذا كان يتطابق مع جميع الحقول المحدّدة في الفلتر. يتطابق أيّ حقل غير محدّد في الفلتر مع جميع السياقات.
ردّ الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
(contexts: ExtensionContext[]) => void
```
- السياقات
  
  ExtensionContext[]
  
  السياقات المطابِقة، إن وجدت

المرتجعات

Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

عرض تفاصيل عن التطبيق أو الإضافة من البيان الكائن الذي يتم إرجاعه هو تسلسل ملف البيان الكامل.

المرتجعات

عنصر

تفاصيل البيان

getPackageDirectoryEntry()

الوعد المقدّمة فقط

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

عرض عنصر DirectoryEntry لدليل الحزمة

المعلمات

ردّ الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
(directoryEntry: DirectoryEntry) => void
```
- directoryEntry
  
  DirectoryEntry

المرتجعات

Promise<DirectoryEntry>

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

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

getPlatformInfo()

الوعد

chrome.runtime.getPlatformInfo(
  callback?: function,
)

لعرض معلومات عن المنصة الحالية.

المعلمات

ردّ الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
(platformInfo: PlatformInfo) => void
```
- platformInfo
  
  PlatformInfo

المرتجعات

Promise<PlatformInfo>

Chrome 99 والإصدارات الأحدث

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

getURL()

chrome.runtime.getURL(
  path: string,
)

تحوِّل هذه الدالة مسارًا نسبيًا ضمن دليل تثبيت التطبيق أو الإضافة إلى عنوان URL مؤهَّل بالكامل.

المعلمات

المسار

سلسلة

مسار إلى مورد داخل تطبيق أو إضافة يتم التعبير عنه نسبةً إلى دليل التثبيت

المرتجعات

سلسلة

عنوان URL المؤهّل بالكامل للمورد

openOptionsPage()

الوعد

chrome.runtime.openOptionsPage(
  callback?: function,
)

افتح صفحة خيارات الإضافة، إن أمكن.

قد يعتمد السلوك الدقيق على مفتاح options_ui أو options_page في البيان، أو على الميزات التي يتيحها Chrome في الوقت الحالي. على سبيل المثال، قد يتم فتح الصفحة في علامة تبويب جديدة أو ضمن chrome://extensions أو داخل تطبيق، أو قد يتم التركيز فقط على صفحة خيارات مفتوحة. ولن يؤدي ذلك أبدًا إلى إعادة تحميل صفحة المتصل.

إذا لم تُعلِن إضافتك عن صفحة خيارات، أو تعذّر على Chrome إنشاء صفحة لسبب آخر، سيضبط المرجع المرجعي القيمة lastError.

المعلمات

ردّ الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

المرتجعات

Promise<void>

Chrome 99 والإصدارات الأحدث

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

reload()

chrome.runtime.reload()

تؤدي هذه العملية إلى إعادة تحميل التطبيق أو الإضافة. لا تتوفّر هذه الطريقة في وضع "الكشك". بالنسبة إلى وضع "الكشك"، استخدِم الطريقة chrome.runtime.restart()‎.

requestUpdateCheck()

الوعد

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

يطلب إجراء عملية تحقّق فورية من توفّر تحديث لهذا التطبيق/هذه الإضافة.

ملاحظة مهمة: يجب عدم استخدام معظم الإضافات أو التطبيقات لهذه الطريقة، لأنّ Chrome يُجري عمليات تحقّق تلقائية كل بضع ساعات، ويمكنك الاستماع إلى الحدث runtime.onUpdateAvailable بدون الحاجة إلى طلب requestUpdateCheck.

لا تكون هذه الطريقة مناسبة إلا للاتصال في حالات محدودة جدًا، مثل إذا كانت الإضافة تتواصل مع خدمة خلفية، وتبيّن لخدمة الخلفية أنّ إصدار إضافة العميل قديم جدًا وأنّك تريد مطالبة المستخدم بالتحديث. إنّ معظم الاستخدامات الأخرى لدالة requestUpdateCheck، مثل استدعاؤها بدون قيد أو شرط استنادًا إلى موقّت متكرّر، قد تؤدي على الأرجح إلى إهدار موارد العميل والشبكة والخادم فقط.

ملاحظة: عند استدعاء هذه الدالة مع دالة ردّ اتصال، بدلاً من عرض عنصر، ستعرض الدالة السمتَين كوسيطات منفصلة يتم تمريرها إلى دالة ردّ الاتصال.

المعلمات

ردّ الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
(result: object) => void
```
- نتيجة
  
  عنصر
  
  Chrome 109 والإصدارات الأحدث
  
  عنصر RequestUpdateCheckResult الذي يحتوي على حالة التحقّق من التحديث وأي تفاصيل عن النتيجة في حال توفّر تحديث
  - status
    
    RequestUpdateCheckStatus
    
    نتيجة التحقّق من التحديث
  - إصدار
    
    سلسلة اختيارية
    
    إذا كان هناك تحديث متوفّر، سيتضمّن هذا الحقل رقم إصدار التحديث.

المرتجعات

Promise<object>

Chrome 109 والإصدارات الأحدث

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

restart()

chrome.runtime.restart()

أعِد تشغيل جهاز ChromeOS عندما يعمل التطبيق في وضع Kiosk. بخلاف ذلك، لن يتم تنفيذ أي إجراء.

restartAfterDelay()

الوعد Chrome 53 والإصدارات الأحدث

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

أعِد تشغيل جهاز ChromeOS عندما يعمل التطبيق في وضع Kiosk بعد مرور الثواني المحدّدة. في حال تمّت الدعوة مرة أخرى قبل انتهاء الوقت، سيتم تأخير إعادة التشغيل. في حال استدعاء هذه الوظيفة باستخدام القيمة -1، سيتم إلغاء عملية إعادة التشغيل. لا يمكن تنفيذ هذا الإجراء في وضع غير وضع الكشك. ولا يُسمح إلا للإضافة الأولى باستدعاء هذه الواجهة بشكل متكرّر.

المعلمات

ثانية

الرقم

الوقت الذي يجب الانتظار خلاله بالثواني قبل إعادة تشغيل الجهاز، أو -1 لإلغاء عملية إعادة تشغيل مجدوَلة.
ردّ الاتصال

الدالة اختيارية

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

المرتجعات

Promise<void>

Chrome 99 والإصدارات الأحدث

لا تتوفّر الوعود إلا في الإصدار 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 على رسالة الخطأ.

المرتجعات

Promise<any>

Chrome 99 والإصدارات الأحدث

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

sendNativeMessage()

الوعد

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

إرسال رسالة واحدة إلى تطبيق أصلي تتطلّب هذه الطريقة إذن "nativeMessaging".

المعلمات

التطبيق

سلسلة

اسم مضيف المراسلة مع التطبيقات الأصلية
رسالة

عنصر

الرسالة التي سيتم تمريرها إلى مضيف المراسلة الأصلي
ردّ الاتصال

الدالة اختيارية

Chrome 99 والإصدارات الأحدث

تظهر المَعلمة callback على النحو التالي:
```
(response: any) => void
```
- رد
  
  أي واحد
  
  رسالة الردّ التي أرسلها مضيف المراسلة مع التطبيقات الأصلية في حال حدوث خطأ أثناء الاتصال بمضيف المراسلة الأصلي، سيتمّ استدعاء دالة الاستدعاء بدون أيّ وسيطات، وسيتمّ ضبط runtime.lastError على رسالة الخطأ.

المرتجعات

Promise<any>

Chrome 99 والإصدارات الأحدث

لا تتوفّر الوعود إلا في الإصدار 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 والإصدارات الأحدث

لا تتوفّر الوعود إلا في الإصدار 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 76 والإصدارات الأحدث

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

يتم تشغيله عند إجراء عملية ربط من تطبيق أصلي. يتطلب هذا الحدث الحصول على إذن "nativeMessaging". لا تتوفّر هذه الميزة إلا على نظام التشغيل ChromeOS.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(port: Port) => void
```
- المنفذ
  
  المنفذ

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

يتم تشغيله عند تثبيت الإضافة لأول مرة، وعند تحديث الإضافة إلى إصدار جديد، وعند تحديث Chrome إلى إصدار جديد.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  عنصر
  - id
    
    سلسلة اختيارية
    
    يشير إلى رقم تعريف إضافة الوحدة المشترَكة التي تمّ تعديلها. لا يظهر هذا الحقل إلا إذا كان "سبب" هو "shared_module_update".
  - previousVersion
    
    سلسلة اختيارية
    
    يشير إلى الإصدار السابق من الإضافة الذي تم تعديله للتو. لا يظهر هذا الحقل إلّا إذا كان "سبب" هو "تعديل".
  - السبب
    
    OnInstalledReason
    
    سبب إرسال هذا الحدث.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

يتم تشغيله عند إرسال رسالة من عملية إضافة (من خلال runtime.sendMessage) أو نص برمجي للمحتوى (من خلال tabs.sendMessage).

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- رسالة
  
  أي واحد
- المُرسِل
  
  MessageSender
- sendResponse
  
  دالة
  
  تظهر المَعلمة sendResponse على النحو التالي:
```
() => void
```
- returns
  boolean | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

يتم تشغيله عند إرسال رسالة من إضافة أخرى (باستخدام runtime.sendMessage). لا يمكن استخدامه في نص برمجي للمحتوى.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- رسالة
  
  أي واحد
- المُرسِل
  
  MessageSender
- sendResponse
  
  دالة
  
  تظهر المَعلمة sendResponse على النحو التالي:
```
() => void
```
- returns
  boolean | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

يتم تشغيله عندما يكون من الضروري إعادة تشغيل تطبيق أو الجهاز الذي يعمل عليه. من المفترض أن يغلق التطبيق جميع نوافذه في أقرب وقت ممكن للسماح بإعادة التشغيل. إذا لم يفعل التطبيق أي شيء، سيتم فرض إعادة تشغيله بعد مرور فترة سماح مدتها 24 ساعة. لا يتم حاليًا تشغيل هذا الحدث إلا لتطبيقات kiosk على نظام التشغيل ChromeOS.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(reason: OnRestartRequiredReason) => void
```
- السبب
  
  OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

يتم تشغيله عند بدء تشغيل ملف شخصي تم تثبيت هذه الإضافة عليه لأول مرة. لا يتم تشغيل هذا الحدث عند بدء ملف شخصي في وضع التصفّح المتخفي، حتى إذا كانت هذه الإضافة تعمل في وضع التصفّح المتخفي "المقسّم".

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

يتم إرسالها إلى صفحة الحدث قبل إلغاء تحميلها مباشرةً. يمنح هذا الإجراء الإضافة فرصة لإجراء بعض عمليات التنظيف. يُرجى العِلم أنّه بما أنّ الصفحة يتم إلغاء تحميلها، لا يمكن ضمان اكتمال أي عمليات غير متزامنة بدأت أثناء معالجة هذا الحدث. إذا حدث المزيد من الأنشطة لصفحة الحدث قبل إلغاء تحميلها، سيتم إرسال الحدث onSuspendCanceled ولن يتم إلغاء تحميل الصفحة.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

يتم إرسالها بعد onSuspend للإشارة إلى أنّه لن يتم تفريغ التطبيق بعد كل شيء.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

يتم تشغيله عندما يتوفّر تحديث، ولكن لا يتم تثبيته على الفور لأنّ التطبيق قيد التشغيل حاليًا. إذا لم تتّخذ أي إجراء، سيتم تثبيت التحديث في المرة التالية التي يتم فيها تفريغ صفحة الخلفية. وإذا أردت تثبيته في وقت أقرب، يمكنك استدعاء chrome.runtime.reload() صراحةً استجابةً لهذا الحدث. إذا كانت الإضافة تستخدم صفحة خلفية دائمة، لن يتم تفريغ صفحة الخلفية أبدًا، لذا لن يتم تثبيت التحديث إلا في المرة التالية التي تتم فيها إعادة تشغيل Chrome نفسه، ما لم تستدعي chrome.runtime.reload() يدويًا استجابةً لهذا الحدث. إذا لم تكن هناك معالجات تستمع إلى هذا الحدث، وكانت إضافتك تحتوي على صفحة خلفية دائمة، ستتصرف كما لو تم استدعاء chrome.runtime.reload() استجابةً لهذا الحدث.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(details: object) => void
```
- التفاصيل
  
  عنصر
  - إصدار
    
    سلسلة
    
    رقم إصدار التحديث المتاح

onUserScriptConnect

الإصدار 115 من Chrome والإصدارات الأحدث الإصدار 3 من MV والإصدارات الأحدث

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

يتم تشغيله عند إجراء اتصال من نص برمجي للمستخدم من هذه الإضافة.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(port: Port) => void
```
- المنفذ
  
  المنفذ

onUserScriptMessage

الإصدار 115 من Chrome والإصدارات الأحدث الإصدار 3 من MV والإصدارات الأحدث

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

يتم تشغيله عند إرسال رسالة من نص برمجي للمستخدِم مرتبط بالإجراء الإضافي نفسه.

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- رسالة
  
  أي واحد
- المُرسِل
  
  MessageSender
- sendResponse
  
  دالة
  
  تظهر المَعلمة sendResponse على النحو التالي:
```
() => void
```
- returns
  boolean | undefined