chrome.userScripts

توضیحات

از userScripts API برای اجرای اسکریپت های کاربر در زمینه User Scripts استفاده کنید.

مجوزها

userScripts

برای استفاده از User Scripts API، chrome.userScripts ، مجوز "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+

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

یک اسکریپت کاربر یک قطعه کد است که به یک صفحه وب تزریق می شود تا ظاهر یا رفتار آن را تغییر دهد. برخلاف سایر ویژگی‌های برنامه افزودنی، مانند Content Scripts و chrome.scripting API ، User Scripts API به شما امکان می‌دهد کد دلخواه را اجرا کنید. این API برای برنامه‌های افزودنی که اسکریپت‌های ارائه‌شده توسط کاربر را اجرا می‌کنند و نمی‌توانند به عنوان بخشی از بسته برنامه افزودنی شما ارسال شوند، لازم است.

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

به‌عنوان یک توسعه‌دهنده برنامه‌های افزودنی، از قبل حالت برنامه‌نویس را در نصب Chrome فعال کرده‌اید. برای پسوندهای اسکریپت کاربر، کاربران شما نیز باید حالت توسعه دهنده را فعال کنند. در اینجا دستورالعمل هایی وجود دارد که می توانید آنها را کپی و در اسناد خود جایگذاری کنید.

  1. با وارد کردن chrome://extensions در یک برگه جدید، به صفحه افزونه ها بروید. (بر اساس طراحی chrome:// URL ها قابل پیوند نیستند.)

  2. با کلیک کردن روی سوئیچ کنار حالت برنامه‌نویس، حالت برنامه‌نویس را فعال کنید.

    صفحه برنامه های افزودنی

    صفحه برنامه های افزودنی (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 صفحه مستثنی است.

InjectionResult

Chrome 135+

خواص

  • شناسه سند

    رشته

    سند مرتبط با تزریق

  • خطا

    رشته اختیاری

    خطا، در صورت وجود. error و result متقابل هستند.

  • frameId

    شماره

    قاب مرتبط با تزریق

  • نتیجه

    هر اختیاری

    نتیجه اجرای اسکریپت.

InjectionTarget

Chrome 135+

خواص

  • همه فریم ها

    بولی اختیاری

    اینکه آیا اسکریپت باید به همه فریم‌های داخل برگه تزریق شود یا خیر. پیش فرض به نادرست. اگر frameIds مشخص شده باشد، این نباید درست باشد.

  • شناسه های اسناد

    رشته[] اختیاری است

    شناسه های documentIds خاص برای تزریق. اگر frameIds تنظیم شده باشد، این نباید تنظیم شود.

  • FrameIds

    شماره[] اختیاری

    شناسه فریم های خاص برای تزریق

  • tabId

    شماره

    شناسه برگه ای که به آن تزریق می شود.

RegisteredUserScript

خواص

  • همه فریم ها

    بولی اختیاری

    اگر درست باشد، به همه فریم‌ها تزریق می‌شود، حتی اگر فریم بالاترین فریم در برگه نباشد. هر فریم به طور مستقل برای الزامات URL بررسی می شود. اگر الزامات URL برآورده نشود، به فریم های فرزند تزریق نمی شود. پیش‌فرض به false می‌رسد، به این معنی که فقط فریم بالایی مطابقت دارد.

  • Globs را حذف کنید

    رشته[] اختیاری است

    الگوهای حروف عام را برای صفحاتی که این اسکریپت کاربر در آنها تزریق نمی شود مشخص می کند.

  • منطبق بر

    رشته[] اختیاری است

    صفحاتی را که این اسکریپت کاربر در غیر این صورت به آنها تزریق می‌شد، استثنا نمی‌کند. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید.

  • شناسه

    رشته

    شناسه اسکریپت کاربر مشخص شده در تماس API. این ویژگی نباید با «_» شروع شود زیرا به عنوان پیشوند برای شناسه های اسکریپت تولید شده رزرو شده است.

  • شامل Globs

    رشته[] اختیاری است

    الگوهای حروف عام را برای صفحاتی که این اسکریپت کاربر در آنها تزریق می شود مشخص می کند.

  • js

    ScriptSource [] اختیاری است

    لیستی از اشیاء ScriptSource که منابع اسکریپت هایی را که باید به صفحات منطبق تزریق شوند را تعریف می کند. این ویژگی باید برای ${ref:register} مشخص شود، و زمانی که مشخص شد باید یک آرایه غیر خالی باشد.

  • مسابقات

    رشته[] اختیاری است

    مشخص می کند که این اسکریپت کاربر به چه صفحاتی تزریق شود. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید. این ویژگی باید برای ${ref:register} مشخص شود.

  • runAt

    RunAt اختیاری است

    زمان تزریق فایل های جاوا اسکریپت به صفحه وب را مشخص می کند. مقدار ترجیحی و پیش فرض document_idle است.

  • جهان

    ExecutionWorld اختیاری است

    محیط اجرای جاوا اسکریپت برای اجرای اسکریپت. پیش فرض `USER_SCRIPT` است.

  • شناسه جهان

    رشته اختیاری

    Chrome 133+

    شناسه جهان اسکریپت کاربر را برای اجرا مشخص می کند. اگر حذف شود، اسکریپت در دنیای پیش فرض اسکریپت کاربر اجرا می شود. فقط در صورتی معتبر است که world حذف شده باشد یا USER_SCRIPT باشد. مقادیر با زیرخط اصلی ( _ ) محفوظ است.

ScriptSource

خواص

  • کد

    رشته اختیاری

    رشته ای حاوی کد جاوا اسکریپت برای تزریق. دقیقا یکی از file یا code باید مشخص شود.

  • فایل

    رشته اختیاری

    مسیر فایل جاوا اسکریپت برای تزریق نسبت به دایرکتوری ریشه پسوند. دقیقا یکی از file یا code باید مشخص شود.

UserScriptFilter

خواص

  • شناسه

    رشته[] اختیاری است

    getScripts فقط اسکریپت هایی را با شناسه های مشخص شده در این لیست برمی گرداند.

UserScriptInjection

Chrome 135+

خواص

  • بلافاصله تزریق کنید

    بولی اختیاری

    اینکه آیا تزریق باید در اسرع وقت در هدف آغاز شود یا خیر. توجه داشته باشید که این تضمینی نیست که تزریق قبل از بارگیری صفحه انجام شود، زیرا ممکن است تا زمانی که اسکریپت به هدف می رسد، صفحه قبلاً بارگذاری شده باشد.

  • لیستی از اشیاء ScriptSource که منابع اسکریپت هایی را که باید به هدف تزریق شوند را تعریف می کند.

  • جزئیات مشخص کننده هدفی که اسکریپت به آن تزریق شود.

  • جهان

    ExecutionWorld اختیاری است

    "جهان" جاوا اسکریپت برای اجرای اسکریپت. پیش فرض USER_SCRIPT است.

  • شناسه جهان

    رشته اختیاری

    شناسه جهان اسکریپت کاربر را برای اجرا مشخص می کند. اگر حذف شود، اسکریپت در دنیای پیش فرض اسکریپت کاربر اجرا می شود. فقط در صورتی معتبر است که world حذف شده باشد یا USER_SCRIPT باشد. مقادیر با زیرخط اصلی ( _ ) محفوظ است.

WorldProperties

خواص

  • csp

    رشته اختیاری

    csp جهان را مشخص می کند. پیش‌فرض csp جهانی `ISOLATED` است.

  • پیام رسانی

    بولی اختیاری

    مشخص می‌کند که آیا APIهای پیام‌رسان در معرض نمایش هستند یا خیر. پیش فرض false است.

  • شناسه جهان

    رشته اختیاری

    Chrome 133+

    شناسه دنیای اسکریپت کاربر خاص را برای به روز رسانی مشخص می کند. در صورت عدم ارائه، ویژگی های دنیای اسکریپت کاربر پیش فرض را به روز می کند. مقادیر با زیرخط اصلی ( _ ) محفوظ است.

روش ها

configureWorld()

قول بده
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

محیط اجرای `USER_SCRIPT` را پیکربندی می‌کند.

پارامترها

  • خواص

    WorldProperties

    شامل پیکربندی جهان اسکریپت کاربر است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

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

execute()

Promise Chrome 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

یک اسکریپت را به یک زمینه هدف تزریق می کند. به‌طور پیش‌فرض، اسکریپت در document_idle اجرا می‌شود، یا اگر صفحه قبلاً بارگیری شده باشد، بلافاصله اجرا می‌شود. اگر ویژگی injectImmediately تنظیم شود، اسکریپت بدون انتظار تزریق می‌شود، حتی اگر صفحه بارگذاری تمام نشده باشد. اگر اسکریپت به یک وعده ارزیابی شود، مرورگر منتظر خواهد ماند تا وعده تسویه شود و مقدار حاصل را برگرداند.

پارامترها

برمی گرداند

  • Promise< InjectionResult []>

    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 ارسال می شود حل می شود.

getWorldConfigurations()

Promise Chrome 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

همه پیکربندی های ثبت شده جهان را بازیابی می کند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (worlds: WorldProperties[]) => void

برمی گرداند

  • Promise< WorldProperties []>

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

register()

قول بده
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

پارامترها

  • اسکریپت ها

    RegisteredUserScript []

    حاوی لیستی از اسکریپت های کاربری که باید ثبت شوند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

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

resetWorldConfiguration()

Promise Chrome 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  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,
)

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

