إدراج نصوص برمجية في علامة التبويب النشطة

يمكنك تبسيط تصميم الصفحة الحالية من خلال النقر على رمز شريط أدوات الإضافة.

نظرة عامة

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

في هذا الدليل، سنشرح كيفية تنفيذ ما يلي:

• استخدِم عامل خدمة الإضافة كمنسق الحدث.
• الحفاظ على خصوصية المستخدم من خلال إذن "activeTab"
• تنفيذ الرمز البرمجي عندما ينقر المستخدم على رمز شريط أدوات الإضافة
• إدراج وإزالة جدول أسلوب باستخدام واجهة برمجة التطبيقات Scripting
• استخدِم اختصارًا في لوحة المفاتيح لتنفيذ الرمز البرمجي.

قبل البدء

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

إنشاء الإضافة

للبدء، أنشئ دليلاً جديدًا باسم focus-mode سيحتوي على ملفات الإضافة. إذا كان يُفضّل لك ذلك، يمكنك تنزيل رمز المصدر الكامل من GitHub.

الخطوة 1: إضافة بيانات الإضافة ورموزها

أنشئ ملفًا باسم manifest.json وأدرِج الرمز البرمجي التالي.

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

للاطّلاع على مزيد من المعلومات عن مفاتيح البيان هذه، يمكنك الاطّلاع على الدليل التعليمي "تشغيل النصوص البرمجية في كل علامة تبويب" الذي يوضّح metadata والرموز للإضافات بمزيد من التفصيل.

أنشئ مجلدًا باسم images ثم نزِّل الرموز إليه.

الخطوة 2: بدء الإضافة

يمكن للإضافات مراقبة أحداث المتصفّح في الخلفية باستخدام خدمة worker للإضافة. عناصر الخدمة هي بيئات JavaScript خاصة تعالج الأحداث وتنتهي عندما لا تكون مطلوبة.

ابدأ بتسجيل مشغّل الخدمات في ملف manifest.json:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

أنشئ ملفًا باسم background.js وأضِف الرمز البرمجي التالي:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

الحدث الأول الذي سيتوقّع عامل الخدمة سماعه هو runtime.onInstalled(). تسمح هذه الطريقة للإضافة بضبط حالة أولية أو إكمال بعض المهام عند التثبيت. يمكن للإضافات استخدام واجهتَي برمجة التطبيقات Storage API و IndexedDB لتخزين حالة التطبيق. في هذه الحالة، بما أنّنا نتعامل مع حالتَين فقط، سنستخدم نص شارة الإجراء نفسه لتتبُّع ما إذا كانت الإضافة "مفعّلة" أو "متوقفة".

المصطلح الرئيسي: شارة الإجراء هي بانر ملون يظهر أعلى إجراء الإضافة (رمز شريط الأدوات).

الخطوة 3: تفعيل إجراء الإضافة

يتحكّم إجراء الإضافة في رمز شريط أدوات الإضافة. وبالتالي، عندما ينقر المستخدم على رمز الإضافة، سيتم تنفيذ بعض الرموز البرمجية (كما هو الحال في هذا المثال) أو عرض نافذة منبثقة. أضِف الرمز البرمجي التالي لتعريف إجراء الإضافة في ملف manifest.json:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

استخدام إذن activeTab لحماية خصوصية المستخدم

يمنح إذن activeTab الإضافة إمكانية مؤقتة لتنفيذ الرمز البرمجي في علامة التبويب النشطة. ويسمح أيضًا بالوصول إلى السمات الحسّاسة في علامة التبويب الحالية.

يتم تفعيل هذا الإذن عندما يستخدم المستخدم الإضافة. في هذه الحالة، يستدعي المستخدم الإضافة من خلال النقر على إجراء الإضافة.

💡 ما هي تفاعلات المستخدمين الأخرى التي تفعّل إذن activeTab في إضافتي؟

• الضغط على مجموعة مفاتيح لتشغيل اختصار
• اختيار عنصر من قائمة السياقات
• قبول اقتراح من مربّع البحث الشامل
• فتح نافذة منبثقة لإضافة

