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

يجب أن يتضمّن كل إضافة ملف 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_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"

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

تحدّد هذه السمة الملفات داخل الإضافة التي يمكن لصفحات الويب أو الإضافات الأخرى الوصول إليها. لمزيد من المعلومات، اطّلِع على 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.