chrome.runtime

توضیحات

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

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

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

مانیفست.json:

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

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

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

انتقال پیام
افزونه شما می‌تواند با استفاده از این متدها و رویدادها با زمینه‌های مختلف درون افزونه و همچنین با سایر افزونه‌ها ارتباط برقرار کند: connect() ، onConnect ، onConnectExternal ، sendMessage() ، onMessage و onMessageExternal . علاوه بر این، افزونه شما می‌تواند با استفاده از connectNative() و sendNativeMessage() پیام‌ها را به برنامه‌های بومی روی دستگاه کاربر ارسال کند.
دسترسی به متادیتای افزونه و پلتفرم
این متدها به شما امکان می‌دهند چندین قطعه خاص از فراداده‌ها (metadata) در مورد افزونه و پلتفرم را بازیابی کنید. متدهای این دسته شامل 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"> ). همین امر در مورد افزودن یک فایل افزونه به یک صفحه وب نیز صادق است. دو تفاوت این است که فایل‌های افزونه باید به عنوان منابع قابل دسترسی از طریق وب نمایش داده شوند و اینکه معمولاً اسکریپت‌های محتوا مسئول تزریق فایل‌های افزونه هستند.

در این مثال، افزونه با استفاده از 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 اختیاری

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

  • سیستم عامل

    پلتفرم او اس

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

PlatformNaclArch

کروم ۴۴+

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

شمارشی

"بازو"
معماری کلاینت بومی را به عنوان 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()

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

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

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

بازگشت‌ها

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

    کروم ۹۹+

getContexts()

کروم ۱۱۶+ نسخه MV3+
chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

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

پارامترها

  • فیلتر

    فیلتر متن

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

بازگشت‌ها

getManifest()

chrome.runtime.getManifest(): object

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

بازگشت‌ها

  • شیء

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

getPackageDirectoryEntry()

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

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

بازگشت‌ها

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

    کروم ۱۲۲+

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

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

بازگشت‌ها

getURL()

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

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

پارامترها

  • مسیر

    رشته

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

بازگشت‌ها

  • رشته

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

getVersion()

در حال بررسی
chrome.runtime.getVersion(): string

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

بازگشت‌ها

  • رشته

    نسخه افزونه.

openOptionsPage()

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

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

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

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

بازگشت‌ها

  • قول<void>

    کروم ۹۹+

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

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

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

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

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

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

بازگشت‌ها

  • قول دادن<object>

    کروم ۱۰۹+

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

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

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

پارامترها

  • ثانیه‌ها

    شماره

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

بازگشت‌ها

  • قول<void>

    کروم ۹۹+

sendMessage()

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

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

پارامترها

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

    رشته اختیاری

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

  • پیام

    هر

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

  • گزینه‌ها

    شیء اختیاری

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

      بولی اختیاری

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

بازگشت‌ها

  • قول بده<any>

    کروم ۹۹+

sendNativeMessage()

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

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

پارامترها

  • کاربرد

    رشته

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

  • پیام

    شیء

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

بازگشت‌ها

  • قول بده<any>

    کروم ۹۹+

setUninstallURL()

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

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

پارامترها

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

    رشته

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

بازگشت‌ها

  • قول<void>

    کروم ۹۹+

رویدادها

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

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

    • پیام

      هر

    • فرستنده

      فرستنده پیام

    • ارسال پاسخ

      تابع

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

      () => void

    • بازده

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

onMessageExternal

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

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

پارامترها

  • تماس برگشتی

    تابع

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

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

    • پیام

      هر

    • فرستنده

      فرستنده پیام

    • ارسال پاسخ

      تابع

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

      () => void

    • بازده

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

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

    • جزئیات

      شیء

      • نسخه

        رشته

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

onUserScriptConnect

کروم ۱۱۵+ نسخه MV3+
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

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

    (port: Port) => void

onUserScriptMessage

کروم ۱۱۵+ نسخه MV3+
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

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

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

    • پیام

      هر

    • فرستنده

      فرستنده پیام

    • ارسال پاسخ

      تابع

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

      () => void

    • بازده

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