chrome.runtime

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.runtime API برای بازیابی کارگر سرویس، برگرداندن جزئیات مانیفست، و گوش دادن و پاسخ دادن به رویدادها در چرخه حیات افزونه استفاده کنید. همچنین می‌توانید از این میانای برنامه‌سازی کاربردی برای تبدیل مسیر نسبی نشانی‌های وب به نشانی‌های وب کاملاً واجد شرایط استفاده کنید.

نمای کلی

‫Runtime API روش‌هایی را برای پشتیبانی از تعدادی از حوزه‌های عملکردی ارائه می‌دهد که افزونه‌های شما می‌توانند از آن‌ها استفاده کنند:

انتقال پیام
افزونه شما می‌تواند بااستفاده از این روش‌ها و رویدادها با زمینه‌های مختلف در افزونه شما و همچنین با افزونه‌های دیگر ارتباط برقرار کند: connect()‎، onConnect، onConnectExternal، sendMessage()، onMessage و onMessageExternal. In addition, your extension can pass messages to native applications on the user's device using connectNative() and sendNativeMessage().
دسترسی به فراداده پلاتفرم و افزونه
این روش‌ها به شما امکان می‌دهند چندین بخش خاص از فراداده مربوط به افزونه و پلاتفرم را بازیابی کنید. روش‌های این دسته شامل getManifest() و getPlatformInfo() است.
مدیریت چرخه حیات و گزینه‌های افزونه
این ویژگی‌ها به شما امکان می‌دهند برخی‌از فراعملیات‌ها را در افزونه انجام دهید و صفحه گزینه‌ها را نمایش دهید. روش‌ها و رویدادهای این دسته عبارت‌اند از: onInstalled، onStartup، openOptionsPage()، reload()، requestUpdateCheck()، و setUninstallURL().
برنامه‌های کمکی کمکی
این روش‌ها ابزارهایی مانند تبدیل نمایش منابع داخلی به قالب‌های خارجی را ارائه می‌دهند. روش‌های این دسته شامل getURL() است.
برنامه‌های کمکی حالت کیوسک
این روش‌ها فقط در ChromeOS دردسترس هستند و عمدتاً برای پشتیبانی از پیاده‌سازی‌های کیوسک وجود دارند. روش‌های این دسته شامل restart و restartAfterDelay است.

اجازه‌ها

اکثر روش‌ها در Runtime API به هیچ اجازه‌ای نیاز ندارند، به‌جز sendNativeMessage و connectNative که به اجازه nativeMessaging نیاز دارند.

مانیفست

مثال زیر نحوه اعلام اجازه nativeMessaging را در مانیفست نشان می‌دهد:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

موارد استفاده

افزودن تصویر به صفحه وب

برای اینکه صفحه وب به دارایی میزبانی‌شده در دامنه دیگری دسترسی داشته باشد، باید نشانی وب کامل منبع را مشخص کند (مثلاً <img src="https://example.com/logo.png">). همین امر برای گنجاندن دارایی افزونه در صفحه وب نیز صادق است. دو تفاوت این است که دارایی‌های افزونه باید به‌عنوان منابع قابل‌دسترسی وب نمایش داده شوند و معمولاً متن‌های محتوا مسئول تزریق دارایی‌های افزونه هستند.

در این مثال، افزونه logo.png را به صفحه‌ای اضافه می‌کند که اسکریپت محتوا بااستفاده از runtime.getURL() برای ایجاد نشانی وب کاملاً واجدشرایط به آن تزریق می‌شود. اما ابتدا، دارایی باید به‌عنوان منبع قابل‌دسترسی وب در مانیفست اعلام شود.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

ارسال داده از کارگر سرویس به اسکریپت محتوا

معمولاً اسکریپت‌های محتوای افزونه به داده‌هایی نیاز دارند که توسط بخش دیگری از افزونه مدیریت می‌شود، مانند سرویس‌کار. درست مثل دو پنجره مرورگر که برای یک صفحه وب باز شده‌اند، این دو زمینه نمی‌توانند مستقیماً به مقادیر یکدیگر دسترسی داشته باشند. درعوض، افزونه می‌تواند از ارسال پیام برای هماهنگی در این زمینه‌های مختلف استفاده کند.

در این مثال، اسکریپت محتوا برای مقداردهی اولیه واسط کاربر خود به برخی داده‌ها از کارگر سرویس افزونه نیاز دارد. برای دریافت این داده‌ها، پیام get-user-data را به کارمند خدمات ارسال می‌کند و کارمند خدمات با نسخه‌ای از اطلاعات کاربر پاسخ می‌دهد.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

background.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

جمع‌آوری بازخورد درباره حذف نصب

