اسکریپت ها را به تب فعال تزریق کنید

با کلیک کردن روی نماد نوار ابزار برنامه افزودنی، استایل صفحه فعلی را ساده کنید.

نمای کلی

این آموزش افزونه‌ای ایجاد می‌کند که ظاهر صفحه‌های اسناد افزونه 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: برنامه افزودنی را راه اندازی کنید

برنامه‌های افزودنی می‌توانند رویدادهای مرورگر را در پس‌زمینه با استفاده از سرویس‌دهنده برنامه افزودنی نظارت کنند. سرویس‌کارها محیط‌های جاوا اسکریپت خاصی هستند که رویدادها را مدیریت می‌کنند و در مواقعی که نیازی به آن‌ها نیست پایان می‌دهند.

با ثبت سرویس کارگر در فایل 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 را در برنامه افزودنی خودم فعال می کند؟

  • فشار دادن ترکیب میانبر صفحه کلید.
  • انتخاب یک آیتم منوی زمینه
  • پذیرش پیشنهاد از omnibox.
  • باز کردن پنجره برنامه افزودنی

مجوز "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 API، شیوه نامه را درج یا حذف کنید. با اعلام مجوز "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() برای تزریق جاوا اسکریپت استفاده کنید.

اختیاری: یک میانبر صفحه کلید اختصاص دهید

فقط برای سرگرمی، یک میانبر اضافه کنید تا فعال یا غیرفعال کردن حالت فوکوس آسان تر شود. کلید "commands" را به مانیفست اضافه کنید. 

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

کلید "_execute_action" همان کد رویداد action.onClicked() را اجرا می کند، بنابراین به کد اضافی نیاز نیست.

تست کنید که کار می کند

بررسی کنید که ساختار فایل پروژه شما به شکل زیر باشد:

محتویات پوشه حالت فوکوس: manifest.json، background.js، focus-mode.css و پوشه images.

برنامه افزودنی خود را به صورت محلی بارگیری کنید

برای بارگیری یک برنامه افزودنی بدون بسته‌بندی در حالت برنامه‌نویس، مراحل Hello World را دنبال کنید.

پسوند را در یک صفحه مستندات آزمایش کنید

ابتدا یکی از صفحات زیر را باز کنید:

سپس، روی اقدام افزونه کلیک کنید. اگر میانبر صفحه کلید تنظیم کرده اید، می توانید با فشار دادن Ctrl + B یا Cmd + B آن را آزمایش کنید.

از این باید برود:

پسوند حالت فوکوس خاموش است
پسوند حالت فوکوس خاموش است

به این:

پسوند حالت فوکوس روشن است
پسوند حالت فوکوس روشن است

🎯 پیشرفت های بالقوه

بر اساس آنچه امروز آموخته اید، سعی کنید یکی از موارد زیر را انجام دهید:

  • صفحه سبک CSS را بهبود بخشید.
  • میانبر صفحه کلید دیگری را اختصاص دهید.
  • طرح وبلاگ یا سایت اسناد مورد علاقه خود را تغییر دهید.

به ساختن ادامه بده

به پایان رساندن این آموزش تبریک می گویم 🎉. با تکمیل آموزش های دیگر در این مجموعه به ارتقای سطح مهارت های خود ادامه دهید:

پسوند آنچه خواهید آموخت
زمان خواندن برای درج یک عنصر در مجموعه خاصی از صفحات به طور خودکار.
مدیر زبانه ها برای ایجاد یک پنجره بازشو که برگه های مرورگر را مدیریت می کند.

به کاوش ادامه دهید

امیدواریم از ساخت این افزونه Chrome لذت برده باشید و از ادامه سفر یادگیری توسعه برنامه افزودنی خود هیجان زده باشید. ما مسیرهای یادگیری زیر را توصیه می کنیم:

  • راهنمای توسعه‌دهنده ده‌ها پیوند اضافی به بخش‌هایی از اسناد مربوط به ایجاد برنامه‌های افزودنی پیشرفته دارد.
  • برنامه‌های افزودنی به APIهای قدرتمند فراتر از آنچه در وب باز موجود است دسترسی دارند. اسناد Chrome APIها از طریق هر API بررسی می شوند.