chrome.scripting (original) (raw)

الوصف

استخدِم واجهة برمجة التطبيقات 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 والإصدارات الأحدث

الخصائص

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

CSSInjection

الخصائص

• سلسلة تحتوي على CSS المطلوب إضافته يجب تحديد قيمة واحدة فقط من files وcss.
• مسار ملفات CSS التي سيتم إدراجها، نسبةً إلى الدليل الجذر للإضافة يجب تحديد قيمة واحدة فقط من files وcss.
• الأصل
  StyleOrigin اختياري
  تمثّل هذه السمة مصدر النمط الذي سيتم إضافته. القيمة التلقائية هي 'AUTHOR'.
• تفاصيل تحدّد الهدف الذي سيتم إدراج CSS فيه.

ExecutionWorld

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

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

Enum

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

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

InjectionResult

الخصائص

• الإصدار 106 من Chrome والإصدارات الأحدث
  المستند المرتبط بعملية الإدخال
• Chrome 90 والإصدارات الأحدث
  الإطار المرتبط بعملية الإدخال
• نتيجة تنفيذ النص البرمجي

InjectionTarget

الخصائص

• allFrames
  boolean اختياري
  تحديد ما إذا كان يجب إدراج النص البرمجي في جميع الإطارات ضمن علامة التبويب القيمة التلقائية هي "خطأ". يجب ألا تكون هذه السمة صحيحة إذا تم تحديد frameIds.
• documentIds
  string[] اختياري
  الإصدار 106 من Chrome والإصدارات الأحدث
  معرّفات documentId المحدّدة التي سيتم إدراجها فيها يجب عدم ضبط هذه السياسة في حال ضبط سياسة frameIds.
• frameIds
  number[] اختيارية
  معرّفات الإطارات المحدّدة التي سيتم إدراجها فيها.
• رقم تعريف علامة التبويب التي سيتم إدراج المحتوى فيها

RegisteredContentScript

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

الخصائص

• allFrames
  boolean اختياري
  إذا تم تحديد القيمة true، سيتم إدخالها في جميع الإطارات، حتى إذا لم يكن الإطار هو الإطار الأعلى في علامة التبويب. يتم التحقّق من كل إطار بشكل مستقل للتأكّد من استيفاء متطلبات عنوان URL، ولن يتم إدراجه في الإطارات الفرعية إذا لم يتم استيفاء متطلبات عنوان URL. القيمة التلقائية هي "خطأ"، ما يعني أنّه يتم مطابقة الإطار العلوي فقط.
• قائمة بملفات CSS التي سيتم إدراجها في الصفحات المطابقة يتم إدخالها بالترتيب الذي تظهر به في هذه المصفوفة، قبل إنشاء أي DOM أو عرضه للصفحة.
• excludeMatches
  string[] اختياري
  يستبعد الصفحات التي كان سيتم إدراج نص المحتوى البرمجي فيها. اطّلِع على أنماط المطابقة لمزيد من التفاصيل حول بنية هذه السلاسل.
• معرّف نص برمجي للمحتوى، يتم تحديده في طلب البيانات من واجهة برمجة التطبيقات يجب ألا يبدأ بالرمز "_" لأنّه محجوز كبادئة لمعرّفات النصوص البرمجية التي يتم إنشاؤها.
• قائمة ملفات JavaScript التي سيتم إدراجها في الصفحات المطابقة يتم إدخالها بالترتيب الذي تظهر به في هذه المصفوفة.
• matchOriginAsFallback
  boolean اختياري
  الإصدار 119 من Chrome والإصدارات الأحدث
  توضّح هذه السمة ما إذا كان يمكن إدخال النص البرمجي في إطارات يحتوي عنوان URL الخاص بها على مخطط غير متوافق، وتحديدًا: about:‎ أو data:‎ أو blob:‎ أو filesystem:. في هذه الحالات، يتم التحقّق من مصدر عنوان URL لتحديد ما إذا كان يجب إدخال النص البرمجي. إذا كان المصدر هو null (كما هو الحال بالنسبة إلى عناوين URL للبيانات)، يكون المصدر المستخدَم هو إما الإطار الذي أنشأ الإطار الحالي أو الإطار الذي بدأ عملية الانتقال إلى هذا الإطار. يُرجى العِلم أنّ هذا قد لا يكون الإطار الرئيسي.
• فلتر مطابق لـ
  string[] اختياري
  تحدّد هذه السمة الصفحات التي سيتم إدراج نص المحتوى البرمجي فيها. اطّلِع على أنماط المطابقة لمزيد من التفاصيل حول بنية هذه السلاسل. يجب تحديدها لـ registerContentScripts.
• persistAcrossSessions
  boolean اختياري
  تحدّد هذه السمة ما إذا كان سيتم الاحتفاظ بنص برمجي المحتوى هذا في الجلسات المستقبلية. القيمة التلقائية هي "صحيح".
• تحدّد هذه السمة وقت إدخال ملفات JavaScript في صفحة الويب. القيمة المفضّلة والتلقائية هي document_idle.
• العالم
  ExecutionWorld اختياري
  الإصدار 102 من Chrome والإصدارات الأحدث
  "عالم" JavaScript الذي سيتم تشغيل النص البرمجي فيه القيمة التلقائية هي ISOLATED.

ScriptInjection

الخصائص

• الإصدار 92 من Chrome والإصدارات الأحدث
  الوسيطات التي سيتم تمريرها إلى الدالة المقدَّمة لا يكون هذا صالحًا إلا إذا تم تحديد المَعلمة func. يجب أن تكون هذه الوسيطات قابلة للتسلسل بتنسيق JSON.
• مسار ملفات JavaScript أو CSS التي سيتم إدراجها، نسبةً إلى الدليل الجذر للإضافة يجب تحديد سمة واحدة فقط من files أو func.
• injectImmediately
  boolean اختياري
  الإصدار 102 من Chrome والإصدارات الأحدث
  تحديد ما إذا كان يجب بدء عملية الإدخال في الهدف في أقرب وقت ممكن يُرجى العِلم أنّ هذا لا يضمن حدوث عملية الإدخال قبل تحميل الصفحة، إذ قد تكون الصفحة قد تم تحميلها بالفعل عندما يصل النص البرمجي إلى الهدف.
• تفاصيل تحدّد الهدف الذي سيتم إدخال النص البرمجي فيه.
• العالم
  ExecutionWorld اختياري
  الإصدار 95 من Chrome والإصدارات الأحدث
  "عالم" JavaScript الذي سيتم تشغيل النص البرمجي فيه القيمة التلقائية هي ISOLATED.
• الإصدار 92 من Chrome والإصدارات الأحدث
  دالة JavaScript لإدخالها. سيتم تسلسل هذه الدالة، ثم إلغاء تسلسلها لإدخالها. وهذا يعني أنّه سيتم فقدان أي مَعلمات مرتبطة وسياق التنفيذ. يجب تحديد سمة واحدة فقط من files أو func.
  تبدو الدالة func على النحو التالي:
  () => {...}

StyleOrigin

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

Enum

الطُرق

executeScript()

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

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

المعلمات

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

المرتجعات

• Promise<InjectionResult[]>
  Chrome 90 والإصدارات الأحدث

getRegisteredContentScripts()

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

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

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

المعلمات

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

المرتجعات

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise

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

المعلمات

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

المرتجعات

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

registerContentScripts()

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

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

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

المعلمات

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

المرتجعات

removeCSS()

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

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise

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

المعلمات

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

المرتجعات

unregisterContentScripts()

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

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

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

المعلمات

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

المرتجعات

updateContentScripts()

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

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

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

المعلمات

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

المرتجعات