بسیاری از افزونه‌ها از نظرسنجی‌های پس‌از حذف نصب استفاده می‌کنند تا متوجه شوند افزونه چگونه می‌تواند بهتر به کاربرانش خدمت‌رسانی کند و حفظ کاربر را بهبود بخشد. مثال زیر نحوه افزودن این عملکرد را نشان می‌دهد.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

نمونه‌های افزونه

برای نمونه‌های بیشتر از Runtime API، به نمونه نمایشی Manifest V3 - Web Accessible Resources مراجعه کنید.

انواع

ContextFilter

Chrome نسخه ۱۱۴ و بالاتر

فیلتری برای مطابقت با زمینه‌های افزونه خاص. بافت‌های منطبق باید با همه فیلترهای مشخص‌شده مطابقت داشته باشند؛ هر فیلتری که مشخص نشده باشد با همه بافت‌های دردسترس مطابقت دارد. بنابراین، فیلتر `{}` با همه زمینه‌های موجود مطابقت خواهد داشت.

مشخصات

  • contextIds

    رشته[] اختیاری

  • contextTypes

    ContextType[] اختیاری

  • documentIds

    رشته[] اختیاری

  • documentOrigins

    رشته[] اختیاری

  • documentUrls

    رشته[] اختیاری

  • frameIds

    number[] اختیاری

  • ناشناس

    بولی اختیاری

  • tabIds

    number[] اختیاری

  • windowIds

    number[] اختیاری

ContextType

Chrome نسخه ۱۱۴ و بالاتر

شمارشی

«TAB»
نوع بافت را به‌عنوان برگه مشخص می‌کند

«POPUP»
نوع بافت را به‌عنوان پنجره بالاپر افزونه مشخص می‌کند

«پس‌زمینه»
نوع بافت را به‌عنوان کارگر سرویس مشخص می‌کند.

«OFFSCREEN_DOCUMENT»
نوع بافت را به‌عنوان سند خارج از صفحه مشخص می‌کند.

«SIDE_PANEL»
نوع بافت را به‌عنوان پانل کناری مشخص می‌کند.

«DEVELOPER_TOOLS»
نوع بافت را به‌عنوان ابزارهای توسعه‌دهندگان مشخص می‌کند.

ExtensionContext

Chrome نسخه ۱۱۴ و بالاتر

بافتی که محتوای افزونه را میزبانی می‌کند.

مشخصات

  • contextId

    رشته

    شناسه یکتا برای این زمینه

  • contextType

    ContextType

    نوع زمینه‌ای که این مورد با آن مطابقت دارد.

  • documentId

    رشته اختیاری

    یک UUID برای سند مرتبط با این زمینه، یا تعریف‌نشده اگر این زمینه در سند میزبانی نشده باشد.

  • documentOrigin

    رشته اختیاری

    منشأ سند مرتبط با این زمینه، یا تعریف‌نشده اگر زمینه در سندی میزبانی نشده باشد.

  • documentUrl

    رشته اختیاری

    نشانی وب سند مرتبط با این زمینه، یا تعریف‌نشده اگر زمینه در سندی میزبانی نشده باشد.

  • frameId

    شماره

    شناسه قاب برای این بافت، یا ‎-۱ اگر این بافت در قابی میزبانی نشده باشد.

  • ناشناس

    بولی

    اینکه آیا زمینه با نمایه ناشناس مرتبط است یا نه.

  • tabId

    شماره

    شناسه برگه برای این زمینه، یا ‎-۱ اگر این زمینه در برگه میزبانی نشده باشد.

  • windowId

    شماره

    شناسه پنجره برای این زمینه، یا ۱- اگر این زمینه در پنجره‌ای میزبانی نشده باشد.

ExtensionLoadDetails

Chrome نسخه ۱۵۷ و بالاتر

جزئیات مربوط به رویداد بارگیری افزونه.

مشخصات

  • previousVersion

    رشته اختیاری

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

  • دلیل

    OnLoadedReason

    دلیل ارسال این رویداد.

MessageSender

شیئی حاوی اطلاعاتی درباره بافتار اسکریپتی که پیام یا درخواستی را ارسال کرده است.

