اسکریپت ها را در هر صفحه اجرا کنید

اولین افزونه خود را ایجاد کنید که یک عنصر جدید را در صفحه وارد می کند.

نمای کلی

این آموزش افزونه ای ایجاد می کند که زمان خواندن مورد انتظار را به هر برنامه افزودنی Chrome و صفحه اسناد فروشگاه وب Chrome اضافه می کند.

در این راهنما، قصد داریم مفاهیم زیر را توضیح دهیم:

• مانیفست پسوند.
• یک افزونه از چه اندازه نمادهایی استفاده می کند.
• نحوه تزریق کد به صفحات با استفاده از اسکریپت های محتوا .
• نحوه استفاده از الگوهای مسابقه
• مجوزهای برنامه افزودنی

قبل از شروع

این راهنما فرض می کند که شما تجربه اولیه توسعه وب را دارید. توصیه می کنیم برای آشنایی با گردش کار توسعه برنامه های افزودنی، آموزش Hello world را بررسی کنید.

پسوند را بسازید

برای شروع، یک دایرکتوری جدید به نام reading-time ایجاد کنید تا فایل های برنامه افزودنی را در خود نگه دارید. در صورت تمایل، می توانید کد منبع کامل را از GitHub دانلود کنید.

مرحله 1: اطلاعات مربوط به برنامه افزودنی را اضافه کنید

فایل JSON مانیفست تنها فایل مورد نیاز است. اطلاعات مهمی در مورد برنامه افزودنی در خود دارد. یک فایل manifest.json در ریشه پروژه ایجاد کنید و کد زیر را اضافه کنید:

{
  "manifest_version": 3,
  "name": "Reading time",
  "version": "1.0",
  "description": "Add the reading time to Chrome Extension documentation articles"
}

این کلیدها حاوی ابرداده های اساسی برای برنامه افزودنی هستند. آنها کنترل می کنند که چگونه برنامه افزودنی در صفحه برنامه های افزودنی ظاهر می شود و پس از انتشار، در فروشگاه وب کروم. برای غواصی عمیق‌تر، کلیدهای "name" ، "version" و "description" را در صفحه نمای کلی مانیفست بررسی کنید.

💡 حقایق دیگر درباره افزونه آشکار می شود

• باید در ریشه پروژه قرار گیرد.
• تنها کلیدهای مورد نیاز "manifest_version" ، "name" و "version" هستند.
• در حین توسعه از نظرات ( // ) پشتیبانی می کند، اما قبل از آپلود کد شما در فروشگاه وب Chrome، باید این نظرات حذف شوند.

مرحله 2: نمادها را ارائه دهید

بنابراین، چرا به نمادها نیاز دارید؟ اگرچه نمادها در طول توسعه اختیاری هستند، اما اگر قصد دارید برنامه افزودنی خود را در فروشگاه وب Chrome توزیع کنید، به آنها نیاز دارید. آنها همچنین در مکان های دیگری مانند صفحه مدیریت برنامه های افزودنی ظاهر می شوند.

یک پوشه images ایجاد کنید و آیکون ها را داخل آن قرار دهید. می توانید آیکون ها را در GitHub دانلود کنید. سپس، کد برجسته شده را به مانیفست خود اضافه کنید تا نمادها را اعلام کنید:

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

ما استفاده از فایل‌های PNG را توصیه می‌کنیم، اما سایر فرمت‌های فایل به جز فایل‌های SVG مجاز هستند.

💡 این نمادهای با اندازه های متفاوت در کجا نمایش داده می شوند؟

مرحله 3: اسکریپت محتوا را اعلام کنید

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

کد زیر را به manifest.json اضافه کنید تا یک اسکریپت محتوا به نام content.js ثبت شود.

{
  "content_scripts": [
    {
      "js": ["scripts/content.js"],
      "matches": [
        "https://developer.chrome.com/docs/extensions/*",
        "https://developer.chrome.com/docs/webstore/*"
      ]
    }
  ]
}

فیلد "matches" می‌تواند یک یا چند الگوی مطابقت داشته باشد. اینها به مرورگر اجازه می دهد تا تشخیص دهد که اسکریپت های محتوا را به کدام سایت ها تزریق کند. الگوهای مطابقت از سه بخش تشکیل شده است: <scheme>://<host><path> . آنها می توانند شامل کاراکترهای ' * ' باشند.

💡 آیا این برنامه افزودنی اخطار مجوز نمایش می دهد؟

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

در این مثال، کاربر اخطار مجوز زیر را می بیند:

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

مرحله 4: محاسبه و درج زمان خواندن

اسکریپت های محتوا می توانند از مدل استاندارد شی سند (DOM) برای خواندن و تغییر محتوای یک صفحه استفاده کنند. برنامه افزودنی ابتدا بررسی می کند که آیا صفحه حاوی عنصر <article> است یا خیر. سپس، تمام کلمات موجود در این عنصر را می شمارد و یک پاراگراف ایجاد می کند که کل زمان خواندن را نشان می دهد.

یک فایل به نام content.js در پوشه ای به نام scripts ایجاد کنید و کد زیر را اضافه کنید:

const article = document.querySelector("article");

// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
  const text = article.textContent;
  const wordMatchRegExp = /[^\s]+/g; // Regular expression
  const words = text.matchAll(wordMatchRegExp);
  // matchAll returns an iterator, convert to array to get word count
  const wordCount = [...words].length;
  const readingTime = Math.round(wordCount / 200);
  const badge = document.createElement("p");
  // Use the same styling as the publish information in an article's header
  badge.classList.add("color-secondary-text", "type--caption");
  badge.textContent = `⏱️ ${readingTime} min read`;

  // Support for API reference docs
  const heading = article.querySelector("h1");
  // Support for article docs with date
  const date = article.querySelector("time")?.parentNode;

  (date ?? heading).insertAdjacentElement("afterend", badge);
}

💡 جاوا اسکریپت جالبی که در این کد استفاده شده است

• عبارات منظم فقط برای شمارش کلمات داخل عنصر <article> استفاده می شود.
• insertAdjacentElement() برای درج گره زمان خواندن بعد از عنصر استفاده می شود.
• ویژگی classList برای اضافه کردن نام کلاس های CSS به ویژگی کلاس عنصر استفاده می شود.
• زنجیره اختیاری برای دسترسی به یک ویژگی شی که ممکن است تعریف نشده یا تهی باشد استفاده می شود.
• اگر <date> تهی یا تعریف نشده باشد ، ادغام تهی <heading> را برمی گرداند.

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

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

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

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

یک برنامه افزودنی یا اسناد فروشگاه وب Chrome را باز کنید

در اینجا چند صفحه وجود دارد که می توانید باز کنید تا ببینید خواندن هر مقاله چقدر طول می کشد.

• در فروشگاه وب کروم منتشر کنید
• درک اسکریپت های محتوا

باید به این شکل باشد:

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

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

• الگوی تطابقی دیگری را در manifest.json اضافه کنید تا از سایر صفحات برنامه‌نویس کروم پشتیبانی کنید، مانند ابزارهای توسعه‌دهنده Chrome یا Workbox .
• یک اسکریپت محتوای جدید اضافه کنید که زمان خواندن را به هر یک از وبلاگ ها یا سایت های مستند مورد علاقه شما محاسبه می کند.

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

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

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

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

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