chrome.runtime

توضیحات

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

نمای کلی

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

انتقال پیام
افزونه شما می‌تواند با استفاده از این متدها و رویدادها با زمینه‌های مختلف درون افزونه و همچنین با سایر افزونه‌ها ارتباط برقرار کند: connect() ، onConnect ، onConnectExternal ، sendMessage() ، onMessage و onMessageExternal . علاوه بر این، افزونه شما می‌تواند با استفاده از connectNative() و sendNativeMessage() پیام‌ها را به برنامه‌های بومی روی دستگاه کاربر ارسال کند.
دسترسی به متادیتای افزونه و پلتفرم
این متدها به شما امکان می‌دهند چندین قطعه خاص از فراداده‌ها (metadata) در مورد افزونه و پلتفرم را بازیابی کنید. متدهای این دسته شامل getManifest() و getPlatformInfo() می‌شوند.
مدیریت چرخه عمر افزونه‌ها و گزینه‌ها
این ویژگی‌ها به شما امکان می‌دهند برخی عملیات متا را روی افزونه انجام دهید و صفحه گزینه‌ها را نمایش دهید. متدها و رویدادهای این دسته شامل onInstalled ، onStartup ، openOptionsPage() ، reload() ، requestUpdateCheck() و setUninstallURL() هستند.
ابزارهای کمکی
این متدها کاربردهایی مانند تبدیل نمایش منابع داخلی به فرمت‌های خارجی را ارائه می‌دهند. متدهای این دسته شامل getURL() می‌شوند.
ابزارهای حالت کیوسک
این متدها فقط در ChromeOS در دسترس هستند و عمدتاً برای پشتیبانی از پیاده‌سازی‌های کیوسک وجود دارند. متدهای این دسته شامل restart و restartAfterDelay می‌شوند.

مجوزها

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

مانیفست

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

مانیفست.json:

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

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

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

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

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

مانیفست.json:

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

محتوای.js:

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

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

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

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

محتوای.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);
});

پس‌زمینه.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);
  }
});

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

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

پس‌زمینه.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

کروم ۱۱۴+

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

خواص

  • شناسه‌های زمینه

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

  • انواع زمینه

    نوع متن [] اختیاری

  • شناسه‌های سند

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

  • ریشه‌های سند

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

  • آدرس‌های سند

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

  • شناسه‌های قاب

    عدد[] اختیاری

  • ناشناس

    بولی اختیاری

  • شناسه‌های برگه

    عدد[] اختیاری

  • شناسه‌های پنجره

    عدد[] اختیاری

ContextType

کروم ۱۱۴+

شمارشی

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

"پاپ‌آپ"
نوع زمینه را به عنوان یک پنجره بازشو افزونه مشخص می‌کند

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

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

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

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

ExtensionContext

کروم ۱۱۴+

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

خواص

  • شناسه زمینه

    رشته

    یک شناسه منحصر به فرد برای این زمینه

  • نوع زمینه

    نوع متن

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

  • شناسه سند

    رشته اختیاری

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

  • سند مبدا

    رشته اختیاری

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

  • آدرس سند

    رشته اختیاری

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

  • شناسه قاب

    شماره

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

  • ناشناس

    بولی

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

  • شناسه برگه

    شماره

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

  • شناسه پنجره

    شماره

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

MessageSender

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

خواص

  • شناسه سند

    رشته اختیاری

    کروم ۱۰۶+

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

  • چرخه عمر سند

    رشته اختیاری

    کروم ۱۰۶+

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

  • شناسه قاب

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

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

  • شناسه

    رشته اختیاری

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

  • اپلیکیشن بومی

    رشته اختیاری

    کروم ۷۴+

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

  • منشأ

    رشته اختیاری

    کروم ۸۰+

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

  • تب

    تب اختیاری

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

  • شناسه کانال tls

    رشته اختیاری

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

  • آدرس اینترنتی

    رشته اختیاری

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

OnInstalledReason

کروم ۴۴+

دلیل اینکه این رویداد در حال ارسال است.

شمارشی

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

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

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

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

OnRestartRequiredReason

کروم ۴۴+

دلیل ارسال رویداد. 'app_update' زمانی استفاده می‌شود که راه‌اندازی مجدد به دلیل به‌روزرسانی برنامه به نسخه جدیدتر مورد نیاز باشد. 'os_update' زمانی استفاده می‌شود که راه‌اندازی مجدد به دلیل به‌روزرسانی مرورگر/سیستم‌عامل به نسخه جدیدتر مورد نیاز باشد. 'periodic' زمانی استفاده می‌شود که سیستم بیش از زمان روشن بودن مجاز تعیین‌شده در سیاست سازمانی اجرا شود.

شمارشی

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

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

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

PlatformArch

کروم ۴۴+

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

شمارشی

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

"بازوی ۶۴"
معماری پردازنده را به عنوان arm64 مشخص می‌کند.

"ایکس۸۶-۳۲"
معماری پردازنده را x86-32 مشخص می‌کند.

"ایکس۸۶-۶۴"
معماری پردازنده را x86-64 مشخص می‌کند.

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

"میپس۶۴"
معماری پردازنده را mips64 مشخص می‌کند.

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

PlatformInfo

یک شیء حاوی اطلاعاتی در مورد پلتفرم فعلی.

خواص

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

  • nacl_arch

    پلتفرمNaclArch اختیاری

    از نسخه ۱۴۹ کروم منسوخ شده است

    این ویژگی پس از حذف کامل Native Client منسوخ می‌شود.

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

  • سیستم عامل

    پلتفرم او اس

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

PlatformNaclArch

کروم ۴۴+ از کروم ۱۴۹ منسوخ شده است

این enum پس از حذف کامل Native Client منسوخ می‌شود.

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

شمارشی

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

"ایکس۸۶-۳۲"
معماری کلاینت بومی را x86-32 مشخص می‌کند.

"ایکس۸۶-۶۴"
معماری کلاینت بومی را x86-64 مشخص می‌کند.

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

"میپس۶۴"
معماری کلاینت بومی را mips64 مشخص می‌کند.

PlatformOs

کروم ۴۴+

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

