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

يحدّد المفتاح "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 التي تتطابق مع هذه الكرة الأرضية. الغرض منها محاكاة الكلمة الرئيسية @excluded Greasemonkey.

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

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

• ويتطابق عنوان URL مع أي نمط "matches" و"include_globs".
• لا يتطابق عنوان URL مع النمط "exclude_matches" أو "exclude_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 أو مصدر عنوان 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" على مخاطر كبيرة. يمكن لصفحة المضيف الوصول إلى النص البرمجي الذي تم إدخاله والتداخل معه. راجِع مقالة العمل في عوالم معزولة لمزيد من المعلومات.

مثال

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