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

يجب أن تتضمّن كل إضافة ملف 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"
رمز واحد أو أكثر يمثّل الإضافة. لمعرفة معلومات حول أفضل الممارسات، يُرجى الاطّلاع على مقالة Icons.

الحقول الرئيسية الاختيارية

"action"
يحدّد مظهر رمز الإضافة وسلوكه في شريط أدوات Google. لمزيد من المعلومات، يُرجى الاطّلاع على chrome.action.
"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"
سلسلة تحدّد اللغة التلقائية لإضافة تتوافق مع لغات متعددة. تشمل الأمثلة "ar" و"pt_BR". هذا الحقل مطلوب في الإضافات المترجَمة، ويجب عدم استخدامه في الإضافات غير المترجَمة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تدويل الإضافات.
"devtools_page"
يحدّد الصفحات التي تستخدم واجهات برمجة تطبيقات DevTools.
"export"
يسمح بتصدير الموارد من الإضافة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التصدير.
"externally_connectable"
يحدّد الصفحات والإضافات الأخرى التي يمكنها الاتصال بإضافاتك. لمزيد من المعلومات، يُرجى الاطّلاع على "externally_connectable".
"homepage_url"
سلسلة تحدّد عنوان URL للصفحة الرئيسية للإضافة. إذا لم يتم تحديد هذه السلسلة، ستكون الصفحة الرئيسية تلقائيًا هي صفحة الإضافة في "سوق Chrome الإلكتروني". يكون هذا الحقل مفيدًا بشكل خاص إذا كنت تستضيف الإضافة على موقعك الإلكتروني.
"host_permissions"
يسرد صفحات الويب التي يُسمح لإضافتك بالتفاعل معها، ويتم تحديدها باستخدام أنماط مطابقة عناوين URL. يُطلب إذن المستخدم لهذه المواقع الإلكترونية في وقت التثبيت. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة أذونات المضيف.
"import"
يسمح باستيراد الموارد إلى الإضافة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الاستيراد.
"incognito"
يحدّد سلوك الإضافة في "وضع التصفّح المتخفي". القيم المتاحة هي "spanning"، "split"، و"not_allowed". لمزيد من المعلومات، يُرجى الاطّلاع على مقالة وضع التصفّح المتخفي .
"key"
يحدّد معرّف الإضافة لحالات استخدام مختلفة في التطوير. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة المفتاح.
"mime_types_handler"
يسجّل الإضافة كمعالج لأنواع MIME المتوافقة، مثل application/pdf. لمزيد من المعلومات، يُرجى الاطّلاع على الـ mimeHandler API.
"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". إذا لم يتم تحديد هذه السلسلة، ستظهر قيمة الحقل "version" في صفحة إدارة الإضافات بدلاً منها.
"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.