پارامترها

  • اسکریپت ها

    RegisteredUserScript []

    حاوی لیستی از اسکریپت های کاربر که باید به روز شوند. یک ویژگی فقط در صورتی برای اسکریپت موجود به روز می شود که در این شی مشخص شده باشد. اگر در حین تجزیه اسکریپت/ اعتبارسنجی فایل خطاهایی وجود داشته باشد، یا اگر شناسه های مشخص شده با یک اسکریپت کاملاً ثبت شده مطابقت نداشته باشند، هیچ اسکریپتی به روز نمی شود.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

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

،

توضیحات

از userScripts API برای اجرای اسکریپت های کاربر در زمینه User Scripts استفاده کنید.

مجوزها

userScripts

برای استفاده از User Scripts API، chrome.userScripts ، مجوز "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+

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

یک اسکریپت کاربر یک قطعه کد است که به یک صفحه وب تزریق می شود تا ظاهر یا رفتار آن را تغییر دهد. برخلاف سایر ویژگی‌های برنامه افزودنی، مانند Content Scripts و chrome.scripting API ، User Scripts API به شما امکان می‌دهد کد دلخواه را اجرا کنید. این API برای برنامه‌های افزودنی که اسکریپت‌های ارائه‌شده توسط کاربر را اجرا می‌کنند و نمی‌توانند به عنوان بخشی از بسته برنامه افزودنی شما ارسال شوند، لازم است.

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

