browser.scripting

شرح

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

اجازه‌ها

scripting

دردسترس بودن

Chrome 88+ browser.* از Chrome 148 MV3+

مانیفست

برای استفاده از browser.scripting API، اجازه "scripting" را در مانیفست به‌علاوه اجازه‌های میزبان برای صفحه‌هایی که اسکریپت‌ها به آن‌ها تزریق می‌شود اعلام کنید. از کلید "host_permissions" یا اجازه "activeTab" استفاده کنید که اجازه‌های موقت میزبان را اعطا می‌کند. مثال زیر از اجازه activeTab استفاده می‌کند.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

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

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

هدف‌های تزریق

می‌توانید از پارامتر target برای مشخص کردن هدف برای تزریق جاوا اسکریپت یا CSS استفاده کنید.

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

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

برای اجرا در همه قاب‌های برگه مشخص‌شده، می‌توانید مقدار بولی allFrames را روی true تنظیم کنید.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

همچنین می‌توانید با مشخص کردن شناسه‌های قاب‌های جداگانه، به قاب‌های خاصی از برگه تزریق کنید. برای اطلاعات بیشتر درباره شناسه‌های قاب، به browser.webNavigation API مراجعه کنید.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

توجه: نمی‌توانید هر دو ویژگی "frameIds" و "allFrames" را مشخص کنید.

کد تزریق‌شده

افزونه‌ها می‌توانند کد را برای تزریق ازطریق فایل خارجی یا متغیر زمان اجرا مشخص کنند.

فایل‌ها

فایل‌ها به‌صورت رشته‌هایی مشخص می‌شوند که مسیرهای مربوط به دایرکتوری ریشه افزونه هستند. کد زیر فایل script.js را به قاب اصلی برگه تزریق می‌کند.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

توابع زمان اجرا

هنگام تزریق جاوا اسکریپت با scripting.executeScript()، می‌توانید تابعی را برای اجرا به‌جای فایل مشخص کنید. این تابع باید متغیر تابع دردسترس برای بافت افزونه فعلی باشد.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

بااستفاده از خصوصیت args می‌توانید این مشکل را حل کنید:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

رشته‌های زمان اجرا

اگر CSS را در صفحه‌ای تزریق می‌کنید، می‌توانید رشته‌ای را نیز برای استفاده در ویژگی css مشخص کنید. این گزینه فقط برای scripting.insertCSS() دردسترس است؛ نمی‌توانید رشته‌ای را بااستفاده از scripting.executeScript() اجرا کنید.

function getTabId() { ... }
const css = "body { background-color: red; }";

browser.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

مدیریت نتایج

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

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() هیچ نتیجه‌ای برنمی‌گرداند.

قول‌ها

اگر مقدار حاصل از اجرای اسکریپت یک promise باشد، Chrome منتظر می‌ماند تا promise حل‌وفصل شود و مقدار حاصل را برمی‌گرداند.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

مثال‌ها

لغو ثبت‌نام همه دستورگان‌های محتوای پویا

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

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

نکته کلیدی: لغو ثبت اسکریپت‌های محتوا باعث حذف اسکریپت‌ها یا سبک‌هایی که قبلاً تزریق شده‌اند نمی‌شود.

برای امتحان کردن browser.scripting API، نمونه اسکریپت‌نویسی را از مخزن نمونه‌های افزونه Chrome نصب کنید.

انواع

ContentScriptFilter

Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

• شناسه‌ها

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

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

CSSInjection

مشخصات

• css

  رشته اختیاری

  رشته‌ای که حاوی CSS برای تزریق است. دقیقاً یکی از files و css باید مشخص شود.

• فایل‌ها

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

  مسیر فایل‌های CSS برای تزریق، نسبت‌به دایرکتوری ریشه افزونه. دقیقاً یکی از files و css باید مشخص شود.

• منشأ

  StyleOrigin اختیاری

  مبدأ سبک برای تزریق. پیش‌فرض‌ها به 'AUTHOR'.

• هدف

  InjectionTarget

  جزئیاتی که هدف درج CSS را مشخص می‌کند.

ExecutionWorld

Chrome نسخه ۹۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

دنیای جاوا اسکریپت برای اجرای اسکریپت در آن.

شمارشی

«ISOLATED»
دنیای جداشده را مشخص می‌کند که محیط اجرای منحصربه‌فرد برای این افزونه است.

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

InjectionResult

مشخصات

• documentId

  رشته

  Chrome 106+ browser.* از Chrome 148

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

• frameId

  شماره

  Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

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

• نتیجه

  هر اختیاری

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

InjectionTarget

مشخصات

• allFrames

  بولی اختیاری

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

• documentIds

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

  Chrome 106+ browser.* از Chrome 148

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

• frameIds

  number[] اختیاری

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

• tabId

  شماره

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

RegisteredContentScript

Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

• allFrames

  بولی اختیاری

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

• css

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

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

• excludeMatches

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

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

• id

  رشته

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

• js

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

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

• matchOriginAsFallback

  بولی اختیاری

  Chrome نسخه ۱۱۹ به بالا browser.* از Chrome نسخه ۱۴۸

  نشان می‌دهد که آیا می‌توان اسکریپت را به قاب‌هایی تزریق کرد که نشانی وب آن‌ها حاوی طرح پشتیبانی‌نشده است؛ به‌طور خاص: about:، data:، blob:، یا filesystem:. در این موارد، مبدأ نشانی وب بررسی می‌شود تا مشخص شود آیا اسکریپت باید تزریق شود یا نه. اگر مبدأ null باشد (همان‌طور که برای داده‌ها: نشانی‌های وب)، مبدأ استفاده‌شده یا قابی است که قاب فعلی را ایجاد کرده است یا قابی است که پیمایش به این قاب را آغاز کرده است. توجه داشته باشید که این ممکن است قاب ولی نباشد.