مشخصات

  • documentId

    رشته اختیاری

    Chrome نسخه ۱۰۶ و بالاتر

    شناسه UUID سندی که اتصال را باز کرده است.

  • documentLifecycle

    رشته اختیاری

    Chrome نسخه ۱۰۶ و بالاتر

    چرخه حیات سندی که اتصال را باز کرده است در زمانی که درگاه ایجاد شده است. توجه داشته باشید که ممکن است وضعیت چرخه حیات سند از زمان ایجاد درگاه تغییر کرده باشد.

  • frameId

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

    قابی که اتصال را باز کرده است. ۰ برای قاب‌های سطح بالا، مثبت برای قاب‌های فرزند. این فقط زمانی تنظیم می‌شود که tab تنظیم شده باشد.

  • id

    رشته اختیاری

    شناسه افزونه‌ای که اتصال را باز کرده است (درصورت وجود).

  • nativeApplication

    رشته اختیاری

    Chrome نسخه ۷۴ و بالاتر

    نام برنامه بومی که اتصال را باز کرده است (درصورت وجود).

  • منشأ

    رشته اختیاری

    Chrome نسخه ۸۰ به بالا

    مبدأ صفحه یا قابی که اتصال را باز کرده است. این مقدار می‌تواند با ویژگی url متفاوت باشد (مثلاً about:blank) یا می‌تواند مبهم باشد (مثلاً iframeهای سندباکس‌شده). این روش برای شناسایی اینکه آیا می‌توان به منبع اعتماد کرد یا نه مفید است، به‌ویژه اگر نتوانیم فوراً از نشانی وب به این موضوع پی ببریم.

  • جهش

    برگه اختیاری

    tabs.Tab که اتصال را باز کرده است (درصورت وجود). این ویژگی فقط زمانی وجود خواهد داشت که اتصال از یک برگه (شامل اسکریپت‌های محتوا) باز شده باشد، و فقط اگر گیرنده یک افزونه باشد، نه یک برنامه.

  • tlsChannelId

    رشته اختیاری

    شناسه کانال TLS صفحه یا قابی که اتصال را باز کرده است، درصورت درخواست افزونه و درصورت دردسترس بودن.

  • نشانی وب

    رشته اختیاری

    نشانی وب صفحه یا قابی که اتصال را باز کرده است. اگر فرستنده در iframe باشد، نشانی وب iframe خواهد بود نه نشانی وب صفحه‌ای که میزبان آن است.

OnInstalledReason

Chrome نسخه ۴۴ به بالا

دلیل ارسال این رویداد.

شمارشی

«install»
دلیل رویداد را به‌عنوان نصب مشخص می‌کند.

«update»
دلیل رویداد را به‌عنوان به‌روزرسانی افزونه مشخص می‌کند.

"chrome_update"
دلیل رویداد را به‌عنوان به‌روزرسانی Chrome مشخص می‌کند.

"shared_module_update"
دلیل رویداد را به‌عنوان به‌روزرسانی در یک ماژول هم‌رسانی‌شده مشخص می‌کند.

OnLoadedReason

Chrome نسخه ۱۵۷ و بالاتر

دلیل ارسال این رویداد.

شمارشی

"install"
افزونه به‌تازگی نصب شده است.

«update»
افزونه پس‌از به‌روزرسانی مجدداً بار شد.

«browser_update»
مرورگر به نسخه جدیدی به‌روزرسانی شد.

«فعال کردن»
افزونه از حالت غیرفعال دوباره فعال شد.

«startup»
افزونه درحال بار شدن درطول راه‌اندازی مرورگر است.

«reload»
افزونه مجدداً بار شد (مثلاً ازطریق chrome.runtime.reload() یا کاربر به‌صورت دستی افزونه را مجدداً بار کرد).

OnRestartRequiredReason

Chrome نسخه ۴۴ به بالا

دلیل ارسال رویداد. وقتی بازراه‌اندازی به‌دلیل به‌روزرسانی برنامه به نسخه جدیدتر لازم باشد، از «app_update» استفاده می‌شود. وقتی بازراه‌اندازی به‌دلیل به‌روزرسانی مرورگر/ سیستم‌عامل به نسخه جدیدتر لازم باشد، از os_update استفاده می‌شود. وقتی سیستم بیشتر از زمان فعال بودن دستگاه مجاز تنظیم‌شده در خط‌مشی سازمانی اجرا شود، از «periodic» استفاده می‌شود.

شمارشی

«app_update»
دلیل رویداد را به‌عنوان به‌روزرسانی برنامه مشخص می‌کند.

"os_update"
دلیل رویداد را به‌عنوان به‌روزرسانی سیستم‌عامل مشخص می‌کند.

«periodic»
دلیل رویداد را به‌عنوان بازراه‌اندازی دوره‌ای برنامه مشخص می‌کند.

PlatformArch

Chrome نسخه ۴۴ به بالا

معماری پردازنده دستگاه.

شمارشی

«arm»
معماری پردازنده را به‌عنوان arm مشخص می‌کند.

«arm64»
معماری پردازنده را به‌عنوان arm64 مشخص می‌کند.

