تنسيق ملف البيان

يجب أن تحتوي كل إضافة على ملف manifest.json في الدليل الجذري الذي يعرض معلومات مهمة حول بنية الإضافة وسلوكها. تشرح هذه الصفحة بنية بيانات الإضافات والميزات التي يمكن أن تتضمنها.

أمثلة

تُظهر نماذج البيان التالية بنية البيان الأساسية وبعض الميزات شائعة الاستخدام كنقطة بداية لإنشاء البيان الخاص بك:

{
  "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 الإلكتروني ومربّع حوار التثبيت وصفحة إضافات Chrome لدى المستخدم (chrome://extensions). الحدّ الأقصى للطول هو 75 حرفًا. للحصول على معلومات حول استخدام أسماء خاصة بمناطق محلية معيّنة، يمكنك الاطّلاع على الانتشار على نطاق عالمي.

"version"

سلسلة تحدِّد رقم إصدار الإضافة للحصول على معلومات عن تنسيق رقم الإصدار، راجِع الإصدار.

المفاتيح التي يطلبها "سوق Chrome الإلكتروني"

"description"

سلسلة تصف الإضافة على كل من "سوق Chrome الإلكتروني" وصفحة إدارة الإضافات لدى المستخدم الحد الأقصى لعدد الأحرف المسموح به هو 132 حرفًا. لمزيد من المعلومات عن أقلمة الأوصاف، راجِع القسم الانتشار على نطاق عالمي.

"icons"

رمز واحد أو أكثر يمثّل الإضافة. للحصول على معلومات حول أفضل الممارسات، راجِع الأيقونات.

المفاتيح الاختيارية

"action"

تحدّد هذه السمة مظهر رمز الإضافة وسلوكه في شريط أدوات Google. لمزيد من المعلومات، يُرجى الاطّلاع على chrome.action.

"author"

يحدد عنوان البريد الإلكتروني للحساب الذي تم استخدامه لإنشاء الإضافة.

"background"

يحدد ملف JavaScript الذي يحتوي على مشغّل خدمات الإضافة، والذي يعمل كمعالج للأحداث. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة لمحة عن مشغّلي خدمات الإضافات.

"chrome_settings_overrides"

يحدِّد عمليات الإلغاء لإعدادات Chrome المحدّدة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تجاوز إعدادات Chrome.

"chrome_url_overrides"

يحدِّد عمليات الإلغاء لصفحات Chrome التلقائية. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة إلغاء صفحات Chrome.

"commands"

لتحديد اختصارات لوحة المفاتيح داخل الإضافة. لمزيد من المعلومات، يمكنك الاطّلاع على chrome.commands.

"content_scripts"

تحديد ملفات JavaScript أو CSS التي سيتم استخدامها عندما يفتح المستخدم صفحات ويب معيّنة. لمزيد من المعلومات، يُرجى الاطّلاع على النصوص البرمجية للمحتوى.

"content_security_policy"

تحدّد هذه السياسة القيود المفروضة على النصوص البرمجية والأنماط والموارد الأخرى التي يمكن للإضافة استخدامها. لمزيد من المعلومات، يُرجى الاطّلاع على سياسة أمان المحتوى.

"cross_origin_embedder_policy"

يحدد هذا الإعداد قيمة عنوان HTTP الذي يضبط تضمين الموارد من مصادر متعددة المصادر في صفحة إضافة.

"cross_origin_opener_policy"

يحدد هذا الإعداد قيمة لعنوان HTTP في سياسة Cross-Origin-Opener-Policy، ما يتيح لك التأكّد من أنّ صفحة إضافة المستوى الأعلى لا تشارك مجموعة سياق للتصفّح مع مستندات من مصادر متعددة.

"declarative_net_request"

تحدِّد هذه السياسة قواعد ثابتة لواجهة برمجة التطبيقات declarativeNetRequest، والتي تسمح بحظر طلبات الشبكة وتعديلها.

"default_locale"

سلسلة تحدِّد اللغة التلقائية لإضافة تتيح استخدام لغات متعددة. ومن الأمثلة على ذلك "en" و "pt_BR". هذا المفتاح مطلوب في الإضافات المترجَمة، ويجب عدم استخدامه في الإضافات غير المترجَمة. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة الانتشار على نطاق عالمي.

"devtools_page"

تحدّد الصفحات التي تستخدم واجهات برمجة تطبيقات DevTools.

"export"

يسمح بتصدير الموارد من الإضافة. لمزيد من المعلومات، يمكنك الاطّلاع على تصدير.

"externally_connectable"

يحدد هذا الإعداد الصفحات والإضافات الأخرى التي يمكن ربطها بإضافاتك. لمزيد من المعلومات، يُرجى الاطّلاع على "externally_connectable".

"homepage_url"

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

"host_permissions"

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

"import"

تسمح باستيراد الموارد إلى الإضافة. لمزيد من المعلومات، يُرجى الاطّلاع على استيراد.

"incognito"

تحدد طريقة عمل الإضافة في وضع التصفُّح المتخفي. القيمتان المسموح بإدراجهما هما "spanning" و"split" و"not_allowed". لمزيد من المعلومات، يُرجى الاطّلاع على وضع التصفّح المتخفي.

"key"

يحدد رقم تعريف إضافتك لحالات الاستخدام المختلفة للتطوير. لمزيد من المعلومات، يمكنك الاطّلاع على المفتاح.

"minimum_chrome_version"

يحدِّد هذا الإعداد أقدم إصدار من Chrome يمكنه تثبيت الإضافة. يجب أن تكون القيمة سلسلة فرعية من سلسلة إصدار حالية لمتصفّح Chrome، مثل "107" أو "107.0.5304.87". يظهر تحذير "غير متوافق" في "سوق Chrome الإلكتروني" للمستخدمين الذين لديهم إصدارات أقدم من إصدار Chrome من الحد الأدنى، ولا يمكنهم تثبيت الإضافة. وفي حال إضافته إلى إضافة حالية، لن يتلقّى المستخدمون الذين لديهم إصدار Chrome أقدم تحديثات تلقائية لإضافة تلك الإضافة. ويشمل ذلك مستخدمي الأنشطة التجارية في وضع الملف الشخصي المؤقت.

"oauth2"

يُسمح باستخدام معرّف أمان OAuth 2.0. يجب أن تكون قيمة هذا المفتاح كائنًا مع السمتَين "client_id" و"scopes". لمعرفة التفاصيل، يُرجى الاطّلاع على دليل OAuth 2.0 التعليمي.

"omnibox"

يسمح للإضافة بتسجيل كلمة رئيسية في شريط العناوين في Chrome. لمزيد من المعلومات، راجِع المربّع المتعدد الاستخدامات.

"optional_host_permissions"

يوضح أذونات المضيف الاختيارية لإضافتك.

"optional_permissions"

يفصح عن الأذونات الاختيارية لإضافتك.

"options_page"

يحدد مسارًا إلى ملف options.html للإضافة لاستخدامه كصفحة خيارات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة منح الخيارات للمستخدمين.

"options_ui"

يحدد مسارًا إلى ملف HTML يتيح للمستخدم تغيير خيارات الإضافة من صفحة "إضافات Chrome". لمزيد من المعلومات، يمكنك الاطّلاع على الخيارات المضمّنة.

"permissions"

يفعِّل هذا الإعداد استخدام واجهات برمجة تطبيقات خاصة بإضافات معيّنة. راجِع الأذونات للحصول على شرح عام. تسرد الصفحات المرجعية لواجهات برمجة تطبيقات فردية الأذونات المطلوبة.

"requirements"

يسرد التكنولوجيات المطلوبة لاستخدام الإضافة. للحصول على قائمة بالمتطلبات المتوافقة، راجِع المتطلّبات.

"sandbox"

تحدد هذه السياسة مجموعة من صفحات الإضافات التي لا يمكنها الوصول إلى واجهات برمجة التطبيقات للإضافات أو الوصول المباشر إلى الصفحات غير المشمولة في وضع الحماية. لمزيد من المعلومات، راجِع وضع الحماية.

"short_name"

سلسلة تحتوي على نسخة مختصرة من اسم الإضافة سيتم استخدامها عندما تكون مساحة الأحرف محدودة. الحد الأقصى لعدد الأحرف المسموح به هو 12 حرفًا. وإذا لم يكن ذلك محدّدًا، سيتم عرض نسخة مقتطَعة من مفتاح "name" بدلاً من ذلك.

"side_panel"

يحدد ملف HTML لعرضه في sidePanel.

"storage"

يوضح مخطط JSON لمنطقة التخزين المُدارة. لمزيد من المعلومات، يمكنك الاطّلاع على بيان مناطق التخزين.

"tts_engine"

لتسجيل الإضافة كمحرّك تحويل النص إلى كلام لمزيد من المعلومات، يمكنك الاطّلاع على واجهة برمجة التطبيقات ttsEngine.

"update_url"

سلسلة تحتوي على عنوان URL لصفحة تحديثات الإضافة استخدِم هذا المفتاح في حال استضافة الإضافة خارج "سوق Chrome الإلكتروني".

"version_name"

سلسلة تصف إصدار الإضافة تشمل الأمثلة "1.0 beta" و"build rc2". وفي حال عدم تحديد ذلك، يتم عرض قيمة "الإصدار" على صفحة إدارة الإضافة بدلاً من ذلك.

"web_accessible_resources"

لتحديد الملفات داخل الإضافة التي يمكن الوصول إليها من خلال صفحات الويب أو الإضافات الأخرى. للمزيد من المعلومات، يُرجى الاطّلاع على موارد Web Accessible.

مفاتيح ChromeOS الاختيارية

"file_browser_handlers"

يوفّر هذا الإعداد إمكانية الوصول إلى واجهة برمجة التطبيقات fileBrowserHandler، التي تسمح للإضافات بالوصول إلى متصفِّح الملفات في نظام التشغيل ChromeOS.

"file_handlers"

يحدد هذا الإعداد أنواع الملفات التي ستعالجها إضافات نظام التشغيل ChromeOS. لمزيد من المعلومات، يُرجى الاطّلاع على file_handlers.

"file_system_provider_capabilities"

تتيح هذه السياسة الوصول إلى واجهة برمجة التطبيقات fileSystemProvider، التي تتيح للإضافات إنشاء أنظمة ملفات يمكن لنظام ChromeOS استخدامها.

"input_components"

يسمح باستخدام واجهة برمجة التطبيقات Conversion Method Editor (محرر أسلوب الإدخال). لمزيد من المعلومات، يُرجى الاطّلاع على input_components.