يسمح إذن "activeTab" للمستخدمين باختيار بهدف تشغيل الإضافة في علامة التبويب التي يتم التركيز عليها، ما يحمي خصوصية المستخدم. ومن المزايا الأخرى أنّه لا يؤدي إلى عرض تحذير بشأن الأذونات.

لاستخدام الإذن "activeTab"، أضفه إلى صفيف أذونات البيان:

{
  ...
  "permissions": ["activeTab"],
  ...
}

الخطوة 4: تتبُّع حالة علامة التبويب الحالية

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

const extensions = 'https://developer.chrome.com/docs/extensions';
const webstore = 'https://developer.chrome.com/docs/webstore';

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON';

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

الخطوة 5: إضافة جدول الأنماط أو إزالته

حان الآن وقت تغيير تنسيق الصفحة. أنشئ ملفًا باسم focus-mode.css وأدرِج الرمز التالي فيه:

* {
  display: none !important;
}

html,
body,
*:has(article),
article,
article * {
  display: revert !important;
}

[role='navigation'] {
  display: none !important;
}

article {
  margin: auto;
  max-width: 700px;
}

يمكنك إدراج جدول الأنماط أو إزالته باستخدام واجهة برمجة التطبيقات Scripting. ابدأ ب تقديم بيان عن إذن "scripting" في البيان:

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

النجاح: لا تُطلق واجهة برمجة التطبيقات Scripting API تحذيرًا بشأن الأذونات.

أخيرًا، في background.js، أضِف الرمز التالي لتغيير تنسيق الصفحة:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡 هل يمكنني استخدام واجهة برمجة التطبيقات Scripting API لإدخال رمز برمجي بدلاً من جدول تنسيقات؟

نعم. يمكنك استخدام scripting.executeScript() لإدراج JavaScript.

اختياري: منح اختصار لوحة مفاتيح

يمكنك إضافة اختصار لتسهيل تفعيل "وضع التركيز" أو إيقافه. أضِف مفتاح "commands" إلى البيان.

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

يُشغِّل مفتاح "_execute_action" الرمز نفسه المستخدَم في الحدث action.onClicked()، لذلك لا يلزم استخدام رمز إضافي.

اختبار صلاحية الإعدادات

تأكَّد من أنّ بنية ملف مشروعك تظهر على النحو التالي:

تحميل الإضافة على الجهاز

لتحميل إضافة غير مضغوطة في وضع المطوّر، اتّبِع الخطوات الواردة في مرحبًا بك.

اختبار الإضافة في صفحة مستندات

أولاً، افتح أيًا من الصفحات التالية:

• مرحبًا بك في مستندات إضافات Chrome
• النشر في "سوق Chrome الإلكتروني"
• Scripting API

بعد ذلك، انقر على إجراء الإضافة. إذا أعددت اختصارًا للوحة المفاتيح، يمكنك اختباره بالضغط على Ctrl + B أو Cmd + B.

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

إيقاف إضافة "وضع التركيز"

في ما يلي بعض الخطوات التي يجب اتّباعها:

تفعيل إضافة "وضع التركيز"

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

استنادًا إلى ما تعلمته اليوم، حاوِل تنفيذ أيّ من الإجراءات التالية:

• تحسين صفحة أنماط CSS
• يمكنك تخصيص اختصار مختلف على لوحة المفاتيح.
• تغيير تنسيق مدونتك أو موقعك الإلكتروني المفضّل المخصص للمستندات

واصل العمل.

تهانينا على إكمال هذا الدليل التعليمي 🎉. يمكنك مواصلة تطوير مهاراتك من خلال إكمال دروس مماثلة في هذه السلسلة:

الإضافة	ما ستتعرّف عليه
وقت القراءة	لإدراج عنصر في مجموعة معيّنة من الصفحات تلقائيًا
مدير علامات التبويب	لإنشاء نافذة منبثقة تدير علامات التبويب في المتصفّح

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

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

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