إضافات تصحيح الأخطاء

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

قبل البدء

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

إلغاء الإضافة

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

تصحيح أخطاء البيان

أولاً، عليك تقسيم ملف البيان من خلال تغيير مفتاح "version" إلى "versions":

manifest.json:

{
  "name": "Broken Background Color",
  "version": "1.0",
  "versions": "1.0",
  "description": "Fix an Extension!",
  ...
}

لنجرّب الآن تحميل الإضافة محليًا. سيظهر لك مربّع حوار عن الخطأ يشير إلى المشكلة:

Failed to load extension
Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536.
Could not load manifest.
تؤدي إضافة تتضمّن مفتاح بيان غير صالح إلى ظهور مربّع حوار عن الخطأ عند محاولة التحميل.
مربّع حوار غير صالح لخطأ في مفتاح البيان.

عندما يكون مفتاح البيان غير صالح، يتعذّر تحميل الإضافة، ولكن Chrome يمنحك تلميحًا عن كيفية إصلاح المشكلة.

يمكنك التراجع عن هذا التغيير وإدخال إذن غير صالح لمعرفة ما يحدث. تغيير إذن "activeTab" إلى أحرف صغيرة باللغة "activetab":

manifest.json:

{
  ...
  "permissions": ["activeTab", "scripting", "storage"],
  "permissions": ["activetab", "scripting", "storage"],
  ...
}

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

Permission 'activetab' is unknown or URL pattern is malformed.
النقر على زر الخطأ وعرض رسالة خطأ
العثور على رسالة خطأ بالنقر على زر "الأخطاء".

قبل المتابعة، غيِّر الإذن مرة أخرى وانقر على محو الكل في أعلى يسار الصفحة لمحو السجلّات وإعادة تحميل الإضافة.

زر محو الكل
كيفية محو أخطاء الإضافات

تصحيح أخطاء مشغّل الخدمات

تحديد مكان السجلّات

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

جارٍ فتح أدوات مطوّري البرامج لمشغِّل خدمات الإضافات.
سجلّات مشغّل الخدمات في لوحة "أدوات مطوري البرامج في Chrome"

أخطاء تحديد الموقع

لنعطل مشغّل الخدمات من خلال تغيير onInstalled إلى أحرف صغيرة باللغة oninstalled:

service-work.js:

// There's a typo in the line below;
// ❌ oninstalled should be ✅ onInstalled.
chrome.runtime.onInstalled.addListener(() => { 
chrome.runtime.oninstalled.addListener(() => { 
  chrome.storage.sync.set({ color: '#3aa757' }, () => {
    console.log('The background color is green.');
  });
});

أعِد تحميل الصفحة وانقر على الأخطاء لعرض سجلّ الأخطاء. يُعلمك الخطأ الأول بتعذُّر التسجيل لدى مشغّل الخدمة. يعني ذلك حدوث خطأ ما أثناء البدء: 

Service worker registration failed. Status code: 15.
تعذّر تسجيل عامل الخدمة. رمز الحالة: رسالة خطأ 15
رسالة الخطأ المتعلقة بتسجيل عامل الخدمة.

يأتي الخطأ الفعلي بعد:

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
Uncaught TypeError: تعذر قراءة خصائص رسالة الخطأ غير المحددة
رسالة Uncaught TypeError.

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

التحقّق من حالة مشغّل الخدمات

يمكنك تحديد الوقت الذي يستيقظ فيه مشغّل الخدمات لتنفيذ المهام من خلال اتّباع الخطوات التالية:

  1. انسخ رقم تعريف الإضافة أعلى "فحص طرق العرض".
    رقم تعريف الإضافة في صفحة "إدارة الإضافات"
    رقم تعريف الإضافة في صفحة "إدارة الإضافات".
  2. افتح ملف البيان في المتصفِّح. على سبيل المثال: text chrome-extension://YOUR_EXTENSION_ID/manifest.json
  3. افحص الملف.
  4. انتقِل إلى لوحة التطبيق.
  5. انتقِل إلى جزء Service Workers.

لاختبار الرمز، يمكنك تشغيل عامل الخدمة أو إيقافه باستخدام الروابط بجانب الحالة.

حالة مشغّل الخدمات في لوحة "التطبيق"
حالة مشغّل الخدمات في لوحة "التطبيق". (انقر لتكبير الصورة.)

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

حالة مشغّل الخدمات في لوحة "التطبيق"
تجري إعادة تحميل مشغّل الخدمات في لوحة "التطبيق". (انقر لتكبير الصورة.)

تصحيح أخطاء النافذة المنبثقة

الآن وبعد تهيئة الإضافة بشكل صحيح، لنقسم النافذة المنبثقة من خلال التعليق على الأسطر المميزة أدناه:

popup.js:

...
changeColorButton.addEventListener('click', (event) => {
  const color = event.target.value;

  // Query the active tab before injecting the content script
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => { 
    // Use the Scripting API to execute a script
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      args: [color],
      func: setColor
    });
  });
});

