توضیحات
از 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
فیلتری برای مطابقت با زمینههای برنامه افزودنی خاص. زمینه های منطبق باید با تمام فیلترهای مشخص شده مطابقت داشته باشد. هر فیلتری که مشخص نشده است با تمام زمینه های موجود مطابقت دارد. بنابراین، یک فیلتر از `{}` با تمام زمینه های موجود مطابقت دارد.
خواص
- contextIds
رشته[] اختیاری است
- انواع متن
ContextType [] اختیاری است
- شناسه های اسناد
رشته[] اختیاری است
- documentOrigins
رشته[] اختیاری است
- documentUrls
رشته[] اختیاری است
- FrameIds
شماره[] اختیاری
- ناشناس
بولی اختیاری
- tabIds
شماره[] اختیاری
- windowIds
شماره[] اختیاری
ContextType
Enum
"TAB" "POPUP" "پیشینه" "OFFSCREEN_DOCUMENT" "SIDE_PANEL" "DEVELOPER_TOOLS"
نوع زمینه را به عنوان یک برگه مشخص می کند
نوع زمینه را به عنوان یک پنجره بازشو پسوند مشخص می کند
نوع زمینه را به عنوان یک سرویس دهنده مشخص می کند.
نوع زمینه را به عنوان سند خارج از صفحه مشخص می کند.
نوع زمینه را به عنوان یک پانل جانبی مشخص می کند.
نوع زمینه را به عنوان ابزار توسعه دهنده مشخص می کند.
ExtensionContext
محتوای پسوند میزبانی متن.
خواص
- 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
دلیل اینکه این رویداد در حال ارسال است.
Enum
"نصب" "به روز رسانی" "chrome_update" "shared_module_update"
دلیل رویداد را به عنوان نصب مشخص می کند.
دلیل رویداد را به عنوان بهروزرسانی برنامه افزودنی مشخص میکند.
دلیل رویداد را بهعنوان بهروزرسانی Chrome مشخص میکند.
دلیل رویداد را به عنوان بهروزرسانی یک ماژول مشترک مشخص میکند.
OnRestartRequiredReason
دلیل اینکه این رویداد در حال اعزام است. «app_update» زمانی استفاده میشود که نیاز به راهاندازی مجدد باشد زیرا برنامه به نسخه جدیدتر بهروزرسانی میشود. «os_update» زمانی استفاده میشود که نیاز به راهاندازی مجدد باشد زیرا مرورگر/OS به نسخه جدیدتر بهروزرسانی شده است. "دوره ای" زمانی استفاده می شود که سیستم برای بیش از زمان مجاز تنظیم شده در خط مشی سازمانی اجرا شود.
Enum
"app_update" "os_update" "دوره ای"
دلیل رویداد را به عنوان بهروزرسانی برنامه مشخص میکند.
دلیل رویداد را به عنوان به روز رسانی سیستم عامل مشخص می کند.
دلیل رویداد را به عنوان راه اندازی مجدد دوره ای برنامه مشخص می کند.
PlatformArch
معماری پردازنده دستگاه
Enum
"بازو" "arm64" "x86-32" "x86-64" "mips" "mips64"
معماری پردازنده را به عنوان بازو مشخص می کند.
معماری پردازنده را به عنوان arm64 مشخص می کند.
معماری پردازنده را x86-32 مشخص می کند.
معماری پردازنده را x86-64 مشخص می کند.
معماری پردازنده را به صورت mips مشخص می کند.
معماری پردازنده را به صورت mips64 مشخص می کند.
PlatformInfo
یک شی حاوی اطلاعات در مورد پلت فرم فعلی.
خواص
- قوس
معماری پردازنده دستگاه
- nacl_arch
معماری مشتری بومی این ممکن است با قوس در برخی از سکوها متفاوت باشد.
- سیستم عامل
سیستم عامل کروم در حال اجرا است.
PlatformNaclArch
معماری مشتری بومی این ممکن است با قوس در برخی از سکوها متفاوت باشد.
Enum
"بازو" "x86-32" "x86-64" "mips" "mips64"
معماری مشتری اصلی را به عنوان بازو مشخص می کند.
معماری مشتری اصلی را به عنوان x86-32 مشخص می کند.
معماری مشتری اصلی را به عنوان x86-64 مشخص می کند.
معماری مشتری اصلی را به عنوان mips مشخص می کند.
معماری مشتری اصلی را به عنوان mips64 مشخص می کند.
PlatformOs
سیستم عامل Chrome در حال اجرا است.
Enum
"مک" "برد" "اندروید" "صلیب" "لینوکس" "openbsd" "فوشیا"
سیستم عامل MacOS را مشخص می کند.
سیستم عامل ویندوز را مشخص می کند.
سیستم عامل اندروید را مشخص می کند.
سیستم عامل کروم را مشخص می کند.
سیستم عامل لینوکس را مشخص می کند.
سیستم عامل OpenBSD را مشخص می کند.
سیستم عامل Fuchsia را مشخص می کند.
Port
یک شی که امکان ارتباط دو طرفه با صفحات دیگر را فراهم می کند. برای اطلاعات بیشتر به اتصالات طولانی مدت مراجعه کنید.
خواص
- نام
رشته
نام پورت، همانطور که در تماس با
runtime.connect
مشخص شده است. - در قطع اتصال
رویداد<functionvoidvoid>
هنگامی که پورت از انتهای (های) دیگر جدا می شود، فعال می شود. ممکن است
runtime.lastError
تنظیم شود اگر پورت با خطا قطع شده باشد. اگر پورت از طریق قطع اتصال بسته شود، این رویداد فقط در انتهای دیگر فعال می شود. این رویداد حداکثر یک بار اجرا می شود (همچنین به طول عمر بندر مراجعه کنید).تابع
onDisconnect.addListener
به شکل زیر است:(callback: function) => {...}
- onMessage
رویداد<functionvoidvoid>
این رویداد زمانی فعال می شود که postMessage توسط انتهای دیگر پورت فراخوانی شود.
تابع
onMessage.addListener
به شکل زیر است:(callback: function) => {...}
- فرستنده
MessageSender اختیاری است
این ویژگی فقط در پورت های ارسال شده به شنوندگان onConnect / onConnectExternal / onConnectNative وجود خواهد داشت.
- قطع کن
باطل
فوراً پورت را جدا کنید. فراخوانی
disconnect()
در پورتی که قبلاً قطع شده است، تأثیری ندارد. هنگامی که یک پورت قطع می شود، هیچ رویداد جدیدی به این پورت ارسال نمی شود.تابع
disconnect
به نظر می رسد:() => {...}
- پست پیام
باطل
به انتهای دیگر پورت پیام ارسال کنید. اگر پورت قطع شود، یک خطا ایجاد می شود.
تابع
postMessage
به شکل زیر است:(message: any) => {...}
- پیام
هر
Chrome 52+پیام برای ارسال. این شی باید JSON-ifiable باشد.
RequestUpdateCheckStatus
نتیجه بررسی به روز رسانی
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()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
اطلاعات مربوط به زمینه های فعال مرتبط با این برنامه افزودنی را واکشی می کند
پارامترها
- فیلتر
فیلتری برای یافتن زمینه های منطبق. اگر زمینه با تمام فیلدهای مشخص شده در فیلتر مطابقت داشته باشد، مطابقت دارد. هر قسمت نامشخص در فیلتر با همه زمینه ها مطابقت دارد.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(contexts: ExtensionContext[]) => void
- زمینه ها
زمینه های منطبق، در صورت وجود.
برمی گرداند
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 >
Chrome 99+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
getURL()
chrome.runtime.getURL(
path: string,
)
یک مسیر نسبی را در دایرکتوری نصب برنامه/افزونه به یک URL کاملاً واجد شرایط تبدیل میکند.
پارامترها
- مسیر
رشته
مسیری به منبعی در یک برنامه/افزونه که نسبت به دایرکتوری نصب آن بیان شده است.
برمی گرداند
رشته
URL کاملاً واجد شرایط منبع.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
در صورت امکان صفحه گزینه های برنامه افزودنی خود را باز کنید.
رفتار دقیق ممکن است به [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)
یا [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)
مانیفست شما بستگی داشته باشد [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_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 که وضعیت بررسی بهروزرسانی و هرگونه جزئیات نتیجه را در صورت وجود بهروزرسانی در دسترس نگه میدارد.
- وضعیت
نتیجه بررسی به روز رسانی
- نسخه
رشته اختیاری
اگر بهروزرسانی در دسترس باشد، این شامل نسخه بهروزرسانی موجود است.
برمی گرداند
قول<object>
Chrome 109+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
restart()
chrome.runtime.restart()
وقتی برنامه در حالت کیوسک اجرا می شود، دستگاه ChromeOS را راه اندازی مجدد کنید. در غیر این صورت، آن را بدون عملیات.
restartAfterDelay()
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
) ایجاد می شود، فعال می شود.
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
هنگامی که اتصال از یک برنامه افزودنی دیگر (توسط runtime.connect
)، یا از یک وب سایت قابل اتصال خارجی برقرار می شود، فعال می شود.
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
هنگامی که اتصال از یک برنامه بومی ایجاد می شود، فعال می شود. این رویداد به مجوز "nativeMessaging"
نیاز دارد. فقط در سیستم عامل کروم پشتیبانی می شود.
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
تابع
پارامتر
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
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.runtime.onUserScriptConnect.addListener(
callback: function,
)
هنگامی که یک اتصال از یک اسکریپت کاربر از این برنامه افزودنی ایجاد می شود، فعال می شود.
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
هنگامی که پیامی از یک اسکریپت کاربری مرتبط با همان برنامه افزودنی ارسال می شود، فعال می شود.
پارامترها
- پاسخ به تماس
تابع
پارامتر
callback
به نظر می رسد:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
- پیام
هر
- فرستنده
- sendResponse
تابع
پارامتر
sendResponse
به نظر می رسد:() => void
- برمی گرداند
بولی | تعریف نشده