به‌عنوان یک توسعه‌دهنده برنامه‌های افزودنی، از قبل حالت برنامه‌نویس را در نصب Chrome فعال کرده‌اید. برای پسوندهای اسکریپت کاربر، کاربران شما نیز باید حالت توسعه دهنده را فعال کنند. در اینجا دستورالعمل هایی وجود دارد که می توانید آنها را کپی و در اسناد خود جایگذاری کنید.

  1. با وارد کردن chrome://extensions در یک برگه جدید، به صفحه افزونه ها بروید. (بر اساس طراحی chrome:// URL ها قابل پیوند نیستند.)

  2. با کلیک کردن روی سوئیچ کنار حالت برنامه‌نویس، حالت برنامه‌نویس را فعال کنید.

    صفحه برنامه های افزودنی

    صفحه برنامه های افزودنی (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 صفحه مستثنی است.

InjectionResult

Chrome 135+

خواص

  • شناسه سند

    رشته

    سند مرتبط با تزریق

  • خطا

    رشته اختیاری

    خطا، در صورت وجود. error و result متقابل هستند.

  • frameId

    شماره

    قاب مرتبط با تزریق

  • نتیجه

    هر اختیاری

    نتیجه اجرای اسکریپت.

InjectionTarget

Chrome 135+

خواص

  • همه فریم ها

    بولی اختیاری

    اینکه آیا اسکریپت باید به همه فریم‌های داخل برگه تزریق شود یا خیر. پیش فرض به نادرست. اگر frameIds مشخص شده باشد، این نباید درست باشد.

  • شناسه های اسناد

    رشته[] اختیاری است

    شناسه های documentIds خاص برای تزریق. اگر frameIds تنظیم شده باشد، این نباید تنظیم شود.

  • FrameIds

    شماره[] اختیاری

    شناسه فریم های خاص برای تزریق

  • tabId

    شماره

    شناسه برگه ای که به آن تزریق می شود.

RegisteredUserScript

خواص

  • همه فریم ها

    بولی اختیاری

    اگر درست باشد، به همه فریم‌ها تزریق می‌شود، حتی اگر فریم بالاترین فریم در برگه نباشد. هر فریم به طور مستقل برای الزامات URL بررسی می شود. اگر الزامات URL برآورده نشود، به فریم های فرزند تزریق نمی شود. پیش‌فرض به false می‌رسد، به این معنی که فقط فریم بالایی مطابقت دارد.

  • Globs را حذف کنید

    رشته[] اختیاری است

    الگوهای حروف عام را برای صفحاتی که این اسکریپت کاربر در آنها تزریق نمی شود مشخص می کند.

  • منطبق بر

    رشته[] اختیاری است

    صفحاتی را که این اسکریپت کاربر در غیر این صورت به آنها تزریق می‌شد، استثنا نمی‌کند. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید.

  • شناسه

    رشته

    شناسه اسکریپت کاربر مشخص شده در تماس API. این ویژگی نباید با «_» شروع شود زیرا به عنوان پیشوند برای شناسه های اسکریپت تولید شده رزرو شده است.

  • شامل Globs

    رشته[] اختیاری است

    الگوهای حروف عام را برای صفحاتی که این اسکریپت کاربر در آنها تزریق می شود مشخص می کند.

  • js

    ScriptSource [] اختیاری است

    لیستی از اشیاء ScriptSource که منابع اسکریپت هایی را که باید به صفحات منطبق تزریق شوند را تعریف می کند. این ویژگی باید برای ${ref:register} مشخص شود، و زمانی که مشخص شد باید یک آرایه غیر خالی باشد.

  • مسابقات

    رشته[] اختیاری است

    مشخص می کند که این اسکریپت کاربر به چه صفحاتی تزریق شود. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید. این ویژگی باید برای ${ref:register} مشخص شود.

  • runAt

    RunAt اختیاری است

    زمان تزریق فایل های جاوا اسکریپت به صفحه وب را مشخص می کند. مقدار ترجیحی و پیش فرض document_idle است.

  • جهان

    ExecutionWorld اختیاری است

    محیط اجرای جاوا اسکریپت برای اجرای اسکریپت. پیش فرض `USER_SCRIPT` است.

  • شناسه جهان

    رشته اختیاری

    Chrome 133+

    شناسه جهان اسکریپت کاربر را برای اجرا مشخص می کند. اگر حذف شود، اسکریپت در دنیای پیش فرض اسکریپت کاربر اجرا می شود. فقط در صورتی معتبر است که world حذف شده باشد یا USER_SCRIPT باشد. مقادیر با زیرخط اصلی ( _ ) محفوظ است.

ScriptSource

خواص

  • کد

    رشته اختیاری

    رشته ای حاوی کد جاوا اسکریپت برای تزریق. دقیقا یکی از file یا code باید مشخص شود.

  • فایل

    رشته اختیاری

    مسیر فایل جاوا اسکریپت برای تزریق نسبت به دایرکتوری ریشه پسوند. دقیقا یکی از file یا code باید مشخص شود.

UserScriptFilter

خواص

  • شناسه

    رشته[] اختیاری است

    getScripts فقط اسکریپت هایی را با شناسه های مشخص شده در این لیست برمی گرداند.

UserScriptInjection

Chrome 135+

خواص

  • بلافاصله تزریق کنید

    بولی اختیاری

    اینکه آیا تزریق باید در اسرع وقت در هدف آغاز شود یا خیر. توجه داشته باشید که این تضمینی نیست که تزریق قبل از بارگیری صفحه انجام شود، زیرا ممکن است تا زمانی که اسکریپت به هدف می رسد، صفحه قبلاً بارگذاری شده باشد.

  • لیستی از اشیاء ScriptSource که منابع اسکریپت هایی را که باید به هدف تزریق شوند را تعریف می کند.

  • جزئیات مشخص کننده هدفی که اسکریپت به آن تزریق شود.

  • جهان

    ExecutionWorld اختیاری است

    "جهان" جاوا اسکریپت برای اجرای اسکریپت. پیش فرض USER_SCRIPT است.

  • شناسه جهان

    رشته اختیاری

    شناسه جهان اسکریپت کاربر را برای اجرا مشخص می کند. اگر حذف شود، اسکریپت در دنیای پیش فرض اسکریپت کاربر اجرا می شود. فقط در صورتی معتبر است که world حذف شده باشد یا USER_SCRIPT باشد. مقادیر با زیرخط اصلی ( _ ) محفوظ است.

WorldProperties

خواص

  • csp

    رشته اختیاری

    csp جهان را مشخص می کند. پیش‌فرض csp جهانی `ISOLATED` است.

  • پیام رسانی

    بولی اختیاری

    مشخص می‌کند که آیا APIهای پیام‌رسان در معرض نمایش هستند یا خیر. پیش فرض false است.

  • شناسه جهان

    رشته اختیاری

    Chrome 133+

    شناسه دنیای اسکریپت کاربر خاص را برای به روز رسانی مشخص می کند. در صورت عدم ارائه، ویژگی های دنیای اسکریپت کاربر پیش فرض را به روز می کند. مقادیر با زیرخط اصلی ( _ ) محفوظ است.

روش ها

configureWorld()

قول بده
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

محیط اجرای `USER_SCRIPT` را پیکربندی می‌کند.

پارامترها

  • خواص

    WorldProperties

    شامل پیکربندی جهان اسکریپت کاربر است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

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

execute()

Promise Chrome 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

یک اسکریپت را به یک زمینه هدف تزریق می کند. به‌طور پیش‌فرض، اسکریپت در document_idle اجرا می‌شود، یا اگر صفحه قبلاً بارگیری شده باشد، بلافاصله اجرا می‌شود. اگر ویژگی injectImmediately تنظیم شود، اسکریپت بدون انتظار تزریق می‌شود، حتی اگر صفحه بارگذاری تمام نشده باشد. اگر اسکریپت به یک وعده ارزیابی شود، مرورگر منتظر خواهد ماند تا وعده تسویه شود و مقدار حاصل را برگرداند.

پارامترها

برمی گرداند

  • Promise< InjectionResult []>

    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 ارسال می شود حل می شود.

getWorldConfigurations()

Promise Chrome 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

همه پیکربندی های ثبت شده جهان را بازیابی می کند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (worlds: WorldProperties[]) => void

برمی گرداند

  • Promise< WorldProperties []>

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

register()

قول بده
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

پارامترها

  • اسکریپت ها

    RegisteredUserScript []

    حاوی لیستی از اسکریپت های کاربری که باید ثبت شوند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

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

resetWorldConfiguration()

Promise Chrome 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  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,
)

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

