chrome.scripting

الوصف

استخدِم واجهة برمجة التطبيقات chrome.scripting API لتنفيذ نص برمجي في سياقات مختلفة.

الأذونات

scripting

مدى توفّر الخدمة

Chrome 88 والإصدارات الأحدث MV3 والإصدارات الأحدث

البيان

لاستخدام واجهة برمجة تطبيقات chrome.scripting، يجب تحديد إذن "scripting" في البيان بالإضافة إلى أذونات المضيف للصفحات لإدخال نصوص برمجية فيها. استخدِم المفتاح "host_permissions" أو إذن "activeTab" الذي يمنح أذونات المضيف المؤقتة. يستخدم المثال التالي إذن ActiveTab.

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

المفاهيم والاستخدام

يمكنك استخدام chrome.scripting API لإدخال JavaScript وCSS في المواقع الإلكترونية. وهذا يشبه ما يمكنك فعله باستخدام النصوص البرمجية للمحتوى. ولكن باستخدام مساحة الاسم chrome.scripting، يمكن للإضافات اتخاذ القرارات في وقت التشغيل.

استهدافات الحقن

يمكنك استخدام المَعلمة target لتحديد هدف لإدخال JavaScript أو 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"));

الرمز الذي تم إدخاله

يمكن للإضافات تحديد الرمز المطلوب إدخاله إما من خلال ملف خارجي أو من خلال متغيِّر وقت تشغيل.

Files

ويتم تحديد الملفات كسلاسل تمثّل مسارات نسبية إلى الدليل الجذري للإضافة. سيُدخِل الرمز التالي الملف script.js في الإطار الرئيسي لعلامة التبويب.

function getTabId() { ... }

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

دوال وقت التشغيل

عند إدخال JavaScript باستخدام 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"));

التعامل مع النتائج

ويتم تمرير نتائج تنفيذ JavaScript إلى الإضافة. يتم تضمين نتيجة واحدة في كل إطار ويتم ضمان أن يكون الإطار الرئيسي هو الفهرس الأول في الصفيف الناتج، أما جميع الإطارات الأخرى وتكون بترتيب غير حتمي.

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()".

وعود

إذا كانت القيمة الناتجة لتنفيذ النص البرمجي هي وعودًا، سينتظر Chrome حتى يستقر الوعد ويعرض القيمة الناتجة.

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 والإصدارات الأحدث

أماكن إقامة

  • ids

    سلسلة[] اختيارية

    وفي حال تحديدها، لن تعرض getRegisteredContentScripts إلا النصوص البرمجية ذات المعرف المحدد في هذه القائمة.

CSSInjection

أماكن إقامة

  • css

    سلسلة اختيارية

    سلسلة تحتوي على CSS المطلوب إدخالها يجب تحديد سمة واحدة من files وcss بالضبط.

  • ملف

    سلسلة[] اختيارية

    مسار ملفات CSS المطلوب إدخالها، وفقًا للدليل الجذر للإضافة. يجب تحديد سمة واحدة من files وcss بالضبط.

  • الأصل

    StyleOrigin اختيارية

    أصل النمط للإدخال. وتكون الإعدادات التلقائية 'AUTHOR'.

  • الاستهداف

    InjectionTarget

    تفاصيل تحدد الهدف الذي يتم إدراج CSS فيه.

ExecutionWorld

Chrome 95 والإصدارات الأحدث

عالم JavaScript لتنفيذ النص البرمجي بداخله.

التعداد

"ISOLATED"
يحدد العالم المعزول، وهو بيئة التنفيذ الفريدة لهذه الإضافة.

"MAIN"
يحدد العالم الرئيسي لـ DOM، وهو بيئة التنفيذ التي تتم مشاركتها مع JavaScript لصفحة المضيف.

InjectionResult

أماكن إقامة

  • documentId

    سلسلة

    Chrome 106 والإصدارات الأحدث

    المستند المرتبط بعملية الحقن.

  • frameId

    الرقم

    Chrome 90 والإصدارات الأحدث

    الإطار المرتبط بالحقن

  • نتيجة

    أي اختياري

    هي نتيجة تنفيذ النص البرمجي.

InjectionTarget

أماكن إقامة

  • allFrames

    منطقية اختيارية

    ما إذا كان يجب إدخال النص البرمجي في جميع الإطارات ضمن علامة التبويب يكون الإعداد التلقائي بالقيمة "خطأ". يجب ألا يكون هذا صحيحًا في حال تحديد frameIds.

  • documentIds

    سلسلة[] اختيارية

    Chrome 106 والإصدارات الأحدث

    معرّفات لمعرّفات مستندات محدّدة لإدخالها. ويجب عدم ضبط هذا الإعداد إذا تم ضبط frameIds.

  • frameIds

    number[] اختيارية

    أرقام تعريف إطارات معيّنة لإدخالها فيها.

  • tabId

    الرقم

    رقم تعريف علامة التبويب التي سيتم إدخال الرمز فيها.

