إنشاء إضافتك الأولى التي تُدرج عنصرًا جديدًا في الصفحة.
نظرة عامة
ينشئ هذا البرنامج التعليمي إضافة تضيف وقت القراءة المتوقع إلى أي إضافة Chrome وصفحة مستندات "سوق Chrome الإلكتروني".
في هذا الدليل، سنشرح المفاهيم التالية:
- بيان الإضافة
- أحجام الرموز التي تستخدمها الإضافة
- كيفية إدخال رمز في الصفحات باستخدام النصوص البرمجية للمحتوى
- كيفية استخدام أنماط المطابقة.
- أذونات الإضافات.
قبل البدء
يفترض هذا الدليل أن لديك خبرة أساسية في تطوير الويب. ننصحك بالاطّلاع على البرنامج التعليمي Hello world للاطّلاع على مقدّمة حول سير عمل تطوير الإضافات.
إنشاء الإضافة
للبدء، أنشِئ دليلاً جديدًا يُسمى reading-time للاحتفاظ بملفات الإضافة. يمكنك تنزيل رمز المصدر الكامل من GitHub إذا كنت تفضّل ذلك.
الخطوة 1: إضافة معلومات حول الإضافة
جدير بالذكر أنّ ملف البيان بتنسيق JSON هو الملف الوحيد المطلوب. وهو يحتوي على معلومات مهمة حول الإضافة. أنشئ ملف manifest.json في جذر المشروع وأضف الرمز التالي:
{
"manifest_version": 3,
"name": "Reading time",
"version": "1.0",
"description": "Add the reading time to Chrome Extension documentation articles"
}
تحتوي هذه المفاتيح على بيانات وصفية أساسية للإضافة. وهي تتحكّم في كيفية ظهور الإضافة على صفحة الإضافات، وكذلك على "سوق Chrome الإلكتروني" عند نشرها. لمزيد من التفاصيل، يمكنك الاطّلاع على مفاتيح
"name" و"version" و"description" في صفحة النظرة العامة على
البيان.
💡 حقائق أخرى حول بيان الإضافات
- ويجب أن يكون في جذر المشروع.
- المفاتيح الوحيدة المطلوبة هي
"manifest_version"و"name"و"version". - وهو يدعم التعليقات (
//) أثناء التطوير، ولكن يجب إزالتها قبل تحميل الرمز إلى "سوق Chrome الإلكتروني".
الخطوة 2: تقديم الرموز
إذن، لماذا تحتاج إلى الأيقونات؟ وعلى الرغم من أنّ الرموز اختيارية أثناء التطوير، إلا أنّها مطلوبة إذا كنت تخطّط لتوزيع إضافتك على "سوق Chrome الإلكتروني". كما تظهر في أماكن أخرى مثل صفحة إدارة الإضافات.
أنشِئ مجلد "images" وضع الرموز بداخله. يمكنك تنزيل الرموز من GitHub. بعد ذلك، أضِف الرمز المميّز إلى ملف البيان لتوضيح الرموز:
{
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
وننصح باستخدام ملفات PNG، ولكن يُسمح باستخدام تنسيقات الملفات الأخرى، باستثناء ملفات SVG.
💡 أين يتم عرض هذه الرموز ذات الأحجام المختلفة؟
| حجم الرمز | استخدام الرمز |
|---|---|
| 16x16 | الرمز المفضّل في صفحات الإضافة وقائمة السياق. |
| 32 × 32 | غالبًا ما تتطلب أجهزة الكمبيوتر التي تعمل بنظام التشغيل Windows هذا الحجم. |
| 48 × 48 | يظهر على صفحة "الإضافات". |
| 128 × 128 | يتم عرضها عند التثبيت وفي "سوق Chrome الإلكتروني". |
الخطوة 3: تعريف النص البرمجي للمحتوى
يمكن للإضافات تشغيل نصوص برمجية تقرأ محتوى صفحة وتعدّله. ويُطلق عليها اسم النصوص البرمجية للمحتوى. وهي تعيش في عالم منعزل، ما يعني أنه يمكنها إجراء تغييرات على بيئة JavaScript بدون التعارض مع النصوص البرمجية للمحتوى للصفحة المضيفة أو الإضافات الأخرى.
أضِف الرمز التالي إلى manifest.json لتسجيل نص برمجي لمحتوى يحمل اسم
content.js.
{
"content_scripts": [
{
"js": ["scripts/content.js"],
"matches": [
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/webstore/*"
]
}
]
}
يمكن أن يحتوي الحقل "matches" على نمط مطابقة واحد أو أكثر. يتيح ذلك للمتصفح تحديد المواقع الإلكترونية التي يجب إدخال النصوص البرمجية للمحتوى فيها. تتألف أنماط المطابقة من ثلاثة أجزاء:
<scheme>://<host><path>. ويمكن أن تحتوي على أحرف "*".
💡 هل تعرض هذه الإضافة تحذيرًا بشأن الإذن؟
عندما يثبّت المستخدم إحدى الإضافات، يخبره المتصفّح بالإجراءات التي يمكن للإضافة تنفيذها. تطلب النصوص البرمجية للمحتوى إذنًا بتشغيلها على المواقع الإلكترونية التي تستوفي معايير نمط المطابقة.
في هذا المثال، سيظهر للمستخدم التحذير التالي بشأن الإذن:
لمزيد من التفاصيل حول أذونات الإضافات، يُرجى الاطّلاع على بيان الأذونات وتحذير المستخدمين.
الخطوة 4: حساب وقت القراءة وإدخاله
يمكن للنصوص البرمجية للمحتوى استخدام نموذج كائن المستند (DOM) العادي لقراءة محتوى الصفحة وتغييره. ستتحقق الإضافة أولاً مما إذا كانت الصفحة تحتوي على العنصر <article>.
بعد ذلك، سيحسب جميع الكلمات داخل هذا العنصر وينشئ فقرة تعرض إجمالي وقت القراءة.
أنشئ ملفًا باسم content.js داخل مجلد باسم scripts وأضِف الرمز التالي:
const article = document.querySelector("article");
// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
const text = article.textContent;
const wordMatchRegExp = /[^\s]+/g; // Regular expression
const words = text.matchAll(wordMatchRegExp);
// matchAll returns an iterator, convert to array to get word count
const wordCount = [...words].length;
const readingTime = Math.round(wordCount / 200);
const badge = document.createElement("p");
// Use the same styling as the publish information in an article's header
badge.classList.add("color-secondary-text", "type--caption");
badge.textContent = `⏱️ ${readingTime} min read`;
// Support for API reference docs
const heading = article.querySelector("h1");
// Support for article docs with date
const date = article.querySelector("time")?.parentNode;
(date ?? heading).insertAdjacentElement("afterend", badge);
}
💡 تم استخدام محتوى JavaScript مثير للاهتمام في هذا الرمز البرمجي
- التعبيرات العادية المستخدمة لاحتساب الكلمات داخل العنصر
<article>فقط. - تُستخدَم السمة
insertAdjacentElement()لإدراج عقدة وقت القراءة بعد العنصر. - الخاصية classList المُستخدَمة لإضافة أسماء فئات CSS إلى سمة فئة العنصر.
- التسلسل الاختياري المستخدَم للوصول إلى خاصية كائن قد تكون غير معرَّفة أو فارغة.
- يؤدي الدمج الفارغ إلى عرض
<heading>إذا كانت قيمة<date>فارغة أو غير معرَّفة.
اختبار ما إذا كان يعمل
تحقق من أن بنية ملف مشروعك تبدو كما يلي:
تحميل الإضافة محليًا
لتحميل إضافة تم فك حزمتها في وضع مطوّر البرامج، اتبع الخطوات الواردة في أساسيات التطوير.
فتح إضافة أو مستندات "سوق Chrome الإلكتروني"
في ما يلي بعض الصفحات التي يمكنك فتحها لمعرفة المدة التي ستستغرقها قراءة كل مقالة.
يُفترض أن يظهر على النحو التالي:
🎯 التحسينات المحتملة
بناءً على ما تعلمته اليوم، حاول تنفيذ أي مما يلي:
- أضِف نمط مطابقة آخر في ملفManifest.json لتتوافق مع صفحات مطوّري Chrome الأخرى، مثل أدوات مطوري البرامج في Chrome أو Workbox.
- أضِف نصًا برمجيًا جديدًا للمحتوى يحسب وقت القراءة لأي من المدونات أو مواقع الوثائق المفضّلة لديك.
مواصلة الإنشاء
تهانينا على إكمال هذا البرنامج التعليمي 🎉. استمر في بناء مهاراتك من خلال إكمال برامج تعليمية أخرى في هذه السلسلة:
| الإضافة | ما سوف تتعلمه |
|---|---|
| وضع التركيز | لتشغيل الرمز في الصفحة الحالية بعد النقر على إجراء الإضافة. |
| مدير علامات التبويب | لإنشاء نافذة منبثقة تدير علامات تبويب المتصفّح |
مواصلة الاستكشاف
نأمل أن تكون قد استمتعت بإنشاء إضافة Chrome هذه ونتطلّع إلى مواصلة رحلة التعلّم المتعلّقة بتطوير Chrome. نوصي بالمسار التعليمي التالي:
- يحتوي دليل مطوّر البرامج على العشرات من الروابط الإضافية لأجزاء من المستندات ذات الصلة بإنشاء الإضافات المتقدمة.
- يمكن للإضافات الوصول إلى واجهات برمجة تطبيقات فعّالة أكثر مما هو متاح على الويب المفتوح. تشرح وثائق واجهات برمجة التطبيقات في Chrome كل واجهة برمجة تطبيقات.