پارامترها

  • اسکریپت ها

    RegisteredUserScript []

    حاوی لیستی از اسکریپت های کاربر که باید به روز شوند. یک ویژگی فقط در صورتی برای اسکریپت موجود به روز می شود که در این شی مشخص شده باشد. اگر در حین تجزیه اسکریپت/ اعتبارسنجی فایل خطاهایی وجود داشته باشد، یا اگر شناسه های مشخص شده با یک اسکریپت کاملاً ثبت شده مطابقت نداشته باشند، هیچ اسکریپتی به روز نمی شود.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

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

،

توضیحات

از userScripts API برای اجرای اسکریپت های کاربر در زمینه User Scripts استفاده کنید.

مجوزها

userScripts

برای استفاده از User Scripts API، chrome.userScripts ، مجوز "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+

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

یک اسکریپت کاربر یک قطعه کد است که به یک صفحه وب تزریق می شود تا ظاهر یا رفتار آن را تغییر دهد. برخلاف سایر ویژگی‌های برنامه افزودنی، مانند Content Scripts و chrome.scripting API ، User Scripts API به شما امکان می‌دهد کد دلخواه را اجرا کنید. این API برای برنامه‌های افزودنی که اسکریپت‌های ارائه‌شده توسط کاربر را اجرا می‌کنند و نمی‌توانند به عنوان بخشی از بسته برنامه افزودنی شما ارسال شوند، لازم است.

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

