تشغيل النصوص البرمجية على كل صفحة

قم بإنشاء أول إضافة تدرج عنصرًا جديدًا في الصفحة.

نظرة عامة

ينشئ هذا البرنامج التعليمي إضافة تضيف وقت القراءة المتوقّع إلى أي إضافة من إضافات 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.

💡 أين يتم عرض هذه الرموز ذات الأحجام المختلفة؟

الخطوة 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 الإلكتروني"

في ما يلي بعض الصفحات التي يمكنك فتحها لمعرفة المدة التي ستستغرقها قراءة كل مقالة.

• النشر في "سوق Chrome الإلكتروني"
• فهم النصوص البرمجية للمحتوى

من المفترض أن يظهر على النحو التالي:

🎯 التحسينات المحتمَلة

بناءً على ما تعلمته اليوم، حاول تنفيذ أي مما يلي:

• إضافة نمط مطابقة آخر في ملف البيان.json لدعم مطوّري برامج Chrome الآخرين الصفحات، مثل أدوات مطوري البرامج في Chrome أو Workbox.
• إضافة نص محتوى جديد يحسب وقت القراءة إلى أي من المدونات أو المدونات المفضلة لديك مواقع التوثيق.

مواصلة البناء

تهانينا على إكمال هذا الدليل التعليمي 🎉. واصِل تطوير مهاراتك من خلال إكمال أنشطة البرامج التعليمية حول هذه السلسلة:

الاطّلاع على معلومات إضافية

نأمل أن تكون قد استمتعت بإنشاء إضافة Chrome هذه وتسرّنا مواصلة استخدام Chrome. رحلة التعلم والتطوير. نقترح عليك المسار التعليمي التالي:

• يحتوي دليل المطوِّر على عشرات الروابط الإضافية التي تؤدي إلى مستندات. ذات صلة بإنشاء الإضافات المتقدمة.
• يمكن للإضافات الوصول إلى واجهات برمجة تطبيقات فعّالة غير تلك المتاحة على الويب المفتوح. تتناول مستندات واجهات برمجة تطبيقات Chrome كل واجهة برمجة تطبيقات.