chrome.extension

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأنواع

ViewType

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

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

تعداد

"tab"

"popup"

الخصائص

inIncognitoContext

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

النوع

قيمة منطقية

lastError

≤ الإصدار 2 من Manifest تم إيقافه نهائيًا منذ الإصدار 58 من Chrome

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

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

النوع

عنصر

الخصائص

  • رسالة

    سلسلة

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

الطُرق

getBackgroundPage()

في المقدّمة فقط 
chrome.extension.getBackgroundPage(): Window | undefined

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

المرتجعات

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

getExtensionTabs()

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

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

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

المعلمات

  • windowId

    number اختياري

المرتجعات

  • Window[]

    مصفوفة تتضمّن عناصر النوافذ العامة

getURL()

≤ الإصدار 2 من Manifest تم إيقافه نهائيًا منذ الإصدار 58 من Chrome
chrome.extension.getURL(
  path: string,
): string

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

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

المعلمات

  • المسار

    سلسلة

    مسار إلى أحد الموارد ضِمن إضافة، ويتم التعبير عنه بالنسبة إلى دليل التثبيت.

المرتجعات

  • سلسلة

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

getViews()

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

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

المعلمات

  • fetchProperties

    كائن اختياري

    • tabId

      number اختياري

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

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

    • النوع

      ViewType اختياري

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

    • windowId

      number اختياري

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

المرتجعات

  • Window[]

    مصفوفة تتضمّن عناصر عامة

isAllowedFileSchemeAccess()

وعد 
chrome.extension.isAllowedFileSchemeAccess(
  callback?: function,
): Promise<boolean>

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

المعلمات

  • callback

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      قيمة منطقية

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

المرتجعات

  • Promise<boolean>

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

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

isAllowedIncognitoAccess()

وعد 
chrome.extension.isAllowedIncognitoAccess(
  callback?: function,
): Promise<boolean>

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

المعلمات

  • callback

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      قيمة منطقية

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

المرتجعات

  • Promise<boolean>

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

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

sendRequest()

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

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

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

المعلمات

  • extensionId

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

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

  • طلب

    أي واحد

  • callback

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

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

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

    (response: any) => void

    • رد

      أي واحد

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

المرتجعات

  • Promise<any>

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

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

setUpdateUrlData()

chrome.extension.setUpdateUrlData(
  data: string,
): void

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

المعلمات

  • البيانات

    سلسلة

الفعاليات

onRequest

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

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

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

المعلمات

  • callback

    دالة

    تظهر المَعلمة 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

    دالة

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

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

    • طلب

      أي واحد

    • المُرسِل

      runtime.MessageSender

    • sendResponse

      دالة

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

      () => void