فرمت فایل مانیفست

هر افزونه باید یک فایل manifest.json در دایرکتوری ریشه خود داشته باشد که اطلاعات مهم در مورد ساختار و رفتار آن افزونه را فهرست می‌کند. این صفحه ساختار manifestهای افزونه و ویژگی‌هایی که می‌توانند شامل شوند را توضیح می‌دهد.

مثال‌ها

مانیفست‌های نمونه زیر ساختار اولیه مانیفست و برخی از ویژگی‌های رایج را به عنوان نقطه شروع برای ایجاد مانیفست خودتان نشان می‌دهند:

{
  "manifest_version": 3,
  "name": "Minimal Manifest",
  "version": "1.0.0",
  "description": "A basic example extension with only required keys",
  "icons": {
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

{
  "manifest_version": 3,
  "name": "Run script automatically",
  "description": "Runs a script on www.example.com automatically when user installs the extension",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "content_scripts": [
    {
      "js": [
        "content-script.js"
      ],
      "matches": [
        "http://*.example.com//"
      ]
    }
  ]
}

{
  "manifest_version": 3,
  "name": "Click to run",
  "description": "Runs a script when the user clicks the action toolbar icon.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "background": {
    "service_worker": "service-worker.js"
  },
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  "permissions": ["scripting", "activeTab"]
}

{
  "manifest_version": 3,
  "name": "Popup extension that requests permissions",
  "description": "Extension that includes a popup and requests host permissions and storage permissions.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "host_permissions": [
    "https://*.example.com/"
  ],
  "permissions": [
    "storage"
  ]
}