انتقِل مجددًا إلى صفحة "إدارة الإضافات". يظهر زر الأخطاء مرة أخرى. انقر فوقه لعرض السجل الجديد. وتعرض رسالة الخطأ التالية:

Uncaught ReferenceError: tabs is not defined
صفحة "إدارة الإضافات" تعرض خطأ في نافذة منبثقة
صفحة "إدارة الإضافات" تعرض خطأ في نافذة منبثقة

يمكنك فتح "أدوات مطوري البرامج" في النافذة المنبثقة من خلال فحص النافذة المنبثقة.

أدوات مطوري البرامج تعرض خطأ في نافذة منبثقة
"أدوات مطوري البرامج" تعرض خطأ في نافذة منبثقة.

يشير الخطأ tabs is undefined إلى أنّ الإضافة لا تعرف مكان إدخال النص البرمجي للمحتوى. يمكنك تصحيح ذلك من خلال طلب الرقم tabs.query()، ثم اختيار علامة التبويب النشطة.

لتحديث الرمز، انقر على زر محو الكل في الزاوية العلوية اليسرى، ثم أعد تحميل الإضافة.

تصحيح أخطاء النصوص البرمجية للمحتوى

لنقسم الآن النص البرمجي للمحتوى من خلال تغيير المتغير "color" إلى "colors" (اللون):

content.js:

...
function setColor(color) {
  // There's a typo in the line below;
  // ❌ colors should be ✅ color.
  document.body.style.backgroundColor = color;
  document.body.style.backgroundColor = colors;
}

حدّث الصفحة، وافتح النافذة المنبثقة وانقر على المربع الأخضر. لا يحدث شيء.

عند الانتقال إلى صفحة "إدارة الإضافات"، لن يظهر الزر الأخطاء. ويرجع ذلك إلى أنّه يتم تسجيل أخطاء وقت التشغيل console.warning وconsole.error فقط في صفحة "إدارة الإضافات".

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

Uncaught ReferenceError: colors is not defined
خطأ في الإضافة معروض في وحدة التحكّم في صفحات الويب
خطأ في الإضافة معروض في وحدة التحكّم في صفحات الويب.

لاستخدام "أدوات مطوري البرامج" من داخل النص البرمجي للمحتوى، انقر على سهم القائمة المنسدلة بجانب أعلى واختَر الإضافة.

Uncaught ReferenceError: الألوان غير محددة
خطأ ReferenceError: عدم تحديد الألوان

يشير الخطأ إلى أنّه لم يتم تحديد colors. يجب ألا تمرِّر الإضافة المتغيّر بشكل صحيح. صحح النص البرمجي الذي تم إدخاله لتمرير متغير اللون إلى التعليمة البرمجية.

مراقبة طلبات الشبكة

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

إعادة التحميل داخل لوحة الشبكة لعرض طلبات الشبكة في النافذة المنبثقة
إعادة تحميل الصفحة داخل لوحة الشبكة لعرض طلبات الشبكة المنبثقة

تضمين الأذونات في نموذج البيان

تتطلب بعض واجهات برمجة التطبيقات للإضافات أذونات. ارجع إلى مقالة الأذونات وواجهات برمجة تطبيقات Chrome للتأكد من أن الإضافة تطلب الأذونات الصحيحة في البيان.

  {
    "name": "Broken Background Color",
    ...
    "permissions": [
      "activeTab",
      "declarativeContent",
      "storage"
    ],
  ...
  }

محتوى إضافي للقراءة

تعرَّف على مزيد من المعلومات عن أدوات مطوري البرامج في Chrome من خلال قراءة المستندات.