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

chrome.userScripts

شرح

از 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 120+ MV3+

مفاهیم و کاربرد

یک اسکریپت کاربر کمی کد است که به یک صفحه وب تزریق می شود تا ظاهر یا رفتار آن را تغییر دهد. اسکریپت ها یا توسط کاربران ایجاد می شوند یا از یک مخزن اسکریپت یا یک پسوند اسکریپت کاربر دانلود می شوند.

حالت توسعه دهنده برای کاربران برنامه افزودنی

به‌عنوان یک توسعه‌دهنده برنامه‌های افزودنی، از قبل حالت برنامه‌نویس را در نصب 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

"اصلی"
محیط اجرای DOM را مشخص می کند که محیط اجرای مشترک با جاوا اسکریپت صفحه میزبان است.

"USER_SCRIPT"
محیط اجرایی را مشخص می کند که مختص اسکریپت های کاربر است و از 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` را پیکربندی می‌کند.

مولفه های

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

برمی گرداند

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

getScripts()

وعده

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

همه اسکریپت های کاربر ثبت شده به صورت پویا را برای این برنامه افزودنی برمی گرداند.

مولفه های

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

برمی گرداند

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

register()

وعده

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

یک یا چند اسکریپت کاربر را برای این برنامه افزودنی ثبت می کند.

مولفه های

اسکریپت ها
RegisteredUserScript []
حاوی لیستی از اسکریپت های کاربری که باید ثبت شوند.
پاسخ به تماس
عملکرد اختیاری
پارامتر 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,
)

یک یا چند اسکریپت کاربر را برای این برنامه افزودنی به روز می کند.

مولفه های

اسکریپت ها
RegisteredUserScript []
حاوی لیستی از اسکریپت های کاربر که باید به روز شوند. یک ویژگی فقط در صورتی برای اسکریپت موجود به روز می شود که در این شی مشخص شده باشد. اگر در حین تجزیه اسکریپت/ اعتبارسنجی فایل خطاهایی وجود داشته باشد، یا اگر شناسه های مشخص شده با یک اسکریپت کاملاً ثبت شده مطابقت نداشته باشند، هیچ اسکریپتی به روز نمی شود.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
()=>void
```

برمی گرداند

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