شمارشی

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

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

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

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

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

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

Port

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

خواص

  • نام

    رشته

    نام پورت، همانطور که در فراخوانی runtime.connect مشخص شده است.

  • روشن/خاموش

    رویداد<functionvoidvoid>

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

    تابع onDisconnect.addListener به شکل زیر است: 

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

    • تماس برگشتی

      تابع

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

      (port: Port) => void

  • onMessage

    رویداد<functionvoidvoid>

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

    تابع onMessage.addListener به شکل زیر است: 

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

    • تماس برگشتی

      تابع

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

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

  • فرستنده

    فرستنده پیام اختیاری

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

  • قطع ارتباط

    باطل

    فوراً پورت را قطع کنید. فراخوانی disconnect() روی پورتی که از قبل قطع شده است، هیچ تاثیری ندارد. وقتی پورتی قطع می‌شود، هیچ رویداد جدیدی به این پورت ارسال نخواهد شد.

    تابع disconnect به شکل زیر است: 

    () => {...}

  • پستپیام

    باطل

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

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

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

    • پیام

      هر

      کروم ۵۲+

      پیامی که باید ارسال شود. این شیء باید با JSON سازگار باشد.

RequestUpdateCheckStatus

کروم ۴۴+

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

شمارشی

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

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

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

خواص

id

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

نوع

رشته

lastError

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

نوع

شیء

خواص

  • پیام

    رشته اختیاری

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

روش‌ها

connect()

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

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

پارامترها

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

    رشته اختیاری

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

  • اطلاعات اتصال

    شیء اختیاری

    • شامل شناسه کانال Tls

      بولی اختیاری

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

    • نام

      رشته اختیاری

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

بازگشت‌ها

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

connectNative()

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

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

پارامترها

  • کاربرد

    رشته

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

بازگشت‌ها

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

getBackgroundPage()

فقط Promise Foreground از کروم ۱۳۳ منسوخ شده است
 
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

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

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

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

    (backgroundPage?: Window) => void

    • صفحه پس‌زمینه

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

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

بازگشت‌ها

  • قول <پنجره | تعریف نشده>

    کروم ۹۹+

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

getManifest()

chrome.runtime.getManifest(): object

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

بازگشت‌ها

  • شیء

    جزئیات آشکار.

getPackageDirectoryEntry()

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

یک DirectoryEntry برای دایرکتوری پکیج برمی‌گرداند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

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

    (directoryEntry: DirectoryEntry) => void

    • ورودی دایرکتوری

      ورودی دایرکتوری

بازگشت‌ها

  • قول <ورودی دایرکتوری>

    کروم ۱۲۲+

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

getPlatformInfo()

وعده
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

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

پارامترها

بازگشت‌ها

  • کروم ۹۹+

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

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

getURL()

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

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

پارامترها

  • مسیر

    رشته

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

بازگشت‌ها

  • رشته

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

getVersion()

کروم ۱۴۳+
chrome.runtime.getVersion(): string

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

بازگشت‌ها

  • رشته

    نسخه افزونه.

openOptionsPage()

وعده
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

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

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

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

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

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۹+

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

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

وعده
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

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

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

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

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

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

    (result: object) => void

    • نتیجه

      شیء

      کروم ۱۰۹+

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

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

      • نسخه

        رشته اختیاری

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

بازگشت‌ها

  • قول دادن<object>

    کروم ۱۰۹+

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

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

قول کروم ۵۳+
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

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

پارامترها

  • ثانیه‌ها

    شماره

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

  • تماس برگشتی

    تابع اختیاری

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

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۹+

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

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

sendMessage()

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

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

پارامترها

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

    رشته اختیاری

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

  • پیام

    هر

    پیامی که باید ارسال شود. این پیام باید یک شیء با قابلیت پشتیبانی از JSON باشد.

  • گزینه‌ها

    شیء اختیاری

    • شامل شناسه کانال Tls

      بولی اختیاری

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

  • تماس برگشتی

    تابع اختیاری

    کروم ۹۹+

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

    (response: any) => void

    • پاسخ

      هر

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

بازگشت‌ها

  • قول بده<any>

    کروم ۹۹+

    پشتیبانی از Promise برای زمینه‌های افزونه در کروم ۹۹ اضافه شد. هنگام برقراری ارتباط از یک صفحه وب به یک افزونه، Promiseها از کروم ۱۱۸ در دسترس هستند.

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

sendNativeMessage()

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

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

پارامترها

  • کاربرد

    رشته

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

  • پیام

    شیء

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

  • تماس برگشتی

    تابع اختیاری

    کروم ۹۹+

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

    (response: any) => void

    • پاسخ

      هر

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

بازگشت‌ها

  • قول بده<any>

    کروم ۹۹+

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

setUninstallURL()

وعده
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

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

پارامترها

  • آدرس اینترنتی

    رشته

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

  • تماس برگشتی

    تابع اختیاری

    کروم ۴۵+

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

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۹+

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

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

رویدادها

onBrowserUpdateAvailable

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

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

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر 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.runtime.onConnectNative.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

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

    (port: Port) => void

onEnabled

در حال بررسی
chrome.runtime.onEnabled.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک افزونه از حالت غیرفعال به حالت فعال تغییر وضعیت دهد.

پارامترها

  • تماس برگشتی

    تابع

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

    () => void

onInstalled

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

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

پارامترها

  • تماس برگشتی

    تابع

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

    (details: object) => void

    • جزئیات

      شیء

      • شناسه

        رشته اختیاری

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

      • نسخه قبلی

        رشته اختیاری

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

      • دلیل

        دلیل نصب

        دلیل اینکه این رویداد در حال ارسال است.

onMessage

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

زمانی اجرا می‌شود که پیامی از runtime.sendMessage یا tabs.sendMessage ارسال شود.

پارامترها

  • تماس برگشتی

    تابع

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

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

    • پیام

      هر

    • فرستنده

      فرستنده پیام

    • ارسال پاسخ

      تابع

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

      (response?: any) => void

      • پاسخ

        هر اختیاری

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

    • بازده

      بولی | قول <any> | تعریف نشده