«x86-32»
ساختار پردازنده را به‌عنوان x86-32 مشخص می‌کند.

«x86-64»
معماری پردازنده را به‌عنوان x86-64 مشخص می‌کند.

«mips»
معماری پردازنده را به‌عنوان mips مشخص می‌کند.

«mips64»
معماری پردازنده را به‌عنوان mips64 مشخص می‌کند.

«riscv64»
ساختار پردازنده را به‌عنوان riscv64 مشخص می‌کند.

PlatformInfo

شیئی حاوی اطلاعاتی درباره پلاتفرم فعلی.

مشخصات

  • طاق

    PlatformArch

    معماری پردازنده دستگاه.

  • nacl_arch

    PlatformNaclArch اختیاری

    از Chrome 149 منسوخ شده است

    این مشخصه به‌دنبال حذف کامل Native Client منسوخ شده است.

    معماری کارخواه بومی. این ممکن است با arch در برخی پلاتفرم‌ها متفاوت باشد.

  • سیستم‌عاملی که Chrome روی آن اجرا می‌شود.

PlatformNaclArch

Chrome نسخه ۴۴ به بالا از Chrome نسخه ۱۴۹ منسوخ شده است

این شمارشگر به‌دنبال حذف کامل Native Client منسوخ شده است.

معماری کارخواه بومی. این ممکن است با arch در برخی پلاتفرم‌ها متفاوت باشد.

شمارشی

«arm»
معماری کارخواه بومی را به‌عنوان arm مشخص می‌کند.

«x86-32»
معماری کلاینت بومی را به‌عنوان x86-32 مشخص می‌کند.

«x86-64»
معماری کلاینت بومی را به‌عنوان x86-64 مشخص می‌کند.

«mips»
معماری کلاینت بومی را به‌عنوان mips مشخص می‌کند.

"mips64"
معماری کارخواه بومی را به‌عنوان mips64 مشخص می‌کند.

PlatformOs

Chrome نسخه ۴۴ به بالا

سیستم‌عاملی که Chrome روی آن اجرا می‌شود.

شمارشی

«mac»
سیستم‌عامل MacOS را مشخص می‌کند.

"win"
سیستم‌عامل Windows را مشخص می‌کند.

"android"
سیستم‌عامل Android را مشخص می‌کند.

«cros»
سیستم‌عامل Chrome را مشخص می‌کند.

«linux»
سیستم‌عامل Linux را مشخص می‌کند.

"openbsd"
سیستم‌عامل OpenBSD را مشخص می‌کند.

Port

شیئی که امکان ارتباط دوطرفه با صفحه‌های دیگر را فراهم می‌کند. برای اطلاعات بیشتر، اتصال‌های طولانی‌مدت را ببینید.

مشخصات

  • نام

    رشته

    نام درگاه، همان‌طور که در تماس با runtime.connect مشخص شده است.

  • onDisconnect

    Event<functionvoidvoid>

    وقتی درگاه از سر(های) دیگر قطع شود، فعال می‌شود. اگر درگاه به‌دلیل خطا قطع شده باشد، ممکن است runtime.lastError تنظیم شود. اگر درگاه ازطریق قطع اتصال بسته شود، این رویداد فقط در طرف دیگر فعال می‌شود. این رویداد حداکثر یک‌بار فعال می‌شود (طول عمر درگاه را نیز ببینید).

    تابع onDisconnect.addListener به‌صورت زیر است: 

    (callback: function) => {...}

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

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

    تابع onMessage.addListener به‌صورت زیر است: 

    (callback: function) => {...}

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      (message: any, port: Port) => void

  • فرستنده

    MessageSender اختیاری

    این ویژگی فقط در درگاه‌هایی وجود خواهد داشت که به شنوندگان onConnect / onConnectExternal / onConnectNative ارسال شده‌اند.

  • قطع کردن اتصال

    باطل کردن

    فوراً درگاه را جدا کنید. Calling disconnect() on an already-disconnected port has no effect. وقتی درگاهی قطع می‌شود، هیچ رویداد جدیدی به این درگاه ارسال نخواهد شد.

    تابع disconnect به‌صورت زیر است: 

    () => {...}

  • postMessage

    باطل کردن

    پیامی به سر دیگر درگاه ارسال کنید. اگر درگاه قطع شود، خطایی ایجاد می‌شود.

    تابع postMessage به‌صورت زیر است: 

    (message: any) => {...}

    • پیام

      همه

      Chrome نسخه ۵۲ و بالاتر

      پیام برای ارسال. این شیء باید JSON-ifiable باشد.

RequestUpdateCheckStatus

Chrome نسخه ۴۴ به بالا

