مانیفست - متن‌های محتوا

کلید "content_scripts" فایل CSS یا جاوا اسکریپت بارشده به‌صورت ایستا را مشخص می‌کند تا هربار که صفحه‌ای مطابق با الگوی نشانی وب خاصی باز می‌شود، از آن استفاده شود. افزونه‌ها همچنین می‌توانند متن‌های محتوا را به‌صورت برنامه‌نویسی تزریق کنند، برای جزئیات بیشتر به تزریق متن‌ها مراجعه کنید.

مانیفست

این‌ها کلیدهای پشتیبانی‌شده برای "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" - آرایه،
اختیاری. آرایه‌ای از مسیرهای فایل جاوا اسکریپت که به ترتیبی که در این آرایه ظاهر می‌شوند، پس‌از تزریق فایل‌های css تزریق می‌شوند. هر رشته در آرایه باید مسیر نسبی به منبعی در دایرکتوری ریشه افزونه باشد. خط مورب ابتدایی (/) به‌طور خودکار حذف می‌شود.

مطابقت نشانی‌های وب

فقط خصوصیت "matches" لازم است. سپس می‌توانید از "exclude_matches"، "include_globs"، و "exclude_globs" برای سفارشی‌سازی نشانی‌های وبی که کد به آن‌ها تزریق می‌شود استفاده کنید. کلید "matches" هشدار را راه‌اندازی می‌کند.

‫"matches" - آرایه
الزامی. مشخص می‌کند که دستورگان محتوا به کدام الگوهای نشانی وب تزریق شود. برای نحو، الگوهای مطابقت را ببینید.
"exclude_matches" - آرایه
اختیاری. الگوهای نشانی وب را برای تزریق متون محتوا مستثنی می‌کند. برای نحو، الگوهای مطابقت را ببینید.
"include_globs" - آرایه
اختیاری. پس‌از مطابقت‌ها اعمال می‌شود تا فقط نشانی‌های وبی را که با این glob مطابقت دارند دربرگیرد. برای شبیه‌سازی کلیدواژه Greasemonkey @include درنظر گرفته شده است.
‫"exclude_globs" - آرایه
اختیاری. پس‌از مطابقت‌ها اعمال می‌شود تا نشانی‌های وب مطابق با این glob مستثنی شوند. برای شبیه‌سازی کلیدواژه @exclude Greasemonkey درنظر گرفته شده است.

نشانی‌های وب Glob نشانی‌هایی هستند که حاوی «نویسه‌های عام» * و علامت سؤال هستند. نویسه عام * با هر رشته‌ای با هر طولی، ازجمله رشته خالی، مطابقت دارد، درحالی‌که علامت سؤال ؟ با هر نویسه تکی مطابقت دارد.

متن محتوا در صفحه تزریق می‌شود اگر:

  • نشانی وب آن با هریک از الگوهای "matches" و "include_globs" مطابقت داشته باشد.
  • و نشانی وب با الگوهای "exclude_matches" یا "exclude_globs" مطابقت ندارد.

نمونه‌های تطابق نشانی وب و الگوهای تطابق

"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" مشخص می‌کند که آیا اسکریپت محتوا باید به همه فریم‌های منطبق با الزامات نشانی وب مشخص‌شده تزریق شود یا نه. اگر روی false تنظیم شود، فقط به بالاترین قاب تزریق می‌شود. می‌توان از آن همراه با "match_about_blank" برای تزریق به قاب about:blank استفاده کرد.

برای تزریق به قاب‌های دیگر مانند data:، blob:، و filesystem:، "match_origin_as_fallback" را روی true تنظیم کنید. برای جزئیات، تزریق در قاب‌های مرتبط را ببینید

"all_frames" بولی
اختیاری. به‌طور پیش‌فرض روی false تنظیم شده است، یعنی فقط قاب بالایی مطابقت داده می‌شود. اگر روی «درست» تنظیم شود، به همه قاب‌ها تزریق می‌شود، حتی اگر قاب بالاترین قاب در برگه نباشد. هر قاب به‌طور مستقل ازنظر الزامات نشانی وب بررسی می‌شود و اگر الزامات نشانی وب برآورده نشود، در قاب‌های فرزند تزریق نخواهد شد.
"match_about_blank"- بولی
اختیاری. پیش‌فرض‌ها به false. آیا اسکریپت باید به قاب about:blank تزریق شود که در آن نشانی وب اصلی با یکی از الگوهای اعلام‌شده در "matches" مطابقت دارد یا نه.
"match_origin_as_fallback" - بولی
اختیاری. پیش‌فرض‌ها به false. اینکه آیا اسکریپت باید در قاب‌هایی که توسط مبدأ منطبق ایجاد شده‌اند تزریق شود یا نه، اما نشانی وب یا مبدأ آن ممکن است مستقیماً با الگو مطابقت نداشته باشد. این شامل قاب‌هایی با طرح‌های مختلف، مانند 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
اختیاری. دنیای جاوا اسکریپت برای اجرای اسکریپت در آن. به‌طور پیش‌فرض روی "ISOLATED" تنظیم شده است که محیط اجرای منحصربه‌فرد برای اسکریپت محتوا است. انتخاب دنیای "MAIN" به این معنی است که اسکریپت محیط اجرا را با جاوا اسکریپت صفحه میزبان هم‌رسانی خواهد کرد. برای کسب اطلاعات بیشتر، به کار در محیط‌های مجزا مراجعه کنید.

مثال

برای ساختن افزونه‌ای که متن محتوا را در مانیفست تزریق می‌کند، آموزش اجرا در هر صفحه را ببینید.