النصوص البرمجية للمحتوى

النصوص البرمجية للمحتوى هي ملفات يتم تشغيلها في سياق صفحات الويب. باستخدام نموذج ملف العناصر (DOM) العادي، يمكن لهذه الإضافات قراءة تفاصيل صفحات الويب التي يزورها المتصفّح وإجراء تعديلات عليها ونقل المعلومات إلى الإضافة الرئيسية.

فهم إمكانات النصوص البرمجية للمحتوى

يمكن للنصوص البرمجية للمحتوى الوصول إلى واجهات برمجة تطبيقات Chrome التي تستخدمها الإضافة الرئيسية من خلال تبادل الرسائل. باستخدام الإضافة. ويمكنهم أيضًا الوصول إلى عنوان URL لملف إحدى الإضافات باستخدام chrome.runtime.getURL() واستخدام النتيجة نفسها المستخدَمة في عناوين URL الأخرى.

// Code for displaying EXTENSION_DIR/images/myimage.png:
var imgURL = chrome.runtime.getURL("images/myimage.png");
document.getElementById("someImage").src = imgURL;

بالإضافة إلى ذلك، يمكن للنص البرمجي للمحتوى الوصول مباشرةً إلى واجهات برمجة تطبيقات Chrome التالية:

لا يمكن للنصوص البرمجية للمحتوى الوصول إلى واجهات برمجة التطبيقات الأخرى مباشرةً.

العمل في عوالم معزولة

تعمل نصوص المحتوى البرمجية في بيئة معزولة، ما يسمح لها بإجراء تغييرات على بيئة JavaScript بدون التأثير في الصفحة أو نصوص المحتوى البرمجية الإضافية.

قد يتم تشغيل إضافة في صفحة ويب بها رمز مشابه للمثال أدناه.

<html>
  <button id="mybutton">click me</button>
  <script>
    var greeting = "hello, ";
    var button = document.getElementById("mybutton");
    button.person_name = "Bob";
    button.addEventListener("click", function() {
      alert(greeting + button.person_name + ".");
    }, false);
  </script>
</html>

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

var greeting = "hola, ";
var button = document.getElementById("mybutton");
button.person_name = "Roberto";
button.addEventListener("click", function() {
  alert(greeting + button.person_name + ".");
}, false);

سيظهر كلا التنبيهَين في حال الضغط على الزر.

لا تسمح العوالم المنعزلة للنصوص البرمجية للمحتوى والإضافات وصفحات الويب بالوصول إلى أي متغيّرات أو وظائف أنشأها الآخرون. يتيح ذلك أيضًا النصوص البرمجية للمحتوى إمكانية الوظائف التي ينبغي ألا تتوفر من خلال صفحة الويب.

إدخال النصوص البرمجية

يمكن إدخال نصوص المحتوى البرمجية آليًا أو بشكل صريح.

الإدراج آليًا

استخدِم ميزة "الإدراج الآلي" لنصوص المحتوى التي يجب عرضها في مناسبات معيّنة.

لإدراج نص برمجي للمحتوى، يجب تقديم إذن activeTab في البيان. يمنح هذا الإذن الوصول الآمن إلى مضيف الموقع الإلكتروني النشط والوصول المؤقت إلى إذن علامات التبويب ، ما يتيح تشغيل نص المحتوى في علامة التبويب النشطة الحالية بدون تحديد أذونات مصادر متعددة.

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab"
  ],
  ...
}

يمكن إدخال النصوص البرمجية للمحتوى كرمز.

chrome.runtime.onMessage.addListener(
  function(message, callback) {
    if (message == "changeColor"){
      chrome.tabs.executeScript({
        code: 'document.body.style.backgroundColor="orange"'
      });
    }
  });

أو يمكن إدخال ملف بأكمله.

chrome.runtime.onMessage.addListener(
  function(message, callback) {
    if (message == "runContentScript"){
      chrome.tabs.executeScript({
        file: 'contentScript.js'
      });
    }
  });

الإدراج بشكل صريح

استخدِم ميزة "الإدراج التعريفي" للنصوص البرمجية للمحتوى التي يجب تشغيلها تلقائيًا على صفحات محدّدة.

