chrome.scripting

توضیحات

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

مجوزها

scripting

در دسترس بودن

کروم ۸۸+ نسخه ۳+

مانیفست

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

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

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

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

اهداف تزریق

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

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

function getTabId() { ... }

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

برای اجرا در تمام فریم‌های تب مشخص شده، می‌توانید مقدار بولی allFrames را روی 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() هیچ نتیجه‌ای برنمی‌گرداند.

وعده‌ها

اگر مقدار حاصل از اجرای اسکریپت یک promise باشد، کروم منتظر می‌ماند تا 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;
}

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

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

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

انواع

ContentScriptFilter

کروم ۹۶+

خواص

• شناسه‌ها

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

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

CSSInjection

خواص

• سی‌اس‌اس

  رشته اختیاری

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

• فایل‌ها

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

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

• منشأ

  StyleOrigin اختیاری

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

• هدف

  هدف تزریق

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

ExecutionWorld

کروم ۹۵+

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

شمارشی

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

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

InjectionResult

خواص

• شناسه سند

  رشته

  کروم ۱۰۶+

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

• شناسه قاب

  شماره

  کروم ۹۰+

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

• نتیجه

  هر اختیاری

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

InjectionTarget

خواص

• همه فریم‌ها

  بولی اختیاری

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

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

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

  کروم ۱۰۶+

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

• شناسه‌های قاب

  عدد[] اختیاری

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

• شناسه برگه

  شماره

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

RegisteredContentScript

کروم ۹۶+

خواص

• همه فریم‌ها

  بولی اختیاری

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

• سی‌اس‌اس

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

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

• موارد استثنا

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

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

• شناسه

  رشته

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

• جی‌اس

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

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

• matchOriginAsFallback

  بولی اختیاری

  کروم ۱۱۹+

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

• مسابقات

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

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

• persistAcrossSessions

  بولی اختیاری

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

• اجرا کن

  اجرای اختیاری

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

• جهان

  دنیای اجرا اختیاری

  کروم ۱۰۲+

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

ScriptInjection

خواص

• استدلال‌ها

  هر [] اختیاری

  کروم ۹۲+

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

• فایل‌ها

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

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

• فوراً تزریق کنید

  بولی اختیاری

  کروم ۱۰۲+

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

• هدف

  هدف تزریق

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

• جهان

  دنیای اجرا اختیاری

  کروم ۹۵+

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

• تابع

  اختیاری باطل

  کروم ۹۲+

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

  تابع func به شکل زیر است:

  () => {...}

StyleOrigin

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

شمارشی

«نویسنده»

"کاربر"

روش‌ها

executeScript()

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

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

پارامترها

• تزریق

  تزریق اسکریپت

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

بازگشت‌ها

• قول < تزریق نتیجه []>

  کروم ۹۰+

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

getRegisteredContentScripts()

کروم ۹۶+

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

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

پارامترها

• فیلتر

  فیلتر اسکریپت محتوا (اختیاری)

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

بازگشت‌ها

• قول < RegisteredContentScript []>

insertCSS()

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

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

پارامترها

• تزریق

  تزریق CSS

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

بازگشت‌ها

• قول<void>

  کروم ۹۰+

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

registerContentScripts()

کروم ۹۶+

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

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

پارامترها

• اسکریپت‌ها

  اسکریپت محتوای ثبت‌شده []

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

بازگشت‌ها

• قول<void>

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

removeCSS()

کروم ۹۰+

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

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

پارامترها

• تزریق

  تزریق CSS

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

بازگشت‌ها

• قول<void>

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

unregisterContentScripts()

کروم ۹۶+

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

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

پارامترها

• فیلتر

  فیلتر اسکریپت محتوا (اختیاری)

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

بازگشت‌ها

• قول<void>

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

updateContentScripts()

کروم ۹۶+

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

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

پارامترها

• اسکریپت‌ها

  اسکریپت محتوای ثبت‌شده []

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

بازگشت‌ها

• قول<void>

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