chrome.runtime

توضیحات

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

اکثر اعضای این API به هیچ مجوزی نیاز ندارند . این مجوز برای connectNative() ، sendNativeMessage() و onNativeConnect مورد نیاز است.

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

manifest.json:

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

مفاهیم و کاربرد

Runtime API روش هایی را برای پشتیبانی از تعدادی از مناطقی که افزونه های شما می توانند استفاده کنند ارائه می دهد:

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

هنگامی که یک برنامه افزودنی بدون بسته بندی مجدد بارگیری می شود، این به عنوان یک به روز رسانی در نظر گرفته می شود. این بدان معنی است که رویداد chrome.runtime.onInstalled با دلیل "update" فعال می شود. این شامل زمانی است که برنامه افزودنی با chrome.runtime.reload() بارگذاری مجدد شود.

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

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

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

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);
}
داده ها را از یک اسکریپت محتوا به کارمند سرویس ارسال کنید

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

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

service-worker.js:

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

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});
در مورد حذف بازخورد جمع آوری کنید

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

background.js:

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

برای نمونه‌های بیشتر Runtime API، نسخه ی نمایشی Manifest V3 - Web Accessible Resources را ببینید.

انواع
ContextFilter
Chrome 114+

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

خواص
  • contextIds

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

  • انواع متن

    ContextType [] اختیاری است

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

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

  • documentOrigins

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

  • documentUrls

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

  • FrameIds

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

  • ناشناس

    بولی اختیاری

  • tabIds

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

  • windowIds

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

ContextType
Chrome 114+
Enum

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

"POPUP"
نوع زمینه را به عنوان یک پنجره بازشو پسوند مشخص می کند

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

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

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

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

ExtensionContext
Chrome 114+

محتوای پسوند میزبانی متن.

خواص
  • contextId

    رشته

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

  • contextType

    ContextType

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

  • شناسه سند

    رشته اختیاری

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

  • documentOrigin

    رشته اختیاری

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

  • documentUrl

    رشته اختیاری

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

  • frameId

    شماره

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

  • ناشناس

    بولی

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

  • tabId

    شماره

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

  • شناسه پنجره

    شماره

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

MessageSender

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

خواص
  • شناسه سند

    رشته اختیاری

    Chrome 106+

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

  • documentLifecycle

    رشته اختیاری

    Chrome 106+

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

  • frameId

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

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

  • شناسه

    رشته اختیاری

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

  • NativeApplication

    رشته اختیاری

    Chrome 74+

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

  • منشاء

    رشته اختیاری

    Chrome 80+

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

  • برگه

    برگه اختیاری است

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

  • tlsChannelId

    رشته اختیاری

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

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

    رشته اختیاری

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

OnInstalledReason
Chrome 44+

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

Enum

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

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

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

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

OnRestartRequiredReason
Chrome 44+

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

Enum

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

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

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

PlatformArch
Chrome 44+

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

Enum

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

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

"x86-32"
معماری پردازنده را x86-32 مشخص می کند.

"x86-64"
معماری پردازنده را x86-64 مشخص می کند.

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

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

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

PlatformInfo

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

خواص
  • قوس

    PlatformArch

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

  • nacl_arch

    PlatformNaclArch اختیاری است

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

  • سیستم عامل

    PlatformOs

    سیستم عامل کروم در حال اجرا است.

PlatformNaclArch
Chrome 44+

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

Enum

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

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

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

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

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

PlatformOs
Chrome 44+

سیستم عامل کروم در حال اجرا است.

Enum

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

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

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

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

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

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

Port

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

خواص
  • نام

    رشته

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

  • در قطع اتصال

    رویداد<functionvoidvoid>

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

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

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

    • پاسخ به تماس

      تابع

      پارامتر callback به نظر می رسد: 

      (port: Port) => void

  • onMessage

    رویداد<functionvoidvoid>

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

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

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

    • پاسخ به تماس

      تابع

      پارامتر callback به نظر می رسد: 

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

  • فرستنده

    MessageSender اختیاری است

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

  • قطع کن

    باطل

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

    تابع disconnect به نظر می رسد: 

    () => {...}

  • پست پیام

    باطل

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

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

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

    • پیام

      هر

      Chrome 52+

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

