chrome.extension

الوصف

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

الأنواع

ViewType

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

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

التعداد

أماكن إقامة

inIncognitoContext

صحيح بالنسبة إلى النصوص البرمجية للمحتوى التي يتم تشغيلها داخل علامات تبويب التصفح المتخفي، ولصفحات الإضافات التي يتم تشغيلها داخل عملية التصفح المتخفي. ولا ينطبق الإجراء الثاني إلا على الإضافات التي تتضمن 'split'explore_behavior.

النوع

boolean

lastError

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

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

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

النوع

كائن

أماكن إقامة

  • رسالة

    سلسلة

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

الطُرق

getBackgroundPage()

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

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

المرتجعات

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

getExtensionTabs()

≤ MV2 المقدمة فقط متوقّفة نهائيًا
chrome.extension.getExtensionTabs(
  windowId?: number,
)

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

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

المَعلمات

  • windowId

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

المرتجعات

  • نافذة[]

    مصفوفة من كائنات النافذة العامة

getURL()

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

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

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

المَعلمات

  • المسار

    سلسلة

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

المرتجعات

  • سلسلة

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

getViews()

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

تعرض صفيفًا من كائنات "نافذة" JavaScript لكل صفحة من الصفحات التي يتم تشغيلها داخل الإضافة الحالية.

المَعلمات

  • fetchProperties

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

    • tabId

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

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

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

    • كتابة

      ViewType اختيارية

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

    • windowId

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

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

المرتجعات

  • نافذة[]

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

isAllowedFileSchemeAccess()

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

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

المَعلمات

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

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

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

    (isAllowedAccess: boolean)=>void

    • isAllowedAccess

      boolean

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

المرتجعات

  • Promise<boolean>

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

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

isAllowedIncognitoAccess()

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

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

المَعلمات

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

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

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

    (isAllowedAccess: boolean)=>void

    • isAllowedAccess

      boolean

      صحيح إذا كان بإمكان الإضافة الوصول إلى وضع التصفُّح المتخفي، وإلا فلن يحدث أي تغيير.

المرتجعات

  • Promise<boolean>

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

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

sendRequest()

الوعد &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 على رسالة الخطأ.

المرتجعات

  • وعد<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