پسوند Hello World

با ساختن اولین برنامه افزودنی Hello World خود، اصول اولیه توسعه برنامه افزودنی Chrome را بیاموزید.

نمای کلی

شما یک مثال "Hello World" ایجاد می‌کنید، برنامه افزودنی را به صورت محلی بارگیری می‌کنید، گزارش‌ها را پیدا می‌کنید و توصیه‌های دیگر را بررسی می‌کنید.

سلام دنیا

هنگامی که کاربر روی نماد نوار ابزار برنامه افزودنی کلیک می کند، این برنامه افزودنی "Hello Extensions" را نمایش می دهد.

سلام پسوند
پاپ آپ Hello Extension

با ایجاد یک دایرکتوری جدید برای ذخیره فایل های پسوند خود شروع کنید. اگر ترجیح می دهید، می توانید کد منبع کامل را از GitHub دانلود کنید.

در مرحله بعد، یک فایل جدید به نام manifest.json در این فهرست ایجاد کنید. این فایل JSON قابلیت ها و پیکربندی برنامه افزودنی را شرح می دهد. برای مثال، اکثر فایل‌های مانیفست حاوی یک کلید "action" هستند که نشان می‌دهد تصویری که Chrome باید به‌عنوان نماد عمل برنامه‌های افزودنی استفاده کند و صفحه HTML را برای نمایش در یک پنجره بازشو هنگام کلیک روی نماد اقدام برنامه افزودنی نشان می‌دهد.

{
  "manifest_version": 3,
  "name": "Hello Extensions",
  "description": "Base Level Extension",
  "version": "1.0",
  "action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  }
}

نماد را در دایرکتوری خود دانلود کنید و حتماً نام آن را تغییر دهید تا با آنچه در کلید "default_icon" است مطابقت داشته باشد.

برای پنجره بازشو، یک فایل به نام hello.html ایجاد کنید و کد زیر را اضافه کنید:

<html>
  <body>
    <h1>Hello Extensions</h1>
  </body>
</html>

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

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

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

  1. با وارد کردن chrome://extensions در یک برگه جدید، به صفحه افزونه ها بروید. (بر اساس طراحی chrome:// URL ها قابل پیوند نیستند.)
    • همچنین، روی دکمه پازل منوی برنامه‌های افزودنی کلیک کرده و Manage Extensions را در پایین منو انتخاب کنید.
    • یا روی منوی Chrome کلیک کنید، نشانگر را روی More Tools نگه دارید، سپس Extensions را انتخاب کنید.
  2. با کلیک کردن روی سوئیچ کنار حالت برنامه‌نویس، حالت برنامه‌نویس را فعال کنید.
  3. روی دکمه Load unpacked کلیک کنید و فهرست برنامه افزودنی را انتخاب کنید.
    صفحه برنامه های افزودنی
    صفحه برنامه های افزودنی (chrome://extensions)

تا-دا! برنامه افزودنی با موفقیت نصب شد. اگر هیچ نماد برنامه افزودنی در مانیفست گنجانده نشده باشد، یک نماد عمومی برای برنامه افزودنی ایجاد می شود.

پسوند را پین کنید

به طور پیش فرض، وقتی برنامه افزودنی خود را به صورت محلی بارگیری می کنید، در منوی برنامه های افزودنی ظاهر می شود ( پازل ). برنامه افزودنی خود را به نوار ابزار پین کنید تا در طول توسعه به سرعت به برنامه افزودنی خود دسترسی پیدا کنید.

پین کردن پسوند
پین کردن پسوند

روی نماد اقدام برنامه افزودنی (نماد نوار ابزار) کلیک کنید. شما باید یک پنجره بازشو ببینید

سلام جهان گسترش
پسوند Hello World

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

به کد بازگردید و نام برنامه افزودنی را به "Hello Extensions of the world!" در مانیفست

{
  "manifest_version": 3,
  "name": "Hello Extensions of the world!",
  ...
}

پس از ذخیره فایل، برای مشاهده این تغییر در مرورگر باید افزونه را نیز Refresh کنید. به صفحه برنامه‌های افزودنی بروید و روی نماد تازه‌سازی در کنار کلید روشن / خاموش کلیک کنید:

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

زمان بارگیری مجدد برنامه افزودنی

جدول زیر نشان می دهد که کدام مؤلفه ها برای مشاهده تغییرات باید دوباره بارگذاری شوند:

جزء پسوند به بارگیری مجدد برنامه افزودنی نیاز دارد
مانیفست بله
کارگر خدمات بله
اسکریپت های محتوا بله (به علاوه صفحه میزبان)
پنجره بازشو خیر
صفحه گزینه ها خیر
سایر صفحات HTML افزونه خیر

لاگ ها و خطاهای کنسول را پیدا کنید

لاگ های کنسول

در طول توسعه، می‌توانید کد خود را با دسترسی به گزارش‌های کنسول مرورگر اشکال زدایی کنید. در این مورد، ما گزارش های مربوط به پنجره بازشو را پیدا می کنیم. با افزودن یک تگ اسکریپت به hello.html شروع کنید.

<html>
  <body>
    <h1>Hello Extensions</h1>
    <script src="popup.js"></script>
  </body>
</html>

یک فایل popup.js ایجاد کنید و کد زیر را اضافه کنید:

console.log("This is a popup!")

برای دیدن این پیام وارد شده در کنسول:

  1. پاپ آپ را باز کنید.
  2. روی پنجره بازشو راست کلیک کنید.
  3. Inspect را انتخاب کنید.
    بازرسی پنجره بازشو
    بازرسی یک پنجره بازشو
  4. در DevTools به پنل کنسول بروید.
    پنل کد DevTools
    بازرسی یک پنجره بازشو

گزارش های خطا

حالا بیایید پسوند را بشکنیم. ما می توانیم این کار را با حذف نقل قول بسته در popup.js انجام دهیم:

console.log("This is a popup!) // ❌ broken code

به صفحه Extensions بروید و پنجره بازشو را باز کنید. یک دکمه Errors ظاهر می شود.

صفحه برنامه های افزودنی با دکمه خطا

برای کسب اطلاعات بیشتر در مورد خطا، روی دکمه Errors کلیک کنید:

جزئیات خطای برنامه افزودنی

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

ساختار یک پروژه توسعه

راه های زیادی برای ساختار یک پروژه توسعه وجود دارد. با این حال، تنها پیش نیاز این است که فایل manifest.json را در دایرکتوری ریشه برنامه افزودنی مانند مثال زیر قرار دهید:

محتویات یک پوشه پسوند: manifest.json، background.js، پوشه اسکریپت، پوشه popup و پوشه تصاویر.

از TypeScript استفاده کنید

اگر در حال توسعه با استفاده از ویرایشگر کد مانند VSCode یا Atom هستید، می‌توانید از بسته‌های npm chrome-types استفاده کنید تا از مزایای تکمیل خودکار برای Chrome API استفاده کنید. وقتی کد منبع Chromium تغییر می کند، این بسته npm به طور خودکار به روز می شود.

🚀 آماده شروع ساخت هستید؟

هر یک از آموزش‌های زیر را برای شروع سفر یادگیری افزونه خود انتخاب کنید.

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