شرح
از userScripts API برای اجرای اسکریپت‌های کاربر در بافت «اسکریپت‌های کاربر» استفاده کنید.
اجازه‌ها
userScriptsبرای استفاده از User Scripts API، browser.userScripts، اجازه "userScripts" را به manifest.json خود و "host_permissions" را برای سایت‌هایی که می‌خواهید اسکریپت‌ها را در آن‌ها اجرا کنید اضافه کنید.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
دردسترس بودن
مفاهیم و کاربرد
اسکریپت کاربر تکه‌کدی است که به صفحه وب تزریق می‌شود تا ظاهر یا رفتار آن را تغییر دهد. برخلاف دیگر ویژگی‌های افزونه، مثل اسکریپت‌های محتوا و browser.scripting API، با User Scripts API می‌توانید کد دلخواه اجرا کنید. این میانای برنامه‌سازی کاربردی برای افزونه‌هایی لازم است که اسکریپت‌های ارائه‌شده توسط کاربر را اجرا می‌کنند و نمی‌توانند به‌عنوان بخشی از بسته افزونه شما ارسال شوند.
فعال کردن استفاده از میانای برنامه‌سازی کاربردی userScripts
پس‌از اینکه افزونه شما اجازه استفاده از userScripts API را دریافت کرد، کاربران باید کلید خاصی را فعال کنند تا به افزونه شما اجازه دهند از API استفاده کند. کلید خاص موردنیاز و رفتار API درصورت غیرفعال بودن، بسته به نسخه Chrome متفاوت است.
از بررسی زیر برای تعیین اینکه کاربر کدام کلید را باید فعال کند استفاده کنید، برای مثال، درطول آماده‌سازی کاربر جدید:
let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
// Allow User Scripts toggle will be used.
} else {
// Developer mode toggle will be used.
}
بخش‌های زیر کلیدهای مختلف و نحوه فعال کردن آن‌ها را شرح می‌دهد.
نسخه‌های Chrome قبل‌از ۱۳۸ (کلید حالت توسعه‌دهنده)
به‌عنوان توسعه‌دهنده افزونه، ازقبل «حالت توسعه‌دهنده» را در نسخه نصب‌شده Chrome خود فعال کرده‌اید. کاربرانتان نیز باید «حالت توسعه‌دهنده» را فعال کنند.
می‌توانید دستورالعمل‌های زیر را کپی کنید و در اسناد افزونه‌تان برای کاربران جای‌گذاری کنید
- با وارد کردن
chrome://extensionsدر برگه جدید، به صفحه «افزونه‌ها» بروید. (طبق طراحی، نشانی‌های وبchrome://قابل‌پیوند نیستند.) با کلیک کردن روی کلید کنار حالت توسعه‌دهنده، «حالت توسعه‌دهنده» را فعال کنید.
صفحه افزونه‌ها (chrome://extensions)
Chrome نسخه ۱۳۸ و جدیدتر (کلید «مجاز کردن دستورگان کاربر»)
کلید روشن/خاموش مجاز کردن اسکریپت‌های کاربر در صفحه جزئیات هر افزونه (برای مثال، chrome://extensions/?id=YOUR_EXTENSION_ID) قرار دارد.
می‌توانید دستورالعمل‌های زیر را کپی و در مستندات افزونه‌تان برای کاربران جای‌گذاری کنید:
- با وارد کردن
chrome://extensionsدر برگه جدید، به صفحه «افزونه‌ها» بروید. (طبق طراحی، نشانی‌های وبchrome://قابل‌پیوند نیستند.) - روی دکمه «جزئیات» در کارت افزونه کلیک کنید تا اطلاعات دقیق درباره افزونه را مشاهده کنید.
- روی کلید کنار مجاز کردن دستورگان کاربر کلیک کنید.
بررسی دردسترس بودن میانای برنامه‌سازی کاربردی
توصیه می‌کنیم برای تعیین اینکه userScripts API فعال است یا نه، بررسی زیر را انجام دهید،
چون این بررسی در همه نسخه‌های Chrome کار می‌کند. این بررسی تلاش می‌کند روش browser.userScripts() را فراخوانی کند که همیشه باید درصورت دردسترس بودن API موفق شود. اگر این فراخوانی خطایی ایجاد کند، میانای برنامه‌سازی کاربردی دردسترس نیست:
function isUserScriptsAvailable() {
try {
// Method call which throws if API permission or toggle is not enabled.
browser.userScripts.getScripts();
return true;
} catch {
// Not available.
return false;
}
}
کار در دنیاهای مجزا
هر دو اسکریپت کاربر و محتوا می‌توانند در دنیای ایزوله یا در دنیای اصلی اجرا شوند. دنیای ایزوله محیط اجرایی است که برای صفحه میزبان یا افزونه‌های دیگر قابل‌دسترسی نیست. این به اسکریپت کاربر اجازه می‌دهد محیط جاوا اسکریپت خود را بدون تأثیر بر صفحه میزبان یا اسکریپت‌های کاربر و محتوای افزونه‌های دیگر تغییر دهد. برعکس، اسکریپت‌های کاربر (و اسکریپت‌های محتوا) برای صفحه میزبان یا اسکریپت‌های کاربر و محتوای افزونه‌های دیگر قابل‌مشاهده نیستند. دستورگان‌هایی که در دنیای اصلی اجرا می‌شوند برای صفحه‌های میزبان و سایر افزونه‌ها دردسترس هستند و برای صفحه‌های میزبان و سایر افزونه‌ها قابل‌مشاهده‌اند. برای انتخاب جهان، هنگام تماس با userScripts.register()، "USER_SCRIPT" یا "MAIN" را وارد کنید.
برای پیکربندی خط‌مشی امنیتی محتوا برای دنیای USER_SCRIPT، userScripts.configureWorld() را فراخوانی کنید:
browser.userScripts.configureWorld({
csp: "script-src 'self'"
});
پیام‌رسانی
مانند اسکریپت‌های محتوا و اسناد خارج از صفحه، اسکریپت‌های کاربر بااستفاده از پیام‌رسانی با بخش‌های دیگر افزونه ارتباط برقرار می‌کنند (به این معنی که می‌توانند runtime.sendMessage() و runtime.connect() را مانند هر بخش دیگری از افزونه فراخوانی کنند). بااین‌حال، این رویدادها بااستفاده از کنترل‌کننده‌های رویداد اختصاصی دریافت می‌شوند (یعنی از onMessage یا onConnect استفاده نمی‌کنند). این کنترل‌کننده‌ها runtime.onUserScriptMessage و runtime.onUserScriptConnect نامیده می‌شوند. گرداننده‌های اختصاصی شناسایی پیام‌های دریافتی از اسکریپت‌های کاربر را که زمینه‌ای با اعتماد کمتر است آسان‌تر می‌کند.
قبل‌از ارسال پیام، باید configureWorld() را با آرگومان messaging تنظیم‌شده روی true فراخوانی کنید. توجه داشته باشید که هر دو متغیر مستقل csp و messaging را می‌توان هم‌زمان ارسال کرد.
browser.userScripts.configureWorld({
messaging: true
});
به‌روزرسانی‌های افزونه
وقتی افزونه‌ای به‌روز می‌شود، اسکریپت‌های کاربر پاک می‌شود. می‌توانید آن‌ها را با اجرای کد در گرداننده رویداد runtime.onInstalled در کارگر سرویس افزونه دوباره اضافه کنید. فقط به "update" دلیل ارسال‌شده به فراخوان رویداد پاسخ دهید.
مثال
این مثال از نمونه userScript در مخزن نمونه‌های ما است.
ثبت کردن دستورگان
مثال زیر یک فراخوانی پایه به register() را نشان می‌دهد. آرگومان اول آرایه‌ای از اشیا است که اسکریپت‌های ثبت‌شدنی را تعریف می‌کند. گزینه‌های بیشتری نسبت به آنچه در اینجا نشان داده شده است وجود دارد.
browser.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
انواع
ExecutionWorld
دنیای جاوا اسکریپت برای اجرای اسکریپت کاربر در آن.
شمارشی
«MAIN»
محیط اجرای DOM را مشخص می‌کند که محیط اجرای مشترک با جاوا اسکریپت صفحه میزبان است.
"USER_SCRIPT"
محیط اجرایی را که مختص اسکریپت‌های کاربر است و از CSP صفحه معاف است مشخص می‌کند.
InjectionResult
مشخصات
-
documentId
رشته
سند مرتبط با تزریق.
-
خطا
رشته اختیاری
خطا، درصورت وجود.
errorوresultبه‌صورت متقابل انحصاری‌اند. -
frameId
شماره
قاب مرتبط با تزریق.
-
نتیجه
هر اختیاری
نتیجه اجرای متن.
InjectionTarget
مشخصات
-
allFrames
بولی اختیاری
آیا اسکریپت باید به همه قاب‌های درون برگه تزریق شود یا نه. پیش‌فرض: نادرست. اگر
frameIdsمشخص شده باشد، این نباید درست باشد. -
documentIds
رشته[] اختیاری
شناسه‌های documentIds خاص برای تزریق به آن. اگر
frameIdsتنظیم شده باشد، این مورد نباید تنظیم شود. -
frameIds
number[] اختیاری
شناسه‌های قاب‌های خاصی که باید به آن‌ها تزریق شود.
-
tabId
شماره
شناسه برگه‌ای که باید تزریق در آن انجام شود.
RegisteredUserScript
مشخصات
-
allFrames
بولی اختیاری
اگر درست باشد، به همه قاب‌ها تزریق می‌شود، حتی اگر قاب بالاترین قاب در برگه نباشد. هر قاب به‌طور مستقل ازنظر الزامات نشانی وب بررسی می‌شود؛ اگر الزامات نشانی وب برآورده نشود، به قاب‌های فرزند تزریق نخواهد شد. به‌طور پیش‌فرض روی false تنظیم شده است، یعنی فقط قاب بالایی مطابقت داده می‌شود.
-
excludeGlobs
رشته[] اختیاری
الگوهای عام را برای صفحه‌هایی که این اسکریپت کاربر در آن‌ها تزریق نخواهد شد مشخص می‌کند.
-
excludeMatches
رشته[] اختیاری
صفحه‌هایی را که این اسکریپت کاربر درغیراین‌صورت به آن‌ها تزریق می‌شد مستثنی می‌کند. برای جزئیات بیشتر درباره نحو این رشته‌ها، الگوهای مطابقت را ببینید.
-
id
رشته
شناسه اسکریپت کاربر مشخص‌شده در فراخوانی میانای برنامه‌سازی کاربردی. این ویژگی نباید با «_» شروع شود زیرا به‌عنوان پیشوند برای شناسه‌های تولیدشده اسکریپت رزرو شده است.
-
includeGlobs
رشته[] اختیاری
الگوهای عام را برای صفحه‌هایی که این اسکریپت کاربر در آن‌ها تزریق خواهد شد مشخص می‌کند.
-
js
ScriptSource[] اختیاری
فهرست اشیای ScriptSource که منابع دستورگان را برای تزریق به صفحه‌های منطبق تعریف می‌کند. این ویژگی باید برای ${ref:register} مشخص شود و وقتی مشخص شد، باید آرایه‌ای غیرخالی باشد.
-
انطباق‌ها
رشته[] اختیاری
مشخص می‌کند این اسکریپت کاربر به کدام صفحه‌ها تزریق خواهد شد. برای جزئیات بیشتر درباره نحو این رشته‌ها، الگوهای مطابقت را ببینید. این ویژگی باید برای ${ref:register} مشخص شود.
-
runAt
RunAt اختیاری
مشخص می‌کند چه زمانی فایل‌های جاوا اسکریپت به صفحه وب تزریق می‌شوند. مقدار پیش‌فرض و ترجیحی
document_idleاست. -
جهان
ExecutionWorld اختیاری
محیط اجرای جاوا اسکریپت برای اجرای دستورگان. پیش‌فرض
`USER_SCRIPT`است. -
worldId
رشته اختیاری
Chrome نسخه ۱۳۳ و بالاتر browser.* از Chrome نسخه ۱۴۸شناسه جهان اسکریپت کاربر را برای اجرا در آن مشخص می‌کند. اگر حذف شود، اسکریپت در دنیای اسکریپت کاربر پیش‌فرض اجرا خواهد شد. فقط درصورتی معتبر است که
worldحذف شده باشد یاUSER_SCRIPTباشد. مقادیری که با زیرخط (_) شروع می‌شوند رزرو شده‌اند.
ScriptSource
مشخصات
-
کد
رشته اختیاری
رشته‌ای که حاوی کد جاوا اسکریپت برای تزریق است. دقیقاً یکی از
fileیاcodeباید مشخص شود. -
فایل
رشته اختیاری
مسیر فایل جاوا اسکریپت برای تزریق نسبت به دایرکتوری ریشه افزونه. دقیقاً یکی از
fileیاcodeباید مشخص شود.
UserScriptFilter
مشخصات
-
شناسه‌ها
رشته[] اختیاری
getScriptsفقط اسکریپت‌هایی را برمی‌گرداند که شناسه‌هایشان در این فهرست مشخص شده است.
UserScriptInjection
مشخصات
-
injectImmediately
بولی اختیاری
آیا تزریق باید در اسرع وقت در هدف راه‌اندازی شود یا نه. توجه داشته باشید که این تضمین نمی‌کند که تزریق قبل‌از بار شدن صفحه انجام شود، زیرا ممکن است صفحه تا زمانی که اسکریپت به هدف برسد بار شده باشد.
-
js
فهرست اشیای ScriptSource که منابع دستورگان را برای تزریق به هدف تعریف می‌کند.
-
هدف
جزئیاتی که هدف تزریق اسکریپت را مشخص می‌کند.
-
جهان
ExecutionWorld اختیاری
«جهان» جاوا اسکریپت برای اجرای دستورگان در آن. پیش‌فرض
USER_SCRIPTاست. -
worldId
رشته اختیاری
شناسه جهان اسکریپت کاربر را برای اجرا در آن مشخص می‌کند. اگر حذف شود، اسکریپت در دنیای اسکریپت کاربر پیش‌فرض اجرا خواهد شد. فقط درصورتی معتبر است که
worldحذف شده باشد یاUSER_SCRIPTباشد. مقادیری که با زیرخط (_) شروع می‌شوند رزرو شده‌اند.
WorldProperties
مشخصات
-
csp
رشته اختیاری
world csp را مشخص می‌کند. پیش‌فرض
`ISOLATED`world csp است. -
پیام‌رسانی
بولی اختیاری
مشخص می‌کند که آیا میاناهای برنامه‌سازی کاربردی پیام‌رسانی درمعرض دید قرار گرفته‌اند یا نه. پیش‌فرض
falseاست. -
worldId
رشته اختیاری
Chrome نسخه ۱۳۳ و بالاتر browser.* از Chrome نسخه ۱۴۸شناسه دنیای اسکریپت کاربر خاص را برای به‌روزرسانی مشخص می‌کند. اگر ارائه نشود، ویژگی‌های دنیای اسکریپت کاربر پیش‌فرض را به‌روز می‌کند. مقادیری که با زیرخط (
_) شروع می‌شوند رزرو شده‌اند.
روش‌ها
configureWorld()
browser.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
محیط اجرای `USER_SCRIPT` را پیکربندی می‌کند.
پارامترها
-
اقامتگاه‌ها
حاوی پیکربندی دنیای دستورگان کاربر است.
بازگشتی‌ها
-
Promise<void>
Promise که پس‌از پیکربندی جهان حل می‌شود.
execute()
browser.userScripts.execute(
injection: UserScriptInjection,
): Promise<InjectionResult[]>
اسکریپتی را به بافت هدف تزریق می‌کند. به‌طور پیش‌فرض، اسکریپت در document_idle اجرا می‌شود، یا اگر صفحه قبلاً بار شده باشد، فوراً اجرا می‌شود. اگر ویژگی injectImmediately تنظیم شده باشد، تزریق اسکریپت بدون انتظار انجام می‌شود، حتی اگر بار کردن صفحه تمام نشده باشد. اگر اسکریپت به یک promise ارزیابی شود، مرورگر منتظر می‌ماند تا promise حل‌وفصل شود و مقدار حاصل را برمی‌گرداند.
پارامترها
-
تزریق
بازگشتی‌ها
-
Promise<InjectionResult[]>
getScripts()
browser.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
همه اسکریپت‌های کاربر ثبت‌شده به‌صورت پویا را برای این افزونه برمی‌گرداند.
پارامترها
-
فیلتر کردن
UserScriptFilter اختیاری
اگر مشخص شده باشد، این روش فقط اسکریپت‌های کاربری را که با آن مطابقت دارد برمی‌گرداند.
بازگشتی‌ها
-
Promise<RegisteredUserScript[]>
قولی که با دستورگان ثبت‌شده حل می‌شود. اگر خطایی رخ دهد، وعده رد خواهد شد.
getWorldConfigurations()
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
همه پیکربندی‌های ثبت‌شده جهان را بازیابی می‌کند.
بازگشتی‌ها
-
Promise<WorldProperties[]>
Promise که با پیکربندی‌های ثبت‌شده جهان حل می‌شود.
register()
browser.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
یک یا چند اسکریپت کاربر را برای این افزونه ثبت می‌کند.
پارامترها
-
متن‌ها
حاوی فهرستی از اسکریپت‌های کاربر برای ثبت است.
بازگشتی‌ها
-
Promise<void>
Promise که پس‌از ثبت کامل اسکریپت‌ها حل می‌شود. اگر خطایی رخ دهد، وعده رد خواهد شد.
resetWorldConfiguration()
browser.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
پیکربندی را برای دنیای دستورگان کاربر بازنشانی می‌کند. هر اسکریپتی که با شناسه مشخص‌شده به جهان تزریق شود، از پیکربندی پیش‌فرض جهان استفاده خواهد کرد.
پارامترها
-
worldId
رشته اختیاری
شناسه دنیای دستورگان کاربر برای بازنشانی. اگر حذف شود، پیکربندی دنیای پیش‌فرض را بازنشانی می‌کند.
بازگشتی‌ها
-
Promise<void>
Promise که وقتی پیکربندی بازنشانی می‌شود، حل می‌شود.
unregister()
browser.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
ثبت همه اسکریپت‌های کاربر ثبت‌شده به‌صورت پویا را برای این افزونه لغو می‌کند.
پارامترها
-
فیلتر کردن
UserScriptFilter اختیاری
اگر مشخص شده باشد، این روش فقط ثبت‌نام اسکریپت‌های کاربری را که با آن مطابقت دارند لغو می‌کند.
بازگشتی‌ها
-
Promise<void>
Promise that resolves once scripts have been fully unregistered. اگر خطایی رخ دهد، وعده رد خواهد شد.
update()
browser.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
یک یا چند اسکریپت کاربر را برای این افزونه به‌روز می‌کند.
پارامترها
-
متن‌ها
حاوی فهرستی از اسکریپت‌های کاربر برای به‌روزرسانی است. یک ویژگی فقط برای اسکریپت موجود به‌روزرسانی می‌شود اگر در این شیء مشخص شده باشد. اگر درطول تجزیه اسکریپت/اعتبارسنجی فایل خطایی رخ دهد، یا اگر شناسه‌های مشخص‌شده با اسکریپت کاملاً ثبت‌شده مطابقت نداشته باشند، هیچ اسکریپتی به‌روز نمی‌شود.
بازگشتی‌ها
-
Promise<void>
Promise که پس‌از به‌روزرسانی کامل اسکریپت‌ها حل می‌شود. اگر خطایی رخ دهد، وعده رد خواهد شد.