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

يحدّد مفتاح "content_scripts" ملف JavaScript أو CSS يتم تحميله بشكل ثابت ليتم استخدامه في كل مرة يتم فيها فتح صفحة تتطابق مع نمط عنوان URL معيّن. يمكن للإضافات أيضًا إدخال نصوص برمجية للمحتوى آليًا، راجِع إدخال النصوص البرمجية لمعرفة التفاصيل.

البيان

في ما يلي المفاتيح المتوافقة مع "content_scripts". يجب توفير المفتاح "matches" وإما "js" أو "css" فقط.

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

الملفات

يجب أن يحتوي كل ملف على مسار نسبي إلى مورد في الدليل الجذري للإضافة. يتم تلقائيًا اقتطاع الشرطات المائلة في البداية (/). يحدّد المفتاح "run_at" وقت إدخال كل ملف.

‫"css" - مصفوفة

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

‫"js" - مصفوفة

اختياري: مصفوفة من مسارات ملفات JavaScript، يتم إدخالها بالترتيب الذي تظهر به في هذه المصفوفة، بعد إدخال ملفات CSS. يجب أن تكون كل سلسلة في الصفيف مسارًا نسبيًا لمورد في الدليل الجذري للإضافة. تتم تلقائيًا إزالة الشرطات المائلة ('/') في بداية المسار.

مطابقة عناوين URL

يجب استخدام السمة "matches" فقط. ويمكنك بعد ذلك استخدام "exclude_matches" و"include_globs" و"exclude_globs" لتخصيص عناوين URL التي يتم إدخال الرمز فيها. سيؤدي مفتاح "matches" إلى ظهور تحذير.

‫"matches" - مصفوفة

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

‫"exclude_matches" - مصفوفة

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

‫"include_globs" - مصفوفة

اختياري: يتم تطبيقها بعد المطابقات لتضمين عناوين URL التي تتطابق أيضًا مع هذا النمط العام فقط. تهدف إلى محاكاة الكلمة الرئيسية @include في Greasemonkey.

‫"exclude_globs" - مصفوفة

اختياري: يتم تطبيق هذا الفلتر بعد المطابقات لاستبعاد عناوين URL التي تتطابق مع هذا النمط. تهدف إلى محاكاة الكلمة الرئيسية @exclude في Greasemonkey.

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

يتم إدخال النص البرمجي للمحتوى في صفحة في الحالات التالية:

• يتطابق عنوان URL الخاص به مع أي من نمطَي "matches" و"include_globs".
• ولا يتطابق عنوان URL مع أنماط "exclude_matches" أو "exclude_globs".

أمثلة على مطابقة Globs وعناوين URL

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}

أعواد ثقاب

https://www.example.com/foo/bar
https://the.example.com/foo/

لا يطابق

https://my.example.com/foo/bar
https://example.com/foo/*
https://www.example.com/foo

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}

أعواد ثقاب

https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html

لا يطابق

https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}

أعواد ثقاب

https://history.example.com
https://.example.com/music

لا يطابق

https://science.example.com
https://www.example.com/science

مثال على التخصيص المتقدّم

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}

أعواد ثقاب

https://www.example.com/arts/index.html
https://.example.com/jobs/index.html

لا يطابق

https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

الإطارات

يحدّد المفتاح "all_frames" ما إذا كان يجب إدخال نص المحتوى البرمجي في جميع الإطارات التي تتطابق مع متطلبات عنوان URL المحدّد. في حال ضبط السياسة على false، سيتم إدخال النص البرمجي في الإطار العلوي فقط. ويمكن استخدامها مع "match_about_blank" لإدخالها في إطار about:blank.

لإدخال الإضافات في إطارات أخرى، مثل data: وblob: وfilesystem:، اضبط "match_origin_as_fallback" على true. لمعرفة التفاصيل، يُرجى الاطّلاع على الحقن في الإطارات ذات الصلة

"all_frames" قيمة منطقية

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

‫"match_about_blank": قيمة منطقية

اختياري: القيمة التلقائية هي false. تحدّد هذه السياسة ما إذا كان يجب حقن النص البرمجي في إطار about:blank يتطابق فيه عنوان URL الرئيسي مع أحد الأنماط الموضّحة في "matches".

"match_origin_as_fallback" - قيمة منطقية

اختياري: القيمة التلقائية هي false. ما إذا كان يجب حقن النص البرمجي في الإطارات التي تم إنشاؤها بواسطة مصدر مطابق، ولكن قد لا يتطابق عنوان URL أو المصدر الخاص بها مع النمط مباشرةً. ويشمل ذلك الإطارات ذات المخططات المختلفة، مثل about: وdata: وblob: وfilesystem:.

وقت التشغيل وبيئة التنفيذ

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

"run_at" - document_start | document_end | document_idle

اختياري: تحدّد هذه السمة وقت إدخال النص البرمجي في الصفحة. وهي تتوافق مع حالات تحميل Document.readyState:

• ‫"document_start": لا يزال DOM قيد التحميل.
• ‫"document_end": لا تزال موارد الصفحة قيد التحميل
• ‫"document_idle": تم الانتهاء من تحميل DOM والموارد. وهذا هو الخيار التلقائي.

"world" - ISOLATED | MAIN

اختياري: تمثّل هذه السمة بيئة JavaScript التي يتم تنفيذ النص البرمجي فيها. القيمة التلقائية هي "ISOLATED"، وهي بيئة التنفيذ الفريدة للنص البرمجي للمحتوى. يعني اختيار بيئة "MAIN" أنّ النص البرمجي سيشارك بيئة التنفيذ مع JavaScript في الصفحة المضيفة. لمزيد من المعلومات، يُرجى الاطّلاع على العمل في بيئات معزولة.

تحذير: هناك مخاطر مرتبطة باستخدام عالم ""MAIN"". يمكن للصفحة المضيفة الوصول إلى النص البرمجي المُدخَل والتدخّل فيه. يُرجى الاطّلاع على العمل في بيئات معزولة لمزيد من المعلومات.

مثال

يمكنك الاطّلاع على البرنامج التعليمي التشغيل في كل صفحة لإنشاء إضافة تُدخِل نصًا برمجيًا للمحتوى في البيان.