تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

chrome.runtime

الوصف

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

لا تتطلّب معظم واجهات برمجة التطبيقات هذه أي أذونات. هذا الإذن مطلوب لتفعيل connectNative() وsendNativeMessage() وonNativeConnect.

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

manifest.json:

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

المفاهيم والاستخدام

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

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

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

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

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

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

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

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

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

manifest.json:

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

content.js:

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

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

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

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

أمثلة

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

الأنواع

ContextFilter

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

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

الخصائص

contextIds

string[] اختياري
contextTypes

ContextType[] اختياري
documentIds

string[] اختياري
documentOrigins

string[] اختياري
documentUrls

string[] اختياري
frameIds

number[] اختيارية
incognito

boolean اختياري
tabIds

number[] اختيارية
windowIds

number[] اختيارية

ContextType

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

Enum

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

‫"POPUP"
تحدّد نوع السياق على أنّه نافذة منبثقة خاصة بإضافة

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

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

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

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

ExtensionContext

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

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

الخصائص

contextId

سلسلة

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

ContextType

نوع السياق الذي يتطابق معه هذا المعرّف.
documentId

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

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

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

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

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

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

الرقم

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

قيمة منطقية

تحديد ما إذا كان السياق مرتبطًا بملف شخصي للتصفّح المتخفي
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 والإصدارات الأحدث

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

Enum

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

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

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

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

OnRestartRequiredReason

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

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

Enum

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

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

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

PlatformArch

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

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

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 اختياري

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

PlatformOs

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

PlatformNaclArch

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

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

Enum

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

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

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

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

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

PlatformOs

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

نظام التشغيل الذي يعمل عليه 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
```
  - المنفذ
    
    المنفذ
onMessage

Event<functionvoidvoid>

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

تبدو الدالة onMessage.addListener على النحو التالي:
```
(callback: function) => {...}
```
- callback
  
  دالة
  
  تظهر المَعلمة callback على النحو التالي:
```
(message: any, port: Port) => void
```
  - رسالة
    
    أي واحد
  - المنفذ
    
    المنفذ
المُرسِل

‫MessageSender اختياري

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

void

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

تبدو الدالة disconnect على النحو التالي:
```
() => {...}
```
postMessage

void

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

تبدو الدالة postMessage على النحو التالي:
```
(message: any) => {...}
```
- رسالة
  
  أي واحد
  
  Chrome 52 والإصدارات الأحدث
  
  الرسالة المطلوب إرسالها يجب أن يكون هذا العنصر قابلاً للتحويل إلى JSON.

RequestUpdateCheckStatus

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

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

Enum

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

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

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

لا تتوفّر صفحات الخلفية في إضافات الإصدار 3 من Manifest.

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

المرتجعات

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 المؤهّل بالكامل للمرجع.

openOptionsPage()

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

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

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

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

المرتجعات

Promise<void>

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

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

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

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

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

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

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

المرتجعات

Promise<object>

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

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

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

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

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

المعلمات

ثانية

الرقم

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

المرتجعات

Promise<void>

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

sendMessage()

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

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

المعلمات

extensionId

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

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

أي واحد

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

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

المرتجعات

Promise<any>

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

sendNativeMessage()

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

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

المعلمات

التطبيق

سلسلة

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

عنصر

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

المرتجعات

Promise<any>

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

setUninstallURL()

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

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

المعلمات

url

سلسلة

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

المرتجعات

Promise<void>

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

الفعاليات

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

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

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

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

المعلمات

callback

دالة

تظهر المَعلمة callback على النحو التالي:
```
(port: Port) => 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 | undefined
```
- رسالة
  
  أي واحد
- المُرسِل
  
  MessageSender
- sendResponse
  
  دالة
  
  تظهر المَعلمة sendResponse على النحو التالي:
```
() => void
```
- returns
  boolean | undefined

onMessageExternal

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

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

المعلمات

callback

دالة

تظهر المَعلمة callback على النحو التالي:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- رسالة
  
  أي واحد
- المُرسِل
  
  MessageSender
- sendResponse
  
  دالة
  
  تظهر المَعلمة sendResponse على النحو التالي:
```
() => void
```
- returns
  boolean | undefined

onRestartRequired

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

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

المعلمات

callback

دالة

تظهر المَعلمة callback على النحو التالي:
```
(reason: OnRestartRequiredReason) => void
```
- السبب
  
  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

‫Chrome 115 أو إصدار أحدث الإصدار 3 أو إصدار أحدث من Manifest

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

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

المعلمات

callback

دالة

تظهر المَعلمة callback على النحو التالي:
```
(port: Port) => void
```
- المنفذ
  
  المنفذ

onUserScriptMessage

‫Chrome 115 أو إصدار أحدث الإصدار 3 أو إصدار أحدث من Manifest

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

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

المعلمات

callback

دالة

تظهر المَعلمة callback على النحو التالي:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- رسالة
  
  أي واحد
- المُرسِل
  
  MessageSender
- sendResponse
  
  دالة
  
  تظهر المَعلمة sendResponse على النحو التالي:
```
() => void
```
- returns
  boolean | undefined

chrome.runtime تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الوصف

المفاهيم والاستخدام

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

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

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

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

جمع الملاحظات حول إلغاء التثبيت

أمثلة

الأنواع

ContextFilter

الخصائص

ContextType

Enum

ExtensionContext

الخصائص

MessageSender

الخصائص

OnInstalledReason

Enum

OnRestartRequiredReason

Enum

PlatformArch

Enum

PlatformInfo

الخصائص

PlatformNaclArch

Enum

PlatformOs

Enum

Port

الخصائص

RequestUpdateCheckStatus

Enum

الخصائص

id

النوع

lastError

النوع

الخصائص

الطُرق

connect()

المعلمات

المرتجعات

connectNative()

المعلمات

المرتجعات

getBackgroundPage()

المرتجعات

getContexts()

المعلمات

المرتجعات

getManifest()

المرتجعات

getPackageDirectoryEntry()

المرتجعات

getPlatformInfo()

المرتجعات

getURL()

المعلمات

المرتجعات

openOptionsPage()

المرتجعات

reload()

requestUpdateCheck()

المرتجعات

restart()

restartAfterDelay()

المعلمات

المرتجعات

sendMessage()

المعلمات

المرتجعات

sendNativeMessage()

المعلمات

المرتجعات

setUninstallURL()

المعلمات

المرتجعات

الفعاليات

chrome.runtime