{
  "manifest_version": 3,
  "name": "Side panel extension",
  "version": "1.0",
  "description": "Extension with a default side panel.",
  "icons": {
    "16": "images/icon-16.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "permissions": ["sidePanel"]
}

کلیدهای مانیفست

در زیر لیستی از تمام کلیدهای مانیفست پشتیبانی شده آمده است.

کلیدهای مورد نیاز پلتفرم افزونه‌ها

"manifest_version"

یک عدد صحیح که نسخه فرمت فایل مانیفست مورد استفاده افزونه شما را مشخص می‌کند. تنها مقدار پشتیبانی شده 3 است.

"name"

رشته‌ای که افزونه را در فروشگاه وب کروم ، پنجره نصب و صفحه افزونه‌های کروم کاربر ( chrome://extensions ) مشخص می‌کند. حداکثر طول ۷۵ کاراکتر است. برای اطلاعات بیشتر در مورد استفاده از نام‌های مختص به زبان، به بین‌المللی‌سازی مراجعه کنید.

"version"

رشته‌ای که شماره نسخه افزونه را مشخص می‌کند. برای اطلاعات بیشتر در مورد قالب‌بندی شماره نسخه، به Version مراجعه کنید.

کلیدهای مورد نیاز فروشگاه وب Chrome

"description"

رشته‌ای که افزونه را هم در فروشگاه وب کروم و هم در صفحه مدیریت افزونه‌های کاربر توصیف می‌کند. حداکثر طول آن ۱۳۲ کاراکتر است. برای اطلاعات بیشتر در مورد بومی‌سازی توضیحات، به بین‌المللی‌سازی مراجعه کنید.

"icons"

یک یا چند آیکون که نمایانگر افزونه شما هستند. برای اطلاعات بیشتر در مورد بهترین شیوه‌ها، به بخش آیکون‌ها مراجعه کنید.

کلیدهای اختیاری

"action"

ظاهر و رفتار آیکون افزونه را در نوار ابزار گوگل تعریف می‌کند. برای اطلاعات بیشتر، به chrome.action مراجعه کنید.

"background"

فایل جاوا اسکریپتی را مشخص می‌کند که شامل سرویس ورکر افزونه است و به عنوان یک مدیریت‌کننده رویداد عمل می‌کند. برای اطلاعات بیشتر، به «درباره سرویس ورکرهای افزونه» مراجعه کنید.

"chrome_settings_overrides"

تنظیمات انتخاب‌شده‌ی کروم را لغو می‌کند. برای اطلاعات بیشتر، به لغو تنظیمات کروم مراجعه کنید.

"chrome_url_overrides"

صفحات پیش‌فرض کروم را لغو می‌کند. برای اطلاعات بیشتر، به لغو صفحات کروم مراجعه کنید.

"commands"

میانبرهای صفحه‌کلید را در افزونه تعریف می‌کند. برای اطلاعات بیشتر، به chrome.commands مراجعه کنید.

"content_scripts"

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

"content_security_policy"

محدودیت‌هایی را برای اسکریپت‌ها، استایل‌ها و سایر منابعی که یک افزونه می‌تواند استفاده کند، تعریف می‌کند. برای اطلاعات بیشتر، به سیاست امنیتی محتوا مراجعه کنید.

"cross_origin_embedder_policy"

مقداری را برای هدر HTTP مربوط به Cross-Origin-Embedder-Policy مشخص می‌کند که جاسازی منابع cross-origin را در یک صفحه افزونه پیکربندی می‌کند.

"cross_origin_opener_policy"

مقداری را برای هدر HTTP مربوط به Cross-Origin-Opener-Policy مشخص می‌کند که به شما امکان می‌دهد اطمینان حاصل کنید که یک صفحه افزونه سطح بالا، گروه زمینه مرور را با اسناد cross-origin به اشتراک نمی‌گذارد.

"declarative_net_request"

قوانین ایستا را برای API اعلانی NetRequest تعریف می‌کند که امکان مسدود کردن و تغییر درخواست‌های شبکه را فراهم می‌کند.

"default_locale"

رشته‌ای که زبان پیش‌فرض افزونه‌ای را که از چندین زبان پشتیبانی می‌کند، تعریف می‌کند. مثال‌هایی از آن شامل "en" و "pt_BR" می‌شود. این کلید در افزونه‌های بومی‌سازی‌شده مورد نیاز است و نباید در افزونه‌هایی که بومی‌سازی نشده‌اند، استفاده شود. برای اطلاعات بیشتر، به بین‌المللی‌سازی مراجعه کنید.

"devtools_page"

صفحاتی را تعریف می‌کند که از APIهای DevTools استفاده می‌کنند.

"export"

اجازه می‌دهد منابع از افزونه صادر شوند. برای اطلاعات بیشتر، به «صادرات» مراجعه کنید.

"externally_connectable"

مشخص می‌کند که چه صفحات و افزونه‌های دیگری می‌توانند به افزونه‌های شما متصل شوند. برای اطلاعات بیشتر، به "externally_connectable" مراجعه کنید.

"homepage_url"

رشته‌ای که URL صفحه اصلی افزونه را مشخص می‌کند. اگر این مقدار تعریف نشده باشد، صفحه اصلی به طور پیش‌فرض صفحه فروشگاه وب کروم افزونه است. این فیلد به ویژه در صورتی مفید است که افزونه را در سایت خود میزبانی می‌کنید .

"host_permissions"

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

"import"

اجازه می‌دهد منابع به افزونه وارد شوند. برای اطلاعات بیشتر، به بخش «وارد کردن» مراجعه کنید.

"incognito"

نحوه رفتار افزونه در حالت ناشناس را تعریف می‌کند. مقادیر پشتیبانی‌شده عبارتند از "spanning" ، "split" و "not_allowed" . برای اطلاعات بیشتر، به حالت ناشناس مراجعه کنید.

"key"

شناسه افزونه شما را برای موارد استفاده مختلف توسعه مشخص می‌کند. برای اطلاعات بیشتر، به کلید مراجعه کنید.

"minimum_chrome_version"

قدیمی‌ترین نسخه کروم که می‌تواند افزونه شما را نصب کند را تعریف می‌کند. مقدار باید زیررشته‌ای از رشته نسخه مرورگر کروم موجود باشد، مانند "107" یا "107.0.5304.87" . کاربرانی که نسخه‌های کروم آنها قدیمی‌تر از حداقل نسخه است، هشدار "سازگار نیست" را در فروشگاه وب کروم مشاهده می‌کنند و قادر به نصب افزونه شما نیستند. اگر این را به یک افزونه موجود اضافه کنید، کاربرانی که نسخه کروم آنها قدیمی‌تر است، به‌روزرسانی‌های خودکار افزونه شما را دریافت نخواهند کرد. این شامل کاربران تجاری در حالت موقت نیز می‌شود.

"oauth2"

اجازه استفاده از شناسه امنیتی OAuth 2.0 را می‌دهد. مقدار این کلید باید یک شیء با ویژگی‌های "client_id" و "scopes" باشد. برای جزئیات بیشتر، به آموزش OAuth 2.0 مراجعه کنید.

"omnibox"

به افزونه اجازه می‌دهد تا یک کلمه کلیدی را در نوار آدرس کروم ثبت کند. برای اطلاعات بیشتر، به Omnibox مراجعه کنید.

"optional_host_permissions"

مجوزهای میزبان اختیاری را برای افزونه شما اعلام می‌کند.

"optional_permissions"

مجوزهای اختیاری را برای افزونه شما اعلام می‌کند.

"options_page"

مسیری را به فایل options.html برای افزونه مشخص می‌کند تا به عنوان صفحه گزینه‌ها از آن استفاده شود. برای اطلاعات بیشتر، به «دادن گزینه‌های به کاربران» مراجعه کنید.

"options_ui"

مسیری را به یک فایل HTML مشخص می‌کند که به کاربر اجازه می‌دهد گزینه‌های افزونه را از صفحه افزونه‌های کروم تغییر دهد. برای اطلاعات بیشتر، به گزینه‌های تعبیه‌شده مراجعه کنید.

"permissions"

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

"requirements"

فناوری‌های مورد نیاز برای استفاده از افزونه را فهرست می‌کند. برای فهرستی از الزامات پشتیبانی‌شده، به الزامات مراجعه کنید.

"sandbox"

مجموعه‌ای از صفحات افزونه را تعریف می‌کند که به APIهای افزونه یا صفحات غیر sandbox شده دسترسی مستقیم ندارند. برای اطلاعات بیشتر، به Sandbox مراجعه کنید.

"short_name"

رشته‌ای حاوی نسخه‌ی کوتاه‌شده‌ی نام افزونه که در صورت محدودیت فضای کاراکتری استفاده می‌شود. حداکثر طول آن ۱۲ کاراکتر است. اگر این مقدار تعریف نشده باشد، نسخه‌ی کوتاه‌شده‌ی کلید "name" نمایش داده می‌شود.

"side_panel"

یک فایل HTML را برای نمایش در sidePanel شناسایی می‌کند.

"storage"

یک طرحواره JSON برای ناحیه ذخیره‌سازی مدیریت‌شده اعلام می‌کند. برای اطلاعات بیشتر، به Manifest برای نواحی ذخیره‌سازی مراجعه کنید.

"tts_engine"

افزونه را به عنوان موتور تبدیل متن به گفتار ثبت می‌کند. برای اطلاعات بیشتر، به API مربوط به ttsEngine مراجعه کنید.

"update_url"

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

"version_name"

رشته‌ای که نسخه افزونه را توصیف می‌کند. مثال‌ها شامل "1.0 beta" و "build rc2" هستند. اگر این مورد مشخص نشده باشد، مقدار "version" در صفحه مدیریت افزونه نمایش داده می‌شود.

"web_accessible_resources"

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

کلیدهای اختیاری ChromeOS

"file_browser_handlers"

دسترسی به API fileBrowserHandler را فراهم می‌کند که به افزونه‌ها اجازه می‌دهد به مرورگر فایل ChromeOS دسترسی داشته باشند.

"file_handlers"

انواع فایل‌هایی را که افزونه‌های ChromeOS باید مدیریت کنند، مشخص می‌کند. برای اطلاعات بیشتر، به file_handlers مراجعه کنید.

"file_system_provider_capabilities"

دسترسی به رابط برنامه‌نویسی کاربردی fileSystemProvider را امکان‌پذیر می‌کند، که به افزونه‌ها اجازه می‌دهد سیستم‌های فایلی ایجاد کنند که ChromeOS بتواند از آنها استفاده کند.

"input_components"

اجازه استفاده از API ویرایشگر متد ورودی را می‌دهد. برای اطلاعات بیشتر، به input_components مراجعه کنید.