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

يمكن للإضافات الوصول إلى أدوات مطوري البرامج في 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-worker.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.

رسالة خطأ تسجيل مشغّل الخدمات

ملاحظة: إذا تعذّر تسجيل مشغّل الخدمات، لن تتمكّن من استخدام "أدوات مطوري البرامج في Chrome" إلى أن يتم إصلاح خطأ التسجيل.

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

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

رسالة خطأ من نوع لم يتم العثور عليه

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

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

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

1. انسخ رقم تعريف الإضافة الظاهر أعلى "فحص الملفات الشخصية".

   

   رقم تعريف الإضافة في صفحة "إدارة الإضافات".

2. افتح ملف البيان في المتصفح. على سبيل المثال: text chrome-extension://YOUR_EXTENSION_ID/manifest.json
3. افحص الملف.
4. انتقِل إلى لوحة التطبيق.
5. انتقِل إلى لوحة مشغِّلو الخدمات.

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

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

وإذا أجريت تغييرات على رمز مشغّل الخدمات، يمكنك النقر على تعديل أو skipwking لتطبيق التغييرات على الفور.

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

ملاحظة: لن يؤدي هذا الإجراء إلى إعادة تحميل أي مكونات إضافات أخرى.

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

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

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" إلى "الألوان":

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: لم يتم تحديد الألوان.

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

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

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

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

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

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

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

نقطة رئيسية: لإجراء طلبات fetch() على خادم خارجي، يجب الإفصاح عن عنوان URL باعتباره إذن مضيف.

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

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