نتیجه بررسی به‌روزرسانی.

شمارشی

«throttled»
مشخص می‌کند که بررسی وضعیت محدود شده است. این اتفاق ممکن است پس‌از بررسی‌های مکرر در مدت‌زمان کوتاهی رخ دهد.

"no_update"
مشخص می‌کند که هیچ به‌روزرسانی‌ای برای نصب دردسترس نیست.

"update_available"
مشخص می‌کند که به‌روزرسانی دردسترسی برای نصب وجود دارد.

مشخصات

id

شناسه افزونه/برنامه.

نوع

رشته

lastError

اگر فراخوانی تابع میانای برنامه‌سازی کاربردی ناموفق باشد، با پیام خطا پر می‌شود؛ درغیراین‌صورت تعریف‌نشده است. این فقط در محدوده کال بک آن تابع تعریف شده است. اگر خطایی ایجاد شود، اما در بازگشت تماس به runtime.lastError دسترسی پیدا نشود، پیامی در کنسول ثبت می‌شود که تابع API ایجادکننده خطا را فهرست می‌کند. توابع API که وعده‌ها را برمی‌گردانند این ویژگی را تنظیم نمی‌کنند.

نوع

شیء

مشخصات

  • پیام

    رشته اختیاری

    جزئیات مربوط به خطایی که رخ داده است.

روش‌ها

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

تلاش می‌کند شنوندگان را در افزونه (مثل صفحه پس‌زمینه) یا افزونه‌ها/برنامه‌های دیگر متصل کند. این امر برای اسکریپت‌های محتوا که به فرایندهای افزونه خود متصل می‌شوند، ارتباط بین برنامه/افزونه، و پیام‌رسانی وب مفید است. توجه داشته باشید که این به هیچ شنونده‌ای در اسکریپت محتوا متصل نمی‌شود. افزونه‌ها ممکن است ازطریق tabs.connect به متن‌های محتوای جاسازی‌شده در برگه‌ها متصل شوند.

پارامترها

  • extensionId

    رشته اختیاری

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

  • connectInfo

    شیء اختیاری

    • includeTlsChannelId

      بولی اختیاری

      اینکه آیا شناسه کانال TLS برای فرایندهایی که به رویداد اتصال گوش می‌دهند به onConnectExternal ارسال خواهد شد یا نه.

    • نام

      رشته اختیاری

      برای فرایندهایی که منتظر رویداد اتصال هستند، به onConnect منتقل خواهد شد.

بازگشتی‌ها

  • درگاهی که ازطریق آن پیام‌ها ارسال و دریافت می‌شوند. اگر افزونه وجود نداشته باشد، رویداد onDisconnect درگاه فعال می‌شود.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

به برنامه بومی در دستگاه میزبان متصل می‌شود. این روش به اجازه "nativeMessaging" نیاز دارد. برای اطلاعات بیشتر، پیام‌رسانی بومی را ببینید.

پارامترها

  • برنامه

    رشته

    نام برنامه ثبت‌شده برای اتصال به آن.

بازگشتی‌ها

  • درگاهی که ازطریق آن می‌توان با برنامه پیام ارسال و دریافت کرد

getBackgroundPage()

Promise فقط پیش‌زمینه از Chrome 133 منسوخ شده است
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

صفحه‌های پس‌زمینه در افزونه‌های MV3 وجود ندارند.

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (backgroundPage?: Window) => void

    • backgroundPage

      پنجره اختیاری

      شیء «پنجره» جاوا اسکریپت برای صفحه پس‌زمینه.

بازگشتی‌ها

  • Promise<Window | undefined>

    Chrome نسخه ۹۹ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getManifest()

chrome.runtime.getManifest(): object

جزئیات مربوط به برنامه یا افزونه را از مانیفست برمی‌گرداند. شیء برگردانده‌شده سری‌سازی‌شده فایل مانیفست کامل است.

بازگشتی‌ها

  • شیء

    جزئیات مانیفست.

getPackageDirectoryEntry()

Promise فقط پیش‌زمینه 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

DirectoryEntry را برای دایرکتوری بسته برمی‌گرداند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

بازگشتی‌ها

  • Promise<DirectoryEntry>

    Chrome نسخه ۱۲۲ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getPlatformInfo()

قول 
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

اطلاعات مربوط به پلاتفرم فعلی را برمی‌گرداند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (platformInfo: PlatformInfo) => void

بازگشتی‌ها

  • Promise<PlatformInfo>

    Chrome نسخه ۹۹ و بالاتر

    Promise که با اطلاعات مربوط به پلاتفرم فعلی حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getURL()

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

