chrome.extension

تاریخ به‌روزرسانی: 2026-09-25 ربات‌ها: noindex

توضیحات

API chrome.extension دارای ابزارهایی است که می‌تواند توسط هر صفحه افزونه‌ای مورد استفاده قرار گیرد. این API شامل پشتیبانی از تبادل پیام بین یک افزونه و اسکریپت‌های محتوای آن یا بین افزونه‌ها است، همانطور که به تفصیل در بخش «انتقال پیام» توضیح داده شده است.

انواع

ViewType

کروم ۴۴+

نوع نمای افزونه.

شمارشی

"تب"

"پاپ‌آپ"

خواص

inIncognitoContext

برای اسکریپت‌های محتوایی که درون تب‌های ناشناس اجرا می‌شوند و برای صفحات افزونه که درون یک فرآیند ناشناس اجرا می‌شوند، صادق است. مورد دوم فقط برای افزونه‌هایی با رفتار ناشناس «split» اعمال می‌شود.

نوع

بولی

lastError

≤ MV2 از زمان کروم ۵۸ منسوخ شده است

لطفاً از runtime.lastError استفاده کنید.

اگر یک API افزونه‌ی غیرهمزمان منجر به خطا شده باشد، برای طول عمر یک فراخوانی برگشتی تنظیم می‌شود. اگر هیچ خطایی رخ نداده باشد، lastError undefined خواهد بود.

نوع

شیء

خواص

  • پیام

    رشته

    شرح خطای رخ داده.

روش‌ها

getBackgroundPage()

فقط پیش‌زمینه
chrome.extension.getBackgroundPage(): Window | undefined

شیء 'window' جاوا اسکریپت را برای صفحه پس‌زمینه که درون افزونه فعلی اجرا می‌شود، برمی‌گرداند. اگر افزونه هیچ صفحه پس‌زمینه‌ای نداشته باشد، مقدار null را برمی‌گرداند.

بازگشت‌ها

  • پنجره | تعریف نشده

getExtensionTabs()

≤ فقط پیش‌زمینه MV2 منسوخ شده
 
chrome.extension.getExtensionTabs(
  windowId?: number,
): Window[]

لطفاً از extension.getViews {type: "tab"} استفاده کنید.

آرایه‌ای از اشیاء «پنجره» جاوا اسکریپت را برای هر یک از تب‌هایی که درون افزونه فعلی اجرا می‌شوند، برمی‌گرداند. اگر windowId مشخص شده باشد، فقط اشیاء «پنجره» تب‌هایی که به پنجره مشخص شده متصل هستند را برمی‌گرداند.

پارامترها

  • شناسه پنجره

    شماره اختیاری

بازگشت‌ها

  • پنجره[]

    آرایه‌ای از اشیاء پنجره سراسری

getURL()

≤ MV2 از زمان کروم ۵۸ منسوخ شده است
 
chrome.extension.getURL(
  path: string,
): string

لطفا از runtime.getURL استفاده کنید.

یک مسیر نسبی را در دایرکتوری نصب افزونه به یک URL کاملاً معتبر تبدیل می‌کند.

پارامترها

  • مسیر

    رشته

    مسیری به منبعی درون یک افزونه که نسبت به دایرکتوری نصب آن بیان شده است.

بازگشت‌ها

  • رشته

    آدرس اینترنتی (URL) کاملاً واجد شرایط برای منبع.

getViews()

فقط پیش‌زمینه
chrome.extension.getViews(
  fetchProperties?: object,
): Window[]

آرایه‌ای از اشیاء «پنجره» جاوا اسکریپت را برای هر یک از صفحاتی که درون افزونه فعلی اجرا می‌شوند، برمی‌گرداند.

