chrome.scripting

توضیحات

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

مجوزها

scripting

در دسترس بودن

Chrome 88+ MV3+

آشکار

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

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

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

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

اهداف تزریق

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

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

function getTabId() { ... }

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

برای اجرا در تمام فریم های تب مشخص شده، می توانید allFrames boolean را روی true تنظیم کنید.

function getTabId() { ... }

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

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

function getTabId() { ... }

chrome.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() { ... }

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

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

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

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

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

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

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

chrome.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;
}

chrome.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; }";

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

به نتایج رسیدگی کنید

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

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

chrome.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() هیچ نتیجه ای را بر نمی گرداند.

وعده ها

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

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;
}

chrome.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 chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts(scriptIds);
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

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

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

انواع

ContentScriptFilter

Chrome 96+

خواص

• شناسه

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

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

CSSInjection

خواص

• css

  رشته اختیاری

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

• فایل ها

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

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

• منشاء

  StyleOrigin اختیاری است

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

• هدف

  InjectionTarget

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

ExecutionWorld

Chrome 95+

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

Enum

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

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

InjectionResult

خواص

• شناسه سند

  رشته

  Chrome 106+

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

• frameId

  شماره

  Chrome 90+

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

• نتیجه

  هر اختیاری

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

InjectionTarget

خواص

• همه فریم ها

  بولی اختیاری

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

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

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

  Chrome 106+

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

• FrameIds

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

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

• tabId

  شماره

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

RegisteredContentScript

Chrome 96+

خواص

• همه فریم ها

  بولی اختیاری

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

• css

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

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

• منطبق بر

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

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

• شناسه

  رشته

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

• js

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

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

• matchOriginAsFallback

  بولی اختیاری

  Chrome 119+

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

• مسابقات

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

  مشخص می کند که این اسکریپت محتوا به چه صفحاتی تزریق شود. برای جزئیات بیشتر در مورد نحو این رشته ها به Match Patterns مراجعه کنید. باید برای registerContentScripts مشخص شود.

• persistAcrossSessions

  بولی اختیاری

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

• runAt

  RunAt اختیاری است

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

• جهان

  ExecutionWorld اختیاری است

  Chrome 102+

  "جهان" جاوا اسکریپت برای اجرای ISOLATED .

ScriptInjection

خواص

• ارگ

  هر[] اختیاری

  Chrome 92+

  آرگومان هایی که باید به تابع ارائه شده منتقل شوند. این تنها زمانی معتبر است که پارامتر func مشخص شده باشد. این آرگومان ها باید JSON-Serializable باشند.

• فایل ها

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

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

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

  بولی اختیاری

  Chrome 102+

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

• هدف

  InjectionTarget

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

• جهان

  ExecutionWorld اختیاری است

  Chrome 95+

  "جهان" جاوا اسکریپت برای اجرای ISOLATED .

• تابع

  باطل اختیاری

  Chrome 92+

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

  تابع func به نظر می رسد:

  () => {...}

StyleOrigin

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

Enum

"نویسنده"

"کاربر"

روش ها

executeScript()

قول بده

chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

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

پارامترها

• تزریق

  ScriptInjection

  جزئیات فیلمنامه که باید تزریق شود.

• پاسخ به تماس

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

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

  (results: InjectionResult[]) => void

  • نتایج

    نتیجه تزریق []

برمی گرداند

• Promise< InjectionResult []>

  Chrome 90+

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

getRegisteredContentScripts()

Promise Chrome 96+

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

پارامترها

• فیلتر کنید

  ContentScriptFilter اختیاری است

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

• پاسخ به تماس

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

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

  (scripts: RegisteredContentScript[]) => void

  • اسکریپت ها

    RegisteredContentScript []

برمی گرداند

• Promise< RegisteredContentScript []>

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

insertCSS()

قول بده

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

پارامترها

• تزریق

  CSSInjection

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

• پاسخ به تماس

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

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

  () => void

برمی گرداند

• قول<باطل>

  Chrome 90+

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

registerContentScripts()

Promise Chrome 96+

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

پارامترها

• اسکریپت ها

  RegisteredContentScript []

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

• پاسخ به تماس

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

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

  () => void

برمی گرداند

• قول<باطل>

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

removeCSS()

Promise Chrome 90+

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

پارامترها

• تزریق

  CSSInjection

  جزئیات سبک هایی که باید حذف شوند. توجه داشته باشید که ویژگی های css , files و origin باید دقیقاً با شیوه نامه درج شده از طریق insertCSS مطابقت داشته باشند. تلاش برای حذف یک شیوه نامه ناموجود یک کار غیرفعال است.

• پاسخ به تماس

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

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

  () => void

برمی گرداند

• قول<باطل>

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

unregisterContentScripts()

Promise Chrome 96+

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

پارامترها

• فیلتر کنید

  ContentScriptFilter اختیاری است

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

• پاسخ به تماس

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

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

  () => void

برمی گرداند

• قول<باطل>

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

updateContentScripts()

Promise Chrome 96+

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

پارامترها

• اسکریپت ها

  RegisteredContentScript []

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

• پاسخ به تماس

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

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

  () => void

برمی گرداند

• قول<باطل>

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