browser.scripting

الوصف

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

الأذونات

scripting

مدى التوفّر

الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome الإصدار 3 من MV والإصدارات الأحدث

البيان

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

function getTabId() { ... }

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

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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• ids

  string[] اختياري

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

CSSInjection

الخصائص

• css

  string اختياري

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

• ملفات

  string[] اختياري

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

• الأصل

  StyleOrigin اختياري

  مصدر النمط لعملية الحقن القيمة التلقائية هي 'AUTHOR'.

• target

  InjectionTarget

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

ExecutionWorld

الإصدار 95 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

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

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

InjectionResult

الخصائص

• documentId

  سلسلة

  الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

  المستند المرتبط بالحقن

• frameId

  الرقم

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• نتيجة

  أيّ اختياري

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

InjectionTarget

الخصائص

• allFrames

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

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

• documentIds

  string[] اختياري

  الإصدار 106 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• frameIds

  number[] اختيارية

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

• tabId

  الرقم

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

RegisteredContentScript

الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• allFrames

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

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

• css

  string[] اختياري

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

• excludeMatches

  string[] اختياري

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

• id

  سلسلة

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

• js

  string[] اختياري

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

• matchOriginAsFallback

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

  الإصدار 119 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

  string[] اختياري

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

• persistAcrossSessions

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

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

• runAt

  RunAt اختيارية

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

• العالم

  ‫ExecutionWorld اختياري

  الإصدار 102 من Chrome والإصدارات الأحدث browser.* منذ الإصدار 148 من Chrome

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

ScriptInjection

الخصائص

• args

  any[] اختيارية

  الإصدار 92 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• ملفات

  string[] اختياري

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

• injectImmediately

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

  الإصدار 102 من Chrome والإصدارات الأحدث browser.* منذ الإصدار 148 من Chrome

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

• target

  InjectionTarget

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

• العالم

  ‫ExecutionWorld اختياري

  الإصدار 95 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• func

  void اختياري

  الإصدار 92 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

  () => {...}

StyleOrigin

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

Enum

"AUTHOR"

"USER"

الطُرق

executeScript()

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

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

المعلمات

• حُقْنَة

  ScriptInjection

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

المرتجعات

• Promise<InjectionResult[]>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

getRegisteredContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

المعلمات

• تصفية

  ContentScriptFilter اختياري

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

المرتجعات

• Promise<RegisteredContentScript[]>

insertCSS()

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

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

المعلمات

• حُقْنَة

  CSSInjection

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

المرتجعات

• وعد<فراغ>

  الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

registerContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

المعلمات

• نصوص برمجية

  RegisteredContentScript[]

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

المرتجعات

• وعد<فراغ>

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

removeCSS()

الإصدار 90 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

المعلمات

• حُقْنَة

  CSSInjection

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

المرتجعات

• وعد<فراغ>

  تعرض هذه الطريقة كائن Promise يتم حله عند اكتمال عملية الإزالة.

unregisterContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

المعلمات

• تصفية

  ContentScriptFilter اختياري

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

المرتجعات

• وعد<فراغ>

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

updateContentScripts()

الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

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

المعلمات

• نصوص برمجية

  RegisteredContentScript[]

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

المرتجعات

• وعد<فراغ>

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