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

يجب أن تحتوي كل إضافة على ملف 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-Embedder-Policy، الذي يضبط عملية تضمين الموارد من مصادر متعددة في صفحة إضافة.

"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"

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

"import"

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

"incognito"

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

"key"

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

"minimum_chrome_version"

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

"oauth2"

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

"omnibox"

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

"optional_host_permissions"

يُفصِح عن أذونات المضيف الاختيارية ل إضافة Chrome.

"optional_permissions"

تُستخدَم هذه السمة للإعلان عن الأذونات الاختيارية التي تطلبها إضافتك.

"options_page"

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

"options_ui"

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

.

"permissions"

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

"requirements"

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

"sandbox"

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

"short_name"

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

"side_panel"

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

"storage"

يُعلن عن مخطّط JSON لـ مساحة التخزين المُدارة. لمزيد من المعلومات، يُرجى الاطّلاع على بيان مساحات التخزين.

"tts_engine"

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

"update_url"

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

"version_name"

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

"web_accessible_resources"

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

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

"file_browser_handlers"

يتيح الوصول إلى واجهة برمجة التطبيقات fileBrowserHandler ، التي تتيح للإضافات الوصول إلى متصفّح ملفات ChromeOS.

"file_handlers"

تُستخدَم لتحديد أنواع الملفات التي يمكن لإضافات ChromeOS معالجتها. لمزيد من المعلومات، يُرجى الاطّلاع على file_handlers.

"file_system_provider_capabilities"

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

"input_components"

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