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

يحدّد المفتاح "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",
   }
 ],
 ...
}

Files

يجب أن يحتوي كل ملف على مسار نسبي إلى مورد في الدليل الجذر للإضافة. يتم تلقائيًا اقتطاع الشرطات المائلة البادئة (/). يحدّد مفتاح "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 التي تتطابق مع هذه الكلمة الرئيسية. الغرض منها محاكاة الكلمة الرئيسية @استبعاد من النوع Grease ألف.

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

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

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

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

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

مثال

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