chrome.runtime

الوصف

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

نظرة عامة

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

تمرير الرسائل
يمكن أن تتواصل الإضافة مع سياقات مختلفة ضمن الإضافة نفسها ومع إضافات أخرى باستخدام الطرق والأحداث التالية: connect()‎ و onConnect و onConnectExternal و sendMessage() و onMessage و onMessageExternal. بالإضافة إلى ذلك، يمكن للإضافة تمرير الرسائل إلى التطبيقات الأصلية على جهاز المستخدم باستخدام connectNative() و sendNativeMessage().
الوصول إلى البيانات الوصفية للإضافة والمنصة
تتيح لك هذه الطرق استرداد عدة أجزاء محدّدة من البيانات الوصفية حول الإضافة والمنصة. تشمل الطرق في هذه الفئة getManifest() و getPlatformInfo().
إدارة دورة حياة الإضافة وخياراتها
تتيح لك هذه الخصائص تنفيذ بعض العمليات الوصفية على الإضافة وعرض صفحة الخيارات. تشمل الطرق والأحداث في هذه الفئة ما يلي: onInstalled وonStartup وopenOptionsPage() وreload() وrequestUpdateCheck() وsetUninstallURL().
أدوات مساعدة
توفّر هذه الطرق أدوات مساعدة مثل تحويل تمثيلات الموارد الداخلية إلى تنسيقات خارجية. تشمل الطرق في هذه الفئة getURL().
أدوات وضع Kiosk
لا تتوفّر هذه الطرق إلا على ChromeOS، وهي متوفّرة بشكل أساسي لدعم عمليات تنفيذ وضع Kiosk. تشمل الطرق في هذه الفئة 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);
}

إرسال البيانات من مشغّل الخدمة إلى نص برمجي للمحتوى

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

في هذا المثال، يحتاج البرنامج النصي للمحتوى إلى بعض البيانات من عامل الخدمة الخاص بالإضافة من أجل تهيئة واجهة المستخدم. للحصول على هذه البيانات، يرسل المتصفّح رسالة 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');
  }
});

أمثلة على الإضافات

اطّلِع على عرض Manifest V3 التوضيحي حول "الموارد المتاحة على الويب" للحصول على المزيد من الأمثلة على Runtime API.

الأنواع

ContextFilter

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

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

الخصائص

  • contextIds

    string[] اختياري

  • contextTypes

    ‫ContextType[] اختيارية

  • documentIds

    string[] اختياري

  • documentOrigins

    string[] اختياري

  • documentUrls

    string[] اختياري

  • frameIds

    number[] اختيارية

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

    boolean اختياري

  • tabIds

    number[] اختيارية

  • windowIds

    number[] اختيارية

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

    number اختياري

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

  • id

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

    رقم تعريف الإضافة التي فتحت الاتصال، إن وُجد.

  • nativeApplication

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

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

    تمثّل هذه السمة اسم التطبيق الأصلي الذي فتح الاتصال، إذا كان ذلك منطبقًا.

  • الأصل

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

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

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

  • ‏:

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

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

  • tlsChannelId

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

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

  • url

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

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

OnInstalledReason

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

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

تعداد

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

"تعديل"
تحدّد هذه السمة سبب الحدث على أنّه تعديل إضافة.

‏"chrome_update"
تحدّد هذه السمة سبب الحدث على أنّه تحديث Chrome.

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

OnRestartRequiredReason

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

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

تعداد

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

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

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

PlatformArch

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

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

تعداد

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

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

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

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

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

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

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

PlatformInfo

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

الخصائص

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

  • nacl_arch

    PlatformNaclArch اختياري

    تم إيقافها نهائيًا منذ الإصدار 149 من Chrome

    تم إيقاف هذه السمة نهائيًا بعد إزالة Native Client بالكامل.

    بنية العميل الأصلي قد يختلف هذا عن بنية بعض المنصات.

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

PlatformNaclArch

‫Chrome 44+ تم إيقافها نهائيًا منذ الإصدار 149 من Chrome

تم إيقاف هذا النوع من التعداد نهائيًا بعد إزالة Native Client بالكامل.

بنية العميل الأصلي قد يختلف هذا عن بنية بعض المنصات.

تعداد

‫"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.

Port

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

الخصائص

  • الاسم

    سلسلة

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

  • onDisconnect

    Event<functionvoidvoid>

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

    تبدو الدالة onDisconnect.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

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

    تبدو الدالة onMessage.addListener على النحو التالي: 

    (callback: function) => {...}

    • callback

      دالة

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

      (message: any, port: Port) => void

  • المُرسِل

    MessageSender اختياري

    لن تظهر هذه السمة إلا في المنافذ التي تم تمريرها إلى برامج معالجة الأحداث onConnect / onConnectExternal / onConnectNative.

  • إلغاء الربط

    باطل

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

    تبدو الدالة disconnect على النحو التالي: 

    () => {...}

  • postMessage

    باطل

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

    تبدو الدالة postMessage على النحو التالي: 

    (message: any) => {...}

    • رسالة

      أي واحد

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

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