به‌عنوان یک توسعه‌دهنده برنامه‌های افزودنی، از قبل حالت برنامه‌نویس را در نصب Chrome فعال کرده‌اید. برای پسوندهای اسکریپت کاربر، کاربران شما نیز باید حالت توسعه دهنده را فعال کنند. در اینجا دستورالعمل هایی وجود دارد که می توانید آنها را کپی و در اسناد خود جایگذاری کنید.

  1. با وارد کردن chrome://extensions در یک برگه جدید، به صفحه افزونه ها بروید. (بر اساس طراحی chrome:// URL ها قابل پیوند نیستند.)

  2. با کلیک کردن روی سوئیچ کنار حالت برنامه‌نویس، حالت برنامه‌نویس را فعال کنید.

    صفحه برنامه های افزودنی

    صفحه برنامه های افزودنی (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 صفحه مستثنی است.

InjectionResult

Chrome 135+

خواص

  • شناسه سند

    رشته

    سند مرتبط با تزریق

  • خطا

    رشته اختیاری

    خطا، در صورت وجود. error و result متقابل هستند.

  • frameId

    شماره

    قاب مرتبط با تزریق

  • نتیجه

    هر اختیاری

    نتیجه اجرای اسکریپت.

InjectionTarget

Chrome 135+

خواص

  • همه فریم ها

    بولی اختیاری

    اینکه آیا اسکریپت باید به همه فریم‌های داخل برگه تزریق شود یا خیر. پیش فرض به نادرست. اگر frameIds مشخص شده باشد، این نباید درست باشد.

  • شناسه های اسناد

    رشته[] اختیاری است

    شناسه های documentIds خاص برای تزریق. اگر frameIds تنظیم شده باشد، این نباید تنظیم شود.

  • FrameIds

    شماره[] اختیاری

    شناسه فریم های خاص برای تزریق

  • tabId

    شماره

    شناسه برگه ای که به آن تزریق می شود.

RegisteredUserScript

خواص

  • همه فریم ها

    بولی اختیاری

    اگر درست باشد، به همه فریم‌ها تزریق می‌شود، حتی اگر فریم بالاترین فریم در برگه نباشد. هر فریم به طور مستقل برای الزامات URL بررسی می شود. اگر الزامات URL برآورده نشود، به فریم های فرزند تزریق نمی شود. پیش فرض به دروغ ، به این معنی که فقط قاب بالا همسان است.

  • Gloadglobs

    رشته [] اختیاری

    الگوهای کارت وحشی را برای صفحاتی که این اسکریپت کاربر به آن تزریق نمی شود ، مشخص می کند.

  • استثناء

    رشته [] اختیاری

    صفحاتی را که این اسکریپت کاربر در غیر این صورت تزریق می شود ، مستثنی می کند. برای اطلاعات بیشتر در مورد نحو این رشته ها به الگوهای مسابقه مراجعه کنید.

  • شناسه

    رشته

    شناسه اسکریپت کاربر مشخص شده در تماس API. این ویژگی نباید با یک "_" شروع شود زیرا به عنوان پیشوند شناسه های اسکریپت تولید شده محفوظ است.

  • شامل globs

    رشته [] اختیاری

    الگوهای کارت وحشی را برای صفحاتی که این اسکریپت کاربر به آن تزریق می شود ، مشخص می کند.

  • js

    scriptsource [] اختیاری

    لیست اشیاء ScriptSource که منابع اسکریپت ها را در صفحات تطبیق تزریق می کنند. این ویژگی باید برای $ {Ref: Register} مشخص شود ، و در صورت مشخص شدن ، باید یک آرایه غیر خالی باشد.

  • مسابقات

    رشته [] اختیاری

    مشخص می کند که این اسکریپت کاربر به کدام صفحات تزریق می شود. برای اطلاعات بیشتر در مورد نحو این رشته ها به الگوهای مسابقه مراجعه کنید. این ویژگی باید برای $ {Ref: Register} مشخص شود.

  • رونات

    Runat اختیاری

    مشخص می کند که پرونده های JavaScript به صفحه وب تزریق می شوند. مقدار ترجیحی و پیش فرض document_idle است.

  • جهان

    EXECUTIONWORLD اختیاری

    محیط اجرای JavaScript برای اجرای اسکریپت. پیش فرض `USER_SCRIPT` است.

  • جهان

    رشته ای اختیاری

    Chrome 133+

    در صورت حذف ، اسکریپت را در دنیای اسکریپت کاربر پیش فرض اجرا می کند. فقط اگر world حذف شده باشد یا USER_SCRIPT باشد معتبر است. مقادیر با زیرکرهای پیشرو ( _ ) محفوظ است.

ScriptSource

خواص

  • کد

    رشته ای اختیاری

    رشته ای حاوی کد JavaScript برای تزریق. دقیقاً یکی از file یا code باید مشخص شود.

  • فایل

    رشته ای اختیاری

    مسیر پرونده JavaScript برای تزریق نسبت به دایرکتوری ریشه پسوند. دقیقاً یکی از file یا code باید مشخص شود.

UserScriptFilter

خواص

  • شناسه

    رشته [] اختیاری

    getScripts فقط اسکریپت ها را با شناسه های مشخص شده در این لیست برمی گرداند.

UserScriptInjection

Chrome 135+

خواص

  • به طور مستقیم

    بولی اختیاری

    این که آیا تزریق باید در اسرع وقت در هدف ایجاد شود. توجه داشته باشید که این تضمینی نیست که تزریق قبل از بار صفحه رخ خواهد داد ، زیرا ممکن است این صفحه تا زمانی که اسکریپت به هدف برسد بارگذاری شده باشد.

  • لیست اشیاء ScriptSource که منابع اسکریپت ها را که به هدف تزریق می شوند ، تعیین می کنند.

  • جزئیات مشخص شده هدف را برای تزریق اسکریپت مشخص می کند.

  • جهان

    EXECUTIONWORLD اختیاری

    JavaScript "جهان" برای اجرای اسکریپت. پیش فرض USER_SCRIPT است.

  • جهان

    رشته ای اختیاری

    در صورت حذف ، اسکریپت را در دنیای اسکریپت کاربر پیش فرض اجرا می کند. فقط اگر world حذف شده باشد یا USER_SCRIPT باشد معتبر است. مقادیر با زیرکرهای پیشرو ( _ ) محفوظ است.

WorldProperties

خواص

  • csp

    رشته ای اختیاری

    جهان CSP را مشخص می کند. پیش فرض جهان `ISOLATED` CSP است.

  • پیام رسانی

    بولی اختیاری

    مشخص می کند که آیا API های پیام رسانی در معرض دید هستند یا خیر. پیش فرض false است.

  • جهان

    رشته ای اختیاری

    Chrome 133+

    شناسه دنیای اسکریپت کاربر خاص را برای به روزرسانی مشخص می کند. در صورت عدم ارائه ، خصوصیات دنیای اسکریپت کاربر پیش فرض را به روز می کند. مقادیر با زیرکرهای پیشرو ( _ ) محفوظ است.

روش ها

configureWorld()

قول بده
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

محیط اجرای `USER_SCRIPT` پیکربندی می کند.

پارامترها

  • حاوی پیکربندی دنیای اسکریپت کاربر است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

execute()

قول Chrome 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

یک اسکریپت را به یک زمینه هدف تزریق می کند. به طور پیش فرض ، اسکریپت در document_idle اجرا می شود ، یا بلافاصله اگر صفحه قبلاً بارگیری شده باشد. اگر خاصیت injectImmediately تنظیم شود ، اسکریپت بدون انتظار تزریق می شود ، حتی اگر صفحه بارگیری نشده باشد. اگر اسکریپت به یک وعده ارزیابی کند ، مرورگر منتظر قول تسویه و بازگشت مقدار حاصل خواهد بود.

پارامترها

برمی گرداند

  • وعده < تزریق []>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

getScripts()

قول بده
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

پارامترها

  • فیلتر

    usercriptfilter اختیاری

    در صورت مشخص شدن ، این روش فقط اسکریپت های کاربر را که با آن مطابقت دارد برمی گرداند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (scripts: RegisteredUserScript[]) => void

برمی گرداند

  • وعده < RegistenduScript []>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

getWorldConfigurations()

قول Chrome 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

همه تنظیمات ثبت شده جهان را بازیابی می کند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (worlds: WorldProperties[]) => void

برمی گرداند

  • وعده < WorldProperties []>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

register()

قول بده
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

پارامترها

  • اسکریپت ها

    RegireedUserscript []

    شامل لیستی از اسکریپت های کاربر برای ثبت نام است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

resetWorldConfiguration()

قول Chrome 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

تنظیمات را برای دنیای اسکریپت کاربر تنظیم مجدد می کند. هر اسکریپتی که با شناسه مشخص به جهان تزریق می شود ، از پیکربندی پیش فرض جهان استفاده می کند.

پارامترها

  • جهان

    رشته ای اختیاری

    شناسه دنیای اسکریپت کاربر برای تنظیم مجدد. در صورت حذف ، پیکربندی پیش فرض جهان را مجدداً تنظیم می کند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

unregister()

قول بده
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

پارامترها

  • فیلتر

    usercriptfilter اختیاری

    در صورت مشخص شدن ، این روش فقط اسکریپت های کاربر را که با آن مطابقت دارد ، ثبت نمی کند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

update()

قول بده
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

پارامترها

  • اسکریپت ها

    RegireedUserscript []

    شامل لیستی از اسکریپت های کاربر برای به روزرسانی است. اگر در این شیء مشخص شود ، یک ویژگی فقط برای اسکریپت موجود به روز می شود. اگر در هنگام اعتبار سنجی اسکریپت/اعتبار سنجی پرونده خطایی وجود داشته باشد ، یا اگر شناسه های مشخص شده با یک اسکریپت کاملاً ثبت شده مطابقت ندارند ، هیچ اسکریپت به روز نمی شود.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

،

توضیحات

برای اجرای اسکریپت های کاربر در متن اسکریپت های کاربر از API API userScripts استفاده کنید.

مجوزها

userScripts

برای استفاده از API SCRIPTS کاربر ، chrome.userScripts ، مجوز "userScripts" را به مانیفست خود اضافه کنید. json و "host_permissions" برای سایت هایی که می خواهید اسکریپت ها را اجرا کنید.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

در دسترس بودن

Chrome 120+ MV3+

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

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

حالت توسعه دهنده برای کاربران پسوند

به عنوان یک توسعه دهنده پسوند ، شما در حال حاضر حالت توسعه دهنده را در نصب Chrome فعال کرده اید. برای برنامه های افزودنی اسکریپت کاربر ، کاربران شما نیز باید حالت توسعه دهنده را فعال کنند. در اینجا دستورالعمل هایی وجود دارد که می توانید در مستندات خود کپی و چسباندن کنید.

  1. با وارد کردن chrome://extensions در یک برگه جدید به صفحه پسوند بروید. (توسط طراحی chrome:// URL ها قابل پیوند نیستند.)

  2. با کلیک کردن روی سوئیچ کنار حالت برنامه‌نویس، حالت برنامه‌نویس را فعال کنید.

    صفحه پسوند

    صفحه پسوند (کروم: // پسوند)

می توانید با بررسی اینکه آیا chrome.userScripts خطایی را به وجود می آورد ، تعیین کنید که آیا حالت توسعه دهنده فعال است. به عنوان مثال:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

کار در جهان های منزوی

هر دو اسکریپت های کاربر و محتوا می توانند در دنیای منزوی یا در دنیای اصلی اجرا شوند. دنیای منزوی یک محیط اعدام است که برای یک صفحه میزبان یا سایر پسوندها قابل دسترسی نیست. این امر به یک اسکریپت کاربر اجازه می دهد تا محیط JavaScript خود را بدون تأثیرگذاری در صفحه میزبان یا اسکریپت های کاربر و محتوای دیگر پسوندها تغییر دهد. در مقابل ، اسکریپت های کاربر (و اسکریپت های محتوا) برای صفحه میزبان یا اسکریپت های کاربر و محتوا از پسوندهای دیگر قابل مشاهده نیستند. اسکریپت هایی که در دنیای اصلی در حال اجرا هستند برای صفحات میزبان و سایر برنامه های افزودنی قابل دسترسی هستند و برای صفحات میزبان و سایر پسوندها قابل مشاهده هستند. برای انتخاب جهان ، هنگام فراخوانی 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 نامیده می شوند. دستگیرندگان اختصاصی ، شناسایی پیام ها از اسکریپت های کاربر را که یک زمینه کمتر محقق هستند ، آسانتر می کند.

قبل از ارسال پیام ، باید با استدلال messaging که روی true تنظیم شده است ، با configureWorld() تماس بگیرید. توجه داشته باشید که هر دو استدلال csp و messaging می توانند همزمان تصویب شوند.

chrome.userScripts.configureWorld({
  messaging: true
});

به روزرسانی های پسوند

اسکریپت های کاربر هنگام بروزرسانی پسوند پاک می شوند. می توانید با اجرای کد در runtime.onInstalled آنها را با استفاده از برنامه کاربردی برنامه افزودنی در زمان اجرا اضافه کنید. فقط به دلیل "update" که به تماس تلفنی رسیده است پاسخ دهید.

مثال

این مثال از نمونه کاربران در مخزن نمونه ما است.

یک اسکریپت را ثبت کنید

مثال زیر یک تماس اصلی برای register() را نشان می دهد. استدلال اول مجموعه ای از اشیاء است که اسکریپت ها را برای ثبت نام تعریف می کنند. گزینه های بیشتری از آنچه در اینجا نشان داده شده است وجود دارد.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

انواع

ExecutionWorld

دنیای JavaScript برای اجرای یک اسکریپت کاربر در داخل.

Enum

"اصلی"
محیط اجرای DOM را که محیط اعدام است که با JavaScript صفحه میزبان به اشتراک گذاشته شده است ، مشخص می کند.

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

InjectionResult

Chrome 135+

خواص

  • مستند

    رشته

    سند مرتبط با تزریق.

  • خطا

    رشته ای اختیاری

    خطا ، در صورت وجود. error و result متقابل است.

  • قاب

    شماره

    قاب مرتبط با تزریق.

  • نتیجه

    هر اختیاری

    نتیجه اجرای فیلمنامه.

InjectionTarget

Chrome 135+

خواص

  • همه چیز

    بولی اختیاری

    این که آیا اسکریپت باید به تمام فریم های موجود در برگه تزریق شود. پیش فرض به نادرست. در صورت مشخص شدن frameIds این نباید صحیح باشد.

  • مستندات

    رشته [] اختیاری

    شناسه های DocumentID های خاص برای تزریق. در صورت تنظیم frameIds نباید این تنظیم شود.

  • قاب

    شماره [] اختیاری

    شناسه فریم های خاص برای تزریق.

  • زبانه

    شماره

    شناسه برگه ای که در آن تزریق می شود.

RegisteredUserScript

خواص

  • همه چیز

    بولی اختیاری

    اگر درست باشد ، به تمام فریم ها تزریق می شود ، حتی اگر قاب بهترین قاب در برگه نباشد. هر فریم به طور مستقل برای نیازهای URL بررسی می شود. در صورت عدم تحقق الزامات URL ، به فریم های کودک تزریق نمی شود. پیش فرض به دروغ ، به این معنی که فقط قاب بالا همسان است.

  • Gloadglobs

    رشته [] اختیاری

    الگوهای کارت وحشی را برای صفحاتی که این اسکریپت کاربر به آن تزریق نمی شود ، مشخص می کند.

  • استثناء

    رشته [] اختیاری

    صفحاتی را که این اسکریپت کاربر در غیر این صورت تزریق می شود ، مستثنی می کند. برای اطلاعات بیشتر در مورد نحو این رشته ها به الگوهای مسابقه مراجعه کنید.

  • شناسه

    رشته

    شناسه اسکریپت کاربر مشخص شده در تماس API. این ویژگی نباید با یک "_" شروع شود زیرا به عنوان پیشوند شناسه های اسکریپت تولید شده محفوظ است.

  • شامل globs

    رشته [] اختیاری

    الگوهای کارت وحشی را برای صفحاتی که این اسکریپت کاربر به آن تزریق می شود ، مشخص می کند.

  • js

    scriptsource [] اختیاری

    لیست اشیاء ScriptSource که منابع اسکریپت ها را در صفحات تطبیق تزریق می کنند. این ویژگی باید برای $ {Ref: Register} مشخص شود ، و در صورت مشخص شدن ، باید یک آرایه غیر خالی باشد.

  • مسابقات

    رشته [] اختیاری

    مشخص می کند که این اسکریپت کاربر به کدام صفحات تزریق می شود. برای اطلاعات بیشتر در مورد نحو این رشته ها به الگوهای مسابقه مراجعه کنید. این ویژگی باید برای $ {Ref: Register} مشخص شود.

  • رونات

    Runat اختیاری

    مشخص می کند که پرونده های JavaScript به صفحه وب تزریق می شوند. مقدار ترجیحی و پیش فرض document_idle است.

  • جهان

    EXECUTIONWORLD اختیاری

    محیط اجرای JavaScript برای اجرای اسکریپت. پیش فرض `USER_SCRIPT` است.

  • جهان

    رشته ای اختیاری

    Chrome 133+

    در صورت حذف ، اسکریپت را در دنیای اسکریپت کاربر پیش فرض اجرا می کند. فقط اگر world حذف شده باشد یا USER_SCRIPT باشد معتبر است. مقادیر با زیرکرهای پیشرو ( _ ) محفوظ است.

ScriptSource

خواص

  • کد

    رشته ای اختیاری

    رشته ای حاوی کد JavaScript برای تزریق. دقیقاً یکی از file یا code باید مشخص شود.

  • فایل

    رشته ای اختیاری

    مسیر پرونده JavaScript برای تزریق نسبت به دایرکتوری ریشه پسوند. دقیقاً یکی از file یا code باید مشخص شود.

UserScriptFilter

خواص

  • شناسه

    رشته [] اختیاری

    getScripts فقط اسکریپت ها را با شناسه های مشخص شده در این لیست برمی گرداند.

UserScriptInjection

Chrome 135+

خواص

  • به طور مستقیم

    بولی اختیاری

    این که آیا تزریق باید در اسرع وقت در هدف ایجاد شود. توجه داشته باشید که این تضمینی نیست که تزریق قبل از بار صفحه رخ خواهد داد ، زیرا ممکن است این صفحه تا زمانی که اسکریپت به هدف برسد بارگذاری شده باشد.

  • لیست اشیاء ScriptSource که منابع اسکریپت ها را که به هدف تزریق می شوند ، تعیین می کنند.

  • جزئیات مشخص شده هدف را برای تزریق اسکریپت مشخص می کند.

  • جهان

    EXECUTIONWORLD اختیاری

    JavaScript "جهان" برای اجرای اسکریپت. پیش فرض USER_SCRIPT است.

  • جهان

    رشته ای اختیاری

    در صورت حذف ، اسکریپت را در دنیای اسکریپت کاربر پیش فرض اجرا می کند. فقط اگر world حذف شده باشد یا USER_SCRIPT باشد معتبر است. مقادیر با زیرکرهای پیشرو ( _ ) محفوظ است.

WorldProperties

خواص

  • csp

    رشته ای اختیاری

    جهان CSP را مشخص می کند. پیش فرض جهان `ISOLATED` CSP است.

  • پیام رسانی

    بولی اختیاری

    مشخص می کند که آیا API های پیام رسانی در معرض دید هستند یا خیر. پیش فرض false است.

  • جهان

    رشته ای اختیاری

    Chrome 133+

    شناسه دنیای اسکریپت کاربر خاص را برای به روزرسانی مشخص می کند. در صورت عدم ارائه ، خصوصیات دنیای اسکریپت کاربر پیش فرض را به روز می کند. مقادیر با زیرکرهای پیشرو ( _ ) محفوظ است.

روش ها

configureWorld()

قول بده
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

محیط اجرای `USER_SCRIPT` پیکربندی می کند.

پارامترها

  • حاوی پیکربندی دنیای اسکریپت کاربر است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

execute()

قول Chrome 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

یک اسکریپت را به یک زمینه هدف تزریق می کند. به طور پیش فرض ، اسکریپت در document_idle اجرا می شود ، یا بلافاصله اگر صفحه قبلاً بارگیری شده باشد. اگر خاصیت injectImmediately تنظیم شود ، اسکریپت بدون انتظار تزریق می شود ، حتی اگر صفحه بارگیری نشده باشد. اگر اسکریپت به یک وعده ارزیابی کند ، مرورگر منتظر قول تسویه و بازگشت مقدار حاصل خواهد بود.

پارامترها

برمی گرداند

  • وعده < تزریق []>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

getScripts()

قول بده
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

پارامترها

  • فیلتر

    usercriptfilter اختیاری

    در صورت مشخص شدن ، این روش فقط اسکریپت های کاربر را که با آن مطابقت دارد برمی گرداند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (scripts: RegisteredUserScript[]) => void

برمی گرداند

  • وعده < RegistenduScript []>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

getWorldConfigurations()

قول Chrome 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

همه تنظیمات ثبت شده جهان را بازیابی می کند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (worlds: WorldProperties[]) => void

برمی گرداند

  • وعده < WorldProperties []>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

register()

قول بده
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

پارامترها

  • اسکریپت ها

    RegireedUserscript []

    شامل لیستی از اسکریپت های کاربر برای ثبت نام است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

resetWorldConfiguration()

قول Chrome 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

تنظیمات را برای دنیای اسکریپت کاربر تنظیم مجدد می کند. هر اسکریپتی که با شناسه مشخص به جهان تزریق می شود ، از پیکربندی پیش فرض جهان استفاده می کند.

پارامترها

  • جهان

    رشته ای اختیاری

    شناسه دنیای اسکریپت کاربر برای تنظیم مجدد. در صورت حذف ، پیکربندی پیش فرض جهان را مجدداً تنظیم می کند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

unregister()

قول بده
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

پارامترها

  • فیلتر

    usercriptfilter اختیاری

    در صورت مشخص شدن ، این روش فقط اسکریپت های کاربر را که با آن مطابقت دارد ، ثبت نمی کند.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.

update()

قول بده
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

پارامترها

  • اسکریپت ها

    RegireedUserscript []

    شامل لیستی از اسکریپت های کاربر برای به روزرسانی است. اگر در این شیء مشخص شود ، یک ویژگی فقط برای اسکریپت موجود به روز می شود. اگر در هنگام اعتبار سنجی اسکریپت/اعتبار سنجی پرونده خطایی وجود داشته باشد ، یا اگر شناسه های مشخص شده با یک اسکریپت کاملاً ثبت شده مطابقت ندارند ، هیچ اسکریپت به روز نمی شود.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول <void>

    وعده ها در مانیفست V3 و بعد از آن پشتیبانی می شوند ، اما تماس های برگشتی برای سازگاری عقب مانده ارائه می شود. شما نمی توانید از هر دو در یک تماس عملکردی استفاده کنید. این وعده با همان نوع که به پاسخ به تماس منتقل می شود ، حل می شود.