مرجع API

اکثر افزونه‌ها برای عملکرد خود نیاز به دسترسی به یک یا چند API افزونه‌های کروم دارند. این مرجع API، APIهای موجود برای استفاده در افزونه‌ها را شرح می‌دهد و مثال‌هایی از موارد استفاده را ارائه می‌دهد.

از نسخه ۱۴۴ کروم، تمام APIهای افزونه‌های کروم تحت فضای نام browser (مثلاً browser.tabs.create({}) ) نیز در دسترس هستند. این یک نام مستعار برای فضای نام chrome (مثلاً chrome.tabs.create({}) ) است که برای سازگاری با سایر مرورگرهایی که از فضای نام browser برای APIهای افزونه خود استفاده می‌کنند، ارائه شده است.

ویژگی‌های API افزونه‌های رایج

یک API افزونه‌ها شامل یک فضای نام است که شامل متدها و ویژگی‌هایی برای انجام کار افزونه‌ها و معمولاً، اما نه همیشه، فیلدهای manifest برای فایل manifest.json است. به عنوان مثال، فضای نام chrome.action به یک شیء "action" در manifest نیاز دارد. بسیاری از APIها نیز به مجوزهایی در manifest نیاز دارند.

متدهای موجود در APIهای توسعه‌یافته ناهمزمان هستند، مگر اینکه خلاف آن ذکر شده باشد. متدهای ناهمزمان بلافاصله و بدون انتظار برای اتمام عملیاتی که آنها را فراخوانی می‌کند، برمی‌گردند. از promiseها برای دریافت نتایج این متدهای ناهمزمان استفاده کنید.

APIهای افزونه‌های کروم

ویژگی‌ها

از API chrome.accessibilityFeatures برای مدیریت ویژگی‌های دسترسی کروم استفاده کنید. این API برای دریافت و تنظیم ویژگی‌های دسترسی مجزا، به نمونه اولیه ChromeSetting از نوع API متکی است. برای دریافت وضعیت ویژگی‌ها، افزونه باید مجوز accessibilityFeatures.read را درخواست کند. برای تغییر وضعیت ویژگی، افزونه به مجوز accessibilityFeatures.modify نیاز دارد. توجه داشته باشید که accessibilityFeatures.modify به معنای مجوز accessibilityFeatures.read نیست.

عمل
کروم ۸۸+ نسخه ۳+

از API chrome.action برای کنترل آیکون افزونه در نوار ابزار گوگل کروم استفاده کنید.

آلارم ها

از API chrome.alarms برای زمان‌بندی کد جهت اجرا به صورت دوره‌ای یا در زمان مشخصی در آینده استفاده کنید.

صوتی
فقط کروم او اس نسخه ۵۹ به بالا

رابط برنامه‌نویسی کاربردی chrome.audio به کاربران اجازه می‌دهد تا اطلاعاتی در مورد دستگاه‌های صوتی متصل به سیستم دریافت کرده و آنها را کنترل کنند. این رابط برنامه‌نویسی کاربردی در حال حاضر فقط در حالت کیوسک برای ChromeOS در دسترس است.

بوک‌مارک‌ها

از API chrome.bookmarks برای ایجاد، سازماندهی و دستکاری بوکمارک‌ها استفاده کنید. همچنین به بخش Override Pages مراجعه کنید که می‌توانید از آن برای ایجاد یک صفحه مدیریت بوکمارک سفارشی استفاده کنید.

مرور داده‌ها

از API chrome.browsingData برای حذف داده‌های مرور از پروفایل محلی کاربر استفاده کنید.

ارائه دهنده گواهی
فقط کروم او اس ۴۶+

از این API برای نمایش گواهینامه‌ها به پلتفرمی استفاده کنید که می‌تواند از این گواهینامه‌ها برای احراز هویت TLS استفاده کند.

دستورات

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

تنظیمات محتوا

از API chrome.contentSettings برای تغییر تنظیماتی که کنترل می‌کنند آیا وب‌سایت‌ها می‌توانند از ویژگی‌هایی مانند کوکی‌ها، جاوا اسکریپت و افزونه‌ها استفاده کنند یا خیر، استفاده کنید. به طور کلی، تنظیمات محتوا به شما امکان می‌دهد رفتار کروم را به جای سراسری، بر اساس هر سایت سفارشی کنید.

منوهای زمینه

از API chrome.contextMenus برای افزودن موارد به منوی زمینه گوگل کروم استفاده کنید. می‌توانید انتخاب کنید که موارد اضافه شده به منوی زمینه روی چه نوع اشیایی اعمال شوند، مانند تصاویر، هایپرلینک‌ها و صفحات.

