chrome.scripting

الوصف

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

الأذونات

scripting

مدى التوفّر

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

البيان

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

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

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

يمكنك استخدام واجهة برمجة التطبيقات chrome.scripting لإدخال 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واجهة برمجة التطبيقات.

function getTabId() { ... }

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

الرمز المُدخَل

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

الملفات

يتم تحديد الملفات كسلاسل تمثّل مسارات ذات صلة بالدليل الجذري للإضافة. سيؤدي الرمز التالي إلى إدراج الملف 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({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

لتجربة واجهة برمجة التطبيقات chrome.scripting، ثبِّت نموذج البرمجة من مستودع نماذج إضافات Chrome.

الأنواع

ContentScriptFilter

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

الخصائص

  • ids

    string[] اختياري

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

CSSInjection

الخصائص

  • css

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

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

  • ملفات

    string[] اختياري

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

  • الأصل

    StyleOrigin اختياري

    تمثّل هذه السمة مصدر النمط الذي سيتم إضافته. القيمة التلقائية هي 'AUTHOR'.

  • الاستهداف

    InjectionTarget

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

ExecutionWorld

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

بيئة JavaScript التي سيتم تنفيذ النص البرمجي فيها

Enum

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

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

InjectionResult

الخصائص

  • documentId

    سلسلة

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

    المستند المرتبط بعملية الإدخال

  • frameId

    الرقم

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

    الإطار المرتبط بعملية الإدخال

  • نتيجة

    أي اختياري

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

InjectionTarget

الخصائص

  • allFrames

    boolean اختياري

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

  • documentIds

    string[] اختياري

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

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

  • frameIds

    number[] اختيارية

    معرّفات الإطارات المحدّدة التي سيتم إدراجها فيها.

  • tabId

    الرقم

    رقم تعريف علامة التبويب التي سيتم إدراج المحتوى فيها

RegisteredContentScript

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

الخصائص

  • allFrames

    boolean اختياري

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

  • css

    string[] اختياري

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

  • excludeMatches

    string[] اختياري

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

  • id

    سلسلة

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

  • js

    string[] اختياري

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

  • matchOriginAsFallback

    boolean اختياري

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

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

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

    string[] اختياري

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

  • persistAcrossSessions

    boolean اختياري

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

  • runAt

    RunAt اختياري

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

  • العالم

    ExecutionWorld اختياري

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

    "عالم" JavaScript الذي سيتم تشغيل النص البرمجي فيه القيمة التلقائية هي ISOLATED.

ScriptInjection

الخصائص

  • args

    any[] اختيارية

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

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

  • ملفات

    string[] اختياري

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

  • injectImmediately

    boolean اختياري

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

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

  • الاستهداف

    InjectionTarget

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

  • العالم

    ExecutionWorld اختياري

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

    "عالم" JavaScript الذي سيتم تشغيل النص البرمجي فيه القيمة التلقائية هي ISOLATED.

  • func

    void اختياري

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

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

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

    () => {...}

StyleOrigin

تمثّل هذه السمة مصدر تغيير النمط. يمكنك الاطّلاع على مصادر الأنماط للحصول على مزيد من المعلومات.

Enum

"AUTHOR"

"USER"

الطُرق

executeScript()

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

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

المعلمات

  • الحقن

    ScriptInjection

    تمثّل هذه السمة تفاصيل النص البرمجي الذي سيتم إدراجه.

المرتجعات

getRegisteredContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

المعلمات

  • تصفية

    ‫ContentScriptFilter اختياري

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

المرتجعات

insertCSS()

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

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

المعلمات

  • الحقن

    CSSInjection

    تمثّل هذه السمة تفاصيل الأنماط التي سيتم إدراجها.

المرتجعات

  • Promise<void>

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

registerContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

المعلمات

  • نصوص برمجية

    RegisteredContentScript[]

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

المرتجعات

  • Promise<void>

removeCSS()

Chrome 90 والإصدارات الأحدث 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

المعلمات

  • الحقن

    CSSInjection

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

المرتجعات

  • Promise<void>

unregisterContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

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

المعلمات

  • تصفية

    ‫ContentScriptFilter اختياري

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

المرتجعات

  • Promise<void>

updateContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

المعلمات

  • نصوص برمجية

    RegisteredContentScript[]

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

المرتجعات

  • Promise<void>