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"));

ملاحظة: لا يمكنك تحديد كل من السمتَين "frameIds" و"allFrames".

الرمز الذي تم إدخاله

يمكن للإضافات تحديد الرمز المُراد إدخاله إما عن طريق ملف خارجي أو متغير وقت التشغيل.

الملفات

يتم تحديد الملفات كسلاسل مسارات ذات صلة بجذر الإضافة. الدليل. سيُدخل الرمز التالي الملف 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

  • النتائج

    InjectionResult[]

المرتجعات

• Promise<InjectionResult[]>

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

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

getRegisteredContentScripts()

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

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

المعلمات

• تصفية

  ContentScriptFilter اختياري

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

• رد الاتصال

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

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

  (scripts: RegisteredContentScript[]) => void

  • نصوص برمجية

    RegisteredContentScript[]

المرتجعات

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