کوکی‌ها

از API chrome.cookies برای جستجو و تغییر کوکی‌ها و مطلع شدن از تغییرات آنها استفاده کنید.

اشکال‌زدا

رابط برنامه‌نویسی کاربردی chrome.debugger به عنوان یک ابزار جایگزین برای پروتکل اشکال‌زدایی از راه دور کروم عمل می‌کند. از chrome.debugger برای اتصال به یک یا چند تب به منظور بررسی تعامل شبکه، اشکال‌زدایی جاوا اسکریپت، تغییر DOM و CSS و موارد دیگر استفاده کنید. از ویژگی Debuggee tabId برای هدف‌گیری تب‌ها با sendCommand و مسیریابی رویدادها توسط tabId از فراخوانی‌های onEvent استفاده کنید.

محتوای اعلانی

از API chrome.declarativeContent برای انجام اقداماتی بسته به محتوای یک صفحه، بدون نیاز به مجوز برای خواندن محتوای صفحه، استفاده کنید.

اعلانی درخواست شبکه
کروم ۸۴+

API chrome.declarativeNetRequest برای مسدود کردن یا تغییر درخواست‌های شبکه با تعیین قوانین اعلانی استفاده می‌شود. این به افزونه‌ها اجازه می‌دهد درخواست‌های شبکه را بدون رهگیری و مشاهده محتوای آنها تغییر دهند و در نتیجه حریم خصوصی بیشتری را فراهم کنند.

ضبط دسکتاپ

رابط برنامه‌نویسی کاربردی (API) ضبط دسکتاپ، محتوای صفحه نمایش، پنجره‌های مجزا یا تب‌های مجزا را ضبط می‌کند.

devtools.inspectedWindow

از API مربوط به chrome.devtools.inspectedWindow برای تعامل با پنجره‌ی بازرسی‌شده استفاده کنید: شناسه‌ی برگه (tab ID) صفحه‌ی بازرسی‌شده را به دست آورید، کد را در متن پنجره‌ی بازرسی‌شده ارزیابی کنید، صفحه را مجدداً بارگذاری کنید یا فهرست منابع درون صفحه را به دست آورید.

ابزار توسعه (devtools.network)

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

پنل‌های توسعه

از API مربوط به chrome.devtools.panels برای ادغام افزونه خود در رابط کاربری پنجره ابزارهای توسعه‌دهندگان استفاده کنید: پنل‌های خودتان را ایجاد کنید، به پنل‌های موجود دسترسی پیدا کنید و سایدبارها را اضافه کنید.

ابزارهای توسعه.عملکرد
کروم ۱۲۹+

از API chrome.devtools.performance برای گوش دادن به به‌روزرسانی‌های وضعیت ضبط در پنل Performance در DevTools استفاده کنید.

ضبط‌کننده ابزار توسعه
کروم ۱۰۵+

برای سفارشی‌سازی پنل ضبط‌کننده در DevTools از API chrome.devtools.recorder استفاده کنید.

دی‌ان‌اس
کانال توسعه‌دهندگان

برای حل مشکل DNS از API chrome.dns استفاده کنید.

اسکن سند
فقط کروم او اس ۴۴+

از API chrome.documentScan برای کشف و بازیابی تصاویر از اسکنرهای اسناد پیوست شده استفاده کنید.

دام
کروم ۸۸+

از API chrome.dom برای دسترسی به APIهای ویژه DOM برای افزونه‌ها استفاده کنید.

دانلودها

از API مربوط به chrome.downloads برای شروع، نظارت، دستکاری و جستجوی دانلودها به صورت برنامه‌نویسی شده استفاده کنید.

ویژگی‌های دستگاه سازمانی
کروم ۴۶+ فقط سیستم عامل کروم نیاز به خط‌مشی دارد

از API مربوط به chrome.enterprise.deviceAttributes برای خواندن ویژگی‌های دستگاه استفاده کنید. توجه: این API فقط برای افزونه‌هایی که طبق سیاست سازمانی به زور نصب شده‌اند، در دسترس است.

پلتفرم سخت‌افزار سازمانی

از API مربوط به chrome.enterprise.hardwarePlatform برای دریافت سازنده و مدل پلتفرم سخت‌افزاری که مرورگر روی آن اجرا می‌شود، استفاده کنید. توجه: این API فقط برای افزونه‌هایی که توسط سیاست‌های سازمانی نصب شده‌اند، در دسترس است.

ورود به سیستم سازمانی
کروم ۱۳۹+ فقط سیستم عامل کروم نیاز به خط‌مشی دارد