مسیر نسبی را در دایرکتوری نصب برنامه/ افزونه به نشانی وب کاملاً واجد شرایط تبدیل می‌کند.

پارامترها

  • مسیر

    رشته

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

بازگشتی‌ها

  • رشته

    نشانی وب کاملاً واجد شرایط منبع.

getVersion()

Chrome نسخه ۱۴۳ و بالاتر 
chrome.runtime.getVersion(): string

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

بازگشتی‌ها

  • رشته

    نسخه افزونه.

openOptionsPage()

قول 
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

درصورت امکان، صفحه گزینه‌های «افزونه» را باز کنید.

رفتار دقیق ممکن است به کلید options_ui یا options_page مانیفست شما یا آنچه Chrome در آن زمان پشتیبانی می‌کند بستگی داشته باشد. برای مثال، ممکن است صفحه در برگه جدیدی، در chrome://extensions، در یک برنامه باز شود، یا ممکن است فقط روی صفحه گزینه‌های باز تمرکز کند. این کار هرگز باعث بار کردن مجدد صفحه تماس‌گیرنده نمی‌شود.

اگر «افزونه» شما صفحه گزینه‌ها را اعلام نکند، یا Chrome به دلیل دیگری نتواند آن را ایجاد کند، فراخوان برگشتی lastError را تنظیم خواهد کرد.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۹ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

reload()

chrome.runtime.reload(): void

برنامه یا افزونه را مجدداً بار می‌کند. این روش در حالت کیوسک پشتیبانی نمی‌شود. برای حالت کیوسک، از روش chrome.runtime.restart() استفاده کنید.

requestUpdateCheck()

قول 
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

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

مهم: اکثر افزونه‌ها/برنامه‌ها نباید از این روش استفاده کنند، زیرا Chrome ازقبل هر چند ساعت یک‌بار بررسی‌های خودکار انجام می‌دهد و شما می‌توانید بدون نیاز به فراخوانی requestUpdateCheck، رویداد runtime.onUpdateAvailable را گوش دهید.

این روش فقط برای فراخوانی در شرایط بسیار محدود مناسب است، مثلاً اگر افزونه شما با سرویس پس‌زمینه‌ای صحبت می‌کند و سرویس پس‌زمینه‌ای تشخیص داده است که نسخه افزونه کارخواه بسیار قدیمی است و می‌خواهید از کاربر بخواهید به‌روزرسانی کند. اکثر موارد استفاده دیگر از requestUpdateCheck، مانند فراخوانی بی‌قیدوشرط آن براساس زمان‌سنج تکرارشونده، احتمالاً فقط باعث هدر رفتن منابع کارخواه، شبکه، و سرور می‌شود.

توجه: وقتی با فراخوانی متقابل تماس گرفته می‌شود، این عملکرد به‌جای برگرداندن شیء، دو ویژگی را به‌عنوان متغیرهای مستقل جداگانه که به فراخوانی متقابل ارسال شده‌اند برمی‌گرداند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: object) => void

    • نتیجه

      شیء

      Chrome نسخه ۱۰۹ و بالاتر

      شیء RequestUpdateCheckResult که وضعیت بررسی به‌روزرسانی و جزئیات نتیجه را درصورت دردسترس بودن به‌روزرسانی نگه می‌دارد

      • نتیجه بررسی به‌روزرسانی.

      • نسخه

        رشته اختیاری

        اگر به‌روزرسانی دردسترس باشد، این مورد حاوی نسخه به‌روزرسانی دردسترس است.

بازگشتی‌ها

  • Promise<object>

    Chrome نسخه ۱۰۹ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

restart()

chrome.runtime.restart(): void

وقتی برنامه در حالت کیوسک اجرا می‌شود، دستگاه ChromeOS را بازراه‌اندازی کنید. درغیراین‌صورت، هیچ عملیاتی انجام نمی‌شود.

restartAfterDelay()

Promise Chrome 53+ 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

وقتی برنامه در حالت کیوسک اجرا می‌شود، دستگاه ChromeOS را پس‌از ثانیه‌های مشخص‌شده بازراه‌اندازی کنید. اگر قبل‌از پایان زمان دوباره فراخوانی شود، راه‌اندازی مجدد به‌تأخیر خواهد افتاد. اگر با مقدار ۱- فراخوانی شود، بازراه‌اندازی لغو خواهد شد. در حالت غیرکیوسک، این عملیات انجام نمی‌شود. فقط اولین افزونه‌ای که این API را فراخوانی می‌کند مجاز است آن را به‌طور مکرر فراخوانی کند.