onMessageExternal

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

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

پارامترها

  • تماس برگشتی

    تابع

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

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

    • پیام

      هر

    • فرستنده

      فرستنده پیام

    • ارسال پاسخ

      تابع

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

      (response?: any) => void

      • پاسخ

        هر اختیاری

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

    • بازده

      بولی | قول <any> | تعریف نشده

onRestartRequired

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

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

پارامترها

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.runtime.reload() در پاسخ به این رویداد فراخوانی شده است.

پارامترها

  • تماس برگشتی

    تابع

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

    (details: object) => void

    • جزئیات

      شیء

      • نسخه

        رشته

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

،

توضیحات

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

نمای کلی

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

انتقال پیام
افزونه شما می‌تواند با استفاده از این متدها و رویدادها با زمینه‌های مختلف درون افزونه و همچنین با سایر افزونه‌ها ارتباط برقرار کند: connect() ، onConnect ، onConnectExternal ، sendMessage() ، onMessage و onMessageExternal . علاوه بر این، افزونه شما می‌تواند با استفاده از connectNative() و sendNativeMessage() پیام‌ها را به برنامه‌های بومی روی دستگاه کاربر ارسال کند.
دسترسی به متادیتای افزونه و پلتفرم
این متدها به شما امکان می‌دهند چندین قطعه خاص از فراداده‌ها (metadata) در مورد افزونه و پلتفرم را بازیابی کنید. متدهای این دسته شامل getManifest() و getPlatformInfo() می‌شوند.
مدیریت چرخه عمر افزونه‌ها و گزینه‌ها
این ویژگی‌ها به شما امکان می‌دهند برخی عملیات متا را روی افزونه انجام دهید و صفحه گزینه‌ها را نمایش دهید. متدها و رویدادهای این دسته شامل onInstalled ، onStartup ، openOptionsPage() ، reload() ، requestUpdateCheck() و setUninstallURL() هستند.
ابزارهای کمکی
این متدها کاربردهایی مانند تبدیل نمایش منابع داخلی به فرمت‌های خارجی را ارائه می‌دهند. متدهای این دسته شامل getURL() می‌شوند.
ابزارهای حالت کیوسک
این متدها فقط در ChromeOS در دسترس هستند و عمدتاً برای پشتیبانی از پیاده‌سازی‌های کیوسک وجود دارند. متدهای این دسته شامل restart و restartAfterDelay می‌شوند.

مجوزها

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

مانیفست

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

مانیفست.json:

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

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

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

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

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

مانیفست.json:

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

محتوای.js:

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

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

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

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

محتوای.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);
});

پس‌زمینه.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);
  }
});

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

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

پس‌زمینه.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

کروم ۱۱۴+

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

خواص

  • شناسه‌های زمینه

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

  • انواع زمینه

    نوع متن [] اختیاری

  • شناسه‌های سند

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

  • ریشه‌های سند

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

  • آدرس‌های سند

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

  • شناسه‌های قاب

    عدد[] اختیاری

  • ناشناس

    بولی اختیاری

  • شناسه‌های برگه

    عدد[] اختیاری

  • شناسه‌های پنجره

    عدد[] اختیاری

ContextType

کروم ۱۱۴+

شمارشی

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

"پاپ‌آپ"
نوع زمینه را به عنوان یک پنجره بازشو افزونه مشخص می‌کند

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

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

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

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

ExtensionContext

کروم ۱۱۴+

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

خواص

  • شناسه زمینه

    رشته

    یک شناسه منحصر به فرد برای این زمینه

  • نوع زمینه

    نوع متن

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

  • شناسه سند

    رشته اختیاری

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

  • سند مبدا

    رشته اختیاری

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

  • آدرس سند

    رشته اختیاری

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

  • شناسه قاب

    شماره

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

  • ناشناس

    بولی

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

  • شناسه برگه

    شماره

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

  • شناسه پنجره

    شماره

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

MessageSender

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

خواص

  • شناسه سند

    رشته اختیاری

    کروم ۱۰۶+

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

  • چرخه عمر سند

    رشته اختیاری

    کروم ۱۰۶+

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

  • شناسه قاب

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

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

  • شناسه

    رشته اختیاری

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

  • اپلیکیشن بومی

    رشته اختیاری

    کروم ۷۴+

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

  • منشأ

    رشته اختیاری

    کروم ۸۰+

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

  • تب

    تب اختیاری

    The tabs.Tab which opened the connection, if any. This property will only be present when the connection was opened from a tab (including content scripts), and only if the receiver is an extension, not an app.

  • tlsChannelId

    string optional

    The TLS channel ID of the page or frame that opened the connection, if requested by the extension, and if available.

  • آدرس اینترنتی

    string optional

    The URL of the page or frame that opened the connection. If the sender is in an iframe, it will be iframe's URL not the URL of the page which hosts it.

OnInstalledReason

Chrome 44+

The reason that this event is being dispatched.

شمارشی

"install"
Specifies the event reason as an installation.

"update"
Specifies the event reason as an extension update.

"chrome_update"
Specifies the event reason as a Chrome update.

"shared_module_update"
Specifies the event reason as an update to a shared module.

OnRestartRequiredReason

Chrome 44+

The reason that the event is being dispatched. 'app_update' is used when the restart is needed because the application is updated to a newer version. 'os_update' is used when the restart is needed because the browser/OS is updated to a newer version. 'periodic' is used when the system runs for more than the permitted uptime set in the enterprise policy.

شمارشی

"app_update"
Specifies the event reason as an update to the app.

"os_update"
Specifies the event reason as an update to the operating system.

"periodic"
Specifies the event reason as a periodic restart of the app.

PlatformArch

Chrome 44+

The machine's processor architecture.

شمارشی

"arm"
Specifies the processer architecture as arm.

"arm64"
Specifies the processer architecture as arm64.

"x86-32"
Specifies the processer architecture as x86-32.

"x86-64"
Specifies the processer architecture as x86-64.

"mips"
Specifies the processer architecture as mips.

"mips64"
Specifies the processer architecture as mips64.

"riscv64"
Specifies the processer architecture as riscv64.

PlatformInfo