برای خروج از جلسات مهمان مدیریت‌شده از API مربوط به chrome.enterprise.login استفاده کنید. توجه: این API فقط برای افزونه‌هایی که توسط خط‌مشی سازمانی در جلسات مهمان مدیریت‌شده ChromeOS نصب شده‌اند، در دسترس است.

ویژگی‌های شبکه سازمانی
فقط Chrome نسخه ۸۵+، سیستم عامل Chrome، نیازمند خط‌مشی است

از API مربوط به chrome.enterprise.networkingAttributes برای خواندن اطلاعات مربوط به شبکه فعلی خود استفاده کنید. توجه: این API فقط برای افزونه‌هایی که طبق سیاست سازمانی به زور نصب شده‌اند، در دسترس است.

کلیدهای پلتفرم سازمانی

از API chrome.enterprise.platformKeys برای تولید کلیدها و نصب گواهی‌نامه‌ها برای این کلیدها استفاده کنید. گواهی‌نامه‌ها توسط پلتفرم مدیریت می‌شوند و می‌توانند برای احراز هویت TLS، دسترسی به شبکه یا سایر افزونه‌ها از طریق chrome.platformKeys مورد استفاده قرار گیرند.

رویدادها

فضای نام chrome.events شامل انواع داده‌های رایجی است که توسط APIها برای ارسال رویدادها استفاده می‌شوند تا هنگام وقوع اتفاق جالبی به شما اطلاع دهند.

پسوند

API chrome.extension دارای ابزارهایی است که می‌تواند توسط هر صفحه افزونه‌ای مورد استفاده قرار گیرد. این API شامل پشتیبانی از تبادل پیام بین یک افزونه و اسکریپت‌های محتوای آن یا بین افزونه‌ها است، همانطور که به تفصیل در بخش «انتقال پیام» توضیح داده شده است.

انواع افزونه

API chrome.extensionTypes شامل اعلان‌های نوع برای افزونه‌های کروم است.

مدیریت کننده فایل مرورگر
فقط سیستم عامل کروم فقط در پیش‌زمینه

از API مربوط به chrome.fileBrowserHandler برای گسترش مرورگر فایل سیستم عامل کروم استفاده کنید. برای مثال، می‌توانید از این API برای فعال کردن امکان آپلود فایل توسط کاربران در وب‌سایت خود استفاده کنید.

ارائه دهنده سیستم فایل
فقط سیستم عامل کروم

از API مربوط به chrome.fileSystemProvider برای ایجاد سیستم‌های فایلی استفاده کنید که از طریق مدیریت فایل در سیستم‌عامل کروم قابل دسترسی باشند.

تنظیمات فونت

برای مدیریت تنظیمات فونت کروم از API مربوط به chrome.fontSettings استفاده کنید.

جی سی ام

chrome.gcm برای فعال کردن ارسال و دریافت پیام‌ها از طریق Firebase Cloud Messaging (FCM) برای برنامه‌ها و افزونه‌ها استفاده کنید.

تاریخ

از API chrome.history برای تعامل با سابقه صفحات بازدید شده مرورگر استفاده کنید. می‌توانید URLها را در تاریخچه مرورگر اضافه، حذف و جستجو کنید. برای لغو صفحه تاریخچه با نسخه خودتان، به بخش لغو صفحات مراجعه کنید.

آی۱۸ان

از زیرساخت chrome.i18n برای پیاده‌سازی بین‌المللی‌سازی در کل برنامه یا افزونه خود استفاده کنید.

هویت

برای دریافت توکن‌های دسترسی OAuth2 از API chrome.identity استفاده کنید.

بیکار

از API chrome.idle برای تشخیص زمان تغییر حالت بیکاری دستگاه استفاده کنید.

زمان ورودی
فقط سیستم عامل کروم

از API مربوط به chrome.input.ime برای پیاده‌سازی یک IME سفارشی برای سیستم‌عامل کروم استفاده کنید. این به افزونه شما اجازه می‌دهد تا ضربات کلید را مدیریت کند، ترکیب‌بندی را تنظیم کند و پنجره کاندید را مدیریت کند.

شناسه نمونه
کروم ۴۴+

برای دسترسی به سرویس Instance ID chrome.instanceID استفاده کنید.

وضعیت ورود
فقط کروم ۷۸+ (سیستم عامل کروم)

از API chrome.loginState برای خواندن و نظارت بر وضعیت ورود به سیستم استفاده کنید.

مدیریت

رابط برنامه‌نویسی کاربردی chrome.management روش‌هایی برای مدیریت برنامه‌ها و افزونه‌های نصب‌شده ارائه می‌دهد.

