إضافة Hello World

تعرَّف على أساسيات تطوير إضافة Chrome من خلال إنشاء أول إضافة Hello World.

نظرة عامة

ستنشئ مثال "Hello World"، وتحمِّل الإضافة محليًا، وتحدِّد موقع السجلات، وتستكشف الاقتراحات الأخرى.

Hello World

ستعرض هذه الإضافة "إضافات مرحبًا" عندما ينقر المستخدم على رمز شريط أدوات الإضافة.

إضافة مرحبًا
النافذة المنبثقة "إضافة مرحبًا"

ابدأ بإنشاء دليل جديد لتخزين ملفات الإضافات. ويمكنك تنزيل رمز المصدر الكامل من GitHub، إذا كنت تفضّل ذلك.

بعد ذلك، أنشئ ملفًا جديدًا في هذا الدليل يُسمى manifest.json. يصف ملف JSON هذا إمكانات الإضافة والتكوين. على سبيل المثال، تحتوي معظم ملفات البيان على مفتاح "action" الذي يعلن عن الصورة التي يجب أن يستخدمها Chrome كرمز إجراء الإضافة وأن تظهر صفحة HTML في نافذة منبثقة عند النقر على رمز إجراء الإضافة.

{
  "manifest_version": 3,
  "name": "Hello Extensions",
  "description": "Base Level Extension",
  "version": "1.0",
  "action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  }
}

نزِّل الرمز إلى دليلك، واحرِص على تغيير اسمه ليتطابق مع الاسم الوارد في مفتاح "default_icon".

بالنسبة إلى النافذة المنبثقة، أنشئ ملفًا باسم hello.html وأضِف الرمز التالي:

<html>
  <body>
    <h1>Hello Extensions</h1>
  </body>
</html>

تعرض الإضافة الآن نافذة منبثقة عند النقر على رمز إجراء الإضافة (رمز شريط الأدوات). يمكنك اختباره في Chrome عن طريق تحميله على الجهاز تأكَّد من حفظ جميع الملفات.

تحميل إضافة غير مضغوطة

لتحميل إضافة تم فك حزمتها في وضع مطوّر البرامج:

  1. انتقِل إلى صفحة "الإضافات" من خلال إدخال chrome://extensions في علامة تبويب جديدة. (حسب التصميم، لا يمكن ربط عناوين URL لـ chrome://).
    • بدلاً من ذلك، انقر على زر اللغز في قائمة الإضافات واختَر إدارة الإضافات في أسفل القائمة.
    • أو انقر على قائمة Chrome ومرِّر مؤشر الماوس فوق المزيد من الأدوات، ثم اختر الإضافات.
  2. فعِّل "وضع مطوّر البرامج" من خلال النقر على مفتاح التبديل بجانب وضع مطوّر البرامج.
  3. انقر على الزر تحميل تم فك حزمته واختَر دليل الإضافة.
    صفحة &quot;الإضافات&quot;
    صفحة الإضافات (chrome://extensions)

بهذه السهولة! تم تثبيت الإضافة بنجاح. إذا لم يتم تضمين أي رموز إضافة في البيان، سيتم إنشاء رمز عام للإضافة.

تثبيت الإضافة

وفقًا للإعدادات التلقائية، عندما تُحمِّل إضافتك محليًا، ستظهر في قائمة الإضافات (ألغاز). عليك تثبيت إضافتك في شريط الأدوات للوصول إليها بسرعة أثناء تطويرها.

تثبيت الإضافة
تثبيت الإضافة

انقر على رمز إجراء الإضافة (رمز شريط الأدوات)؛ من المفترض أن تظهر لك نافذة منبثقة.

أهلاً بالعالم
مرحبًا بالامتداد العالمي

إعادة تحميل الإضافة

ارجع إلى الرمز وغيِّر اسم الإضافة إلى "Helloextensions of the world!" في البيان.

{
  "manifest_version": 3,
  "name": "Hello Extensions of the world!",
  ...
}

بعد حفظ الملف، لمشاهدة هذا التغيير في المتصفح، يجب أيضًا تحديث الإضافة. انتقل إلى صفحة "الإضافات" وانقر على رمز التحديث إلى جانب زر التبديل تشغيل/إيقاف:

إعادة تحميل إحدى الإضافات

حالات إعادة تحميل الإضافة

يعرض الجدول التالي المكوّنات التي يجب إعادة تحميلها للاطّلاع على التغييرات:

مكوِّن الإضافة يجب إعادة تحميل الإضافة
البيان نعم
مشغّل الخدمات نعم
النصوص البرمجية للمحتوى نعم (بالإضافة إلى صفحة المضيف)
النافذة المنبثقة لا
صفحة الخيارات لا
صفحات HTML للإضافات الأخرى لا

العثور على سجلّات وحدة التحكّم وأخطائها

سجلات وحدة التحكم

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

<html>
  <body>
    <h1>Hello Extensions</h1>
    <script src="popup.js"></script>
  </body>
</html>

أنشئ ملف popup.js وأضِف الرمز التالي:

console.log("This is a popup!")

للاطّلاع على هذه الرسالة المسجّلة في وحدة التحكّم:

  1. افتح النافذة المنبثقة.
  2. انقر بزر الماوس الأيمن على النافذة المنبثقة.
  3. اختَر فحص.
    جارٍ فحص النافذة المنبثقة.
    فحص النافذة المنبثقة:
  4. في DevTools، انتقِل إلى لوحة وحدة التحكم.
    لوحة الرموز في أدوات مطوّري البرامج
    فحص نافذة منبثقة

سجلّات الأخطاء

الآن دعنا نفصل الامتداد. يمكننا إجراء ذلك عن طريق إزالة علامة الاقتباس الختامية في popup.js:

console.log("This is a popup!) // ❌ broken code

انتقِل إلى صفحة "الإضافات" وافتح النافذة المنبثقة. سيظهر زر الأخطاء.

صفحة الإضافات التي تحتوي على زر الخطأ

انقر على الزر الأخطاء للاطّلاع على مزيد من المعلومات عن الخطأ:

تفاصيل خطأ الإضافة

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

تنظيم مشروع إضافة

هناك العديد من الطرق لتنظيم بنية مشروع إضافة، ولكن الشرط الأساسي الوحيد هو وضع ملف manifest.json في الدليل الجذر للإضافة كما هو موضّح في المثال التالي:

محتوى مجلد الإضافات: البيان.json، وخلفية.js، ومجلد النصوص البرمجية، ومجلد النافذة المنبثقة، ومجلد الصور.

استخدام TypeScript

إذا كنت تطوِّر تطبيقك باستخدام أداة تعديل الرموز مثل VSCode أو Atom، فيمكنك استخدام حزمة npm chrome-types للاستفادة من ميزة الإكمال التلقائي لواجهة برمجة تطبيقات Chrome. يتم تحديث حزمة npm هذه تلقائيًا عند تغيير رمز مصدر Chromium.

🚀 هل أنت جاهز لبدء عملية الإنشاء؟

اختَر أيًا من البرامج التعليمية التالية لبدء رحلة التعلّم الخاصة بالإضافات.

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