An object containing information about the current platform.

خواص

  • قوس

    PlatformArch

    The machine's processor architecture.

  • nacl_arch

    PlatformNaclArch optional

    Deprecated since Chrome 149

    This attribute is deprecated following complete removal of Native Client.

    The native client architecture. This may be different from arch on some platforms.

  • سیستم عامل

    PlatformOs

    The operating system Chrome is running on.

PlatformNaclArch

Chrome 44+ Deprecated since Chrome 149

This enum is deprecated following complete removal of Native Client.

The native client architecture. This may be different from arch on some platforms.

شمارشی

"arm"
Specifies the native client architecture as arm.

"x86-32"
Specifies the native client architecture as x86-32.

"x86-64"
Specifies the native client architecture as x86-64.

"mips"
Specifies the native client architecture as mips.

"mips64"
Specifies the native client architecture as mips64.

PlatformOs

Chrome 44+

The operating system Chrome is running on.

شمارشی

"mac"
Specifies the MacOS operating system.

"win"
Specifies the Windows operating system.

"android"
Specifies the Android operating system.

"cros"
Specifies the Chrome operating system.

"linux"
Specifies the Linux operating system.

"openbsd"
Specifies the OpenBSD operating system.

Port

An object which allows two way communication with other pages. See Long-lived connections for more information.

خواص

  • نام

    رشته

    The name of the port, as specified in the call to runtime.connect .

  • onDisconnect

    Event<functionvoidvoid>

    Fired when the port is disconnected from the other end(s). runtime.lastError may be set if the port was disconnected by an error. If the port is closed via disconnect , then this event is only fired on the other end. This event is fired at most once (see also Port lifetime ).

    The onDisconnect.addListener function looks like: 

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

    • تماس برگشتی

      تابع

      The callback parameter looks like: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    This event is fired when postMessage is called by the other end of the port.

    The onMessage.addListener function looks like: 

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

    • تماس برگشتی

      تابع

      The callback parameter looks like: 

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

  • فرستنده

    MessageSender optional

    This property will only be present on ports passed to onConnect / onConnectExternal / onConnectNative listeners.

  • قطع ارتباط

    باطل

    Immediately disconnect the port. Calling disconnect() on an already-disconnected port has no effect. When a port is disconnected, no new events will be dispatched to this port.

    The disconnect function looks like: 

    () => {...}

  • postMessage

    باطل

    Send a message to the other end of the port. If the port is disconnected, an error is thrown.

    The postMessage function looks like: 

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

    • پیام

      هر

      Chrome 52+

      The message to send. This object should be JSON-ifiable.

RequestUpdateCheckStatus

Chrome 44+

Result of the update check.

شمارشی

"throttled"
Specifies that the status check has been throttled. This can occur after repeated checks within a short amount of time.

"no_update"
Specifies that there are no available updates to install.

"update_available"
Specifies that there is an available update to install.

خواص

id

The ID of the extension/app.

نوع

رشته

lastError

Populated with an error message if calling an API function fails; otherwise undefined. This is only defined within the scope of that function's callback. If an error is produced, but runtime.lastError is not accessed within the callback, a message is logged to the console listing the API function that produced the error. API functions that return promises do not set this property.

نوع

شیء

خواص

  • پیام

    string optional

    Details about the error which occurred.

روش‌ها

connect()

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