RequestUpdateCheckStatus

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

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

تعداد

"throttled"
تحدّد هذه السمة أنّ عملية التحقّق من الحالة قد تمّت إدارتها. يمكن أن يحدث ذلك بعد إجراء عمليات تحقّق متكرّرة خلال فترة زمنية قصيرة.

no_update
تحدّد هذه السمة أنّه لا تتوفّر أي تحديثات لتثبيتها.

"update_available"
تحدّد هذه السمة ما إذا كان هناك تحديث متاح للتثبيت.

الخصائص

id

معرّف الإضافة أو التطبيق

النوع

سلسلة

lastError

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

النوع

عنصر

الخصائص

  • رسالة

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

    تفاصيل حول الخطأ الذي حدث

الطُرق

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

محاولات ربط أدوات معالجة الأحداث داخل إحدى الإضافات (مثل صفحة الخلفية) أو الإضافات/التطبيقات الأخرى ويكون ذلك مفيدًا لبرامج النصوص الخاصة بالمحتوى التي تتصل بعمليات الإضافة، وللتواصل بين التطبيقات أو الإضافات، ولمراسلة الويب. يُرجى العِلم أنّ هذا لا يرتبط بأي مستمعين في نص برمجي للمحتوى. يمكن أن تتصل الإضافات بنصوص برمجية للمحتوى مضمّنة في علامات التبويب من خلال tabs.connect.

المعلمات

  • extensionId

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

    معرّف الإضافة المطلوب الربط بها في حال عدم إدخال رقم، سيتم محاولة الاتصال برقمك الخاص. مطلوب إذا كنت سترسل رسائل من صفحة ويب لاستخدام ميزة المراسلة على الويب.

  • connectInfo

    كائن اختياري

    • includeTlsChannelId

      boolean اختياري

      تحديد ما إذا كان سيتم تمرير معرّف قناة TLS إلى onConnectExternal للعمليات التي تستمع إلى حدث الاتصال

    • الاسم

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

      سيتم تمريرها إلى onConnect للعمليات التي تستمع إلى حدث الاتصال.

المرتجعات

  • المنفذ الذي يمكن من خلاله إرسال الرسائل واستلامها يتم تشغيل حدث onDisconnect للمنفذ إذا لم تكن الإضافة متوفّرة.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

يتصل بتطبيق أصلي على الجهاز المضيف. تتطلّب هذه الطريقة الحصول على إذن "nativeMessaging". يمكنك الاطّلاع على الرسائل الأصلية لمزيد من المعلومات.

المعلمات

  • التطبيق

    سلسلة

    اسم التطبيق المسجَّل الذي تريد الاتصال به.

المرتجعات

  • المنفذ الذي يمكن من خلاله إرسال الرسائل وتلقّيها باستخدام التطبيق

getBackgroundPage()

Promise Foreground only تم إيقافها نهائيًا منذ الإصدار 133 من Chrome
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

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

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

المعلمات

  • callback

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

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

    (backgroundPage?: Window) => void

    • backgroundPage

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

      كائن JavaScript "window" لصفحة الخلفية

المرتجعات

  • Promise<Window | undefined>

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

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

getManifest()

chrome.runtime.getManifest(): object

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

المرتجعات

  • عنصر

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

getPackageDirectoryEntry()

Promise Foreground only 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

تعرض هذه الطريقة DirectoryEntry لدليل الحزمة.

المعلمات

  • callback

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

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

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

المرتجعات

  • Promise<DirectoryEntry>

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

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

getPlatformInfo()

وعد 
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

تعرِض هذه السمة معلومات عن النظام الأساسي الحالي.

المعلمات

  • callback

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

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

    (platformInfo: PlatformInfo) => void

المرتجعات

  • Promise<PlatformInfo>

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

    وعد يتم تنفيذه مع معلومات حول النظام الأساسي الحالي.

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

getURL()

chrome.runtime.getURL(
  path: string,
): string

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

المعلمات

  • المسار

    سلسلة

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

المرتجعات

  • سلسلة

    تمثّل هذه السمة عنوان URL المؤهّل بالكامل للمرجع.

getVersion()

الإصدار 143 من Chrome أو إصدار أحدث 
chrome.runtime.getVersion(): string

تعرض هذه الدالة إصدار الإضافة كما هو موضّح في ملف البيان.

المرتجعات

  • سلسلة

    إصدار الإضافة

openOptionsPage()

وعد 
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

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

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

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

المعلمات

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

وعد 
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

يطلب إجراء فحص فوري للتحديثات لهذا التطبيق أو الإضافة.

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

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

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

المعلمات

  • callback

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

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

    (result: object) => void

    • نتيجة

      عنصر

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

      عنصر RequestUpdateCheckResult يحتوي على حالة التحقّق من التحديث وأي تفاصيل عن النتيجة في حال توفّر تحديث

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

      • الإصدار

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

        في حال توفّر تحديث، يحتوي هذا الحقل على إصدار التحديث المتاح.

المرتجعات

  • Promise<object>

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

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

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

