أول إضافة Chrome لك: شغّل Hello World في 15 دقيقة
💡 الخلاصة في جملة: مجلد واحد، ثلاثة ملفات، ووضع المطوّر في Chrome — 15 دقيقة، ويظهر لك Hello World من إضافتك الخاصة في المتصفح.
في الدرس السابق C1 ما هي إضافات المتصفح أوضحنا المفاهيم: الإضافة هي HTML/CSS/JS مع ملف manifest.json. هذا الدرس عملي — أصلب خطوة في مقدمة إضافات chrome، ليست حفظ عشرة مصطلحات جديدة، بل جعل المتصفح يُظهر فعلًا إضافتك الخاصة.
لا تتخطَّ هذه الـ 15 دقيقة — حتى لو كنت تنوي ترك الذكاء الاصطناعي يكتب الكود كله. التحميل المحلي والتحديث ومشاهدة النافذة المنبثقة هي ثلاثة أفعال ستضطر دائمًا إلى تنفيذها بنفسك، وHello World هو ما يحوّلها إلى ذاكرة عضلية.
ماذا ستستطيع أن تفعل بعد هذا الدرس
- صنع إضافة حقيقية مثبّتة في Chrome: اضغط أيقونة شريط الأدوات فتظهر «Hello Extensions»
- كتابة الحد الأدنى الرسمي من manifest.json حرفًا بحرف، وشرح وظيفة كل حقل
- إتمام التحميل المحلي في ثلاث خطوات:
chrome://extensions← وضع المطوّر ← Load unpacked - تثبيت الإضافة بدبوس في شريط الأدوات لتكون في متناول يدك
- حفظ قاعدة إعادة التحميل: أي الملفات تتطلب تحديث الإضافة عند تعديلها وأيها لا يتطلب
ما الذي تواجهه الآن
- «حفظت كومة من مصطلحات الإضافات: manifest وMV3 وpopup…… لكن لم يشتغل سطر كود واحد منها في المتصفح»
- «الذكاء الاصطناعي كتب الكود، لكن أين أضع هذه الملفات وكيف يتعرّف عليها Chrome، لا أعرف»
- «نسخت من دروس قديمة على الإنترنت، وأول ضغطة على Load unpacked يظهر خطأ ولا أعرف أين المشكلة»
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- تحويل «صنع إضافة» من فكرة إلى واقع — شغّل الحد الأدنى أولًا ثم أضف الميزات فوقه
- التحقق من أن مسار التطوير سليم: إنشاء الملفات، التحميل، رؤية النافذة المنبثقة — اجتياز المراحل الثلاث كلها
- إعطاء متطلباتك للذكاء الاصطناعي نقطة انطلاق ملموسة: شغّل Hello World أولًا، وفي الدرس التالي دع الذكاء الاصطناعي يبني فوقه
ولا تريد أن:
- تقضم كل حقول manifest دفعة واحدة — الدرس التالي C3 يفكّكها واحدًا واحدًا
- تتطرق إلى التغليف والنشر والمراجعة — ذلك شأن C6
- تثبّت أي بيئة تطوير — مجلد واحد + وضع المطوّر المدمج في Chrome يكفي
🎒 التحضير قبل البدء
- إكمال C1 ما هي إضافات المتصفح، ومعرفة أن الإضافة = HTML/CSS/JS + manifest.json، والآن نكتب MV3 فقط
- متصفح Chrome مثبّت على حاسوبك
- أداة لإنشاء ملفات نصية وتحريرها (المفكرة المدمجة تكفي؛ محرر أكواد مثل VS Code أكثر راحة)
- 15 دقيقة
الفكرة الأساسية
الحد الأدنى من إضافة Chrome هو مجلد واحد مع ثلاثة ملفات:
| الملف | الوظيفة | من يستخدمه |
|---|---|---|
manifest.json | بطاقة هوية الإضافة + دليلها: ما اسمها، ما إصدارها، ماذا يحدث عند الضغط على الأيقونة | Chrome يقرأه |
hello.html | الصفحة الصغيرة التي تنبثق عند الضغط على أيقونة شريط الأدوات | المستخدم يراها |
hello_extensions.png | أيقونة شريط الأدوات (يمكن الاستغناء عنها، سيمنحك Chrome أيقونة عامة) | المستخدم يراها |
مبدأ التشغيل في جملة: يتعرّف Chrome على إضافتك عبر manifest.json؛ وaction.default_popup داخل الـ manifest يخبر Chrome «عند الضغط على أيقونة شريط الأدوات، افتح hello.html».
قبل البدء العملي، لنضع قاعدتين:
manifest_versionاكتب 3 فقط. تقول الوثائق الرسمية صراحةً إن القيمة الوحيدة المدعومة هي 3؛ و2 في الدروس القديمة لا تنسخه (شرحنا في C1 أن MV2 محظور بالكامل، وتفصيل قواعد الحقول في C3 شرح مفصّل).- وضع المطوّر ≠ النشر إلى المتجر. وضع المطوّر + Load unpacked هو مجرد مفتاح «يسمح بتثبيت مجلد محلي في المتصفح»؛ أما النشر إلى متجر Chrome فيتطلب تسجيل المطوّر والمراجعة، وهو مسار آخر (انظر C6).
💡 هل يجب الكتابة يدويًا في هذا الدرس
الملفات الثلاثة قليلة حتى إن كتابتها يدويًا تستغرق دقائق فقط، وننصحك في المرة الأولى بكتابتها بنفسك — هذه الخطوة يتعثر فيها الكثيرون بسبب علامة اقتباس أو اسم حقل واحد، وبكتابتها يدويًا مرة ستعرف لاحقًا ما الذي يجب التحقق منه في كود الذكاء الاصطناعي. من الدرس التالي ستتزايد الملفات، وهناك يصبح الذكاء الاصطناعي في عنصره.
نفّذ معي
الخطوة 1: إنشاء مجلد الإضافة
لماذا: الإضافة ليست سوى «بضعة ملفات داخل مجلد واحد»، فلنمنحها أولًا مكانًا تستقر فيه.
الخطوة: أنشئ مجلدًا جديدًا على سطح المكتب (أو في أي مكان تستطيع العثور عليه)، وسمِّه hello-extensions.
إذا أردت مقارنة نتيجتك بالنسخة الجاهزة، فالكود المصدري للمثال الرسمي على GitHub: في مستودع GoogleChrome/chrome-extensions-samples داخل مجلد functional-samples/tutorial.hello-world. لكن يُنصح في هذا الدرس أن تبنيه بنفسك — الملفات ثلاثة فقط في المجمل.
يجب أن ترى: مجلدًا فارغًا.
الخطوة 2: كتابة manifest.json — أول ملف في طريقك إلى إضافات Chrome
لماذا: لا يعترف Chrome إلا بملف manifest.json. بدونه، يكون هذا المجلد مجرد مجلد عادي.
الخطوة: أنشئ داخل المجلد ملف manifest.json، وانسخ محتواه حرفيًا من المثال الرسمي:
{
"name": "Hello Extensions",
"description": "Base Level Extension",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_popup": "hello.html",
"default_icon": "hello_extensions.png"
}
}ماذا يفعل كلٌّ من الحقول الستة:
| الحقل | القيمة في هذا الدرس | ماذا يفعل |
|---|---|---|
name | Hello Extensions | اسم الإضافة، يظهر في صفحة الإضافات وأماكن أخرى |
description | Base Level Extension | وصف بسطر واحد |
version | 1.0 | رقم الإصدار (1-4 مقاطع من أعداد صحيحة تفصلها نقاط) |
manifest_version | 3 | يعلن استخدام MV3 — القيمة الوحيدة المدعومة |
action.default_popup | hello.html | عند النقر على أيقونة شريط الأدوات تُفتح هذه الصفحة المنبثقة |
action.default_icon | hello_extensions.png | تُستخدم هذه الصورة كأيقونة لشريط الأدوات |
⚠️ تفصيلان مهمّان
- لا يمكن كتابة تعليقات داخل JSON — فكلٌّ من
//و/* */يجعل التحليل يفشل فورًا. إذا أردت تدوين ملاحظات، فاكتبها خارج الملف. - لا تريد تجهيز أيقونة؟ احذف السطر الذي يحتوي على
"default_icon"بالكامل، وسيعطي Chrome إضافتك أيقونة عامة تلقائيًا.
يجب أن ترى: ملف manifest.json مستقرًا داخل المجلد.
- فحص صغير: أعد فتحه بالمحرر وتأكد من
"manifest_version": 3، وأن كل علامة اقتباس لها زوج
الخطوة 3: كتابة hello.html مع أيقونة
لماذا: الملف الذي يشير إليه default_popup يجب أن يكون موجودًا فعلًا، حتى يكون هناك ما يُفتح عند النقر على الأيقونة.
الخطوة: أنشئ ملف hello.html، وانسخ محتواه من المثال الرسمي:
<html>
<body>
<h1>Hello Extensions</h1>
</body>
</html>بالنسبة للأيقونة، اختر أحد خيارين:
- الطريقة A (وفق المثال الرسمي): نزِّل أيقونة المثال من صفحة الدرس الرسمي، وأعد تسميتها إلى
hello_extensions.pngوضعها في المجلد — يجب أن يطابق اسم الملف ما هو مكتوب فيdefault_iconحرفيًا دون أي اختلاف. - الطريقة B (أسهل): إذا كنت قد حذفت
default_iconفي الخطوة السابقة، فتجاوز هذه الخطوة مباشرة، وسيعطيك Chrome أيقونة عامة.
يجب أن ترى: ملفين أو ثلاثة داخل المجلد: manifest.json و hello.html، إضافة إلى الأيقونة (إذا اخترت الطريقة A).
الخطوة 4: تشغيل وضع المطوِّر في Chrome، وتحميل Load unpacked محليًا
لماذا: يثبِّت Chrome افتراضيًا الإضافات من المتجر فقط. وضع المطوِّر هو مفتاح «السماح بالتثبيت المحلي»، أما Load unpacked فهو المسؤول عن تثبيت مجلدك في المتصفح.
الخطوات (الخطوات الرسمية الثلاث):
- اكتب
chrome://extensionsفي شريط عنوان تبويب جديد واضغط Enter لفتح صفحة إدارة الإضافات. وهناك مدخلان آخران: زر أحجية شريط الأدوات → Manage Extensions؛ أو قائمة Chrome → More Tools → Extensions. - شغِّل مفتاح Developer mode (وضع المطوِّر).
- انقر Load unpacked، واختر مجلد إضافتك في مربع اختيار الملفات.
انتبه: يجب أن يكون manifest.json موجودًا مباشرةً داخل المجلد المختار — فالمتطلبات الرسمية تنص على وضعه في المجلد الجذري للإضافة، وإذا أضفت مجلدًا فرعيًا إضافيًا فلن يجده Chrome.
يجب أن ترى: ظهور Hello Extensions في قائمة صفحة الإضافات، مع الرسالة The extension has been successfully installed. (تم تثبيت الإضافة بنجاح)؛ وإذا لم توفّر أيقونة، فسيكون Chrome قد خصّص أيقونة عامة تلقائيًا.
- فحص صغير: تظهر بطاقة Hello Extensions بشكل طبيعي، دون ظهور أي مربع حوار خطأ
الخطوة 5: ثبِّتها (Pin) في شريط الأدوات، وافتح أول نافذة منبثقة لك
لماذا: الإضافات المحمَّلة محليًا تبقى مخفية افتراضيًا داخل قائمة الأحجية، وتتطلب نقرة إضافية في كل مرة؛ تثبيتها (Pin) يجعلها في متناول اليد.
الخطوات: انقر زر الأحجية في شريط الأدوات، واعثر على Hello Extensions، وانقر أيقونة الدبوس (Pin) بجانبها لتثبيتها في شريط الأدوات. ثم انقر أيقونة هذه الإضافة في شريط الأدوات.
يجب أن ترى: نافذة منبثقة صغيرة تظهر مكتوبًا فيها Hello Extensions — أول إضافة Chrome لك تعمل بنجاح.
الخطوة 6: عدِّل الكود، وتعلَّم تحديث الإضافة
لماذا: لا تقرأ الإضافة الملفات التي عدّلتها تلقائيًا؛ فمعظم التعديلات لا تسري إلا بعد تحديث يدوي — وهذه أكثر نقطة يخطئ المبتدئون في تقديرها على أنها «الذكاء الاصطناعي كتب الكود خطأً».
الخطوات: غيِّر name في manifest.json إلى "Hello Extensions of the world!"، واحفظ. عُد إلى chrome://extensions، وانقر أيقونة التحديث بجانب مفتاح on/off على بطاقة الإضافة.
يجب أن ترى: تغيُّر اسم الإضافة إلى Hello Extensions of the world!. وإذا لم تنقر على التحديث، فسيبقى الاسم القديم.
جدول قواعد إعادة التحميل الرسمي، احفظه الآن:
| ماذا عدّلت | هل يجب تحديث الإضافة |
|---|---|
| manifest | نعم |
| Service worker | نعم |
| Content scripts | نعم (مع ضرورة تحديث الصفحة المعنية أيضًا) |
| النافذة المنبثقة (popup) | لا |
| صفحة الإعدادات (Options page) | لا |
| صفحات HTML الأخرى للإضافة | لا |
إضافة هذا الدرس تحتوي على نوعين من الملفات فقط: manifest وpopup، والقاعدة بسيطة: عند تعديل manifest، اذهب إلى صفحة الإضافات واضغط تحديث؛ عند تعديل hello.html، لا حاجة للتحديث — أعد فتح النافذة المنبثقة وسترى المحتوى الجديد.
نقطة تحقق ✅
chrome://extensionsتظهر بطاقة Hello Extensions بشكل طبيعي دون أخطاء- تم تثبيت الإضافة (Pin) على شريط الأدوات، والنقر على الأيقونة يفتح Hello Extensions
- بعد تعديل
name، ذهبت إلى صفحة الإضافات وضغطت أيقونة التحديث، وتغير الاسم - أستطيع ذكر قواعد إعادة التحميل: manifest وservice worker وcontent scripts تتطلب تحديثًا؛ أما popup وملفات HTML الأخرى فلا
- أعرف أن وضع المطوّر مجرد مفتاح لـ«التحميل المحلي»، وأن النشر على المتجر يتطلب التسجيل + المراجعة (C6)
تنبيهات للمزالق
❌ كتابة تعليقات داخل manifest.json
صيغة JSON لا تدعم التعليقات. إذا كتبت // أو /* */، سيفشل تحليل manifest — عند التحميل المحلي ستظهر رسالة خطأ مباشرة؛ والجهة الرسمية أيضًا تنص صراحةً بأن وجود تعليقات في JSON عند الحزم والرفع سيؤدي إلى خطأ Cannot parse the manifest.
الطريقة الصحيحة: اكتب التعليقات والملاحظات خارج الملف؛ وإذا لم تكن متأكدًا من معنى حقل ما، راجع C3 مرجع الحقول السريع.
❌ نسخ الدروس القديمة حرفيًا وكتابة manifest_version كـ 2
عدد كبير من الدروس على الإنترنت كُتب في عصر MV2. الآن manifest_version القيمة الوحيدة المدعومة هي 3، وإضافات MV2 محظورة تمامًا في Chrome — النسخ الحرفي يعني عملًا ضائعًا.
الطريقة الصحيحة: قبل البدء، تحقق أولًا من أن هذا السطر هو "manifest_version": 3؛ وإذا رأيت درسًا يعلّم MV2 فأغلقه فورًا.
❌ تعديل الكود دون تحديث الإضافة والاعتقاد بأن «الذكاء الاصطناعي أخطأ»
إذا عدّلت manifest أو service worker أو content scripts دون تحديث، فالمتصفح لا يزال يشغّل الكود القديم — ستظن خطأً أن هناك مشكلة في الكود، فتجعل الذكاء الاصطناعي يعدّل مرارًا كودًا صحيحًا تمامًا.
الطريقة الصحيحة: بعد التعديل، راجع أولًا جدول قواعد إعادة التحميل في الخطوة 6: ما يتطلب تحديثًا اذهب لصفحة الإضافات واضغط أيقونة التحديث، أما تعديل popup فلا يحتاجه. وإذا استمرت المشكلة، فاذهب إلى C5 للعثور على السجلات.
❌ الاعتقاد بأن فتح وضع المطوّر يعني «النشر على المتجر»
وضع المطوّر مجرد مفتاح يسمح بالتثبيت المحلي، والإضافة في هذه الحالة يمكنك أنت وحدك استخدامها. النشر على متجر تطبيقات Chrome يتطلب حتمًا تسجيل المطوّر (بدفع رسم تسجيل لمرة واحدة، والمبلغ وفقًا لصفحة الدفع الفعلية في لوحة تحكم المطوّر) والمراجعة.
الطريقة الصحيحة: بعد نجاح التشغيل محليًا، اتبع C6 مسار النشر الكامل للتسجيل والحزم وتقديم المراجعة.
نصائح متقدمة (اختياري)
🚀 أضف سجلًا إلى النافذة المنبثقة للتعرف مبكرًا على التصحيح. أضف سطر <script src="popup.js"></script> قبل </body> في hello.html، وأنشئ popup.js واكتب فيه console.log("This is a popup!"). افتح النافذة المنبثقة → انقر بزر الفأرة الأيمن عليها → Inspect → لوحة Console، وسترى هذا السجل. عند كتابة كود خاطئ عمدًا (مثل نسيان علامة اقتباس)، ستظهر في صفحة الإضافات زر Errors، انقر عليه للاطلاع على التفاصيل. أما أين توجد سجلات service worker وcontent script، فلدى C5 خريطة كاملة.
هيكل المشروع كما تريد: الجهة الرسمية تنص صراحةً بأن طريقة التنظيم حرة، والمتطلب الصارم الوحيد هو وضع manifest.json في الدليل الجذري للإضافة. إذا كنت تستخدم TypeScript، فتثبيت حزمة npm chrome-types يمنحك الإكمال التلقائي لواجهات Chrome API — وهي تُحدَّث تلقائيًا مع شيفرة مصدر Chromium، والجهة الرسمية تنبه إلى ضرورة الترقية باستمرار.
خلاصة الدرس
✅ هذا هو الدرس الأول في مدخل إضافات chrome، وقد قمت بـ:
- بناء أول إضافة وتشغيلها بنجاح: مجلد +
manifest.json+hello.html، والنقر على الأيقونة يفتح Hello Extensions - إتقان خطوات التحميل المحلي الثلاث:
chrome://extensions→ Developer mode → Load unpacked - تثبيت الإضافة (Pin) على شريط الأدوات لاستخدامها بنقرة في أي وقت
- تذكر قواعد إعادة التحميل: manifest وservice worker وcontent scripts تتطلب تحديثًا بعد التعديل، أما popup فلا
- معرفة المدخل الأول للسجلات: النقر بزر الفأرة الأيمن على النافذة المنبثقة ثم Inspect
مراجعة حقول الإعدادات الأساسية:
| الحقل | قيمة هذا الدرس | الشرح |
|---|---|---|
manifest_version | 3 | القيمة الوحيدة المدعومة، لا تكتب 2 |
name | Hello Extensions | اسم الإضافة |
description | Base Level Extension | الوصف |
version | 1.0 | رقم الإصدار، 1-4 مقاطع من أعداد صحيحة مفصولة بنقاط |
action.default_popup | hello.html | الصفحة التي تظهر عند النقر على الأيقونة |
action.default_icon | hello_extensions.png | الأيقونة؛ إذا لم تُكتب فتُستخدم أيقونة عامة |
استعراض الدرس القادم
في الدرس القادم C3 شرح مفصل لملف manifest.json: سنفكك هذا الدليل الأصغر حقلًا بحقل. ستتعلم:
- قواعد الحقول الإلزامية الثلاثة:
nameبحد أقصى 75 حرفًا، وتفاصيل صيغةversion - الحقول اللازمة للنشر على المتجر:
description(بحد أقصى 132 حرفًا)،icons - كيفية كتابة الحقول الاختيارية عالية التكرار مثل
content_scriptsوpermissions - لماذا تتطلب تعديل حرف خاطئ واحد بعد الرفع إلى المتجر رفع رقم الإصدار وإعادة الحزم
إذا كنت جاهزًا فادخل إلى C3 →