إضافة Hello World

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

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

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

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

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

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

إضافة hello world
إضافة Hello 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

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

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

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

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

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

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

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

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

استخدام TypeScript

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

🚀 هل أنت مستعد لبدء البناء؟

اختَر أيًا من البرامج التعليمية التالية لبدء رحلتك التعليمية.

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