RegisteredContentScript

Chrome 96 والإصدارات الأحدث

أماكن إقامة

  • allFrames

    منطقية اختيارية

    في حال تحديد القيمة "true"، سيتم إدخالها في كل الإطارات، حتى إذا لم يكن الإطار هو أعلى إطار في علامة التبويب. ويتم التحقّق من كل إطار بشكل مستقل لمعرفة متطلبات عنوان URL، ولن يتم إدخاله في الإطارات الفرعية في حال عدم استيفاء متطلبات عناوين URL. ويتم ضبطها تلقائيًا على "خطأ"، ما يعني أنه تتم مطابقة الإطار العلوي فقط.

  • css

    سلسلة[] اختيارية

    قائمة ملفات CSS المطلوب إدخالها في الصفحات المطابقة. يتم إدخال هذه العناصر بالترتيب الذي تظهر به في هذه الصفيف، قبل إنشاء أي نموذج العناصر في المستند (DOM) أو عرضه للصفحة.

  • excludeMatches

    سلسلة[] اختيارية

    تستبعد الصفحات التي تم إدخال نص المحتوى البرمجي فيها بطريقة أخرى. اطّلِع على أنماط المطابقة للحصول على مزيد من التفاصيل عن بنية هذه السلاسل.

  • id

    سلسلة

    معرِّف النص البرمجي للمحتوى، محدّد في طلب بيانات من واجهة برمجة التطبيقات. يجب ألا يبدأ بـ "_" لأنه يتم حجزه كبادئة لأرقام تعريف النصوص البرمجية التي تم إنشاؤها.

  • js

    سلسلة[] اختيارية

    قائمة ملفات JavaScript التي يتم إدخالها في الصفحات المطابقة. يتم إدخال هذه القيم بالترتيب الذي تظهر به في هذه الصفيفة.

  • matchOriginAsFallback

    منطقية اختيارية

    Chrome 119 والإصدارات الأحدث

    تشير هذه السمة إلى ما إذا كان من الممكن إدخال النص البرمجي في الإطارات التي يحتوي فيها عنوان URL على نظام غير متوافق، وعلى وجه التحديد: about: أو data: أو blob: أو filesystem:. وفي هذه الحالات، يتم التحقق من أصل عنوان URL لتحديد ما إذا كان يجب إدخال النص البرمجي. إذا كان المصدر هو null (كما هو الحال مع البيانات: عناوين URL)، يكون المصدر المستخدَم هو الإطار الذي أنشأ الإطار الحالي أو الإطار الذي بدأ التنقّل إلى هذا الإطار. لاحظ أن هذا قد لا يكون الإطار الرئيسي.

  • فلتر مطابق لـ

    سلسلة[] اختيارية

    تحدّد الصفحات التي سيتم إدخال هذا النص البرمجي للمحتوى إليها. اطّلِع على أنماط المطابقة للحصول على مزيد من التفاصيل عن بنية هذه السلاسل. يجب تحديدها لـ registerContentScripts.

  • persistAcrossSessions

    منطقية اختيارية

    تحدِّد هذه السياسة ما إذا كان هذا النص البرمجي للمحتوى سيستمر في الجلسات المستقبلية. الإعداد التلقائي هو true.

  • runAt

    RunAt اختيارية

    تحدِّد هذه السمة وقت إدخال ملفات JavaScript في صفحة الويب. القيمة المفضّلة والتلقائية هي document_idle.

  • العالم

    ExecutionWorld اختياري

    Chrome 102 والإصدارات الأحدث

    لغة JavaScript "العالم" لتشغيل النص البرمجي فيها. وتكون الإعدادات التلقائية ISOLATED.

ScriptInjection

أماكن إقامة

  • args

    أي نوع[] اختياري

    Chrome 92 والإصدارات الأحدث

    الوسيطات المطلوب تمريرها إلى الدالة المقدمة. يكون هذا صالحًا فقط في حال تحديد معلَمة func. يجب أن تكون هذه الوسيطات قابلة للتسلسل بتنسيق JSON.

  • ملف

    سلسلة[] اختيارية

    مسار ملفات JS أو CSS المطلوب إدخالها، وفقًا للدليل الجذري للإضافة. يجب تحديد سمة واحدة من files أو func.

  • injectImmediately

    منطقية اختيارية

    Chrome 102 والإصدارات الأحدث

    ما إذا كان يجب تشغيل الحقن في الهدف في أقرب وقت ممكن. تجدر الإشارة إلى أنّ هذا لا يضمن حدوث الحقن قبل تحميل الصفحة، لأنّه من المحتمل أن يكون قد تم تحميل الصفحة في الوقت الذي يصل فيه النص البرمجي إلى الهدف.

  • الاستهداف

    InjectionTarget

    تفاصيل تحدد الهدف الذي تريد إدخال النص البرمجي فيه.

  • العالم

    ExecutionWorld اختياري

    Chrome 95 والإصدارات الأحدث

    لغة JavaScript "العالم" لتشغيل النص البرمجي فيها. وتكون الإعدادات التلقائية ISOLATED.

  • func

    باطل اختياري

    Chrome 92 والإصدارات الأحدث

    دالة JavaScript لإدخالها. سيتم إنشاء تسلسل لهذه الدالة، ثم إلغاء تسلسلها للحقن. وهذا يعني أنّه سيتم فقدان أي مَعلمات مرتبطة وسياق تنفيذ. يجب تحديد سمة واحدة من files أو func.

    تبدو الدالة func على النحو التالي: 

    ()=> {...}