Promise Chrome 53+ 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

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

المعلمات

  • ثانية

    الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    وعد يتم تنفيذه عند إعادة جدولة طلب إعادة التشغيل بنجاح.

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

sendMessage()

وعد 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
): Promise<any>

ترسل هذه الدالة رسالة واحدة إلى معالجات الأحداث في الإضافة أو في إضافة/تطبيق آخر، وهي تشبه الدالة runtime.connect ولكنّها ترسل رسالة واحدة فقط مع ردّ اختياري. في حال الإرسال إلى الإضافة، سيتم تشغيل الحدث runtime.onMessage في كل إطار من إطارات الإضافة (باستثناء إطار المُرسِل)، أو runtime.onMessageExternal، إذا كانت إضافة مختلفة. يُرجى العِلم أنّه لا يمكن للإضافات إرسال رسائل إلى نصوص المحتوى البرمجية باستخدام هذه الطريقة. لإرسال رسائل إلى نصوص المحتوى البرمجية، استخدِم tabs.sendMessage.

المعلمات

  • extensionId

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

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

  • رسالة

    أي واحد

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

  • الخيارات

    كائن اختياري

    • includeTlsChannelId

      boolean اختياري

      تحديد ما إذا كان سيتم تمرير معرّف قناة بروتوكول أمان طبقة النقل (TLS) إلى onMessageExternal للعمليات التي تستمع إلى حدث الاتصال

  • callback

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

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

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

    (response: any) => void

    • رد

      أي واحد

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

المرتجعات

  • Promise<any>

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

    تمت إضافة دعم Promise لسياقات الإضافات في الإصدار 99 من Chrome. عند التواصل من صفحة ويب إلى إضافة، تتوفّر الوعود بدءًا من الإصدار 118 من Chrome.

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

sendNativeMessage()

وعد 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
): Promise<any>

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

المعلمات

  • التطبيق

    سلسلة

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

  • رسالة

    عنصر

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

  • callback

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

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

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

    (response: any) => void

    • رد

      أي واحد

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

المرتجعات

  • Promise<any>

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

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

setUninstallURL()

وعد 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

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

المعلمات

  • url

    سلسلة

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

  • callback

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

    Chrome 45+

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

    () => void

المرتجعات

  • Promise<void>

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

    وعد يتم تنفيذه عند ضبط عنوان URL الخاص بإلغاء التثبيت. إذا كان عنوان URL المقدَّم غير صالح، سيتم رفض الوعد.

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

الفعاليات

onBrowserUpdateAvailable

تمّت إزالة هذا العمود
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

يُرجى استخدام runtime.onRestartRequired.

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

المعلمات

  • callback

    دالة

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

    () => void

onConnect

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

يتم تنشيط هذا الحدث عند إنشاء اتصال من عملية إضافة أو نص برمجي للمحتوى (باستخدام runtime.connect).

المعلمات

  • callback

    دالة

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

    (port: Port) => void

onConnectExternal

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

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

المعلمات

  • callback

    دالة

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

    (port: Port) => void

onConnectNative

‫Chrome 76 والإصدارات الأحدث 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

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

المعلمات

  • callback

    دالة

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

    (port: Port) => void

onEnabled

الإصدار 155 من Chrome والإصدارات الأحدث 
chrome.runtime.onEnabled.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عندما تنتقل الإضافة من حالة غير مفعّلة إلى حالة مفعّلة.

المعلمات

  • callback

    دالة

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

    () => void

onInstalled

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • id

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

        تشير إلى رقم تعريف إضافة الوحدة المشتركة التي تم استيرادها والتي تم تعديلها. لا تظهر هذه السمة إلا إذا كانت قيمة "السبب" هي shared_module_update.

      • previousVersion

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

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

      • السبب

        OnInstalledReason

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

onMessage

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

يتم تشغيل هذا الحدث عند إرسال رسالة من runtime.sendMessage أو tabs.sendMessage.

المعلمات

  • callback

    دالة

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

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

    • رسالة

      أي واحد

    • المُرسِل

      MessageSender

    • sendResponse

      دالة

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

      (response?: any) => void

      • رد

        أي اختياري

        الردّ الذي سيتم إرجاعه إلى مُرسِل الرسالة

    • returns

      boolean | Promise<any> | undefined

onMessageExternal

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

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

المعلمات

  • callback

    دالة

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

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

    • رسالة

      أي واحد

    • المُرسِل

      MessageSender

    • sendResponse

      دالة

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

      (response?: any) => void

      • رد

        أي اختياري

        الردّ الذي سيتم إرجاعه إلى مُرسِل الرسالة

    • returns

      boolean | Promise<any> | undefined

onRestartRequired

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

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

المعلمات

onStartup

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

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

المعلمات

  • callback

    دالة

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

    () => void

onSuspend

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

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

المعلمات

  • callback

    دالة

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

    () => void

onSuspendCanceled

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

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

المعلمات

  • callback

    دالة

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

    () => void

onUpdateAvailable

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

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

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • الإصدار

        سلسلة

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