اعلان‌ها

از API chrome.notifications برای ایجاد اعلان‌های غنی با استفاده از قالب‌ها استفاده کنید و این اعلان‌ها را در سینی سیستم به کاربران نشان دهید.

خارج از صفحه
کروم ۱۰۹+ نسخه ۳+

از API offscreen برای ایجاد و مدیریت اسناد خارج از صفحه استفاده کنید.

امنی‌باکس

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

ضبط صفحه

از API chrome.pageCapture برای ذخیره یک تب به عنوان MHTML استفاده کنید.

مجوزها

از API chrome.permissions برای درخواست مجوزهای اختیاری اعلام‌شده در زمان اجرا به جای زمان نصب استفاده کنید، تا کاربران دلیل نیاز به مجوزها را درک کرده و فقط مجوزهای ضروری را اعطا کنند.

کلیدهای پلتفرم
فقط کروم ۴۵+ سیستم عامل کروم

از API مربوط به chrome.platformKeys برای دسترسی به گواهینامه‌های کلاینت مدیریت‌شده توسط پلتفرم استفاده کنید. اگر کاربر یا سیاست مربوطه این مجوز را اعطا کند، یک افزونه می‌تواند از چنین گواهینامه‌ای در پروتکل احراز هویت سفارشی خود استفاده کند. به عنوان مثال، این امر امکان استفاده از گواهینامه‌های مدیریت‌شده توسط پلتفرم را در VPNهای شخص ثالث فراهم می‌کند (به chrome.vpnProvider مراجعه کنید).

قدرت

از API chrome.power برای لغو ویژگی‌های مدیریت انرژی سیستم استفاده کنید.

ارائه دهنده چاپگر
کروم ۴۴+

رابط برنامه‌نویسی کاربردی chrome.printerProvider رویدادهایی را که توسط مدیر چاپ استفاده می‌شوند، در اختیار قرار می‌دهد تا چاپگرهای کنترل‌شده توسط افزونه‌ها را جستجو کند، قابلیت‌های آنها را جستجو کند و کارهای چاپ را به این چاپگرها ارسال کند.

چاپ
فقط کروم او اس نسخه ۸۱ به بالا

از API chrome.printing برای ارسال کارهای چاپ به چاپگرهای نصب شده روی Chromebook استفاده کنید.

معیارهای چاپ
فقط Chrome نسخه ۷۹+ سیستم عامل Chrome نیاز به خط‌مشی دارد

از API chrome.printingMetrics برای دریافت داده‌های مربوط به میزان استفاده از چاپ استفاده کنید.

حریم خصوصی

از API chrome.privacy برای کنترل استفاده از ویژگی‌هایی در کروم که می‌توانند بر حریم خصوصی کاربر تأثیر بگذارند، استفاده کنید. این API برای دریافت و تنظیم پیکربندی کروم، به نمونه اولیه ChromeSetting از نوع API متکی است.

فرآیندها
کانال توسعه‌دهندگان

از API chrome.processes برای تعامل با فرآیندهای مرورگر استفاده کنید.

پروکسی

از API chrome.proxy برای مدیریت تنظیمات پروکسی کروم استفاده کنید. این API برای دریافت و تنظیم پیکربندی پروکسی به نمونه اولیه ChromeSetting از نوع API متکی است.

فهرست خواندنی‌ها
کروم ۱۲۰+ نسخه ۳+

از API مربوط به chrome.readingList برای خواندن و تغییر موارد موجود در Reading List استفاده کنید.

زمان اجرا

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

اسکریپت نویسی
کروم ۸۸+ نسخه ۳+

از API chrome.scripting برای اجرای اسکریپت در زمینه‌های مختلف استفاده کنید.

جستجو
کروم ۸۷+

از API chrome.search برای جستجو از طریق ارائه‌دهنده‌ی پیش‌فرض استفاده کنید.

جلسات

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

پنل کناری
کروم ۱۱۴+ نسخه MV3+

از API chrome.sidePanel برای میزبانی محتوا در پنل کناری مرورگر در کنار محتوای اصلی یک صفحه وب استفاده کنید.

ذخیره‌سازی

از API chrome.storage برای ذخیره، بازیابی و پیگیری تغییرات داده‌های کاربر استفاده کنید.

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

از API system.cpu برای جستجوی فراداده‌های CPU استفاده کنید.

سیستم.نمایشگر

از API system.display برای جستجوی فراداده‌های نمایش استفاده کنید.

حافظه سیستم

رابط برنامه‌نویسی کاربردی (API) مربوط به chrome.system.memory ).

سیستم.ذخیره‌سازی