پارامترها

  • ثانیه

    شماره

    زمان انتظار به ثانیه قبل‌از بازراه‌اندازی دستگاه، یا ۱- برای لغو بازراه‌اندازی زمان‌بندی‌شده.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۹ و بالاتر

    Promise که وقتی درخواست بازراه‌اندازی باموفقیت زمان‌بندی مجدد شد، حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

sendMessage()

قول 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
): Promise<any>

یک پیام تکی به شنوندگان رویداد در افزونه شما یا افزونه/برنامه دیگری ارسال می‌کند. مشابه runtime.connect است اما فقط یک پیام تکی با پاسخ اختیاری ارسال می‌کند. اگر به افزونه شما ارسال شود، رویداد runtime.onMessage در هر قاب افزونه شما (به‌جز قاب فرستنده) یا runtime.onMessageExternal (اگر افزونه دیگری باشد) فعال خواهد شد. توجه داشته باشید که افزونه‌ها نمی‌توانند بااستفاده از این روش به دستورگان‌های محتوا پیام ارسال کنند. برای ارسال پیام به دستورگان‌های محتوا، از tabs.sendMessage استفاده کنید.

پارامترها

  • extensionId

    رشته اختیاری

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

  • پیام

    همه

    پیام برای ارسال. این پیام باید شیء JSON-ifiable باشد.

  • گزینه‌ها

    شیء اختیاری

    • includeTlsChannelId

      بولی اختیاری

      آیا شناسه کانال TLS برای فرایندهایی که به رویداد اتصال گوش می‌دهند به onMessageExternal منتقل خواهد شد یا نه.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۹۹ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    (response: any) => void

    • پاسخ

      همه

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

بازگشتی‌ها

  • Promise<any>

    Chrome نسخه ۹۹ و بالاتر

    پشتیبانی Promise برای زمینه‌های افزونه در Chrome 99 اضافه شد. هنگام برقراری ارتباط از صفحه وب به افزونه، وعده‌ها از Chrome 118 دردسترس هستند.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

sendNativeMessage()

قول 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
): Promise<any>

ارسال یک پیام به برنامه بومی. این روش به اجازه "nativeMessaging" نیاز دارد.

پارامترها

  • برنامه

    رشته

    نام میزبان پیام‌رسانی بومی یا جزئیات هدف.

  • پیام

    شیء

    پیامی که به میزبان پیام‌رسانی بومی ارسال خواهد شد.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۹۹ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    (response: any) => void

    • پاسخ

      همه

      پیام پاسخ ارسال‌شده توسط میزبان پیام‌رسانی بومی. اگر هنگام اتصال به میزبان پیام‌رسانی بومی خطایی رخ دهد، فراخوانی برگشتی بدون آرگومان فراخوانی می‌شود و runtime.lastError روی پیام خطا تنظیم می‌شود.

بازگشتی‌ها

  • Promise<any>

    Chrome نسخه ۹۹ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setUninstallURL()

قول 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

نشانی وبی را که باید پس‌از حذف نصب بازدید شود تنظیم می‌کند. ممکن است از این اطلاعات برای پاک‌سازی داده‌های سمت سرور، انجام تجزیه‌وتحلیل، و اجرای نظرسنجی‌ها استفاده شود. حداکثر ۱۰۲۳ نویسه.

پارامترها

  • نشانی وب

    رشته

    نشانی وبی که پس‌از حذف نصب افزونه باز می‌شود. این نشانی وب باید طرح http: ‎ یا https: ‎ داشته باشد. رشته خالی تنظیم کنید تا پس‌از حذف نصب، برگه جدیدی باز نشود.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۴۵ به بالا

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۹ و بالاتر

    Promise که وقتی نشانی وب حذف نصب تنظیم شود حل می‌شود. اگر نشانی وب ارائه‌شده نامعتبر باشد، وعده رد خواهد شد.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onBrowserUpdateAvailable

منسوخ‌شده
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

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

وقتی به‌روزرسانی Chrome دردسترس باشد اما به‌دلیل نیاز به بازراه‌اندازی مرورگر فوراً نصب نشود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

وقتی اتصالی از افزونه دیگری (توسط runtime.connect) یا از وب‌سایت قابل‌اتصال خارجی برقرار شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (port: Port) => void

onConnectNative

Chrome نسخه ۷۶ و بالاتر 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

وقتی اتصالی از برنامه بومی برقرار می‌شود، فعال می‌شود. این رویداد به اجازه "nativeMessaging" نیاز دارد. این ویژگی فقط در Chrome OS پشتیبانی می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (port: Port) => void

onEnabled

Chrome نسخه ۱۵۵ و بالاتر 
chrome.runtime.onEnabled.addListener(
  callback: function,
)

وقتی افزونه‌ای از حالت غیرفعال به حالت فعال می‌رود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onExtensionLoaded

