توضیحات
از userScripts
API برای اجرای اسکریپت های کاربر در زمینه User Scripts استفاده کنید.
مجوزها
userScripts
برای استفاده از chrome.userScripts
API، مجوز "userScripts"
را به manifest.json و "host_permissions"
برای سایتهایی که میخواهید اسکریپتها را روی آنها اجرا کنید، اضافه کنید.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
در دسترس بودن
مفاهیم و کاربرد
یک اسکریپت کاربر کمی کد است که به یک صفحه وب تزریق می شود تا ظاهر یا رفتار آن را تغییر دهد. اسکریپت ها یا توسط کاربران ایجاد می شوند یا از یک مخزن اسکریپت یا یک پسوند اسکریپت کاربر دانلود می شوند.
حالت توسعه دهنده برای کاربران برنامه افزودنی
بهعنوان یک توسعهدهنده برنامههای افزودنی، از قبل حالت برنامهنویس را در نصب Chrome فعال کردهاید. برای پسوندهای اسکریپت کاربر، کاربران شما نیز باید حالت توسعه دهنده را فعال کنند. در اینجا دستورالعمل هایی وجود دارد که می توانید آنها را کپی و در اسناد خود جایگذاری کنید.
- با وارد کردن
chrome://extensions
در یک برگه جدید، به صفحه افزونه ها بروید. (بر اساس طراحیchrome://
URL ها قابل پیوند نیستند.) با کلیک کردن روی سوئیچ کنار حالت برنامهنویس، حالت برنامهنویس را فعال کنید.
صفحه برنامه های افزودنی (chrome://extensions)
میتوانید با بررسی اینکه آیا chrome.userScripts
خطایی ایجاد میکند یا خیر، تعیین کنید که حالت برنامهنویس فعال است یا خیر. به عنوان مثال:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
در جهان های منزوی کار کنید
هم اسکریپت های کاربر و هم محتوا می توانند در یک دنیای ایزوله یا در دنیای اصلی اجرا شوند. دنیای ایزوله یک محیط اجرایی است که برای یک صفحه میزبان یا سایر برنامه های افزودنی قابل دسترسی نیست. این به یک اسکریپت کاربر اجازه می دهد تا محیط جاوا اسکریپت خود را بدون تأثیر بر صفحه میزبان یا اسکریپت های کاربر و محتوای برنامه های افزودنی دیگر تغییر دهد. برعکس، اسکریپت های کاربر (و اسکریپت های محتوا) برای صفحه میزبان یا اسکریپت های کاربر و محتوای سایر برنامه های افزودنی قابل مشاهده نیستند. اسکریپت هایی که در دنیای اصلی اجرا می شوند برای صفحات میزبان و سایر برنامه های افزودنی قابل دسترسی هستند و برای صفحات میزبان و سایر برنامه های افزودنی قابل مشاهده هستند. برای انتخاب جهان، هنگام فراخوانی userScripts.register()
"USER_SCRIPT"
یا "MAIN"
را پاس کنید.
برای پیکربندی یک خطمشی امنیتی محتوا برای دنیای USER_SCRIPT
، با userScripts.configureWorld()
تماس بگیرید:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
پیام رسانی
مانند اسکریپتهای محتوا و اسناد خارج از صفحه، اسکریپتهای کاربر با سایر بخشهای یک افزونه با استفاده از پیامرسانی ارتباط برقرار میکنند (به این معنی که میتوانند runtime.sendMessage()
و runtime.connect()
مانند هر بخش دیگری از یک برنامه افزودنی فراخوانی کنند. با این حال، آنها با استفاده از کنترلرهای رویداد اختصاصی دریافت می شوند (به این معنی که از onMessage
یا onConnect
استفاده نمی کنند). این کنترل کننده ها runtime.onUserScriptMessage
و runtime.onUserScriptConnect
نامیده می شوند. کنترلکنندههای اختصاصی شناسایی پیامها از اسکریپتهای کاربر را آسانتر میکنند، که زمینهای کمتر قابل اعتماد هستند.
قبل از ارسال پیام، باید configureWorld()
با آرگومان messaging
که روی true
تنظیم شده است فراخوانی کنید. توجه داشته باشید که هر دو آرگومان csp
و messaging
را می توان همزمان ارسال کرد.
chrome.userScripts.configureWorld({
messaging: true
});
به روز رسانی برنامه های افزودنی
اسکریپت های کاربر با به روز رسانی برنامه افزودنی پاک می شوند. میتوانید با اجرای کد در runtime.onInstalled
رویداد handler در کارمند خدمات افزونه، آنها را دوباره اضافه کنید. فقط به دلیل "update"
ارسال شده به تماس مجدد رویداد پاسخ دهید.
مثال
این مثال از نمونه userScript در مخزن نمونه ما است.
ثبت یک اسکریپت
مثال زیر یک فراخوان اولیه برای register()
را نشان می دهد. آرگومان اول آرایه ای از اشیاء است که اسکریپت هایی را که باید ثبت شوند را تعریف می کند. گزینه های بیشتری نسبت به آنچه در اینجا نشان داده شده است وجود دارد.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
انواع
ExecutionWorld
دنیای جاوا اسکریپت برای اجرای یک اسکریپت کاربر در داخل.
Enum
"اصلی" "USER_SCRIPT"
محیط اجرای DOM را مشخص می کند که محیط اجرای مشترک با جاوا اسکریپت صفحه میزبان است.
محیط اجرایی را مشخص می کند که مختص اسکریپت های کاربر است و از CSP صفحه مستثنی است.
RegisteredUserScript
خواص
- همه فریم ها
بولی اختیاری
اگر درست باشد، به همه فریمها تزریق میشود، حتی اگر فریم بالاترین فریم در برگه نباشد. هر فریم به طور مستقل برای الزامات URL بررسی می شود. اگر الزامات URL برآورده نشود، به فریم های فرزند تزریق نمی شود. پیشفرض به false میرسد، به این معنی که فقط فریم بالایی مطابقت دارد.
- Globs را حذف کنید
رشته[] اختیاری است
الگوهای حروف عام را برای صفحاتی که این اسکریپت کاربر در آنها تزریق نمی شود مشخص می کند.
- منطبق بر
رشته[] اختیاری است
صفحاتی را که این اسکریپت کاربر در غیر این صورت به آنها تزریق میشد، استثنا نمیکند. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید.
- شناسه
رشته
شناسه اسکریپت کاربر مشخص شده در تماس API. این ویژگی نباید با «_» شروع شود زیرا به عنوان پیشوند برای شناسه های اسکریپت تولید شده رزرو شده است.
- شامل Globs
رشته[] اختیاری است
الگوهای حروف عام را برای صفحاتی که این اسکریپت کاربر در آنها تزریق می شود مشخص می کند.
- js
منبع اسکریپت []
لیستی از اشیاء ScriptSource که منابع اسکریپت هایی را که باید به صفحات منطبق تزریق شوند را تعریف می کند.
- مسابقات
رشته[] اختیاری است
مشخص می کند که این اسکریپت کاربر به چه صفحاتی تزریق شود. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید. این ویژگی باید برای ${ref:register} مشخص شود.
- runAt
RunAt اختیاری است
زمان تزریق فایل های جاوا اسکریپت به صفحه وب را مشخص می کند. مقدار ترجیحی و پیش فرض
document_idle
است. - جهان
ExecutionWorld اختیاری است
محیط اجرای جاوا اسکریپت برای اجرای اسکریپت. پیش فرض
`USER_SCRIPT`
است.
ScriptSource
خواص
- کد
رشته اختیاری
رشته ای حاوی کد جاوا اسکریپت برای تزریق. دقیقاً یکی از
file
یاcode
باید مشخص شود. - فایل
رشته اختیاری
مسیر فایل جاوا اسکریپت برای تزریق نسبت به دایرکتوری ریشه پسوند. دقیقا یکی از
file
یاcode
باید مشخص شود.
UserScriptFilter
خواص
- شناسه
رشته[] اختیاری است
getScripts
فقط اسکریپت هایی را با شناسه های مشخص شده در این لیست برمی گرداند.
WorldProperties
خواص
- csp
رشته اختیاری
csp جهان را مشخص می کند. پیشفرض csp جهانی
`ISOLATED`
است. - پیام رسانی
بولی اختیاری
مشخص میکند که آیا APIهای پیامرسان در معرض نمایش هستند یا خیر. پیش فرض
false
است.
روش ها
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
محیط اجرای `USER_SCRIPT`
را پیکربندی میکند.
پارامترها
- خواص
شامل پیکربندی جهان اسکریپت کاربر است.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
همه اسکریپت های کاربر ثبت شده به صورت پویا را برای این برنامه افزودنی برمی گرداند.
پارامترها
- فیلتر کنید
UserScriptFilter اختیاری است
اگر مشخص شده باشد، این روش فقط اسکریپت های کاربری را برمی گرداند که با آن مطابقت دارند.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(scripts: RegisteredUserScript[]) => void
- اسکریپت ها
برمی گرداند
Promise< RegisteredUserScript []>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
یک یا چند اسکریپت کاربر را برای این برنامه افزودنی ثبت می کند.
پارامترها
- اسکریپت ها
حاوی لیستی از اسکریپت های کاربری که باید ثبت شوند.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
همه اسکریپت های کاربر ثبت شده به صورت پویا را برای این برنامه افزودنی لغو ثبت می کند.
پارامترها
- فیلتر کنید
UserScriptFilter اختیاری است
اگر مشخص شده باشد، این روش فقط اسکریپت های کاربری را که با آن مطابقت دارند لغو ثبت می کند.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
یک یا چند اسکریپت کاربر را برای این برنامه افزودنی به روز می کند.
پارامترها
- اسکریپت ها
حاوی لیستی از اسکریپت های کاربر که باید به روز شوند. یک ویژگی فقط در صورتی برای اسکریپت موجود به روز می شود که در این شی مشخص شده باشد. اگر در حین تجزیه اسکریپت/ اعتبارسنجی فایل خطاهایی وجود داشته باشد، یا اگر شناسه های مشخص شده با یک اسکریپت کاملاً ثبت شده مطابقت نداشته باشند، هیچ اسکریپتی به روز نمی شود.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.