از API مربوط به chrome.system.storage برای جستجوی اطلاعات دستگاه ذخیره‌سازی استفاده کنید و هنگام اتصال و جدا شدن یک دستگاه ذخیره‌سازی قابل جابجایی، مطلع شوید.

سیستم لاگ
کروم ۱۲۵+ فقط سیستم عامل کروم نیاز به خط‌مشی دارد

از API chrome.systemLog برای ثبت گزارش‌های سیستم کروم از افزونه‌ها استفاده کنید.

ضبط تب

از API chrome.tabCapture برای تعامل با جریان‌های رسانه‌ای تب استفاده کنید.

تب‌ها
کروم ۸۹+ نسخه ۳+

از API مربوط به chrome.tabGroups برای تعامل با سیستم گروه‌بندی تب‌های مرورگر استفاده کنید. می‌توانید از این API برای تغییر و تنظیم مجدد گروه‌های تب در مرورگر استفاده کنید. برای گروه‌بندی و خارج کردن تب‌ها از گروه‌بندی، یا برای پرس‌وجو در مورد اینکه چه تب‌هایی در گروه‌ها قرار دارند، از API chrome.tabs استفاده کنید.

زبانه‌ها

از API chrome.tabs برای تعامل با سیستم تب‌های مرورگر استفاده کنید. می‌توانید از این API برای ایجاد، تغییر و تنظیم مجدد تب‌ها در مرورگر استفاده کنید.

سایت‌های برتر

از API مربوط به chrome.topSites برای دسترسی به برترین سایت‌ها (یعنی سایت‌های پربازدید) که در صفحه تب جدید نمایش داده می‌شوند، استفاده کنید. این موارد شامل میانبرهای سفارشی‌سازی‌شده توسط کاربر نمی‌شوند.

تی تی اس

از API chrome.tts برای پخش متن به گفتار ترکیبی (TTS) استفاده کنید. همچنین به API مربوط به ttsEngine مراجعه کنید که به یک افزونه اجازه می‌دهد یک موتور گفتار پیاده‌سازی کند.

موتور tts

از API chrome.ttsEngine برای پیاده‌سازی یک موتور تبدیل متن به گفتار (TTS) با استفاده از یک افزونه استفاده کنید. اگر افزونه شما با استفاده از این API ثبت شود، رویدادهایی حاوی یک جمله برای گفتن و پارامترهای دیگر را دریافت می‌کند، زمانی که هر افزونه یا برنامه Chrome از API tts برای تولید گفتار استفاده می‌کند. افزونه شما سپس می‌تواند از هر فناوری وب موجود برای ترکیب و خروجی گفتار استفاده کند و رویدادها را به تابع فراخوانی کننده ارسال کند تا وضعیت را گزارش دهد.

انواع

API chrome.types شامل اعلان‌های نوع برای کروم است.

اسکریپت‌های کاربر
کروم ۱۲۰+ نسخه ۳+

از رابط برنامه‌نویسی کاربردی userScripts برای اجرای اسکریپت‌های کاربر در چارچوب User Scripts استفاده کنید.

ارائه دهنده vpn
فقط کروم ۴۳+ (سیستم عامل کروم)

برای پیاده‌سازی یک کلاینت VPN از API chrome.vpnProvider استفاده کنید.

کاغذ دیواری
فقط کروم ۴۳+ (سیستم عامل کروم)

برای تغییر تصویر زمینه ChromeOS از API chrome.wallpaper استفاده کنید.

پروکسی احراز هویت وب
کروم ۱۱۵+ نسخه MV3+

رابط برنامه‌نویسی کاربردی chrome.webAuthenticationProxy به نرم‌افزارهای دسکتاپ از راه دور که روی یک میزبان از راه دور اجرا می‌شوند، اجازه می‌دهد تا درخواست‌های رابط برنامه‌نویسی کاربردی احراز هویت وب (WebAuthn) را رهگیری کرده و آنها را در یک کلاینت محلی مدیریت کنند.

ناوبری وب

از API chrome.webNavigation برای دریافت اعلان‌ها در مورد وضعیت درخواست‌های ناوبری در حین پرواز استفاده کنید.

درخواست وب

از API chrome.webRequest برای مشاهده و تحلیل ترافیک و رهگیری، مسدود کردن یا تغییر درخواست‌ها در حین ارسال استفاده کنید.

پنجره‌ها

از API مربوط به chrome.windows برای تعامل با پنجره‌های مرورگر استفاده کنید. می‌توانید از این API برای ایجاد، تغییر و تنظیم مجدد پنجره‌ها در مرورگر استفاده کنید.