• انطباق‌ها

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

  مشخص می‌کند این متن محتوا به کدام صفحه‌ها تزریق خواهد شد. برای جزئیات بیشتر درباره نحو این رشته‌ها، الگوهای مطابقت را ببینید. باید برای registerContentScripts مشخص شود.

• persistAcrossSessions

  بولی اختیاری

  مشخص می‌کند که آیا این اسکریپت محتوا در جلسه‌های آینده باقی می‌ماند یا نه. پیش‌فرض «درست» است.

• runAt

  RunAt اختیاری

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

• جهان

  ExecutionWorld اختیاری

  Chrome نسخه ۱۰۲ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

  «جهان» جاوا اسکریپت برای اجرای دستورگان در آن. پیش‌فرض‌ها به ISOLATED.

ScriptInjection

مشخصات

• متغیرها

  any[] اختیاری

  Chrome 92+ browser.* از Chrome 148

  متغیرهای مستقل برای ارسال به تابع ارائه‌شده. این فقط درصورتی معتبر است که پارامتر func مشخص شده باشد. این آرگومان‌ها باید JSON-serializable باشند.

• فایل‌ها

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

  مسیر فایل‌های JS یا CSS برای تزریق، نسبت به دایرکتوری ریشه افزونه. دقیقاً یکی از files یا func باید مشخص شود.

• injectImmediately

  بولی اختیاری

  Chrome نسخه ۱۰۲ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

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

• هدف

  InjectionTarget

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

• جهان

  ExecutionWorld اختیاری

  Chrome نسخه ۹۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

  «جهان» جاوا اسکریپت برای اجرای دستورگان در آن. پیش‌فرض‌ها به ISOLATED.

• func

  void اختیاری

  Chrome 92+ browser.* از Chrome 148

  تابع جاوا اسکریپت برای تزریق. این تابع سری‌سازی می‌شود و سپس برای تزریق، واگردانی سری‌سازی می‌شود. این یعنی هرگونه پارامتر محدود و زمینه اجرا ازدست خواهد رفت. دقیقاً یکی از files یا func باید مشخص شود.

  تابع func به‌صورت زیر است:

  () => {...}

StyleOrigin

مبدأ تغییر سبک. برای اطلاعات بیشتر، به منشأ سبک مراجعه کنید.

شمارشی

«AUTHOR»

«USER»

روش‌ها

executeScript()

browser.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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

پارامترها

• تزریق

  ScriptInjection

  جزئیات اسکریپتی که باید تزریق شود.

بازگشتی‌ها

• Promise<InjectionResult[]>

  Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

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

getRegisteredContentScripts()

Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

همه متون محتوای ثبت‌شده پویا را برای این افزونه که با فیلتر ارائه‌شده مطابقت دارد برمی‌گرداند.

پارامترها

• فیلتر کردن

  ContentScriptFilter اختیاری

  شیئی برای فیلتر کردن دستورگان ثبت‌شده پویا در افزونه.

بازگشتی‌ها

• Promise<RegisteredContentScript[]>

insertCSS()

browser.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

برگه سبک نگارش CSS را در بافت هدف درج می‌کند. اگر چند قاب مشخص شده باشد، تزریق‌های ناموفق نادیده گرفته می‌شود.

پارامترها

• تزریق

  CSSInjection

  جزئیات سبک‌هایی که باید درج شود.

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

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

registerContentScripts()

Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

browser.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

پارامترها

• متن‌ها

  RegisteredContentScript[]

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

بازگشتی‌ها

• Promise<void>

  یک Promise برمی‌گرداند که پس‌از ثبت کامل اسکریپت‌ها حل می‌شود یا درصورت بروز خطا رد می‌شود.

removeCSS()

Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

برگه سبک نگارش CSS را که قبلاً توسط این افزونه از بافت هدف درج شده بود برمی‌دارد.

پارامترها

• تزریق

  CSSInjection

  جزئیات سبک‌هایی که باید برداشته شود. توجه داشته باشید که ویژگی‌های css، files، و origin باید دقیقاً با برگه سبک نگارش درج‌شده ازطریق insertCSS مطابقت داشته باشد. تلاش برای برداشتن برگه سبک نگارش غیرموجود، عملیاتی بی‌تأثیر است.

بازگشتی‌ها

• Promise<void>

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

unregisterContentScripts()

Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

متن‌های محتوا را برای این افزونه لغو ثبت می‌کند.

پارامترها

• فیلتر کردن

  ContentScriptFilter اختیاری

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

بازگشتی‌ها

• Promise<void>

  یک Promise برمی‌گرداند که پس‌از لغو ثبت‌نام دستورگان حل می‌شود یا درصورت بروز خطا رد می‌شود.

updateContentScripts()

Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

browser.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

پارامترها

• متن‌ها

  RegisteredContentScript[]

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

بازگشتی‌ها

• Promise<void>

  یک Promise برمی‌گرداند که پس‌از به‌روزرسانی اسکریپت‌ها حل می‌شود یا درصورت بروز خطا رد می‌شود.