يتم تسجيل النصوص البرمجية التي تم إدخالها بشكل صريح في البيان ضمن الحقل "content_scripts". ويمكن أن تتضمن ملفات JavaScript أو ملفات CSS أو كليهما. يجب تحديد كل النصوص البرمجية للمحتوى التي يتم تشغيلها تلقائيًا مطابقة الأنماط.

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["http://*.nytimes.com/*"],
     "css": ["myStyles.css"],
     "js": ["contentScript.js"]
   }
 ],
 ...
}
الاسم النوع الوصف
matches {: #matches } مصفوفة من السلاسل مطلوبة تُستخدَم لتحديد الصفحات التي سيتم إدراج نص المحتوى هذا فيها. راجِع أنماط المطابقة للاطّلاع على مزيد من التفاصيل حول بنية هذه السلاسل وأنماط المطابقة والكرات الأرضية للحصول على معلومات عن كيفية استبعاد عناوين URL.
css {: #css } مصفوفة من السلاسل النصية اختياري. قائمة ملفات CSS التي سيتم إدراجها في الصفحات المطابقة يتم إدخالها بالترتيب الذي تظهر به في هذا الصفيف، قبل إنشاء أو عرض أي نموذج كائن في الصفحة.
js {: #js } مصفوفة من السلاسل اختياري قائمة ملفات JavaScript التي سيتم إدراجها في الصفحات المطابقة ويتم إدراجها بالترتيب الذي تظهر به في هذه الصفيف.
match_about_blank {: #match_about_blank } منطقي اختياري ما إذا كان يجب إدراج النص البرمجي في إطار about:blank حيث يتطابق الإطار الرئيسي أو الإطار الافتتاحي مع أحد الأنماط المحدّدة في matches. الإعداد التلقائي هو false.

استبعاد المطابقات والنطاقات الشاملة

يمكن تخصيص مطابقة الصفحة المحدّدة من خلال تضمين الحقول التالية في ملف البيان تسجيل التطبيق.

الاسم النوع الوصف
exclude_matches {: #exclude_matches } مصفوفة من السلاسل النصية اختياري تستثني الصفحات التي سيتمّ إدخال النص البرمجي للمحتوى فيها. اطّلِع على أنماط المطابقة للحصول على مزيد من التفاصيل حول بنية هذه السلاسل.
include_globs {: #include_globs } مصفوفة من السلاسل اختياري. يتم تطبيقها بعد matches لتضمين عناوين URL التي تتطابق أيضًا مع هذه الكرة الأرضية فقط. مخصّصة لمحاكاة الكلمة الرئيسية @include Greasemonkey.
exclude_globs {: #exclude_globs } مصفوفة من السلاسل اختياري. يتم تطبيقها بعد matches لاستبعاد عناوين URL التي تتطابق مع هذا النطاق الشامل. مخصّصة لمحاكاة الكلمة الرئيسية @excludeGreasemonkey.

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

بما أنّ سمة matches مطلوبة، لا يمكن استخدام السمات exclude_matches وinclude_globs وexclude_globs إلا لحصر الصفحات التي ستتأثر.

ستُدخِّل الإضافة التالية النص البرمجي للمحتوى في http://www.nytimes.com/ health ولكن ليس ضمن http://www.nytimes.com/ business .

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

تتبع سمات النطاقات بنية مختلفة وأكثر مرونة من نماذج المطابقة. الكرة الأرضية المقبولة السلاسل هي عناوين URL قد تحتوي على "حرف بدل" العلامات النجمية وعلامات الاستفهام. تتطابق علامة النجمة * مع أي سلسلة بأي طول، بما في ذلك السلسلة الفارغة، في حين تتطابق علامة الاستفهام ? يتطابق مع أي حرف مفرد.

على سبيل المثال، الكرة الأرضية http:// ??? .example.com/foo/ * يتطابق مع أي مما يلي:

  • http:// www .example.com/foo /bar
  • http:// the .example.com/foo /

ومع ذلك، لا يتطابق مع ما يلي:

  • http:// my .example.com/foo/bar
  • http:// example .com/foo/
  • http://www.example.com/foo

وستدخل هذه الإضافة النص البرمجي للمحتوى في http:/www.nytimes.com/ Arts /index.html و http://www.nytimes.com/ job /index.html وليس على http://www.nytimes.com/ Sports /index.html.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

ستدخل هذه الإضافة النص البرمجي للمحتوى في http:// history .nytimes.com و http://.nytimes.com/ History وليس في http:// Science .nytimes.com أو http://www.nytimes.com/ Science

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

يمكن تضمين واحد، أو كل، أو بعض منها لتحقيق النطاق الصحيح.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

وقت التنفيذ

يتم التحكّم في وقت إدخال ملفات JavaScript في صفحة الويب من خلال الحقل run_at. تشير رسالة الأشكال البيانية الحقل المُفضَّل والتلقائي هو "document_idle"، ولكن يمكن أيضًا تحديده على النحو التالي: "document_start" أو "document_end" إذا لزم الأمر.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "run_at": "document_idle",
      "js": ["contentScript.js"]
    }
  ],
  ...
}
الاسم النوع الوصف
document_idle {: #document_idle } سلسلة إجراء مفضل: استخدِم "document_idle" كلما أمكن.

يختار المتصفّح وقتًا لإدراج النصوص البرمجية بين "document_end" ووقت بدء تنشيط الحدث windowonload مباشرةً. تعتمد لحظة الحقن الدقيقة على مدى تعقيد المستند والمدة التي يستغرقها التحميل، ويتم تحسينها لتناسب سرعة تحميل الصفحة.

لا تحتاج النصوص البرمجية للمحتوى التي يتم تشغيلها في "document_idle" إلى الاستماع إلى حدث window.onload، إلا أنها تضمن تشغيلها بعد اكتمال DOM. إذا كان النص البرمجي بحاجة إلى التنفيذ بعد window.onload، يمكن للإضافة التحقّق مما إذا كان onload قد تم تشغيله من خلال استخدام السمة document.readyState.
document_start {: #document_start } سلسلة يتمّ إدراج النصوص البرمجية بعد أيّ ملفات من css، ولكن قبل إنشاء أيّ عنصر تحكم في نموذج البيانات أو تنفيذ أيّ نصّ برمجي آخر.
document_end {: #document_end } سلسلة يتمّ حقن النصوص البرمجية فور اكتمال نموذج DOM، ولكن قبل تحميل الموارد الفرعية، مثل الصور والأطر.

تحديد الإطارات

يسمح الحقل "all_frames" للإضافات بتحديد ما إذا كان يجب إدراج ملفات JavaScript وCSS في جميع الإطارات التي تتطابق مع متطلبات عنوان URL المحدّد أو في الإطار العلوي فقط في علامة تبويب.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "all_frames": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}
الاسم النوع الوصف
all_frames {: #all_frames } منطقي اختياري يتم ضبط هذه الإعدادات على false تلقائيًا، ما يعني أنّه تتم مطابقة الإطار العلوي فقط.

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

التواصل مع صفحة التضمين

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

يمكن تنفيذ مثال باستخدام window.postMessage:

var port = chrome.runtime.connect();

window.addEventListener("message", function(event) {
  // We only accept messages from ourselves
  if (event.source != window)
    return;

  if (event.data.type && (event.data.type == "FROM_PAGE")) {
    console.log("Content script received: " + event.data.text);
    port.postMessage(event.data.text);
  }
}, false);

document.getElementById("theButton").addEventListener("click",
    function() {
  window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*");
}, false);

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

الحفاظ على أمانك

على الرغم من أنّ العوالم المعزولة توفّر طبقة حماية، يمكن أن يؤدي استخدام النصوص البرمجية للمحتوى إلى تعريض الإضافة وصفحة الويب للثغرات الأمنية. إذا تلقّى نص المحتوى محتوًى من موقع ويب منفصل، مثل إنشاء XMLHttpRequest، فاحرص على تصفية المحتوى عبر عدة مواقع يهاجمها باستخدام النصوص البرمجية قبل إدخالها. التواصل عبر HTTPS فقط لتجنب &quot;man-in-the-middle&quot;.

احرص على الفلترة بحثًا عن صفحات الويب الضارّة. على سبيل المثال، الأنماط التالية خطيرة:

var data = document.getElementById("json-data")
// WARNING! Might be evaluating an evil script!
var parsed = eval("(" + data + ")")

var elmt_id = ...
// WARNING! elmt_id might be "); ... evil script ... //"!
window.setTimeout("animate(" + elmt_id + ")", 200);

بدلاً من ذلك، يمكنك تفضيل واجهات برمجة التطبيقات الأكثر أمانًا التي لا تشغّل النصوص البرمجية:

var data = document.getElementById("json-data")
// JSON.parse does not evaluate the attacker's scripts.
var parsed = JSON.parse(data);

var elmt_id = ...
// The closure form of setTimeout does not evaluate scripts.
window.setTimeout(function() {
  animate(elmt_id);
}, 200);