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

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

نظرة عامة

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

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

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

قبل البدء

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

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

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

لاستخدام إذن "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" في ملف البيان:

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

أخيرًا، في 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()، لذا التعليمة البرمجية مطلوبة.

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

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

محتوى مجلد "وضع التركيز":تار.json وbackground.js وFocus-mode.css ومجلد الصور.

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

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

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

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

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

من المفترض أن ينتقل من هذا:

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

لإجراء ذلك:

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

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

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

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

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

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

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

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

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

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