chrome.runtime

الوصف

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

نظرة عامة

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

تمرير الرسالة

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

ملاحظة: اطّلِع على تمرير الرسائل للحصول على نظرة عامة حول الموضوع.

الوصول إلى البيانات الوصفية للإضافات والمنصات

تتيح لك هذه الطرق استرداد عدة أجزاء محدّدة من البيانات الوصفية عن الإضافة والمنصة. ومن الطرق في هذه الفئة ما يلي: getManifest()، و getPlatformInfo().

إدارة دورة حياة الإضافة وخياراتها

تسمح لك هذه السمات بتنفيذ بعض العمليات الوصفية على الإضافة وعرض صفحة الخيارات. تشمل الطرق والأحداث في هذه الفئة ما يلي: onInstalled onStartup, openOptionsPage(), reload()، requestUpdateCheck()، و setUninstallURL().

برامج الخدمات المساعِدة

توفّر هذه الطرق أدوات مفيدة، مثل تحويل تمثيلات الموارد الداخلية إلى تنسيقات خارجية. ومن الطرق في هذه الفئة ما يلي: getURL().

أدوات وضع Kiosk

لا تتوفّر هذه الطرق إلا على نظام التشغيل ChromeOS، وهي مخصّصة بشكل أساسي لدعم عمليات تنفيذ تطبيقات نقاط البيع. تشمل الطرق في هذه الفئة 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);
}

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

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

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

الأنواع

ContextFilter

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

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

أماكن إقامة

• contextIds

  string[] اختيارية

• contextTypes

  ContextType[] اختياري

• documentIds

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

• documentOrigins

  string[] اختيارية

• documentUrls

  string[] اختيارية

• frameIds

  number[] اختياري

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

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

• tabIds

  number[] اختياري

• windowIds

  number[] اختياري

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

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

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

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

• documentLifecycle

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

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

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

• 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

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

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

Enum

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

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

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

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

OnRestartRequiredReason

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

سبب إرسال الحدث "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

  بنية العميل الأصلي. قد يختلف هذا الخيار عن القوس على بعض الأنظمة الأساسية.

• os

  PlatformOs

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

PlatformNaclArch

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

بنية العميل الأصلي. قد يختلف هذا الخيار عن القوس على بعض الأنظمة الأساسية.

Enum

"الذراع"
يحدد هذا الخيار بنية العميل الأصلي كمجموعة تجربة.

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

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

"mips"
يحدد هذا الخيار بنية العميل الأصلي على هيئة mips.

"mips64"
يحدد هذا الخيار بنية البرنامج الأصلي على هيئة mips64.

PlatformOs

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

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

التعداد

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

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

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

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

"linux"
تحديد نظام التشغيل Linux.

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

"fuchsia"
تحديد نظام التشغيل Fuchsia.

Port

كائن يتيح التواصل ثنائي الاتجاه مع الصفحات الأخرى. راجِع الاتصالات طويلة الأمد للحصول على مزيد من المعلومات.

أماكن إقامة

• الاسم

  سلسلة

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

• onDisconnect

  الحدث <functionmutuff>

  يتم تشغيله عند انقطاع اتصال المنفذ بالطرف الآخر. قد يتم ضبط 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

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

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

التعداد

"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,
)

يسترجع عنصر JavaScript "window" للصفحة التي تعمل في الخلفية داخل التطبيق أو الإضافة الحالية. إذا كانت الصفحة التي تعمل في الخلفية هي صفحة حدث، سيحرص النظام على تحميلها قبل استدعاء دالة الاستدعاء. إذا لم تكن هناك صفحة خلفية، يتم ضبط خطأ.

المعلمات

• رد الاتصال

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

  تظهر المَعلمة callback على النحو التالي:

  (backgroundPage?: Window) => void

  • backgroundPage

    النافذة اختيارية

    "نافذة" JavaScript لصفحة الخلفية.

المرتجعات

• Promise<Window | undefined>

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

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

getContexts()

وعود الإصدار 116 من Chrome والإصدارات الأحدث MV3+

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

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

المعلمات

• تصفية

  ContextFilter

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

• رد الاتصال

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

  تظهر المَعلمة callback على النحو التالي:

  (contexts: ExtensionContext[]) => void

  • السياقات

    ExtensionContext[]

    السياقات المطابِقة، إن وجدت

المرتجعات

• Promise&lt;ExtensionContext[]&gt;

  لا تتوفّر الوعود إلا مع الإصدار 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](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>

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

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

      RequestUpdateCheckStatus

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

    • إصدار

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

      في حال توفُّر تحديث، يعني هذا أنه يتضمّن إصدار التحديث المتاح.

المرتجعات

• وعد <object>

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

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

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

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

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

المعلمات

• ثانية

  الرقم

  الوقت الذي يجب الانتظار خلاله بالثواني قبل إعادة تشغيل الجهاز، أو -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>

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

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

sendNativeMessage()

وعود

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

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

المعلمات

• التطبيق

  سلسلة

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

• رسالة

  كائن

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

• ردّ الاتصال

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

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

  تظهر المَعلمة callback على النحو التالي:

  (response: any) => void

  • رد

    أي واحد

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

المرتجعات

• Promise<any>

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

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

setUninstallURL()

وعود

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

تُستخدَم لضبط عنوان URL الذي سيتم الانتقال إليه عند إلغاء التثبيت. ويمكن استخدامها لتنظيف البيانات من جهة الخادم وإجراء الإحصاءات وتنفيذ الاستطلاعات. 1023 حرفًا كحدّ أقصى

المعلمات

• url

  سلسلة

  سيتم فتحه بعد إلغاء تثبيت الإضافة. يجب أن يتضمّن عنوان URL هذا مخطّط http: أو https:. اضبط سلسلة فارغة لعدم فتح علامة تبويب جديدة عند إلغاء التثبيت.

• ردّ الاتصال

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

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

  تظهر المَعلمة 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

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

      يشير إلى الإصدار السابق من الإضافة الذي تم تعديله للتو. لا يتوفّر ذلك إلا إذا كان "السبب" هي 'update'.

    • السبب

      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

    منطقي | غير محدّد

onMessageExternal

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

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

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • رسالة

    أي واحد

  • المُرسِل

    MessageSender

  • sendResponse

    دالة

    تظهر المَعلمة sendResponse على النحو التالي:

    () => void

  • returns

    منطقي | غير محدّد

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,
)

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

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  () => void

onSuspendCanceled

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

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

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  () => void

onUpdateAvailable

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

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

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (details: object) => void

  • التفاصيل

    كائن

    • إصدار

      سلسلة

      تمثّل هذه السمة رقم إصدار التحديث المتاح.

onUserScriptConnect

الإصدار 115 من Chrome أو الإصدارات الأحدث MV3+

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

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

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (port: Port) => void

  • المنفذ

    المنفذ

onUserScriptMessage

الإصدار 115 من Chrome أو الإصدارات الأحدث MV3+

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

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

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • رسالة

    أي واحد

  • المُرسِل

    MessageSender

  • sendResponse

    دالة

    تظهر المَعلمة sendResponse على النحو التالي:

    () => void

  • returns

    boolean | غير محدّدة