پارامترها

  • واکشی ویژگی‌ها

    شیء اختیاری

    • شناسه برگه

      شماره اختیاری

      کروم ۵۴+

      یک نما را بر اساس شناسه برگه پیدا کنید. اگر این فیلد حذف شود، همه نماها را برمی‌گرداند.

    • نوع

      نوع نمایش اختیاری

      نوع نمایی که قرار است دریافت شود. در صورت حذف، تمام نماها (شامل صفحات پس‌زمینه و تب‌ها) را برمی‌گرداند.

    • شناسه پنجره

      شماره اختیاری

      پنجره‌ای که جستجو به آن محدود می‌شود. در صورت حذف، تمام نماها را برمی‌گرداند.

بازگشت‌ها

  • پنجره[]

    آرایه‌ای از اشیاء سراسری

isAllowedFileSchemeAccess()

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

وضعیت دسترسی افزونه به طرح 'file://' را بازیابی می‌کند. این مربوط به تنظیم 'Allow access to File URLs' برای هر افزونه است که توسط کاربر کنترل می‌شود و از طریق صفحه chrome://extensions قابل دسترسی است.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (isAllowedAccess: boolean) => void

    • دسترسی مجاز است

      بولی

      اگر افزونه بتواند به طرح 'file://' دسترسی داشته باشد، مقدار True و در غیر این صورت مقدار False را برمی‌گرداند.

بازگشت‌ها

  • قول <boolean>

    کروم ۹۹+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

isAllowedIncognitoAccess()

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

وضعیت دسترسی افزونه به حالت ناشناس را بازیابی می‌کند. این مربوط به تنظیم «مجاز در حالت ناشناس» برای هر افزونه است که توسط کاربر کنترل می‌شود و از طریق صفحه chrome://extensions قابل دسترسی است.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (isAllowedAccess: boolean) => void

    • دسترسی مجاز است

      بولی

      اگر افزونه به حالت ناشناس دسترسی داشته باشد، مقدار true و در غیر این صورت false است.

بازگشت‌ها

  • قول <boolean>

    کروم ۹۹+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

sendRequest()

Promise ≤ MV2 منسوخ شده
 
chrome.extension.sendRequest(
  extensionId?: string,
  request: any,
  callback?: function,
): Promise<any>

لطفا از runtime.sendMessage استفاده کنید.

یک درخواست واحد را به سایر شنوندگان درون افزونه ارسال می‌کند. مشابه runtime.connect است، اما فقط یک درخواست واحد با یک پاسخ اختیاری ارسال می‌کند. رویداد extension.onRequest در هر صفحه از افزونه اجرا می‌شود.

پارامترها

  • شناسه افزونه

    رشته اختیاری

    شناسه افزونه‌ای که می‌خواهید به آن متصل شوید. در صورت حذف، شناسه پیش‌فرض، افزونه خودتان است.

  • درخواست

    هر

  • تماس برگشتی

    تابع اختیاری

    کروم ۹۹+

    پارامتر callback به شکل زیر است: 

    (response: any) => void

    • پاسخ

      هر

      شیء پاسخ JSON که توسط کنترل‌کننده‌ی درخواست ارسال می‌شود. اگر هنگام اتصال به افزونه خطایی رخ دهد، promise رد خواهد شد.

بازگشت‌ها

  • قول بده<any>

    کروم ۹۹+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

setUpdateUrlData()

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

مقدار پارامتر ap CGI مورد استفاده در URL به‌روزرسانی افزونه را تنظیم می‌کند. این مقدار برای افزونه‌هایی که در گالری افزونه‌های کروم میزبانی می‌شوند، نادیده گرفته می‌شود.

پارامترها

  • داده‌ها

    رشته

رویدادها

onRequest

≤ MV2 منسوخ شده
 
chrome.extension.onRequest.addListener(
  callback: function,
)

لطفا از runtime.onMessage استفاده کنید.

زمانی اجرا می‌شود که درخواستی از یک فرآیند افزونه یا یک اسکریپت محتوا ارسال شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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

onRequestExternal

≤ MV2 منسوخ شده
 
chrome.extension.onRequestExternal.addListener(
  callback: function,
)

لطفاً از runtime.onMessageExternal استفاده کنید.

زمانی اجرا می‌شود که درخواستی از افزونه‌ی دیگری ارسال شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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