chrome.runtime

الوصف

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

لا تتطلّب معظم عناصر واجهة برمجة التطبيقات هذه أي أذونات. يجب الحصول على هذا الإذن لاستخدام connectNative() وsendNativeMessage() وonNativeConnect.

يوضّح المثال التالي كيفية الإفصاح عن الإذن "nativeMessaging" في البيان:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

المفاهيم وطريقة الاستخدام

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

تمرير الرسائل
يمكن أن تتواصل إضافتك مع سياقات مختلفة داخل إضافتك ومع إضافات أخرى باستخدام هذه الطرق والأحداث: connect()، onConnect، onConnectExternal، sendMessage()، onMessage و onMessageExternal. بالإضافة إلى ذلك، يمكن أن تُرسِل الإضافة الرسائل إلى التطبيقات الأصلية على جهاز المستخدم باستخدام رمزَي connectNative() وsendNativeMessage().
الوصول إلى البيانات الوصفية للإضافات والمنصات
تتيح لك هذه الطرق استرداد عدة أجزاء محدّدة من البيانات الوصفية عن الإضافة والمنصة. تشمل الطرق في هذه الفئة getManifest() و getPlatformInfo().
إدارة دورة حياة الإضافة وخياراتها
تسمح لك هذه السمات بتنفيذ بعض العمليات الوصفية على الإضافة وعرض صفحة الخيارات. تشمل الطرق والأحداث في هذه الفئة onInstalled، onStartup، openOptionsPage()، reload()، requestUpdateCheck()، setUninstallURL().
أدوات مساعدة
توفّر هذه الطرق أدوات مفيدة، مثل تحويل تمثيلات الموارد الداخلية إلى تنسيقات خارجية. تشمل الطرق الواردة في هذه الفئة: getURL().
أدوات وضع Kiosk
لا تتوفّر هذه الطرق إلا على نظام التشغيل ChromeOS، وهي مخصّصة بشكل أساسي لدعم عمليات تنفيذ تطبيقات نقاط البيع. تشمل الطرق في هذه الفئة restart() و restartAfterDelay()`.

سلوك الإضافة غير المُعبَّأة

عند إعادة تحميل إضافة تم فك ضغطها، يتم التعامل معها على أنّها تحديث. وهذا يعني أنّه سيتم تنشيط الحدث chrome.runtime.onInstalled مع السبب "update". ويشمل ذلك عمليات إعادة تحميل الإضافة باستخدام chrome.runtime.reload().

حالات الاستخدام

إضافة صورة إلى صفحة ويب

لكي تتمكّن صفحة ويب من الوصول إلى مادة عرض مستضافة على نطاق آخر، يجب أن تحدّد عنوان 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);
});

service-worker.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 - عرض Resources accessible on the web للاطّلاع على المزيد من أمثلة Runtime API.

الأنواع

ContextFilter

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

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

الخصائص

  • contextIds

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

  • contextTypes

    ContextType[] اختياري

  • documentIds

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

  • documentOrigins

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

  • documentUrls

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

  • frameIds

    عدد اختياري

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

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

  • tabIds

    عدد اختياري

  • windowIds

    عدد اختياري

ContextType

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

تعداد

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

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

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

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

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

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

ExtensionContext

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

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

الخصائص

  • 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

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 في بعض المنصات.

  • نظام التشغيل الذي يعمل عليه 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()

Promise Foreground only Deprecated
chrome.runtime.getBackgroundPage(
  callback?: function,
)

لا تتوفّر صفحات الخلفية في إضافات MV3.

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

المعلمات

  • ردّ الاتصال

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

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

عرض إدخال دليل لدليل الحزمة

المعلمات

  • ردّ الاتصال

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

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

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

المرتجعات

  • Promise<DirectoryEntry>

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

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

getPlatformInfo()

الوعد 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

المعلمات

  • ردّ الاتصال

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

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

    (platformInfo: PlatformInfo) => void

المرتجعات

  • 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 الذي يحتوي على حالة التحقّق من التحديث وأي تفاصيل عن النتيجة في حال توفّر تحديث

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

      • إصدار

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

        إذا كان هناك تحديث متوفّر، سيتضمّن هذا الحقل رقم إصدار التحديث.

المرتجعات

  • 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.

المعلمات

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

Chrome 115 والإصدارات الأحدث MV3 والإصدارات الأحدث 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

المعلمات

  • ردّ الاتصال

    دالة

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

    (port: Port) => void

onUserScriptMessage

Chrome 115 والإصدارات الأحدث MV3 والإصدارات الأحدث 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

المعلمات

  • ردّ الاتصال

    دالة

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

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

    • رسالة

      أي واحد

    • المُرسِل

      MessageSender

    • sendResponse

      دالة

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

      () => void

    • returns

      boolean | undefined