این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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
نوع زمینه ای که با آن مطابقت دارد.
شناسه سند
رشته اختیاری
یک 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 مشخص می کند.

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 را مشخص می کند.

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

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,
)

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

پارامترها

شناسه extension
رشته اختیاری
شناسه برنامه افزودنی برای اتصال. در صورت حذف، اتصال با پسوند خود شما انجام خواهد شد. در صورت ارسال پیام از یک صفحه وب برای پیام رسانی وب الزامی است.
connectInfo
شی اختیاری
- شاملTlsChannelId
  بولی اختیاری
  آیا شناسه کانال TLS برای فرآیندهایی که در حال گوش دادن به رویداد اتصال هستند به onConnectExternal منتقل می شود یا خیر.
- نام
  رشته اختیاری
  برای فرآیندهایی که در حال گوش دادن به رویداد اتصال هستند، به onConnect منتقل می شود.

برمی گرداند

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

پارامترها

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

برمی گرداند

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

getBackgroundPage()

فقط پیش زمینه وعده

chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

پارامترها

پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(backgroundPage?: Window) => void
```
- صفحه پس زمینه
  پنجره اختیاری
  شیء "پنجره" جاوا اسکریپت برای صفحه پس زمینه.

برمی گرداند

وعده<Window | تعریف نشده>
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getContexts()

Promise Chrome 116+ MV3+

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

پارامترها

فیلتر
ContextFilter
فیلتری برای یافتن زمینه های منطبق. اگر زمینه با تمام فیلدهای مشخص شده در فیلتر مطابقت داشته باشد، مطابقت دارد. هر قسمت نامشخص در فیلتر با همه زمینه ها مطابقت دارد.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(contexts: ExtensionContext[]) => void
```
- زمینه ها
  ExtensionContext []
  زمینه های منطبق، در صورت وجود.

برمی گرداند

Promise< ExtensionContext []>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getManifest()

chrome.runtime.getManifest()

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

برمی گرداند

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

getPackageDirectoryEntry()

فقط پیش زمینه وعده

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

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

پارامترها

پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(directoryEntry: DirectoryEntry) => void
```
- ورودی دایرکتوری
  ورود دایرکتوری

برمی گرداند

Promise<DirectoryEntry>
Chrome 122+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getPlatformInfo()

قول بده

chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

پارامترها

پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(platformInfo: PlatformInfo) => void
```
- platformInfo
  PlatformInfo

برمی گرداند

وعده< PlatformInfo >
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

پارامترها

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

برمی گرداند

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

openOptionsPage()

قول بده

chrome.runtime.openOptionsPage(
  callback?: function,
)

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

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

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

پارامترها

پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
() => void
```

برمی گرداند

قول<باطل>
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

قول بده

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

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

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

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

پارامترها

پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(result: object) => void
```
- نتیجه
  شی
  Chrome 109+
  آبجکت RequestUpdateCheckResult که وضعیت بررسی به‌روزرسانی و هرگونه جزئیات نتیجه را در صورت وجود به‌روزرسانی در دسترس نگه می‌دارد.
  - وضعیت
    RequestUpdateCheckStatus
    نتیجه بررسی به روز رسانی
  - نسخه
    رشته اختیاری
    اگر به‌روزرسانی در دسترس باشد، این شامل نسخه به‌روزرسانی موجود است.

برمی گرداند

قول<object>
Chrome 109+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome 53+

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

پارامترها

ثانیه
شماره
زمان منتظر ماندن در چند ثانیه قبل از راه اندازی مجدد دستگاه یا -1 برای لغو راه اندازی مجدد برنامه ریزی شده است.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
() => void
```

برمی گرداند

قول<باطل>
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

sendMessage()

قول بده

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

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

پارامترها

شناسه extension
رشته اختیاری
شناسه برنامه افزودنی برای ارسال پیام. در صورت حذف، پیام به برنامه افزودنی/برنامه شخصی شما ارسال خواهد شد. در صورت ارسال پیام از یک صفحه وب برای پیام رسانی وب الزامی است.
پیام
هر
پیام برای ارسال. این پیام باید یک شی با قابلیت JSON-ifiable باشد.
گزینه ها
شی اختیاری
- شاملTlsChannelId
  بولی اختیاری
  آیا شناسه کانال TLS برای فرآیندهایی که در حال گوش دادن به رویداد اتصال هستند به onMessageExternal منتقل می شود یا خیر.
پاسخ به تماس
عملکرد اختیاری
Chrome 99+
پارامتر callback به نظر می رسد:
```
(response: any) => void
```
- پاسخ
  هر
  شی پاسخ JSON ارسال شده توسط کنترل کننده پیام. اگر هنگام اتصال به برنامه افزودنی خطایی رخ دهد، callback بدون آرگومان فراخوانی می شود و runtime.lastError روی پیام خطا تنظیم می شود.

برمی گرداند

قول <هر>
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

sendNativeMessage()

قول بده

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

پارامترها

کاربرد
رشته
نام میزبان پیام رسان بومی.
پیام
شی
پیامی که به میزبان پیام‌رسان بومی ارسال می‌شود.
پاسخ به تماس
عملکرد اختیاری
Chrome 99+
پارامتر callback به نظر می رسد:
```
(response: any) => void
```
- پاسخ
  هر
  پیام پاسخ ارسال شده توسط میزبان پیام رسانی بومی. اگر هنگام اتصال به میزبان پیام رسانی بومی خطایی رخ دهد، تماس برگشتی بدون آرگومان فراخوانی می شود و runtime.lastError روی پیام خطا تنظیم می شود.

برمی گرداند

قول <هر>
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

setUninstallURL()

قول بده

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

پارامترها

آدرس اینترنتی
رشته
URL که پس از حذف نصب برنامه افزودنی باز می شود. این URL باید دارای طرح http: یا https: باشد. یک رشته خالی را طوری تنظیم کنید که پس از حذف، برگه جدیدی باز نشود.
پاسخ به تماس
عملکرد اختیاری
Chrome 45+
پارامتر callback به نظر می رسد:
```
() => void
```

برمی گرداند

قول<باطل>
Chrome 99+
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

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» باشد.
  - نسخه قبلی
    رشته اختیاری
    نشان دهنده نسخه قبلی افزونه است که به تازگی به روز شده است. این فقط در صورتی وجود دارد که «دلیل» «به‌روزرسانی» باشد.
  - دلیل
    OnInstalledReason
    دلیل اینکه این رویداد در حال ارسال است.

onMessage

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

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

پارامترها

پاسخ به تماس
تابع
پارامتر callback به نظر می رسد:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- پیام
  هر
- فرستنده
  پیام فرستنده
- sendResponse
  تابع
  پارامتر sendResponse به نظر می رسد:
```
() => void
```
- برمی گرداند
  بولی | تعریف نشده

onMessageExternal

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

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

پارامترها

پاسخ به تماس
تابع
پارامتر callback به نظر می رسد:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- پیام
  هر
- فرستنده
  پیام فرستنده
- sendResponse
  تابع
  پارامتر sendResponse به نظر می رسد:
```
() => void
```
- برمی گرداند
  بولی | تعریف نشده

onRestartRequired

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

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

پارامترها

پاسخ به تماس
تابع
پارامتر callback به نظر می رسد:
```
(reason: OnRestartRequiredReason) => void
```
- دلیل
  OnRestartRequiredReason

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
```
- پیام
  هر
- فرستنده
  پیام فرستنده
- sendResponse
  تابع
  پارامتر sendResponse به نظر می رسد:
```
() => void
```
- برمی گرداند
  بولی | تعریف نشده