RequestUpdateCheckStatus
Chrome 44+

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

Enum

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

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

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

خواص
id

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

تایپ کنید

رشته

lastError

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

تایپ کنید

شی

خواص
  • پیام

    رشته اختیاری

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

روش ها
connect() 
chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

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

پارامترها
  • شناسه extension

    رشته اختیاری

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

  • connectInfo

    شی اختیاری

    • شاملTlsChannelId

      بولی اختیاری

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

    • نام

      رشته اختیاری

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

برمی گرداند

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

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

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

پارامترها
  • کاربرد

    رشته

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

برمی گرداند

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

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

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

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

برمی گرداند

  • وعده<Window | تعریف نشده>

    Chrome 99+
getContexts()
Chrome 116+ MV3+
chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

اطلاعات مربوط به زمینه های فعال مرتبط با این برنامه افزودنی را واکشی می کند

پارامترها
  • فیلتر

    ContextFilter

    فیلتری برای یافتن زمینه های منطبق. اگر زمینه با تمام فیلدهای مشخص شده در فیلتر مطابقت داشته باشد، مطابقت دارد. هر قسمت نامشخص در فیلتر با همه زمینه ها مطابقت دارد.

برمی گرداند
getManifest() 
chrome.runtime.getManifest(): object

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

برمی گرداند

  • شی

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

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

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

برمی گرداند

  • Promise<DirectoryEntry>

    Chrome 122+
getPlatformInfo() 
chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

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

برمی گرداند
getURL() 
chrome.runtime.getURL(
  path: string,
): string

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

پارامترها
  • مسیر

    رشته

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

برمی گرداند

  • رشته

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

openOptionsPage() 
chrome.runtime.openOptionsPage(): Promise<void>

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

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

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

برمی گرداند

  • قول<باطل>

    Chrome 99+
reload() 
chrome.runtime.reload(): void

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

requestUpdateCheck() 
chrome.runtime.requestUpdateCheck(): Promise<object>

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

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

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

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

برمی گرداند

  • قول<object>

    Chrome 109+
restart() 
chrome.runtime.restart(): void

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

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

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

پارامترها
  • ثانیه

    شماره

    زمان منتظر ماندن در چند ثانیه قبل از راه اندازی مجدد دستگاه یا -1 برای لغو راه اندازی مجدد برنامه ریزی شده است.

برمی گرداند

  • قول<باطل>

    Chrome 99+
sendMessage() 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

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

پارامترها
  • شناسه extension

    رشته اختیاری

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

  • پیام

    هر

    پیام برای ارسال. این پیام باید یک شی با قابلیت JSON-ifiable باشد.

  • گزینه ها

    شی اختیاری

    • شاملTlsChannelId

      بولی اختیاری

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

برمی گرداند

  • قول <هر>

    Chrome 99+
sendNativeMessage() 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

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

پارامترها
  • کاربرد

    رشته

    نام میزبان پیام رسان بومی.

  • پیام

    شی

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

برمی گرداند

  • قول <هر>

    Chrome 99+
setUninstallURL() 
chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

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

پارامترها
  • آدرس اینترنتی

    رشته

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

برمی گرداند

  • قول<باطل>

    Chrome 99+
رویدادها
onBrowserUpdateAvailable
منسوخ شده است
 
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

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

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    () => void

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

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (port: Port) => void

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

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (port: Port) => void

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

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (port: Port) => 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 | undefined

    • برمی گرداند

      بولی | تعریف نشده

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

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

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

    • برمی گرداند

      بولی | تعریف نشده

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

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

پارامترها
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

    • جزئیات

      شی

      • نسخه

        رشته

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

onUserScriptConnect
Chrome 115+ MV3+
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (port: Port) => void

onUserScriptMessage
Chrome 115+ MV3+
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

پارامترها
  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

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

    • برمی گرداند

      بولی | تعریف نشده