Chrome نسخه ۱۵۷ و بالاتر 
chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

وقتی افزونه به مجموعه افزونه‌های فعال اضافه می‌شود، فعال می‌شود. این اتفاق ممکن است در چند سناریو رخ دهد: وقتی افزونه‌ای برای اولین‌بار نصب می‌شود، به نسخه جدیدی به‌روز می‌شود، پس‌از غیرفعال شدن دوباره فعال می‌شود، مجدداً بار می‌شود، درطول راه‌اندازی مرورگر بار می‌شود، یا وقتی مرورگر به نسخه جدیدی به‌روز می‌شود بار می‌شود.

پارامترها

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

هنگامی که افزونه برای اولین‌بار نصب می‌شود، زمانی که افزونه به نسخه جدید به‌روز می‌شود، و زمانی که Chrome به نسخه جدید به‌روز می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • id

        رشته اختیاری

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

      • previousVersion

        رشته اختیاری

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

      • دلیل ارسال این رویداد.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

وقتی پیامی از runtime.sendMessage یا tabs.sendMessage ارسال می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

    • پیام

      همه

    • فرستنده

      MessageSender

    • sendResponse

      عملکرد

      پارامتر sendResponse به‌صورت زیر است: 

      (response?: any) => void

      • پاسخ

        هر اختیاری

        پاسخی که باید به فرستنده پیام برگردانده شود.

    • returns

      boolean | Promise<any> | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

وقتی پیامی از افزونه دیگری ارسال می‌شود (توسط runtime.sendMessage) فعال می‌شود. نمی‌توان از آن در اسکریپت محتوا استفاده کرد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

    • پیام

      همه

    • فرستنده

      MessageSender

    • sendResponse

      عملکرد

      پارامتر sendResponse به‌صورت زیر است: 

      (response?: any) => void

      • پاسخ

        هر اختیاری

        پاسخی که باید به فرستنده پیام برگردانده شود.

    • returns

      boolean | Promise<any> | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

وقتی برنامه یا دستگاهی که برنامه در آن اجرا می‌شود باید بازراه‌اندازی شود، فعال می‌شود. برنامه باید در اولین فرصت مناسب همه پنجره‌هایش را ببندد تا بازراه‌اندازی انجام شود. اگر برنامه کاری انجام ندهد، پس‌از گذشت مهلت ارفاقی ۲۴ ساعته، بازراه‌اندازی اجباری انجام خواهد شد. درحال‌حاضر، این رویداد فقط برای برنامه‌های کیوسکی Chrome OS اجرا می‌شود.

پارامترها

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

درست قبل‌از بارگیری نشدن صفحه رویداد، به آن ارسال می‌شود. این کار به افزونه فرصت می‌دهد تا برخی‌از پاک‌سازی‌ها را انجام دهد. توجه داشته باشید که چون صفحه درحال تخلیه است، تکمیل هیچ‌یک از عملیات‌های ناهمگام شروع‌شده درحین رسیدگی به این رویداد تضمین نمی‌شود. اگر فعالیت بیشتری برای صفحه رویداد قبل‌از بارگیری نشدن آن رخ دهد، رویداد onSuspendCanceled ارسال خواهد شد و صفحه بارگیری نخواهد شد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

پس‌از onSuspend ارسال می‌شود تا نشان دهد که برنامه درنهایت بارگیری نخواهد شد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

وقتی به‌روزرسانی دردسترس باشد اما فوراً نصب نشود چون برنامه درحال‌حاضر درحال اجرا است، این رویداد فعال می‌شود. اگر کاری انجام ندهید، به‌روزرسانی دفعه بعد که صفحه پس‌زمینه بارگیری نشود نصب خواهد شد، اگر می‌خواهید زودتر نصب شود می‌توانید صریحاً chrome.runtime.reload()‎ را فراخوانی کنید. اگر افزونه شما از صفحه پس‌زمینه دائمی استفاده می‌کند، البته صفحه پس‌زمینه هرگز بارگیری نمی‌شود، بنابراین تا زمانی که chrome.runtime.reload()‎ را به‌طور دستی در پاسخ به این رویداد فراخوانی نکنید، به‌روزرسانی تا دفعه بعد که Chrome خودش بازراه‌اندازی شود نصب نخواهد شد. اگر هیچ گرداننده‌ای به این رویداد گوش نمی‌دهد و افزونه شما یک صفحه پس‌زمینه دائمی دارد، طوری رفتار می‌کند که گویی chrome.runtime.reload() در پاسخ به این رویداد فراخوانی می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      • نسخه

        رشته

        شماره نسخه به‌روزرسانی دردسترس.