chrome.runtime

الوصف

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

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

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

manifest.json:

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

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

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

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

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

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

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

background.js:

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

أمثلة

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

الأنواع

ContextFilter

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

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

أماكن إقامة

  • contextIds

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

  • contextTypes

    ContextType[] اختيارية

  • documentIds

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

  • documentOrigins

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

  • documentUrls

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

  • frameIds

    number[] اختيارية

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

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

  • tabIds

    number[] اختيارية

  • windowIds

    number[] اختيارية

ContextType

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

التعداد

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

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

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

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

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

ExtensionContext

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

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

أماكن إقامة

  • contextId

    سلسلة

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

  • contextType

    ContextType

    نوع السياق المتوافق مع هذا المحتوى.

  • documentId

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

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

  • documentOrigin

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

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

  • documentUrl

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

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

  • frameId

    الرقم

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

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

    boolean

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

  • tabId

    الرقم

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

  • windowId

    الرقم

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

MessageSender

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

أماكن إقامة

  • documentId

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

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

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

  • documentLifecycle

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

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

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

  • frameId

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

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

  • id

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

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

  • nativeApplication

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

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

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

  • الأصل

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

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

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

  • ‏

    Tab اختيارية

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

  • tlsChannelId

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

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

  • url

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

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

OnInstalledReason

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

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

التعداد

"install"
يحدد هذا الإعداد سبب الحدث كعملية تثبيت.

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

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

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

OnRestartRequiredReason

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

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

التعداد

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

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

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

PlatformArch

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

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

التعداد

"arm"
يحدد هذا الإعداد بنية المعالج كمجموعة تطبيقات.

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

"x86-32"
يحدد هذا الإعداد بنية المعالج كـ x86-32.

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

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

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

PlatformInfo

كائن يحتوي على معلومات حول النظام الأساسي الحالي.

أماكن إقامة

  • قوس

    PlatformArch

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

  • nacl_arch

    PlatformNaclArch

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

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

PlatformNaclArch

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

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

التعداد

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

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

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

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

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

PlatformOs

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

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

التعداد

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

"win"
يحدد هذا الإعداد نظام التشغيل Windows.

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

"cros"
يحدد نظام التشغيل Chrome.

"linux"
يحدد هذا الإعداد نظام تشغيل Linux.

"openbsd"
يحدد نظام التشغيل OpenBSD.

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

Port

يشير ذلك المصطلح إلى كائن يتيح التواصل المتبادل مع الصفحات الأخرى. راجع الاتصالات طويلة الأجل للحصول على مزيد من المعلومات.

أماكن إقامة

  • اسم

    سلسلة

    اسم المنفذ، كما هو محدّد في المكالمة المرسَلة إلى runtime.connect

  • onDisconnect

    الحدث<functionvitvit>

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

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

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

    • معاودة الاتصال

      الوظيفة

      تبدو معلَمة callback على النحو التالي: 

      (port: Port)=>void

  • onMessage

    الحدث<functionvitvit>

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

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

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

    • معاودة الاتصال

      الوظيفة

      تبدو معلَمة callback على النحو التالي: 

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

  • المُرسِل

    MessageSender اختياري

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

  • إلغاء الربط

    void

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

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

    ()=> {...}

  • postMessage

    void

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

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

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

    • رسالة

      أي فلتر

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

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

RequestUpdateCheckStatus

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

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

التعداد

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

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

"update_available"
تشير إلى توفُّر تحديث للتثبيت.

أماكن إقامة

id

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

النوع

سلسلة

lastError

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

النوع

كائن

أماكن إقامة

  • رسالة

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

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

الطُرق

connect()

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

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

المَعلمات

  • extensionId

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

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

  • connectInfo

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

    • includeTlsChannelId

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

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

    • اسم

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

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

المرتجعات

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

المَعلمات

  • التطبيق

    سلسلة

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

المرتجعات

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

getBackgroundPage()

وعد التي تعمل في المقدمة فقط 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (backgroundPage?: Window)=>void

    • backgroundPage

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

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