Attempts to connect listeners within an extension (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and web messaging . Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via tabs.connect .

Parameters

  • extensionId

    string optional

    The ID of the extension to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for web messaging .

  • connectInfo

    object optional

    • includeTlsChannelId

      boolean optional

      Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.

    • نام

      string optional

      Will be passed into onConnect for processes that are listening for the connection event.

بازگشت‌ها

  • Port through which messages can be sent and received. The port's onDisconnect event is fired if the extension does not exist.

connectNative()

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

Connects to a native application in the host machine. This method requires the "nativeMessaging" permission. See Native Messaging for more information.

Parameters

  • کاربرد

    رشته

    The name of the registered application to connect to.

بازگشت‌ها

  • Port through which messages can be sent and received with the application

getBackgroundPage()

فقط Promise Foreground از کروم ۱۳۳ منسوخ شده است
 
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

Background pages do not exist in MV3 extensions.

Retrieves the JavaScript 'window' object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set.

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (backgroundPage?: Window) => void

    • صفحه پس‌زمینه

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

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

بازگشت‌ها

  • Promise<Window | undefined>

    Chrome 99+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getManifest()

chrome.runtime.getManifest(): object

Returns details about the app or extension from the manifest. The object returned is a serialization of the full manifest file .

بازگشت‌ها

  • شیء

    The manifest details.

getPackageDirectoryEntry()

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

Returns a DirectoryEntry for the package directory.

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (directoryEntry: DirectoryEntry) => void

    • ورودی دایرکتوری

      ورودی دایرکتوری

بازگشت‌ها

  • Promise<DirectoryEntry>

    Chrome 122+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getPlatformInfo()

وعده
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

Returns information about the current platform.

Parameters

بازگشت‌ها

  • Promise< PlatformInfo >

    Chrome 99+

    Promise that resolves with information about the current platform.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getURL()

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

Converts a relative path within an app/extension install directory to a fully-qualified URL.

Parameters

  • مسیر

    رشته

    A path to a resource within an app/extension expressed relative to its install directory.

بازگشت‌ها

  • رشته

    The fully-qualified URL to the resource.

getVersion()

Chrome 143+
chrome.runtime.getVersion(): string

Returns the extension's version as declared in the manifest.

بازگشت‌ها

  • رشته

    The extension's version.

openOptionsPage()

وعده
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

Open your Extension's options page, if possible.

The precise behavior may depend on your manifest's options_ui or options_page key, or what Chrome happens to support at the time. For example, the page may be opened in a new tab, within chrome://extensions, within an App, or it may just focus an open options page. It will never cause the caller page to reload.

If your Extension does not declare an options page, or Chrome failed to create one for some other reason, the callback will set lastError .

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 99+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

reload()

chrome.runtime.reload(): void

Reloads the app or extension. This method is not supported in kiosk mode. For kiosk mode, use chrome.runtime.restart() method.

requestUpdateCheck()

وعده
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

Requests an immediate update check be done for this app/extension.

Important : Most extensions/apps should not use this method, since Chrome already does automatic checks every few hours, and you can listen for the runtime.onUpdateAvailable event without needing to call requestUpdateCheck.

This method is only appropriate to call in very limited circumstances, such as if your extension talks to a backend service, and the backend service has determined that the client extension version is very far out of date and you'd like to prompt a user to update. Most other uses of requestUpdateCheck, such as calling it unconditionally based on a repeating timer, probably only serve to waste client, network, and server resources.

Note: When called with a callback, instead of returning an object this function will return the two properties as separate arguments passed to the callback.

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (result: object) => void

    • نتیجه

      شیء

      Chrome 109+

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

      • Result of the update check.

      • نسخه

        string optional

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

بازگشت‌ها

  • Promise<object>

    Chrome 109+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

restart()

chrome.runtime.restart(): void

Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's no-op.

restartAfterDelay()

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

Restart the ChromeOS device when the app runs in kiosk mode after the given seconds. If called again before the time ends, the reboot will be delayed. If called with a value of -1, the reboot will be cancelled. It's a no-op in non-kiosk mode. It's only allowed to be called repeatedly by the first extension to invoke this API.

Parameters

  • ثانیه‌ها

    شماره

    Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot.

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 99+

    Promise that resolves when a restart request was successfully rescheduled.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

sendMessage()

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

Sends a single message to event listeners within your extension or a different extension/app. Similar to runtime.connect but only sends a single message, with an optional response. If sending to your extension, the runtime.onMessage event will be fired in every frame of your extension (except for the sender's frame), or runtime.onMessageExternal , if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use tabs.sendMessage .

Parameters

  • extensionId

    string optional

    The ID of the extension to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for web messaging .

  • پیام

    هر

    The message to send. This message should be a JSON-ifiable object.

  • گزینه‌ها

    object optional

    • includeTlsChannelId

      boolean optional

      Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.

  • تماس برگشتی

    function optional

    Chrome 99+

    The callback parameter looks like: 

    (response: any) => void

    • پاسخ

      هر

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

بازگشت‌ها

  • Promise<any>

    Chrome 99+

    Promise support was added for extension contexts in Chrome 99. When communicating from a web page to an extension, promises are available from Chrome 118.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

sendNativeMessage()

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

Send a single message to a native application. This method requires the "nativeMessaging" permission.

Parameters

  • کاربرد

    رشته

    The name of the native messaging host, or target details.

  • پیام

    شیء

    The message that will be passed to the native messaging host.

  • تماس برگشتی

    function optional

    Chrome 99+

    The callback parameter looks like: 

    (response: any) => void

    • پاسخ

      هر

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

بازگشت‌ها

  • Promise<any>

    Chrome 99+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setUninstallURL()

وعده
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 1023 characters.

Parameters

  • آدرس اینترنتی

    رشته

    URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation.

  • تماس برگشتی

    function optional

    کروم ۴۵+

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 99+

    Promise that resolves when the uninstall URL is set. If the given URL is invalid, the promise will be rejected.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

رویدادها

onBrowserUpdateAvailable

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

Please use runtime.onRestartRequired .

Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onConnect

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

Fired when a connection is made from either an extension process or a content script (by runtime.connect ).

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (port: Port) => void

onConnectExternal

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

Fired when a connection is made from another extension (by runtime.connect ), or from an externally connectable web site.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (port: Port) => void

onConnectNative

Chrome 76+
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Fired when a connection is made from a native application. This event requires the "nativeMessaging" permission. It is only supported on Chrome OS.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (port: Port) => void

onEnabled

در حال بررسی
chrome.runtime.onEnabled.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک افزونه از حالت غیرفعال به حالت فعال تغییر وضعیت دهد.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onInstalled

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

Fired when the extension is first installed, when the extension is updated to a new version, and when Chrome is updated to a new version.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه

        string optional

        Indicates the ID of the imported shared module extension which updated. This is present only if 'reason' is 'shared_module_update'.

      • previousVersion

        string optional

        Indicates the previous version of the extension, which has just been updated. This is present only if 'reason' is 'update'.

      • The reason that this event is being dispatched.

onMessage

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

Fired when a message is sent from either runtime.sendMessage or tabs.sendMessage .

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

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

    • پیام

      هر

    • فرستنده

      MessageSender

    • sendResponse

      تابع

      The sendResponse parameter looks like: 

      (response?: any) => void

      • پاسخ

        any optional

        The response to return to the message sender.

    • بازده

      boolean | Promise<any> | undefined

onMessageExternal

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

Fired when a message is sent from another extension (by runtime.sendMessage ). Cannot be used in a content script.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

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

    • پیام

      هر

    • فرستنده

      MessageSender

    • sendResponse

      تابع

      The sendResponse parameter looks like: 

      (response?: any) => void

      • پاسخ

        any optional

        The response to return to the message sender.

    • بازده

      boolean | Promise<any> | undefined

onRestartRequired

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

Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps.

Parameters

onStartup

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

Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started, even if this extension is operating in 'split' incognito mode.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onSuspend

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

Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won't be unloaded.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onSuspendCanceled

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

Sent after onSuspend to indicate that the app won't be unloaded after all.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onUpdateAvailable

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

Fired when an update is available, but isn't installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call chrome.runtime.reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call chrome.runtime.reload() manually in response to this event the update will not get installed until the next time Chrome itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if chrome.runtime.reload() is called in response to this event.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • نسخه

        رشته

        The version number of the available update.

،

توضیحات

Use the chrome.runtime API to retrieve the service worker, return details about the manifest, and listen for and respond to events in the extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.

نمای کلی

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

Message passing
Your extension can communicate with different contexts within your extension and also with other extensions using these methods and events: connect() , onConnect , onConnectExternal , sendMessage() , onMessage and onMessageExternal . In addition, your extension can pass messages to native applications on the user's device using connectNative() and sendNativeMessage() .
Accessing extension and platform metadata
These methods let you retrieve several specific pieces of metadata about the extension and the platform. Methods in this category include getManifest() , and getPlatformInfo() .
Managing extension lifecycle and options
These properties let you perform some meta-operations on the extension, and display the options page. Methods and events in this category include onInstalled , onStartup , openOptionsPage() , reload() , requestUpdateCheck() , and setUninstallURL() .
Helper utilities
These methods provide utility such as the conversion of internal resource representations to external formats. Methods in this category include getURL() .
Kiosk mode utilities
این متدها فقط در ChromeOS در دسترس هستند و عمدتاً برای پشتیبانی از پیاده‌سازی‌های کیوسک وجود دارند. متدهای این دسته شامل restart و restartAfterDelay می‌شوند.

مجوزها

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

مانیفست

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

manifest.json:

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

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

Add an image to a web page

For a web page to access an asset hosted on another domain, it must specify the resource's full URL (eg <img src="https://example.com/logo.png"> ). The same is true to include an extension asset on a web page. The two differences are that the extension's assets must be exposed as web accessible resources and that typically content scripts are responsible for injecting extension assets.

In this example, the extension will add logo.png to the page that the content script is being injected into by using runtime.getURL() to create a fully-qualified URL. But first, the asset must be declared as a web accessible resource in the manifest.

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);
}

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

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

