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

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

نظرة عامة

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

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

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

قبل البدء

يفترض هذا الدليل أن لديك خبرة أساسية في تطوير الويب. ننصحك بالاطّلاع على 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"
  }
}

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

أنشئ مجلد images ثم نزِّل الرموز فيه.

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

يمكن للإضافات مراقبة أحداث المتصفّح في الخلفية باستخدام مشغّل الخدمات للإضافة. عاملو الخدمة هم بيئات 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 وأدرِج الرمز التالي:

body > .scaffold > :is(top-nav, navigation-rail, side-nav, footer),
main > :not(:last-child),
main > :last-child > navigation-tree,
main .toc-container {
  display: none;
}

main > :last-child {
  margin-top: min(10vmax, 10rem);
  margin-bottom: min(10vmax, 10rem);
}

أدرج ورقة الأنماط أو أزِلها باستخدام واجهة برمجة تطبيقات البرمجة. ابدأ بتعريف الإذن ""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()، وبالتالي لا حاجة إلى استخدام أي رمز إضافي.

اختبار ما إذا كان يعمل

تحقق من أن بنية ملف مشروعك تبدو كما يلي:

تحميل الإضافة محليًا

لتحميل إضافة تم فك حزمتها في وضع مطوّر البرامج، اتّبِع الخطوات الواردة في Hello World.

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

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

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

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

يُفترض أن يكون من هذا:

إضافة "وضع التركيز" غير مفعَّلة

لإجراء ذلك:

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

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

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

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

استمر في البناء.

تهانينا على الانتهاء من هذا البرنامج التعليمي 🎉. ارتقِ بمهاراتك من خلال إكمال برامج تعليمية أخرى في هذه السلسلة:

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

مواصلة الاستكشاف

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

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