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، وهي متاحة في الأساس لدعم عمليات تنفيذ Kiosk. ومن الطرق في هذه الفئة ما يلي: restart() و restartAfterDelay()`

سلوك الإضافة غير المضغوطة

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

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

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

لتتمكّن صفحة ويب من الوصول إلى مادة عرض مستضافة على نطاق آخر، يجب تحديد عنوان URL الكامل للمورد. (مثال: <img src="https://example.com/logo.png">). وينطبق الأمر نفسه على تضمين مادة عرض الإضافة في صفحة ويب. ويتمثل الاختلافان في أن مواد عرض الإضافة يجب أن تظهر على أنها web موارد الوصول إليها والتي عادةً ما تكون النصوص البرمجية للمحتوى هي المسئولة عن إدخال مواد عرض الإضافات.

في هذا المثال، ستضيف الإضافة logo.png إلى الصفحة التي تتضمن المحتوى يتم إدخال النص البرمجي باستخدام runtime.getURL() لإنشاء عنوان URL مؤهّل بالكامل. في المقابل، يجب أولاً الإعلان في البيان عن مادة العرض كمورد متاح للوصول إلى الويب.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

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

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

في هذا المثال، يحتاج النص البرمجي للمحتوى إلى بعض البيانات من مشغّل الخدمات الخاص بالإضافة إلى تهيئة واجهة المستخدم الخاصة بها. للحصول على هذه البيانات، يتم تمرير رسالة get-user-data التي يحدِّدها المطوّر. إلى عامل الخدمة، ويستجيب بنسخة من معلومات المستخدم.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

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

الأنواع

ContextFilter

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

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

أماكن إقامة

• contextIds

  string[] اختيارية

• contextTypes

  ContextType[] اختياري

• documentIds

  string[] اختيارية

• documentOrigins

  string[] اختيارية

• documentUrls

  string[] اختيارية

• frameIds

  number[] اختياري

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

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

• tabIds

  number[] اختياري

• windowIds

  number[] اختياري

ContextType

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

Enum

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

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

"BACKGROUND"
يحدد هذا الحقل نوع السياق باعتباره عامل خدمة.

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

"SIDE_PANEL"
يحدد هذا الخيار نوع السياق كلوحة جانبية.

ExtensionContext

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

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

أماكن إقامة

• contextId

  سلسلة

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

• contextType

  ContextType

  تمثّل هذه السمة نوع السياق الذي يتوافق مع هذه المعلومات.

• documentId

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

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

• documentOrigin

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

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

• documentUrl

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

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

• frameId

  الرقم

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

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

  منطقي

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

• tabId

  الرقم

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

• windowId

  الرقم

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

MessageSender

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

أماكن إقامة

• documentId

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

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

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

• documentLifecycle

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

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

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

• frameId

  الرقم اختياري

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

• id

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

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

• nativeApplication

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

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

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

• الأصل

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

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

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

• tab

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

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

• tlsChannelId

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

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

• url

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

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

OnInstalledReason

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

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

Enum

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

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

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

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

OnRestartRequiredReason

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

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

Enum

"app_update"
يحدد سبب الحدث باعتباره تحديثًا للتطبيق.

"os_update"
تحديد سبب الحدث كتحديث لنظام التشغيل.

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

PlatformArch

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

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

Enum

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

"arm64"
يتم تحديد بنية معالج البيانات على هيئة Arm64.

"x86-32"
يحدد هذا العمود بنية معالج البيانات على النحو التالي: x86-32.

"x86-64"
يحدد هذا العمود بنية معالج البيانات على النحو التالي: x86-64.

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

"mips64"
يحدد هذا الإعداد بنية معالج البيانات على النحو mips64.

PlatformInfo

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

أماكن إقامة

• قوس

  PlatformArch

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

• nacl_arch

  PlatformNaclArch

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

• نظام التشغيل

  PlatformOs

  نظام التشغيل Chrome قيد التشغيل.

PlatformNaclArch

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

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

Enum

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

"x86-32"
يحدد هذا الخيار بنية العميل الأصلي كـ x86-32.

"x86-64"
يحدد هذا الخيار بنية العميل الأصلي كـ x86-64.

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

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

PlatformOs

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

نظام التشغيل Chrome قيد التشغيل.

Enum

"mac"
حدد نظام التشغيل MacOS.

"win"
تحديد نظام التشغيل Windows.

"android"
تحديد نظام التشغيل Android.

"cros"
يحدد هذا الخيار نظام تشغيل Chrome.

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

"openbsd"
يحدد هذا الخيار نظام التشغيل OpenBSD.

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

Port

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

أماكن إقامة

• الاسم

  سلسلة

  اسم المنفذ، كما هو محدّد في استدعاء runtime.connect.

• onDisconnect

  الحدث <functionuffful>

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

  تبدو دالة onDisconnect.addListener كما يلي:

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

  • رد الاتصال

    دالة

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

    (port: Port) => void

    • المنفذ

      المنفذ

• onMessage

  الحدث <functionuffful>

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

  تبدو دالة onMessage.addListener كما يلي:

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

  • رد الاتصال

    دالة

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

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

    • رسالة

      أي واحد

    • المنفذ

      المنفذ

• المُرسِل

  MessageSender اختياري

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

• إلغاء الربط

  فراغ

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

  تبدو دالة disconnect كما يلي:

  () => {...}

• postMessage

  فراغ

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

  تبدو دالة postMessage كما يلي:

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

  • رسالة

    أي واحد

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

    الرسالة المطلوب إرسالها. يجب أن يكون هذا الكائن قابلاً للتحديد باستخدام JSON.

RequestUpdateCheckStatus

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

نتيجة البحث عن التحديثات

Enum

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

"no_update"
يحدد هذا الحقل عدم وجود تحديثات متاحة لتثبيتها.

"update_available"
يحدد هذا الإعداد أن هناك تحديثًا متاحًا للتثبيت.

أماكن إقامة

id

رقم تعريف الإضافة/التطبيق.

النوع

سلسلة

lastError

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

النوع

كائن

أماكن إقامة

• رسالة

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

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

الطُرق

connect()

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

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

المعلمات

• extensionId

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

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

• connectInfo

  الكائن اختياري

  • includeTlsChannelId

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

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

  • الاسم

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

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

المرتجعات

• المنفذ

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

المعلمات

• التطبيق

  سلسلة

  اسم التطبيق المسجّل المطلوب الاتصال به.

المرتجعات

• المنفذ

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

getBackgroundPage()

وعود واجهة التطبيق فقط

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

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

المعلمات

• رد الاتصال

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

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

  (backgroundPage?: Window) => void

  • backgroundPage

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

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

المرتجعات

• Promise&lt;Window | غير محددة>

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

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

getContexts()

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

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

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

المعلمات

• تصفية

  ContextFilter

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

• رد الاتصال

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

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

  (contexts: ExtensionContext[]) => void

  • السياقات

    ExtensionContext[]

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

المرتجعات

• Promise&lt;ExtensionContext[]&gt;

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

getManifest()

chrome.runtime.getManifest()

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

المرتجعات

• كائن

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

getPackageDirectoryEntry()

وعود واجهة التطبيق فقط

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

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

المعلمات

• رد الاتصال

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

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

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

المرتجعات

• Promise&lt;DirectoryEntry&gt;

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

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

getPlatformInfo()

وعود

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

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

المعلمات

• رد الاتصال

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

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

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

المرتجعات

• Promise&lt;PlatformInfo&gt;

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

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

المعلمات

• المسار

  سلسلة

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

المرتجعات

• سلسلة

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

openOptionsPage()

وعود

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

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

وقد يعتمد السلوك الدقيق على مفتاح [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) أو [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) في ملف البيان، أو ما يحدث لدعم Chrome في ذلك الوقت. على سبيل المثال، قد يتم فتح الصفحة في علامة تبويب جديدة، ضمن chrome://extensions أو داخل تطبيق، أو قد تركِّز فقط على صفحة خيارات مفتوحة. ولن يؤدي ذلك مطلقًا إلى إعادة تحميل صفحة المتصل.

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

المعلمات

• رد الاتصال

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

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

  () => void

المرتجعات

• وعود <باطلة>

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

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

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

وعود

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

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

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

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

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

المعلمات

• رد الاتصال

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

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

  (result: object) => void

  • نتيجة

    كائن

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

    عنصرRequestUpdateCheckResult هو الاحتفاظ بحالة البحث عن التحديثات وأي تفاصيل عن النتيجة في حال توفُّر تحديث

    • status

      RequestUpdateCheckStatus

      نتيجة البحث عن التحديثات

    • إصدار

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

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

المرتجعات

• Promise&lt;object&gt;

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

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

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

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

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

المعلمات

• ثانية

  الرقم

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

• رد الاتصال

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

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

  () => void

المرتجعات

• وعود <باطلة>

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

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

• رد الاتصال

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

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

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

  (response: any) => void

  • رد

    أي واحد

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

المرتجعات

• تقديم وعود<any>

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

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

sendNativeMessage()

وعود

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

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

المعلمات

• التطبيق

  سلسلة

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

• رسالة

  كائن

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

• رد الاتصال

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

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

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

  (response: any) => void

  • رد

    أي واحد

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

المرتجعات

• تقديم وعود<any>

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

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

setUninstallURL()

وعود

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

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

المعلمات

• url

  سلسلة

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

• رد الاتصال

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

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

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

  () => void

المرتجعات

• وعود <باطلة>

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

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

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

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

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

المعلمات

• رد الاتصال

  دالة

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

  (port: Port) => void

  • المنفذ

    المنفذ

onInstalled

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

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

المعلمات

• رد الاتصال

  دالة

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

  (details: object) => void

  • التفاصيل

    كائن

    • id

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

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

    • previousVersion

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

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

    • السبب

      OnInstalledReason

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

onMessage

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

يتم الإطلاق عند إرسال رسالة إما من عملية إضافة (من قِبل runtime.sendMessage) أو من نص برمجي للمحتوى (من قِبل tabs.sendMessage).

المعلمات

• رد الاتصال

  دالة

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

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

  • رسالة

    أي واحد

  • المُرسِل

    MessageSender

  • sendResponse

    دالة

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

    () => void

  • returns

    boolean | غير محدّدة

onMessageExternal

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

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

المعلمات

• رد الاتصال

  دالة

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

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

  • رسالة

    أي واحد

  • المُرسِل

    MessageSender

  • sendResponse

    دالة

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

    () => void

  • returns

    boolean | غير محدّدة

onRestartRequired

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

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

المعلمات

• رد الاتصال

  دالة

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

  (reason: OnRestartRequiredReason) => void

  • السبب

    OnRestartRequiredReason

onStartup

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

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

المعلمات

• رد الاتصال

  دالة

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

  () => void

onSuspend

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

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

المعلمات

• رد الاتصال

  دالة

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

  () => void

onSuspendCanceled

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

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

المعلمات

• رد الاتصال

  دالة

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

  () => void

onUpdateAvailable

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

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

المعلمات

• رد الاتصال

  دالة

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

  (details: object) => void

  • التفاصيل

    كائن

    • إصدار

      سلسلة

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

onUserScriptConnect

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

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

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

المعلمات

• رد الاتصال

  دالة

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

  (port: Port) => void

  • المنفذ

    المنفذ

onUserScriptMessage

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

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

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

المعلمات

• رد الاتصال

  دالة

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

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

  • رسالة

    أي واحد

  • المُرسِل

    MessageSender

  • sendResponse

    دالة

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

    () => void

  • returns

    boolean | غير محدّدة