browser.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، وهي متوفّرة بشكل أساسي لإتاحة عمليات تنفيذ وضع Kiosk. تشمل الطرق في هذه الفئة restart() وrestartAfterDelay()`.

سلوك الإضافة المتاحة

عند إعادة تحميل إضافة غير مضغوطة، يتم التعامل مع ذلك على أنّه تحديث. يعني ذلك أنّه سيتم تنشيط الحدث browser.runtime.onInstalled بالسبب "update". ويشمل ذلك إعادة تحميل الإضافة باستخدام browser.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 = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

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

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

In this example, the content script needs some data from the extension's service worker to initialize its UI. للحصول على هذه البيانات، يتم تمرير رسالة get-user-data التي يحدّدها المطوّر إلى مشغّل الخدمات، ويستجيب بنسخة من معلومات المستخدم.

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.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'
};

browser.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:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

أمثلة

يمكنك الاطّلاع على الإصدار Manifest V3 - العرض التوضيحي للموارد التي يمكن الوصول إليها على الويب لمزيد من الأمثلة على واجهة برمجة التطبيقات Runtime API.

الأنواع

ContextFilter

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

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

الخصائص

• contextIds

  string[] اختياري

• contextTypes

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

• documentIds

  string[] اختياري

• documentOrigins

  string[] اختياري

• documentUrls

  string[] اختياري

• frameIds

  number[] اختيارية

• incognito

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

• tabIds

  number[] اختيارية

• windowIds

  number[] اختيارية

ContextType

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

Enum

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

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

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

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

‫"SIDE_PANEL"
يحدّد نوع السياق كلوحة جانبية.

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

ExtensionContext

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

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

الخصائص

• contextId

  سلسلة

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

• contextType

  ContextType

  يشير إلى نوع السياق الذي يتوافق معه هذا النص.

• documentId

  string اختياري

  معرّف فريد عالمي (UUID) للمستند المرتبط بهذا السياق، أو غير محدّد إذا لم تتم استضافة هذا السياق في مستند.

• documentOrigin

  string اختياري

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

• documentUrl

  string اختياري

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

• frameId

  الرقم

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

• incognito

  قيمة منطقية

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

• tabId

  الرقم

  معرّف علامة التبويب لهذا السياق، أو ‎-1 إذا لم تتم استضافة هذا السياق في علامة تبويب.

• windowId

  الرقم

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

ExtensionLoadDetails

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

تفاصيل حول حدث تحميل الإضافة

الخصائص

• previousVersion

  string اختياري

  يشير إلى الإصدار السابق من الإضافة. لا يظهر هذا الحقل إلا إذا كانت قيمة "reason" هي "update" أو "enable". إذا كان "السبب" هو "التحديث"، فهذا هو إصدار الإضافة قبل تحديثها. إذا كانت قيمة "reason" هي "enable"، فهذا هو الإصدار الحالي من الإضافة.

• reason

  OnLoadedReason

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

MessageSender

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

الخصائص

• documentId

  string اختياري

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

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

• documentLifecycle

  string اختياري

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

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

• frameId

  number اختيارية

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

• id

  string اختياري

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

• nativeApplication

  string اختياري

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

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

• الأصل

  string اختياري

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

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

• ‏:

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

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

• tlsChannelId

  string اختياري

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

• url

  string اختياري

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

OnInstalledReason

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

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

Enum

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

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

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

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

OnLoadedReason

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

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

Enum

"install"
تم تثبيت الإضافة حديثًا.

"update"
تمت إعادة تحميل الإضافة بعد تحديثها.

‫"browser_update"
تم تحديث المتصفّح إلى إصدار جديد.

"enable"
تمت إعادة تفعيل الإضافة بعد أن كانت متوقفة.

"startup"
يتم تحميل الإضافة أثناء بدء تشغيل المتصفّح.

"reload"
تمت إعادة تحميل الإضافة (مثلاً من خلال chrome.runtime.reload()‎ أو أعاد المستخدم تحميل الإضافة يدويًا).

OnRestartRequiredReason

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

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

Enum

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

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

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

PlatformArch

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

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

Enum

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

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

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

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

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

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

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

PlatformInfo

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

الخصائص

• arch

  PlatformArch

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

• nacl_arch

  PlatformNaclArch اختيارية

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

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

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

• os

  PlatformOs

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

PlatformNaclArch

الإصدار 44 من Chrome والإصدارات الأحدث تم إيقافها نهائيًا منذ الإصدار 149 من Chrome

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

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

Enum

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

‫"x86-32"
يحدّد بنية Native Client على أنّها x86-32.

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

"mips"
يحدّد بنية Native Client على أنّها mips.

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

PlatformOs

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

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

Enum

"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

    • المنفذ

      Port (المنفذ)

• onMessage

  Event<functionvoidvoid>

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

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

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

  • callback

    دالة

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

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

    • رسالة

      أي واحد

    • المنفذ

      Port (المنفذ)

• المُرسِل

  MessageSender اختياري

  لن تظهر هذه السمة إلا في المنافذ التي تم تمريرها إلى المستمعين onConnect / onConnectExternal / onConnectNative.

• إلغاء الربط

  void

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

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

  () => {...}

• postMessage

  void

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

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

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

  • رسالة

    أي واحد

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

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

RequestUpdateCheckStatus

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

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

Enum

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

‫"no_update"
تشير إلى عدم توفّر تحديثات لتثبيتها.

"update_available"
تشير إلى توفّر تحديث يمكن تثبيته.

الخصائص

id

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

النوع

سلسلة

lastError

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

النوع

عنصر

الخصائص

• رسالة

  string اختياري

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

الطُرق

connect()

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

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

المعلمات

• extensionId

  string اختياري

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

• connectInfo

  object اختياري

  • includeTlsChannelId

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

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

  • الاسم

    string اختياري

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

المرتجعات

• Port (المنفذ)

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

connectNative()

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

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

المعلمات

• التطبيق

  سلسلة

  اسم التطبيق المسجَّل المطلوب الربط به

المرتجعات

• Port (المنفذ)

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

getBackgroundPage()

في المقدّمة فقط متوقّفة نهائيًا منذ الإصدار 133 من Chrome

chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

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

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

المرتجعات

• Promise<Window | undefined>

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

getContexts()

الإصدار 116 من Chrome والإصدارات الأحدث الإصدار 3 من "بيان الإضافة" والإصدارات الأحدث

chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

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

المعلمات

• تصفية

  ContextFilter

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

المرتجعات

• Promise<ExtensionContext[]>

  وعد يتم حله باستخدام السياقات المطابقة، إن وُجدت.

getManifest()

chrome.runtime.getManifest(): object

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

المرتجعات

• عنصر

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

getPackageDirectoryEntry()

في المقدّمة فقط

chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

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

المرتجعات

• Promise<DirectoryEntry>

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

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

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

المرتجعات

• Promise<PlatformInfo>

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

  وعد يتم حله بمعلومات حول المنصة الحالية

getURL()

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

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

المعلمات

• المسار

  سلسلة

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

المرتجعات

• سلسلة

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

getVersion()

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

chrome.runtime.getVersion(): string

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

المرتجعات

• سلسلة

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

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

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

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

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

المرتجعات

• وعد<فراغ>

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

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

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

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

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

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

المرتجعات

• وعد<كائن>

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

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

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

chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

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

المعلمات

• ثانية

  الرقم

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

المرتجعات

• وعد<فراغ>

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

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

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

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

المعلمات

• extensionId

  string اختياري

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

• رسالة

  أي واحد

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

• الخيارات

  object اختياري

  • includeTlsChannelId

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

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

المرتجعات

• وعد<أي>

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

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

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

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

المعلمات

• التطبيق

  سلسلة

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

• رسالة

  عنصر

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

المرتجعات

• وعد<أي>

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

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

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

المعلمات

• url

  سلسلة

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

المرتجعات

• وعد<فراغ>

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

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

الفعاليات

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

  • المنفذ

    Port (المنفذ)

onConnectExternal

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

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

المعلمات

• callback

  دالة

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

  (port: Port) => void

  • المنفذ

    Port (المنفذ)

onConnectNative

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

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

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

المعلمات

• callback

  دالة

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

  (port: Port) => void

  • المنفذ

    Port (المنفذ)

onEnabled

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

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

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

المعلمات

• callback

  دالة

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

  () => void

onExtensionLoaded

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

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

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

المعلمات

• callback

  دالة

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

  (details: ExtensionLoadDetails) => void

  • التفاصيل

    ExtensionLoadDetails

onInstalled

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

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

المعلمات

• callback

  دالة

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

  (details: object) => void

  • التفاصيل

    عنصر

    • id

      string اختياري

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

    • previousVersion

      string اختياري

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

    • reason

      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.

المعلمات

• callback

  دالة

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

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

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

  • التفاصيل

    عنصر

    • الإصدار

      سلسلة

      رقم إصدار التحديث المتاح

onUserScriptConnect

الإصدار 115 من Chrome أو الإصدارات الأحدث الإصدار 3 من "بيان الإضافة" أو الإصدارات الأحدث

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

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

المعلمات

• callback

  دالة

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

  (port: Port) => void

  • المنفذ

    Port (المنفذ)

onUserScriptMessage

الإصدار 115 من Chrome أو الإصدارات الأحدث الإصدار 3 من "بيان الإضافة" أو الإصدارات الأحدث

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

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

المعلمات

• callback

  دالة

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

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

  • رسالة

    أي واحد

  • المُرسِل

    MessageSender

  • sendResponse

    دالة

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

    (response?: any) => void

    • رد

      أيّ اختياري

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

  • returns

    boolean | undefined