chrome.extension

الوصف

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

الأنواع

ViewType

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

نوع عرض الإضافة

تعداد

"tab"

"popup"

الخصائص

inIncognitoContext

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

النوع

قيمة منطقية

lastError

≤ MV2 تم إيقافه نهائيًا منذ Chrome 58

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

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

النوع

عنصر

الخصائص

  • رسالة

    سلسلة

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

الطُرق

getBackgroundPage()

المقدّمة فقط 
chrome.extension.getBackgroundPage()

عرض عنصر "window" في JavaScript للصفحة التي تعمل في الخلفية داخل الإضافة الحالية تعرِض قيمة فارغة إذا لم يكن لدى الإضافة صفحة خلفية.

المرتجعات

  • النافذة | غير محدّد

getExtensionTabs()

≤ MV2 الأولوية للعناصر الأمامية فقط تم إيقافه نهائيًا
chrome.extension.getExtensionTabs(
  windowId?: number,
)

يُرجى استخدام extension.getViews {type: "tab"}.

تعرِض هذه الدالة صفيفًا من عناصر "window" في JavaScript لكل علامة تبويب يتم تشغيلها داخل الإضافة الحالية. في حال تحديد windowId، يتم عرض عناصر "النافذة" فقط من علامات التبويب المرتبطة بالنافذة المحدّدة.

المعلمات

  • windowId

    رقم اختياري

المرتجعات

  • Window[]

    مصفوفة من عناصر النوافذ الشاملة

getURL()

≤ MV2 تم إيقافه نهائيًا منذ Chrome 58
chrome.extension.getURL(
  path: string,
)

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

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

المعلمات

  • المسار

    سلسلة

    مسار إلى مورد ضمن إضافة يتم التعبير عنه نسبةً إلى دليل التثبيت

المرتجعات

  • سلسلة

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

getViews()

المقدّمة فقط 
chrome.extension.getViews(
  fetchProperties?: object,
)

تعرِض صفيفًا من عناصر "window" في JavaScript لكل صفحة من الصفحات التي تعمل داخل الإضافة الحالية.

المعلمات

  • fetchProperties

    العنصر اختياري

    • tabId

      رقم اختياري

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

      العثور على عرض حسب معرّف علامة تبويب في حال حذف هذا الحقل، يتم عرض جميع طرق العرض.

    • كتابة

      ‫ViewType اختياري

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

    • windowId

      رقم اختياري

      النافذة التي يتم حصر البحث فيها في حال حذف هذا العمود، يتم عرض جميع طرق العرض.

المرتجعات

  • Window[]

    مصفوفة من العناصر الشاملة

isAllowedFileSchemeAccess()

الوعد 
chrome.extension.isAllowedFileSchemeAccess(
  callback?: function,
)

تُسترجع حالة وصول الإضافة إلى المخطط ‎"file://". ويتطابق ذلك مع الإعداد "السماح بالوصول إلى عناوين URL للملفات" الذي يتحكّم فيه المستخدم لكل إضافة ويمكن الوصول إليه من خلال صفحة chrome://extensions.

المعلمات

  • ردّ الاتصال

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      قيمة منطقية

      صحيح إذا كان بإمكان الإضافة الوصول إلى المخطط "file://"، وخطأ في الحالات الأخرى.

المرتجعات

  • Promise<boolean>

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

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

isAllowedIncognitoAccess()

الوعد 
chrome.extension.isAllowedIncognitoAccess(
  callback?: function,
)

يسترجع حالة وصول الإضافة إلى وضع التصفّح المتخفي. ويتطابق ذلك مع الإعداد "مسموح به في وضع التصفّح المتخفي" الذي يتحكّم فيه المستخدم لكل إضافة ويمكن الوصول إليه من خلال صفحة chrome://extensions.

المعلمات

  • ردّ الاتصال

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      قيمة منطقية

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

المرتجعات

  • Promise<boolean>

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

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

sendRequest()

Promise &leq; MV2 تم إيقافه نهائيًا
chrome.extension.sendRequest(
  extensionId?: string,
  request: any,
  callback?: function,
)

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

تُرسِل طلبًا واحدًا إلى المستمعين الآخرين ضمن الإضافة. يشبه runtime.connect، ولكنه يُرسِل طلبًا واحدًا فقط مع ردّ اختياري. يتم بدء الحدث extension.onRequest في كل صفحة من صفحات الإضافة.

المعلمات

  • extensionId

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

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

  • طلب

    أي واحد

  • ردّ الاتصال

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

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

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

    (response: any) => void

    • رد

      أي واحد

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

المرتجعات

  • Promise<any>

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

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

setUpdateUrlData()

chrome.extension.setUpdateUrlData(
  data: string,
)

تُستخدَم لضبط قيمة مَعلمة ap CGI المستخدَمة في عنوان URL الخاص بتحديث الإضافة. يتم تجاهل هذه القيمة للإضافات التي يتم استضافتها في "معرض إضافات Chrome".

المعلمات

  • البيانات

    سلسلة

الفعاليات

onRequest

&leq; MV2 متوقّف نهائيًا
chrome.extension.onRequest.addListener(
  callback: function,
)

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

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

المعلمات

  • ردّ الاتصال

    دالة

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

    (request: any, sender: runtime.MessageSender, sendResponse: function) => void

    • طلب

      أي واحد

    • المُرسِل

      runtime.MessageSender

    • sendResponse

      دالة

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

      () => void

onRequestExternal

&leq; MV2 متوقّف نهائيًا
chrome.extension.onRequestExternal.addListener(
  callback: function,
)

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

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

المعلمات

  • ردّ الاتصال

    دالة

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

    (request: any, sender: runtime.MessageSender, sendResponse: function) => void

    • طلب

      أي واحد

    • المُرسِل

      runtime.MessageSender

    • sendResponse

      دالة

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

      () => void