chrome.scripting

الوصف

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

الأذونات

scripting

مدى التوفّر

الإصدار 88 من Chrome أو الإصدارات الأحدث 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. API:

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(). CANNOT TRANSLATE لم نتمكّن من تنفيذ سلسلة باستخدام السمة 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، تثبيت نموذج النصوص البرمجية من عيّنات إضافات Chrome المستودع.

الأنواع

ContentScriptFilter

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

أماكن إقامة

  • أرقام التعريف

    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

    الرقم

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

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

  • نتيجة

    أي خيار اختياري

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

InjectionTarget

أماكن إقامة

  • allFrames

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

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

  • documentIds

    string[] اختيارية

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

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

  • frameIds

    number[] اختياري

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

  • tabId

    الرقم

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

RegisteredContentScript

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

أماكن إقامة

  • allFrames

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

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

  • css

    string[] اختيارية

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

  • excludeMatches

    string[] اختيارية

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

  • id

    سلسلة

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

  • JavaScript

    string[] اختيارية

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

  • matchOriginAsFallback

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

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

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

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

    string[] اختيارية

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

  • persistAcrossSessions

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

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

  • runAt

    RunAt اختياري

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

  • العالم

    ExecutionWorld اختياري.

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

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

ScriptInjection

أماكن إقامة

  • الوسيط

    أي[] اختياري

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

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

  • ملفات

    string[] اختيارية

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

  • injectImmediately

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

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

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

  • الاستهداف

    InjectionTarget

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

  • العالم

    ExecutionWorld اختياري.

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

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

  • func

    null اختياري

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

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

    تبدو دالة func كما يلي: 

    () => {...}

StyleOrigin

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

Enum

"AUTHOR"

"USER"

الطُرق

executeScript()

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

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

المعلمات

  • الحقن

    ScriptInjection

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (results: InjectionResult[]) => void

المرتجعات

  • Promise<InjectionResult[]>

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

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

getRegisteredContentScripts()

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

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

المعلمات

  • تصفية

    ContentScriptFilter اختياري

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (scripts: RegisteredContentScript[]) => void

المرتجعات

  • Promise<RegisteredContentScript[]>

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

insertCSS()

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

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

المعلمات

  • الحقن

    CSSInjection

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

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

registerContentScripts()

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

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

المعلمات

  • نصوص برمجية

    RegisteredContentScript[]

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

removeCSS()

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

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

المعلمات

  • الحقن

    CSSInjection

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

unregisterContentScripts()

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

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

المعلمات

  • تصفية

    ContentScriptFilter اختياري

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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

updateContentScripts()

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

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

المعلمات

  • نصوص برمجية

    RegisteredContentScript[]

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

  • رد الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

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