در این مثال، اسکریپت محتوا برای مقداردهی اولیه رابط کاربری خود به برخی داده‌ها از سرویس ورکر افزونه نیاز دارد. برای دریافت این داده‌ها، یک پیام 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);
  }
});

Gather feedback on uninstall

Many extensions use post-uninstall surveys to understand how the extension could better serve its users and improve retention. The following example shows how to add this functionality.

background.js:

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

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

See the Manifest V3 - Web Accessible Resources demo for more Runtime API examples.

انواع

ContextFilter

Chrome 114+

A filter to match against certain extension contexts. Matching contexts must match all specified filters; any filter that is not specified matches all available contexts. Thus, a filter of `{}` will match all available contexts.

خواص

  • contextIds

    string[] optional

  • contextTypes

    ContextType [] optional

  • documentIds

    string[] optional

  • documentOrigins

    string[] optional

  • documentUrls

    string[] optional

  • frameIds

    number[] optional

  • ناشناس

    boolean optional

  • tabIds

    number[] optional

  • windowIds

    number[] optional

ContextType

Chrome 114+

شمارشی

"TAB"
Specifies the context type as a tab

"POPUP"
Specifies the context type as an extension popup window

"BACKGROUND"
Specifies the context type as a service worker.

"OFFSCREEN_DOCUMENT"
Specifies the context type as an offscreen document.

"SIDE_PANEL"
Specifies the context type as a side panel.

"DEVELOPER_TOOLS"
Specifies the context type as developer tools.

ExtensionContext

Chrome 114+

A context hosting extension content.

خواص

  • contextId

    رشته

    A unique identifier for this context

  • contextType

    ContextType

    The type of context this corresponds to.

  • documentId

    string optional

    A UUID for the document associated with this context, or undefined if this context is hosted not in a document.

  • documentOrigin

    string optional

    The origin of the document associated with this context, or undefined if the context is not hosted in a document.

  • documentUrl

    string optional

    The URL of the document associated with this context, or undefined if the context is not hosted in a document.

  • frameId

    شماره

    The ID of the frame for this context, or -1 if this context is not hosted in a frame.

  • ناشناس

    بولی

    Whether the context is associated with an incognito profile.

  • tabId

    شماره

    The ID of the tab for this context, or -1 if this context is not hosted in a tab.

  • windowId

    شماره

    The ID of the window for this context, or -1 if this context is not hosted in a window.

MessageSender

An object containing information about the script context that sent a message or request.

خواص

  • documentId

    string optional

    Chrome 106+

    A UUID of the document that opened the connection.

  • documentLifecycle

    string optional

    Chrome 106+

    The lifecycle the document that opened the connection is in at the time the port was created. Note that the lifecycle state of the document may have changed since port creation.

  • frameId

    number optional

    The frame that opened the connection. 0 for top-level frames, positive for child frames. This will only be set when tab is set.

  • شناسه

    string optional

    The ID of the extension that opened the connection, if any.

  • nativeApplication

    string optional

    Chrome 74+

    The name of the native application that opened the connection, if any.

  • منشأ

    string optional

    Chrome 80+

    The origin of the page or frame that opened the connection. It can vary from the url property (eg, about:blank) or can be opaque (eg, sandboxed iframes). This is useful for identifying if the origin can be trusted if we can't immediately tell from the URL.

  • تب

    Tab optional

    The tabs.Tab which opened the connection, if any. This property will only be present when the connection was opened from a tab (including content scripts), and only if the receiver is an extension, not an app.

  • tlsChannelId

    string optional

    The TLS channel ID of the page or frame that opened the connection, if requested by the extension, and if available.

  • آدرس اینترنتی

    string optional

    The URL of the page or frame that opened the connection. If the sender is in an iframe, it will be iframe's URL not the URL of the page which hosts it.

OnInstalledReason

Chrome 44+

The reason that this event is being dispatched.

شمارشی

"install"
Specifies the event reason as an installation.

"update"
Specifies the event reason as an extension update.

"chrome_update"
Specifies the event reason as a Chrome update.

"shared_module_update"
Specifies the event reason as an update to a shared module.

OnRestartRequiredReason

Chrome 44+

The reason that the event is being dispatched. 'app_update' is used when the restart is needed because the application is updated to a newer version. 'os_update' is used when the restart is needed because the browser/OS is updated to a newer version. 'periodic' is used when the system runs for more than the permitted uptime set in the enterprise policy.

شمارشی

"app_update"
Specifies the event reason as an update to the app.

"os_update"
Specifies the event reason as an update to the operating system.

"periodic"
Specifies the event reason as a periodic restart of the app.

PlatformArch

Chrome 44+

The machine's processor architecture.

شمارشی

"arm"
Specifies the processer architecture as arm.

"arm64"
Specifies the processer architecture as arm64.

"x86-32"
Specifies the processer architecture as x86-32.

"x86-64"
Specifies the processer architecture as x86-64.