StyleOrigin

أصل تغيير النمط. لمزيد من المعلومات، يمكنك الاطّلاع على مصادر النمط.

التعداد

"AUTHOR"

"USER"

الطُرق

executeScript()

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

إدخال نص برمجي في سياق مستهدف سيتم تلقائيًا تشغيل النص البرمجي في document_idle أو على الفور إذا سبق تحميل الصفحة. في حال ضبط السمة injectImmediately، سيتم إدخال النص البرمجي بدون انتظار، حتى في حال عدم انتهاء تحميل الصفحة. إذا تم تقييم النص البرمجي على شكل وعد، سينتظر المتصفح إلى أن يستقر الوعد ويعرض القيمة الناتجة.

المَعلمات

  • الحقن

    ScriptInjection

    تفاصيل النص البرمجي المطلوب إدخاله.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (results: InjectionResult[])=>void

المرتجعات

  • Promise<InjectionResult[]>

    Chrome 90 والإصدارات الأحدث

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getRegisteredContentScripts()

الوعد الإصدار 96 من Chrome أو الإصدارات الأحدث 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

عرض جميع النصوص البرمجية للمحتوى المسجّلة ديناميكيًا لهذه الإضافة التي تتطابق مع الفلتر المحدّد.

المَعلمات

  • filter

    ContentScriptFilter اختياري

    كائن لفلترة النصوص البرمجية المسجّلة ديناميكيًا للإضافة.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (scripts: RegisteredContentScript[])=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

insertCSS()

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

يدرج ورقة أنماط CSS في سياق مستهدف. وفي حال تحديد إطارات متعددة، يتم تجاهل عمليات الحقن غير الناجحة.

المَعلمات

  • الحقن

    CSSInjection

    تفاصيل الأنماط المطلوب إدراجها.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    Chrome 90 والإصدارات الأحدث

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

registerContentScripts()

الوعد الإصدار 96 من Chrome أو الإصدارات الأحدث 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

لتسجيل نص برمجي واحد أو أكثر للمحتوى لهذه الإضافة.

المَعلمات

  • نصوص برمجية

    RegisteredContentScript[]

    يحتوي على قائمة بالنصوص البرمجية المطلوب تسجيلها. إذا كانت هناك أخطاء أثناء تحليل النصوص البرمجية/التحقّق من صحة الملفات، أو إذا كانت المُعرّفات المحدَّدة موجودة من قبل، لن يتمّ تسجيل أيّ نصوص برمجية.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

removeCSS()

الوعد الإصدار 90 من Chrome أو الإصدارات الأحدث 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

تُزيل ورقة أنماط CSS التي تم إدراجها سابقًا بواسطة هذه الإضافة من السياق المستهدف.

المَعلمات

  • الحقن

    CSSInjection

    تفاصيل الأنماط المطلوب إزالتها. يُرجى العلم أنّ السمات css وfiles وorigin يجب أن تتطابق تمامًا مع ورقة الأنماط المُدرَجة من خلال insertCSS. محاولة إزالة ورقة أنماط غير موجودة هي محاولة لا.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

unregisterContentScripts()

الوعد الإصدار 96 من Chrome أو الإصدارات الأحدث 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

تلغي تسجيل النصوص البرمجية للمحتوى لهذه الإضافة.

المَعلمات

  • filter

    ContentScriptFilter اختياري

    في حال تحديد هذه السياسة، سيتم فقط إلغاء تسجيل النصوص البرمجية للمحتوى الديناميكي التي تتطابق مع الفلتر. وبخلاف ذلك، سيتم إلغاء تسجيل جميع النصوص البرمجية للمحتوى الديناميكي للإضافة.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

updateContentScripts()

الوعد الإصدار 96 من Chrome أو الإصدارات الأحدث 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

تُعدِّل نصًا برمجيًا واحدًا أو أكثر للمحتوى لهذه الإضافة.

المَعلمات

  • نصوص برمجية

    RegisteredContentScript[]

    يحتوي على قائمة بالنصوص البرمجية المطلوب تعديلها. لا يتم تعديل الخاصية للنص البرمجي الحالي إلّا إذا تم تحديدها في هذا العنصر. إذا كانت هناك أخطاء أثناء تحليل النصوص البرمجية/التحقق من الملف، أو إذا كانت المعرفات المحددة لا تتوافق مع نص برمجي مسجل بالكامل، فلن يتم تحديث أي نصوص برمجية.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.