المرتجعات

  • الوعد<Window|غير محدّد>

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

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

getContexts()

Promise Chrome 116 والإصدارات الأحدث MV3 والإصدارات الأحدث 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

المَعلمات

  • filter

    ContextFilter

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (contexts: ExtensionContext[])=>void

    • السياقات

      ExtensionContext[]

      السياقات المطابِقة، إن توفّرت.

المرتجعات

  • Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

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

المرتجعات

  • كائن

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

getPackageDirectoryEntry()

وعد التي تعمل في المقدمة فقط 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

تعرض DirectoryEntry (إدخال الدليل) لدليل الحزمة.

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (directoryEntry: DirectoryEntry)=>void

    • directoryEntry

      DirectoryEntry

المرتجعات

  • Promise<DirectoryEntry>

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

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

getPlatformInfo()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (platformInfo: PlatformInfo)=>void

المرتجعات

  • Promise<PlatformInfo>

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

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

المَعلمات

  • المسار

    سلسلة

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

المرتجعات

  • سلسلة

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

openOptionsPage()

وعد 
chrome.runtime.openOptionsPage(
  callback?: function,
)

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

وقد يعتمد السلوك الدقيق على مفتاح [options_ui](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

المرتجعات

  • Promise<void>

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

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

    • نتيجة

      كائن

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

      عنصر RequestUpdateCheckResult الذي يحمل حالة البحث عن التحديثات وأي تفاصيل للنتيجة في حال توفر تحديث

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

      • إصدار

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

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

المرتجعات

  • Promise<object>

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

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome 53 أو الإصدارات الأحدث 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

المَعلمات

  • ثانية

    الرقم

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

sendMessage()

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

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

المَعلمات

  • extensionId

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

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

  • رسالة

    أي فلتر

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

  • الخيارات

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

    • includeTlsChannelId

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

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    (response: any)=>void

    • رد

      أي فلتر

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

المرتجعات

  • وعد<any>

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

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

sendNativeMessage()

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

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

المَعلمات

  • التطبيق

    سلسلة

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

  • رسالة

    كائن

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    (response: any)=>void

    • رد

      أي فلتر

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

المرتجعات

  • وعد<any>

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

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

setUninstallURL()

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

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

المَعلمات

  • url

    سلسلة

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

  • معاودة الاتصال

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

فعاليات

onBrowserUpdateAvailable

متوقّف نهائيًا
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

onConnect

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (port: Port)=>void

onConnectExternal

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (port: Port)=>void

onConnectNative

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (port: Port)=>void

onInstalled

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • id

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

        يشير إلى رقم تعريف إضافة الوحدة المشتركة المستورَدة التي تم تعديلها. ولا ينطبق ذلك إلا إذا كان "reason" هو "shared_ أمّا_update".

      • previousVersion

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

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

      • السبب

        OnInstalledReason

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

onMessage

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

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

    • رسالة

      أي فلتر

    • المُرسِل

      MessageSender

    • sendResponse

      الوظيفة

      تبدو معلَمة sendResponse على النحو التالي: 

      ()=>void

    • returns

      boolean|undefined

onMessageExternal

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

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

    • رسالة

      أي فلتر

    • المُرسِل

      MessageSender

    • sendResponse

      الوظيفة

      تبدو معلَمة sendResponse على النحو التالي: 

      ()=>void

    • returns

      boolean|undefined

onRestartRequired

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

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

المَعلمات

onStartup

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

onSuspend

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

onSuspendCanceled

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

onUpdateAvailable

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (details: object)=>void

    • التفاصيل

      كائن

      • إصدار

        سلسلة

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

onUserScriptConnect

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (port: Port)=>void

onUserScriptMessage

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

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

    • رسالة

      أي فلتر

    • المُرسِل

      MessageSender

    • sendResponse

      الوظيفة

      تبدو معلَمة sendResponse على النحو التالي: 

      ()=>void

    • returns

      boolean|undefined