"mips"
Specifies the processer architecture as mips.

"mips64"
Specifies the processer architecture as mips64.

"riscv64"
Specifies the processer architecture as riscv64.

PlatformInfo

An object containing information about the current platform.

خواص

  • قوس

    PlatformArch

    The machine's processor architecture.

  • nacl_arch

    PlatformNaclArch optional

    Deprecated since Chrome 149

    This attribute is deprecated following complete removal of Native Client.

    The native client architecture. This may be different from arch on some platforms.

  • سیستم عامل

    PlatformOs

    The operating system Chrome is running on.

PlatformNaclArch

Chrome 44+ Deprecated since Chrome 149

This enum is deprecated following complete removal of Native Client.

The native client architecture. This may be different from arch on some platforms.

شمارشی

"arm"
Specifies the native client architecture as arm.

"x86-32"
Specifies the native client architecture as x86-32.

"x86-64"
Specifies the native client architecture as x86-64.

"mips"
Specifies the native client architecture as mips.

"mips64"
Specifies the native client architecture as mips64.

PlatformOs

Chrome 44+

The operating system Chrome is running on.

شمارشی

"mac"
Specifies the MacOS operating system.

"win"
Specifies the Windows operating system.

"android"
Specifies the Android operating system.

"cros"
Specifies the Chrome operating system.

"linux"
Specifies the Linux operating system.

"openbsd"
Specifies the OpenBSD operating system.

Port

An object which allows two way communication with other pages. See Long-lived connections for more information.

خواص

  • نام

    رشته

    The name of the port, as specified in the call to runtime.connect .

  • onDisconnect

    Event<functionvoidvoid>

    Fired when the port is disconnected from the other end(s). runtime.lastError may be set if the port was disconnected by an error. If the port is closed via disconnect , then this event is only fired on the other end. This event is fired at most once (see also Port lifetime ).

    The onDisconnect.addListener function looks like: 

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

    • تماس برگشتی

      تابع

      The callback parameter looks like: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    This event is fired when postMessage is called by the other end of the port.

    The onMessage.addListener function looks like: 

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

    • تماس برگشتی

      تابع

      The callback parameter looks like: 

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

  • فرستنده

    MessageSender optional

    This property will only be present on ports passed to onConnect / onConnectExternal / onConnectNative listeners.

  • قطع ارتباط

    باطل

    Immediately disconnect the port. Calling disconnect() on an already-disconnected port has no effect. When a port is disconnected, no new events will be dispatched to this port.

    The disconnect function looks like: 

    () => {...}

  • postMessage

    باطل

    Send a message to the other end of the port. If the port is disconnected, an error is thrown.

    The postMessage function looks like: 

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

    • پیام

      هر

      Chrome 52+

      The message to send. This object should be JSON-ifiable.

RequestUpdateCheckStatus

Chrome 44+

Result of the update check.

شمارشی

"throttled"
Specifies that the status check has been throttled. This can occur after repeated checks within a short amount of time.

"no_update"
Specifies that there are no available updates to install.

"update_available"
Specifies that there is an available update to install.

خواص

id

The ID of the extension/app.

نوع

رشته

lastError

Populated with an error message if calling an API function fails; otherwise undefined. This is only defined within the scope of that function's callback. If an error is produced, but runtime.lastError is not accessed within the callback, a message is logged to the console listing the API function that produced the error. API functions that return promises do not set this property.

نوع

شیء

خواص

  • پیام

    string optional

    Details about the error which occurred.

روش‌ها

connect()

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

