شرح manifest.json: مرجع سريع لحقول MV3
💡 خلاصة في سطر: manifest.json هو الملف الوحيد الذي لا غنى عنه في الإضافة — 3 حقول إلزامية للمنصة كأساس، و2 حقول إلزامية للمتجر للنشر، والباقي يُضاف حسب الوظيفة.
في الدرس السابق C2 أول إضافة Chrome، كان manifest.json منقولًا حرفيًا: يعمل، لكن لماذا كُتب كل حقل بهذه الطريقة قد لا يكون واضحًا. في هذا الدرس سنفكّكه حقلًا حقلًا — أي الحقول يرفض Chrome تحميلها إذا غابت، وأيها لا يُتحقق منها إلا عند النشر، وكيف تُكتب الحقول الاختيارية عالية الاستخدام. لاحقًا سواء كتبت بنفسك أو طلبت من AI التوليد، ستكون قادرًا على الفهم والتعديل وتصحيح الأخطاء.
ماذا ستستطيع أن تفعل بعد التعلم
- ذكر 3 حقول manifest.json الإلزامية للمنصة و2 حقول إلزامية للمتجر، وقيود الطول والتنسيق لكل منها
- بدءًا من المثال الأدنى، إضافة action وbackground وcontent_scripts وpermissions واحدًا واحدًا إلى manifest الخاص بك
- استخدام جدول مرجع سريع واحد لحقول MV3 للوصول إلى دور جميع الحقول البالغ عددها 46 حقلًا
- تجنّب ثلاث نقاط فشل للمبتدئين: كتابة التعليقات في JSON، ونسخ الدروس القديمة لـ MV2، ورقم إصدار غير مطابق
- التحقق وفق قائمة قبل النشر، ومعرفة المعلومات التي لا يمكن تعديلها بعد الرفع
معضلتك الآن
- «ولّد لي AI ملف manifest.json، لكن أي الحقول إلزامي وما وظيفة كل حقل، لا أفهم ذلك إطلاقًا»
- «نسخت من دروس قديمة على الإنترنت، والحقول دائمًا لا تتطابق — ثم عرفت لاحقًا أن ذلك كان أسلوب MV2، فتعبني بلا فائدة»
- «التحميل المحلي يعمل بشكل جيد تمامًا، وبمجرد الرفع إلى المتجر يظهر Cannot parse the manifest، وبحثت طويلًا دون معرفة مكان الخطأ»
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- الاستعلام عن طريقة كتابة وقيود حقل معين في manifest (ما أقصى طول لـ name، وكم جزءًا يمكن أن يحتويه version)
- بناء manifest.json قابل للتحميل من الصفر، أو إضافة حقول لميزات جديدة إلى إضافة قائمة
- التحقق من العناصر الإلزامية قبل النشر، وقمع «اكتشاف الخطأ بعد الرفع» قبل الرفع
ولا تريد:
- قراءة الشرح الكامل لـ 46 حقلًا في الوثائق الرسمية — الجدول المرجعي السريع في الشاشة التالية
- أن يرفض Chrome تحميل الإضافة أو يرفضها المتجر بسبب خطأ في الحقول
- الخلط بين أسلوب MV2 وMV3، فتنسخ الدرس خطأً وتظن أن Chrome معطّل
🎒 التحضير قبل البدء
- إكمال C2 أول إضافة Chrome، ولديك ذلك الملف manifest.json الخاص بـ Hello World القابل للتشغيل
- أداة لتحرير ملفات JSON (المفكرة تكفي، ومحرر مثل VS Code أكثر راحة)
- صفحة
chrome://extensionsلإدارة الإضافات مفتوحة، لتسهيل التحديث والتحقق في أي وقت - 10 دقيقة
الفكرة الأساسية
لدى Chrome متطلب واحد صارم فقط لكل إضافة: يجب أن يوجد ملف manifest.json في المجلد الجذري، فهو يسرد معلومات بنية هذه الإضافة وسلوكها — يعرف Chrome الإضافة به، ويراجعها المتجر به.
قسّمت الوثائق الرسمية جميع الحقول البالغ عددها 46 حقلًا إلى أربع مجموعات، وليحفظ المبتدئ المجموعتين الأوليين أولًا:
| المجموعة | الحقول | ماذا يحدث عند غيابها |
|---|---|---|
| إلزامية للمنصة (3 حقول) | manifest_version وname وversion | يرفض Chrome التحميل مباشرة ويظهر مربع حوار خطأ |
| إلزامية للنشر في المتجر (2 حقول) | description وicons | تعمل محليًا، لكن النشر لا ينجح |
| اختيارية (37 حقلًا) | action وbackground وcontent_scripts وpermissions إلخ | ليست ناقصة، تُضاف حسب الوظيفة |
| اختيارية · خاصة بـ ChromeOS (4 حقول) | file_handlers إلخ | إضافات Chrome على سطح المكتب لا تحتاجها عمليًا |
قاعدتان حديديتان تسريان على الصفحة كلها، احفظهما أولًا:
- لا يمكن كتابة التعليقات في JSON — الرفع إلى المتجر سيُظهر خطأ
Cannot parse the manifest - يجب أن يكون manifest.json في المجلد الجذري — عند التحميل المحلي تختار مجلد الإضافة، وعند حزم zip للنشر يجب أن يكون manifest أيضًا في جذر الحزمة المضغوطة، دون طبقة مجلد إضافية
اتبعني خطوة بخطوة
فيما يلي سنوسّع ملف manifest.json من 3 حقول إلى 10 حقول. عدّل داخل مجلد Hello World من الدرس السابق مباشرة، وبعد كل خطوة تعديل عد إلى chrome://extensions وانقر على أيقونة التحديث في بطاقة الإضافة — أي تعديل على manifest يستلزم تحديث الإضافة حتى يسري مفعوله.
الخطوة 1: اكتب الحقول الثلاثة الإلزامية للمنصة — أساس manifest.json
لماذا: أول ما يفعله Chrome عند تحميل الإضافة هو قراءة manifest.json، وإذا نقص أي من هذه الحقول الثلاثة، يفشل التحميل مباشرة.
أنشئ (أو افتح) manifest.json في الدليل الجذري للإضافة، واكتب فيه:
{
"manifest_version": 3,
"name": "My First Extension",
"version": "1.0.0"
}قيود كل من الحقول الثلاثة:
| الحقل | القيد | الشرح |
|---|---|---|
manifest_version | يدعم 3 فقط | MV3 هو الطريقة الوحيدة حاليًا، ولا تنسخ 2 الواردة في الدروس القديمة |
name | 75 حرفًا كحد أقصى | يُعرض في المتجر ونافذة التثبيت وصفحة chrome://extensions |
version | 1-4 أعداد صحيحة مفصولة بنقاط، كل مقطع 0-65536 | مثل 1.0.0، وإذا كان التنسيق خاطئًا يعرض Chrome رسالة خطأ واضحة |
ينبغي أن ترى: ملف JSON بثلاثة مفاتيح فقط — هذا كل ما تتطلبه المنصة.
إذا أردت أن ترى بعينك كيف تُطبَّق قواعد التنسيق، غيّر version عمدًا إلى "1.0.0.0.0" (خمسة مقاطع) ثم حدّث الإضافة، وسيظهر Chrome نافذة خطأ: Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536. — وإعادته إلى 1.0.0 تُصلح الأمر.
- فحص صغير: manifest.json موجود في الدليل الجذري، والحقول الثلاثة كلها موجودة، ولا توجد تعليقات في JSON
الخطوة 2: أضف description وicons — لاستكمال المثال الرسمي الأدنى
لماذا: هذان البندان لا يؤثران في التشغيل المحلي، لكنهما إلزاميان عند النشر في متجر تطبيقات Chrome؛ و«مثال manifest الأدنى» في الوثائق الرسمية يتضمنهما أيضًا.
أضف هذين البندين إلى JSON السابق، وستحصل على نص Minimal Manifest الرسمي كما هو (يمكنك أيضًا استبدال name باسم إضافتك أنت):
{
"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"
}
}description: 132 حرفًا كحد أقصى، يُعرض في المتجر وصفحة إدارة الإضافاتicons: أيقونة واحدة أو أكثر، المفتاح هو الحجم والقيمة هي مسار الصورة
ينبغي أن ترى: حتى هذه النقطة هو نص Minimal Manifest الرسمي كما هو. الصورة التي يشير إليها icons يجب أن تكون موجودة فعلًا — ملف الأيقونة الذي استخدمته في درس Hello World السابق يصلح للاستخدام، فقط غيّر المسار في icons إلى موقعه الفعلي.
- فحص صغير: description لا يتجاوز 132 حرفًا؛ كل مسار في icons له ملف مقابل يمكن إيجاده في المجلد
الخطوة 3: أضف action وbackground — النافذة المنبثقة ومركز الأحداث
لماذا: action يحدد ما يحدث عند النقر على أيقونة شريط الأدوات؛ background يحدد service worker الخاص بالإضافة (معالج الأحداث). النافذة المنبثقة في الدرس السابق كانت هي عمل action.
أضف هذين المفتاحين إلى manifest (لاحظ إضافة فاصلة في نهاية المفتاح السابق):
"action": {
"default_popup": "hello.html",
"default_icon": "hello_extensions.png"
},
"background": {
"service_worker": "service-worker.js"
}action: يحدد مظهر أيقونة شريط الأدوات وسلوكها؛default_popupيحدد الصفحة التي تنبثق عند النقر على الأيقونة، وdefault_iconيحدد صورة الأيقونةbackground: ملف JS الذي يشير إليهservice_workerهو «دماغ» الإضافة، يبدأ عند الحاجة ويتوقف عند الخمول — الاستخدامات المتقدمة في الدرس التالي
ينبغي أن ترى: بعد تحديث الإضافة، انقر على أيقونة شريط الأدوات وستفتح النافذة المنبثقة كالمعتاد. تذكّر أن تنشئ ملف service-worker.js أولًا (يكفي سطر واحد console.log("background ready") مؤقتًا) — كل مسارات الملفات المصرّح بها في manifest يجب أن تكون موجودة فعلًا.
الخطوة 4: أضف إعداد content_scripts — لتشغيل السكربت تلقائيًا على صفحات الويب المحددة
لماذا: إذا أردت أن تقوم الإضافة «بتعديل الصفحة تلقائيًا فور فتح نوع معين من صفحات الويب»، فما تعتمد عليه هو التصريح الثابت content_scripts — دون النقر على أي زر، يُحقن السكربت من تلقاء نفسه.
أضف هذا المقطع إلى manifest:
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"]
}
]matches: إلزامي. يحدد الصفحات التي يُحقن السكربت فيها، ويُكتب بصياغة match pattern (مثلhttps://*.nytimes.com/*)؛ كل content script يعمل تلقائيًا يجب أن يحدد match patternjs/css: اختياريان. ملفات JS / CSS تُحقن بترتيب المصفوفة، والمسارات نسبية إلى الدليل الجذري للإضافة
ينبغي أن ترى: بعد تحديث الإضافة افتح صفحة تطابق matches ويسري السكربت تلقائيًا. بعد تعديل ملف content script، وإلى جانب تحديث الإضافة يجب أيضًا تحديث الصفحة المضيفة. أما سؤال «لماذا لا يرى السكربت الخاص بي متغيرات الصفحة والعكس» — فالدرس التالي C4 يتناول العوالم المعزولة.
الخطوة 5: أضف تصريح permissions وhost_permissions
لماذا: permissions يفعّل واجهات برمجة التطبيقات المحددة للإضافات، وبدون التصريح لا يمكن استدعاؤها؛ host_permissions يصرّح بالمواقع التي يمكن للإضافة التفاعل معها — وتُطلب صلاحيات هذه المواقع من المستخدم عند التثبيت.
أضف هذين السطرين إلى manifest:
"permissions": ["storage"],
"host_permissions": ["https://*.example.com/"]permissions: ضع في المصفوفة أسماء الواجهات التي تريد تفعيلها، مثلstorageوscriptingوactiveTab؛ صرّح فقط بما تستخدمه فعلًاhost_permissions: اذكر بصياغة match pattern صفحات الويب التي يمكن التفاعل معها
ينبغي أن ترى: حدّث الإضافة، ويتم التحميل بشكل طبيعي. الخطأ الإملائي في اسم الصلاحية لا يمنع التحميل، لكن ستظهر في صفحة الإضافات زر Errors باللون الأحمر — مثلًا إذا كتبت activeTab بالشكل activetab، ستظهر الرسالة Permission 'activetab' is unknown or URL pattern is malformed.. المنهجية الكاملة لاستكشاف الأخطاء في C5.
الخطوة 6: التحميل المحلي للتحقق، والمراجعة بندًا بندًا قبل النشر
لماذا: صحة الحقول لا يحكم عليها سوى Chrome والمتجر. مراجعة محلية أولًا، ثم مراجعة أخرى قبل النشر، توفّر أغلى أنواع إعادة العمل.
الخطوات:
- عد إلى
chrome://extensionsوانقر على أيقونة التحديث في بطاقة الإضافة (طريقة التحميل الثلاثية وردت في الدرس السابق) - عند فشل التحميل تظهر نافذة خطأ — صحّح manifest وفق رسالة الخطأ، ثم حدّث مرة أخرى
- عند الاستعداد للنشر، راجع بندًا بندًا:
| بند المراجعة | المعيار |
|---|---|
name / description | ≤75 / ≤132 حرفًا، بلا أخطاء إملائية — لا يمكن تعديل بيانات manifest الوصفية بعد الرفع، وإذا اكتُشف خطأ إملائي فالحل الوحيد هو تعديل الملف ورفع رقم الإصدار وإعادة الحزم |
version | أكبر من النسخة المرفوعة سابقًا؛ يُنصح للنسخة الأولى بتعيين قيمة منخفضة مثل 0.0.0.1 لترك مجال للزيادة لاحقًا |
| التعليقات | لا يجب أن يحتوي ملف JSON على أي تعليقات، وإلا سيُظهر الرفع خطأ Cannot parse the manifest |
| الحزم | يجب أن يكون manifest.json مباشرة في جذر ملف zip المضغوط، دون مجلد إضافي |
ينبغي أن ترى: التحميل المحلي بدون مربع حوار للأخطاء وبدون أخطاء حمراء؛ وعند فك ضغط ملف zip المرفوع يجب أن يظهر manifest.json في الطبقة الأولى. العملية الكاملة للتسجيل وإرسال المراجعة والمراجعة موجودة في C6.
📋 جدول مرجعي سريع لحقول MV3
💡 كيفية استخدام هذا الجدول
اطرح سؤالين أولًا: إلى أي طبقة ينتمي هذا الحقل (إلزامي للمنصة / إلزامي للمتجر / اختياري)؟ وإلى أي مجموعة تنتمي الوظيفة التي أحتاجها (الواجهة / الأذونات / الشبكة / التوزيع)؟ حدد الصف، واكتب وفقًا له وتحقق من القيود، ثم ارجع إلى الخطوة المقابلة في الصفحة للاطلاع على الشرح المفصل. تم تجميع الحقول والقيود في هذا الجدول من وثيقة Manifest reference الرسمية من Chrome.
إلزامي للمنصة (3 حقول)
| الحقل | القيود | الوظيفة |
|---|---|---|
manifest_version | عدد صحيح، القيمة المدعومة الوحيدة 3 | إصدار تنسيق manifest |
name | ≤75 حرفًا | الاسم المعروض في المتجر ومربع حوار التثبيت وchrome://extensions |
version | 1-4 أعداد صحيحة مفصولة بنقاط، كل جزء 0-65536 | رقم الإصدار، ويجب أن يكون الإصدار الجديد المرفوع أكبر من السابق |
إلزامي للنشر في المتجر (2 حقول)
| الحقل | القيود | الوظيفة |
|---|---|---|
description | ≤132 حرفًا | الوصف في المتجر وصفحة إدارة الإضافات |
icons | أيقونة واحدة أو أكثر | الأيقونة التي تمثل الإضافة |
اختيارية عالية التكرار (تعرّف أولًا على هذه الـ 5 حقول)
| الحقل | نقاط الكتابة | الوظيفة |
|---|---|---|
action | default_popup يشير إلى صفحة النافذة المنبثقة، وdefault_icon يحدد الأيقونة | مظهر وسلوك أيقونة شريط الأدوات |
background | {"service_worker": "service-worker.js"} | يحدد service worker كمعالج للأحداث |
content_scripts | matches إلزامي + مصفوفة js / css | JS/CSS يُحقن تلقائيًا عند فتح صفحات مطابقة |
permissions | مصفوفة أسماء API، مثل ["storage"] | يفعّل API إضافات محددة |
host_permissions | مصفوفة match pattern | تعلن عن صفحات الويب التي يمكن التفاعل معها، وتطلب الإذن عند التثبيت |
حقول اختيارية أخرى (مجمّعة حسب الاستخدام)
الواجهة والتفاعل
| الحقل | الوظيفة |
|---|---|
commands | يعرّف اختصارات لوحة المفاتيح داخل الإضافة |
options_page | يحدد options.html كصفحة إعدادات الإضافة |
options_ui | يتيح للمستخدم تعديل خيارات الإضافة من داخل صفحة إدارة الإضافات |
side_panel | يحدد صفحة HTML المعروضة في الشريط الجانبي |
omnibox | يسجّل كلمة مفتاحية في شريط عنوان Chrome |
chrome_url_overrides | يستبدل صفحات Chrome الافتراضية |
devtools_page | يعرّف الصفحات التي تستخدم DevTools API |
الأذونات والأمان
| الحقل | الوظيفة |
|---|---|
optional_permissions | يعلن عن أذونات API اختيارية |
optional_host_permissions | يعلن عن أذونات host اختيارية |
content_security_policy | يقيد الموارد مثل النصوص البرمجية والأنماط التي يمكن للإضافة تحميلها |
externally_connectable | يحدد أي صفحات الويب والإضافات يمكنها الاتصال بإضافتك |
web_accessible_resources | يعرّف الملفات داخل الإضافة التي يمكن لصفحات الويب أو الإضافات الأخرى الوصول إليها |
sandbox | يعرّف صفحات sandbox لا يمكنها استخدام API الإضافات مباشرة |
incognito | السلوك في وضع التخفي، القيم spanning / split / not_allowed |
key | يحدد معرّف الإضافة لأغراض التطوير |
الشبكة والبيانات
| الحقل | الوظيفة |
|---|---|
declarative_net_request | قواعد ثابتة للطلبات الشبكية التصريحية، يمكنها اعتراض طلبات الشبكة وتعديلها |
oauth2 | يهيّئ OAuth 2.0(client_id وscopes) |
storage | يعلن عن JSON schema لمنطقة التخزين المُدارة |
tts_engine | يسجّل الإضافة كمحرك لتحويل النص إلى كلام |
mime_types_handler | تسجيل الإضافة كمعالج لنوع MIME معين (مثل application/pdf) |
requirements | سرد التقنيات المطلوبة لاستخدام الإضافة |
الإصدار والتوزيع
| الحقل | الوظيفة |
|---|---|
version_name | اسم مستعار للإصدار موجّه للبشر (مثل "1.0 beta")؛ إن لم يُكتب فسيُعرض version |
minimum_chrome_version | الحد الأدنى من إصدار Chrome لتثبيت الإضافة؛ الإصدارات الأقل تُعرض كغير متوافقة، ولا يمكن تثبيتها ولا تحديثها تلقائيًا |
homepage_url | عنوان URL للصفحة الرئيسية للإضافة؛ إن لم يُكتب فالافتراضي هو صفحة المتجر |
update_url | عنوان صفحة التحديث عند التوزيع الذاتي (دون نشر في المتجر) |
import | السماح باستيراد موارد إلى الإضافة |
export | السماح بتصدير موارد من الإضافة |
التدويل والعرض
| الحقل | الوظيفة |
|---|---|
default_locale | اللغة الافتراضية للإضافات متعددة اللغات (مثل en)؛ إلزامية للإضافات المُوَضعَة (localized)، ولا يمكن استخدامها في الإضافات غير المُوَضعَة |
short_name | اسم قصير، ≤12 حرفًا؛ إن لم يُكتب فسيُقتطع name للعرض |
إعدادات Chrome
| الحقل | الوظيفة |
|---|---|
chrome_settings_overrides | تجاوز بعض إعدادات Chrome |
cross_origin_embedder_policy | تكوين ترويسة طلب Cross-Origin-Embedder-Policy |
cross_origin_opener_policy | تكوين ترويسة طلب Cross-Origin-Opener-Policy |
خاص بـ ChromeOS (4 عناصر)
| الحقل | الوظيفة |
|---|---|
file_browser_handlers | الوصول إلى واجهات API المتعلقة بمستعرض ملفات ChromeOS |
file_handlers | تحديد أنواع الملفات التي تعالجها إضافة ChromeOS |
file_system_provider_capabilities | تمكين الإضافة من إنشاء نظام ملفات قابل للاستخدام في ChromeOS |
input_components | استخدام واجهات API لمحرر أسلوب الإدخال (IME) |
نقطة تحقق ✅
- يقع manifest.json في الدليل الجذر للإضافة، ولا يحتوي ملف JSON على أي تعليقات
manifest_versionيساوي 3؛name≤75 حرفًا؛versionهو عدد صحيح منقّط بـ 1-4 مقاطع- في حال النشر في المتجر:
description≤132 حرفًا،iconsكل مسار فيه موجود فعليًا - كُتب
matchesفيcontent_scripts، ويتوافق مع صياغة match pattern - يعلن
permissionsفقط عن واجهات API المستخدمة فعليًا، دون أخطاء إملائية
تنبيهات للمزالق
❌ كتابة تعليقات في manifest.json
{
"manifest_version": 3, // MV3 写死
"name": "My Extension"
}السبب: لا تدعم JSON التعليقات، ويظهر خطأ Cannot parse the manifest مباشرة عند الرفع إلى المتجر. الطريقة الصحيحة: احذف جميع التعليقات قبل الرفع؛ وإذا أردت ترك ملاحظات فاكتبها في README أو في مستند جانبي.
❌ نسخ الدروس القديمة حرفيًا وكتابة manifest_version بقيمة 2
السبب: ما زال عدد كبير من الدروس على الإنترنت يستخدم أسلوب عصر MV2، بينما القيمة الوحيدة المدعومة لـ manifest_version في MV3 هي 3، ونسخ الأسلوب القديم سيذهب جهدك سدى. الطريقة الصحيحة: استخدم "manifest_version": 3 لجميع الإضافات الجديدة؛ وعند الشك في أي حقل راجعه في جدول المراجعة السريعة في هذه الصفحة.
❌ كتابة version بشكل عشوائي ورفض رفع الإصدار الجديد
"version": "1.0.0.0.0" // ❌ 五段,超了
"version": "0.0.0.1" // ✅ 初版设低值,以后只往上加السبب: يجب أن يكون version عددًا صحيحًا منقّطًا بـ 1-4 مقاطع، كل مقطع 0-65536؛ كما يشترط المتجر أن يكون رقم إصدار كل رفعة جديدة أكبر من السابق. الطريقة الصحيحة: اضبط للإصدار الأول قيمة منخفضة مثل 0.0.0.1، وزد رقم الإصدار فقط عند كل إصدار جديد، فيبقى لديك مجال دائمًا.
❌ اكتشاف خطأ إملائي في name بعد الرفع
السبب: بعد الرفع إلى المتجر، لا يمكن تعديل بيانات manifest التعريفية في لوحة المطوّر — ليست مسألة صلاحيات، بل القاعدة نفسها. الطريقة الصحيحة: راجع name وdescription حرفًا بحرف قبل الرفع؛ وإذا حدث خطأ فعلًا فالحل الوحيد هو تعديل manifest، ورفع version، وإعادة الحزم والرفع.
🔧 نصائح متقدمة (اختيارية)
- ربط مخطط manifest الرسمي بالمحرر: اربط مخطط manifest (json.schemastore.org/chrome-manifest) في محرر الأكواد، فتُعلَّم الحقول الخاطئة والعناصر الإلزامية الناقصة بالأحمر فورًا، دون انتظار رفض Chrome للتحميل لكي تكتشفها
version_nameوversionوتقسيم الأدوار:versionهو رقم الإصدار الآلي الذي يقارن به Chrome الأحجام؛ أماversion_name(مثل"1.0 beta") فهو اسم مستعار موجّه للبشر، يُعرض في صفحة إدارة الإضافات. إذا أردت «اسم إصدار جميل + رقم إصدار يتزايد بصرامة» فاكتب كليهماshort_nameللإنقاذ: عندما يكون الاسم طويلًا ومساحة العرض غير كافية، يتدخلshort_name(≤12 حرفًا)؛ وإن لم يُكتب فسيقتطع Chromenameللعرض
خلاصة الدرس
✅ أنجزت في هذا الدرس:
- البنية الطبقية لـ manifest.json: 3 عناصر إلزامية للمنصة، 2 عناصر إلزامية للمتجر، 41 عناصر اختيارية (منها 4 عناصر خاصة بـ ChromeOS)
- بناء الصياغة الكاملة لـ action وbackground وcontent_scripts وpermissions تدريجيًا انطلاقًا من الحد الأدنى للمثال
- قواعد صياغة version وانضباط «التزايد فقط»، إضافة إلى قاعدتين حديديتين: لا تعليقات في JSON، والملف في الدليل الجذر
- قائمة التحقق قبل النشر في المتجر: البيانات التعريفية لا يمكن تعديلها بعد الرفع، وتصحيح خطأ إملائي = إصدار جديد
مراجعة حقول الإعدادات الأساسية:
| الحقل | القيمة الموصى بها / القيود | الوصف |
|---|---|---|
manifest_version | 3 | القيمة الوحيدة المدعومة |
name | ≤75 حرفًا | اسم الإضافة كما يظهر في ثلاثة مواضع |
version | 0.0.0.1 كنقطة بداية، ويزداد فقط | 1-4 أعداد صحيحة مفصولة بنقاط، كل جزء 0-65536 |
description | ≤132 حرفًا | مطلوب للمتجر |
icons | 48 / 128 يبدأ بمستويين | مطلوب للمتجر، ويجب أن يكون المسار موجودًا |
action.default_popup | hello.html | صفحة النافذة المنبثقة عند النقر على الأيقونة |
background.service_worker | service-worker.js | سكربت مركز الأحداث |
content_scripts[].matches | match pattern، إلزامي | يحدد الصفحات التي يتم الحقن فيها |
permissions | اذكر فقط واجهات API المستخدمة | مثل ["storage"] |
host_permissions | مصفوفة من match pattern | يطلب الإذن عند التثبيت |
استعراض الدرس القادم
بعد أن أعلنّا عن الحقول، الدرس القادم C4 Content Script و Service Worker: عقل الإضافة وأدواتها يشرح بعمق الآلية الكامنة خلف هذين الحقلين في ملف manifest.
ستتعلم:
- التعريف الرسمي لكل من content script و service worker، وما يمكن لكل منهما فعله
- «العوالم المعزولة»: لماذا لا يرى سكربتك ومتغيرات صفحة الويب بعضهما البعض
- كيفية الاختيار بين ثلاث طرق: التصريح الثابت، والتصريح الديناميكي، والحقن البرمجي
- طبيعة service worker التي تبدأ عند الحاجة وتتوقف عند الخمول، ومتى تستخدم أيًّا منهما