chrome.extension

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأنواع

ViewType

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

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

Enum

"علامة تبويب"

"popup"

الخصائص

inIncognitoContext

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

النوع

قيمة منطقية

lastError

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

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

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

النوع

عنصر

الخصائص

• رسالة

  سلسلة

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

الطُرق

getBackgroundPage()

في المقدّمة فقط

chrome.extension.getBackgroundPage(): Window | undefined

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

المرتجعات

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

getExtensionTabs()

≤ MV2 المقدّمة فقط متوقّفة نهائيًا

chrome.extension.getExtensionTabs(
  windowId?: number,
): Window[]

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

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

المعلمات

• windowId

  number اختيارية

المرتجعات

• Window[]

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

getURL()

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

chrome.extension.getURL(
  path: string,
): string

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

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

المعلمات

• المسار

  سلسلة

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

المرتجعات

• سلسلة

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

getViews()

في المقدّمة فقط

chrome.extension.getViews(
  fetchProperties?: object,
): Window[]

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

المعلمات

• fetchProperties

  object اختياري

  • tabId

    number اختيارية

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

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

  • النوع

    ViewType اختيارية

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

  • windowId

    number اختيارية

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

المرتجعات

• Window[]

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

isAllowedFileSchemeAccess()

Promise

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

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

المعلمات

• callback

  function اختياري

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

  (isAllowedAccess: boolean) => void

  • isAllowedAccess

    قيمة منطقية

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

المرتجعات

• Promise<boolean>

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

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

isAllowedIncognitoAccess()

Promise

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

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

المعلمات

• callback

  function اختياري

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

  string اختياري

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

• طلب

  أي واحد

• callback

  function اختياري

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

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

  (response: any) => void

  • رد

    أي واحد

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

المرتجعات

• وعد<أي>

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

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

setUpdateUrlData()

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

تحدِّد هذه السياسة قيمة مَعلمة CGI الخاصة بـ "ap" والمستخدَمة في عنوان 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