Attempts to connect listeners within an extension (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and web messaging . Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via tabs.connect .

Parameters

  • extensionId

    string optional

    The ID of the extension to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for web messaging .

  • connectInfo

    object optional

    • includeTlsChannelId

      boolean optional

      Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.

    • نام

      string optional

      Will be passed into onConnect for processes that are listening for the connection event.

بازگشت‌ها

  • Port through which messages can be sent and received. The port's onDisconnect event is fired if the extension does not exist.

connectNative()

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

Connects to a native application in the host machine. This method requires the "nativeMessaging" permission. See Native Messaging for more information.

Parameters

  • کاربرد

    رشته

    The name of the registered application to connect to.

بازگشت‌ها

  • Port through which messages can be sent and received with the application

getBackgroundPage()

فقط Promise Foreground از کروم ۱۳۳ منسوخ شده است
 
chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

Background pages do not exist in MV3 extensions.

Retrieves the JavaScript 'window' object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set.

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (backgroundPage?: Window) => void

    • صفحه پس‌زمینه

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

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

بازگشت‌ها

  • Promise<Window | undefined>

    Chrome 99+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getManifest()

chrome.runtime.getManifest(): object

Returns details about the app or extension from the manifest. The object returned is a serialization of the full manifest file .

بازگشت‌ها

  • شیء

    The manifest details.

getPackageDirectoryEntry()

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

Returns a DirectoryEntry for the package directory.

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (directoryEntry: DirectoryEntry) => void

    • ورودی دایرکتوری

      ورودی دایرکتوری

بازگشت‌ها

  • Promise<DirectoryEntry>

    Chrome 122+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getPlatformInfo()

وعده
chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

Returns information about the current platform.

Parameters

بازگشت‌ها

  • Promise< PlatformInfo >

    Chrome 99+

    Promise that resolves with information about the current platform.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getURL()

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

Converts a relative path within an app/extension install directory to a fully-qualified URL.

Parameters

  • مسیر

    رشته

    A path to a resource within an app/extension expressed relative to its install directory.

بازگشت‌ها

  • رشته

    The fully-qualified URL to the resource.

getVersion()

Chrome 143+
chrome.runtime.getVersion(): string

Returns the extension's version as declared in the manifest.

بازگشت‌ها

  • رشته

    The extension's version.

openOptionsPage()

وعده
chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

Open your Extension's options page, if possible.

The precise behavior may depend on your manifest's options_ui or options_page key, or what Chrome happens to support at the time. For example, the page may be opened in a new tab, within chrome://extensions, within an App, or it may just focus an open options page. It will never cause the caller page to reload.

If your Extension does not declare an options page, or Chrome failed to create one for some other reason, the callback will set lastError .

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 99+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

reload()

chrome.runtime.reload(): void

Reloads the app or extension. This method is not supported in kiosk mode. For kiosk mode, use chrome.runtime.restart() method.

requestUpdateCheck()

وعده
chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

Requests an immediate update check be done for this app/extension.

Important : Most extensions/apps should not use this method, since Chrome already does automatic checks every few hours, and you can listen for the runtime.onUpdateAvailable event without needing to call requestUpdateCheck.

This method is only appropriate to call in very limited circumstances, such as if your extension talks to a backend service, and the backend service has determined that the client extension version is very far out of date and you'd like to prompt a user to update. Most other uses of requestUpdateCheck, such as calling it unconditionally based on a repeating timer, probably only serve to waste client, network, and server resources.

Note: When called with a callback, instead of returning an object this function will return the two properties as separate arguments passed to the callback.

Parameters

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    (result: object) => void

    • نتیجه

      شیء

      Chrome 109+

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

      • Result of the update check.

      • نسخه

        string optional

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

بازگشت‌ها

  • Promise<object>

    Chrome 109+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

restart()

chrome.runtime.restart(): void

Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's no-op.

restartAfterDelay()

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

Restart the ChromeOS device when the app runs in kiosk mode after the given seconds. If called again before the time ends, the reboot will be delayed. If called with a value of -1, the reboot will be cancelled. It's a no-op in non-kiosk mode. It's only allowed to be called repeatedly by the first extension to invoke this API.

Parameters

  • ثانیه‌ها

    شماره

    Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot.

  • تماس برگشتی

    function optional

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 99+

    Promise that resolves when a restart request was successfully rescheduled.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

sendMessage()

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

Sends a single message to event listeners within your extension or a different extension/app. Similar to runtime.connect but only sends a single message, with an optional response. If sending to your extension, the runtime.onMessage event will be fired in every frame of your extension (except for the sender's frame), or runtime.onMessageExternal , if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use tabs.sendMessage .

Parameters

  • extensionId

    string optional

    The ID of the extension to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for web messaging .

  • پیام

    هر

    The message to send. This message should be a JSON-ifiable object.

  • گزینه‌ها

    object optional

    • includeTlsChannelId

      boolean optional

      Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.

  • تماس برگشتی

    function optional

    Chrome 99+

    The callback parameter looks like: 

    (response: any) => void

    • پاسخ

      هر

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

بازگشت‌ها

  • Promise<any>

    Chrome 99+

    Promise support was added for extension contexts in Chrome 99. When communicating from a web page to an extension, promises are available from Chrome 118.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

sendNativeMessage()

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

Send a single message to a native application. This method requires the "nativeMessaging" permission.

Parameters

  • کاربرد

    رشته

    The name of the native messaging host, or target details.

  • پیام

    شیء

    The message that will be passed to the native messaging host.

  • تماس برگشتی

    function optional

    Chrome 99+

    The callback parameter looks like: 

    (response: any) => void

    • پاسخ

      هر

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

بازگشت‌ها

  • Promise<any>

    Chrome 99+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setUninstallURL()

وعده
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 1023 characters.

Parameters

  • آدرس اینترنتی

    رشته

    URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation.

  • تماس برگشتی

    function optional

    کروم ۴۵+

    The callback parameter looks like: 

    () => void

بازگشت‌ها

  • Promise<void>

    Chrome 99+

    Promise that resolves when the uninstall URL is set. If the given URL is invalid, the promise will be rejected.

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

رویدادها

onBrowserUpdateAvailable

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

Please use runtime.onRestartRequired .

Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onConnect

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

Fired when a connection is made from either an extension process or a content script (by runtime.connect ).

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (port: Port) => void

onConnectExternal

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

Fired when a connection is made from another extension (by runtime.connect ), or from an externally connectable web site.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (port: Port) => void

onConnectNative

Chrome 76+
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Fired when a connection is made from a native application. This event requires the "nativeMessaging" permission. It is only supported on Chrome OS.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (port: Port) => void

onEnabled

در حال بررسی
chrome.runtime.onEnabled.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک افزونه از حالت غیرفعال به حالت فعال تغییر وضعیت دهد.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onInstalled

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

Fired when the extension is first installed, when the extension is updated to a new version, and when Chrome is updated to a new version.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • شناسه

        string optional

        Indicates the ID of the imported shared module extension which updated. This is present only if 'reason' is 'shared_module_update'.

      • previousVersion

        string optional

        Indicates the previous version of the extension, which has just been updated. This is present only if 'reason' is 'update'.

      • The reason that this event is being dispatched.

onMessage

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

Fired when a message is sent from either runtime.sendMessage or tabs.sendMessage .

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

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

    • پیام

      هر

    • فرستنده

      MessageSender

    • sendResponse

      تابع

      The sendResponse parameter looks like: 

      (response?: any) => void

      • پاسخ

        any optional

        The response to return to the message sender.

    • بازده

      boolean | Promise<any> | undefined

onMessageExternal

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

Fired when a message is sent from another extension (by runtime.sendMessage ). Cannot be used in a content script.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

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

    • پیام

      هر

    • فرستنده

      MessageSender

    • sendResponse

      تابع

      The sendResponse parameter looks like: 

      (response?: any) => void

      • پاسخ

        any optional

        The response to return to the message sender.

    • بازده

      boolean | Promise<any> | undefined

onRestartRequired

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

Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps.

Parameters

onStartup

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

Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started, even if this extension is operating in 'split' incognito mode.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onSuspend

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

Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won't be unloaded.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onSuspendCanceled

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

Sent after onSuspend to indicate that the app won't be unloaded after all.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    () => void

onUpdateAvailable

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

Fired when an update is available, but isn't installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call chrome.runtime.reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call chrome.runtime.reload() manually in response to this event the update will not get installed until the next time Chrome itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if chrome.runtime.reload() is called in response to this event.

Parameters

  • تماس برگشتی

    تابع

    The callback parameter looks like: 

    (details: object) => void

    • جزئیات

      شیء

      • نسخه

        رشته

        The version number of the available update.