browser.scripting

الوصف

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

الأذونات

scripting

مدى التوفّر

الإصدار 88 من Chrome أو إصدار أحدث MV3+

البيان

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

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

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

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

الاستهدافات المتداخلة

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

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

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

الملفات

يتم تحديد الملفات كسلاسل تمثّل مسارات ذات صلة بالدليل الجذري للإضافة. سيؤدي الرمز التالي إلى إدراج الملف script.js في الإطار الرئيسي للعلامة.

function getTabId() { ... }

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

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

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

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

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

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() أي نتائج.

الوعود

إذا كانت القيمة الناتجة عن تنفيذ البرنامج النصي هي عمليّة غير مكتملة، سينتظر 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;
}

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، ثبِّت نموذج البرمجة من مستودع نماذج إضافات Chrome.

الأنواع

ContentScriptFilter

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

الخصائص

  • ids

    string[] اختياري

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

CSSInjection

الخصائص

  • css

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

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

  • ملفات

    string[] اختياري

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

  • الأصل

    ‫StyleOrigin اختياري

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

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

ExecutionWorld

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

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

تعداد

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

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

InjectionResult

الخصائص

  • documentId

    سلسلة

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

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

  • frameId

    الرقم

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

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

  • نتيجة

    أي اختياري

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

InjectionTarget

الخصائص

  • allFrames

    boolean اختياري

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

  • documentIds

    string[] اختياري

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

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

  • frameIds

    number[] اختيارية

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

  • tabId

    الرقم

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

RegisteredContentScript

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

الخصائص

  • allFrames

    boolean اختياري

    إذا تم تحديد القيمة "صحيح"، سيتم إدخالها في جميع الإطارات، حتى إذا لم يكن الإطار هو الإطار الأعلى في علامة التبويب. يتم التحقّق من كل إطار بشكل مستقل بحثًا عن متطلبات عنوان 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 اختياري

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

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

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

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

  • العالم

    ExecutionWorld اختياري

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

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

  • func

    void اختياري

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

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

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

    () => {...}

StyleOrigin

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

تعداد

"AUTHOR"

"USER"

الطُرق

executeScript()

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

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

المعلمات

  • الحقن

    ScriptInjection

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

المرتجعات

  • Promise<InjectionResult[]>

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

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

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

    تعرض هذه الطريقة Promise يتم تنفيذه عند اكتمال عملية الإدراج.

registerContentScripts()

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

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

المعلمات

  • نصوص برمجية

    RegisteredContentScript[]

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

المرتجعات

  • Promise<void>

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

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>

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

updateContentScripts()

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

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

المعلمات

  • نصوص برمجية

    RegisteredContentScript[]

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

المرتجعات

  • Promise<void>

    تعرض هذه الطريقة Promise يتم تنفيذه بعد تعديل النصوص البرمجية أو رفضه في حال حدوث خطأ.