اگر می‌خواهید یک ابزار کوچک و کاربردی را مستقیماً داخل مرورگر کروم اجرا کنید، ساخت افزونه با جاوااسکریپت و Manifest V3 یکی از بهترین پروژه‌های آموزشی است. در این راهنما از صفر یک افزونه می‌سازیم که متن انتخاب‌شده در صفحه را می‌گیرد، آن را در یک پنجره کوچک نمایش می‌دهد و بدون نیاز به فریم‌ورک یا سرور خارجی، با ساختاری استاندارد قابل توسعه است.

پاسخ کوتاه: برای ساخت افزونه کروم از کجا شروع کنیم؟

یک پوشه بسازید، فایل manifest.json را با مشخصات Manifest V3 بنویسید، سپس فایل‌های HTML، CSS و JavaScript را به آن اضافه کنید. افزونه از صفحه chrome://extensions و گزینه Load unpacked بارگذاری می‌شود. در ادامه، همین فرایند را با یک پروژه واقعی و قابل آزمایش پیش می‌بریم.

فهرست مطالب

افزونه کروم چیست و Manifest V3 چه نقشی دارد؟
ساختار فایل‌های پروژه
نوشتن manifest.json
ساخت رابط کاربری و دریافت متن انتخاب‌شده
بارگذاری و خطایابی افزونه
امنیت، انتشار و ایده‌های توسعه
سوالات متداول

افزونه کروم چیست و Manifest V3 چه نقشی دارد؟

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

در نسخه جدید، این فایل باید بر پایه Manifest V3 باشد. این استاندارد مجوزها را شفاف‌تر می‌کند و به‌جای مدل قدیمی، برای کارهای پس‌زمینه از Service Worker استفاده می‌کند. برای پروژه ساده ما به Service Worker نیاز نداریم، ولی دانستن این تفاوت برای افزونه‌های بزرگ‌تر مهم است.

پروژه نمونه ما چه کاری انجام می‌دهد؟

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

ساختار فایل‌های پروژه افزونه

یک پوشه با نام دلخواه، مثلاً selected-text-extension، بسازید و سه فایل زیر را داخل آن قرار دهید. نام فایل‌ها در این مثال مهم نیست، اما مسیرهایی که در Manifest می‌نویسیم باید دقیقاً با آن‌ها هماهنگ باشد.

manifest.json برای تنظیمات اصلی و مجوزها
popup.html برای رابطی که پس از کلیک باز می‌شود
popup.js برای منطق دریافت متن و نمایش آن

برای شروع به Node.js، نصب پکیج یا ابزار build احتیاج ندارید. یک ویرایشگر ساده مثل VS Code و مرورگر Chrome کافی است. این ویژگی باعث می‌شود افزونه‌نویسی برای تمرین DOM و APIهای مرورگر پروژه‌ای سریع و کم‌هزینه باشد.

نوشتن فایل manifest.json

فایل JSON زیر را در ریشه پروژه ذخیره کنید. مقدار manifest_version باید 3 باشد و بخش action مشخص می‌کند با کلیک روی آیکن، کدام Popup باز شود.

{
  "manifest_version": 3,
  "name": "Selected Text Helper",
  "version": "1.0.0",
  "description": "نمایش متن انتخاب‌شده در یک پنجره کوچک",
  "permissions": ["activeTab", "scripting"],
  "action": {
    "default_popup": "popup.html"
  }
}

مجوز activeTab دسترسی موقت به تب فعالی می‌دهد که کاربر با افزونه تعامل کرده است. مجوز scripting نیز اجازه می‌دهد یک قطعه کد را در همان تب اجرا کنیم. بهتر است از مجوزهای گسترده مثل دسترسی همیشگی به همه سایت‌ها استفاده نکنید؛ مجوز کمتر یعنی امنیت و اعتماد بیشتر.

چرا مجوزها را حداقلی انتخاب کنیم؟

کاربر هنگام نصب باید بداند افزونه چه اطلاعاتی را می‌خواند. اگر افزونه فقط متن انتخاب‌شده را لازم دارد، نیازی به دسترسی دائمی به تاریخچه یا همه صفحات نیست. همین اصل در زمان انتشار در Chrome Web Store نیز بررسی را ساده‌تر می‌کند.

در فایل popup.html یک رابط کوچک و قابل خواندن بسازید. دکمه دریافت متن، ناحیه نمایش نتیجه و پیام وضعیت، تجربه کاربر را واضح می‌کنند.

<!doctype html>
<html lang="fa" dir="rtl">
<head>
  <meta charset="UTF-8">
  <title>متن انتخاب‌شده</title>
  <style>
    body { width: 300px; padding: 16px; font-family: sans-serif; }
    button { width: 100%; padding: 9px; cursor: pointer; }
    #result { margin-top: 12px; line-height: 1.8; white-space: pre-wrap; }
  </style>
</head>
<body>
  <button id="readText">خواندن متن انتخاب‌شده</button>
  <p id="result">ابتدا متنی را در صفحه انتخاب کنید.</p>
  <script src="popup.js"></script>
</body>
</html>

قرار دادن dir="rtl" برای متن فارسی ضروری نیست، اما چیدمان را طبیعی‌تر می‌کند. از آنجا که Popup فضای محدودی دارد، عرض ثابت، فاصله داخلی و شکستن خطوط باید از ابتدا در نظر گرفته شود.

دریافت متن انتخاب‌شده با JavaScript

اکنون منطق اصلی را در popup.js بنویسید. ابتدا تب فعال را پیدا می‌کنیم، سپس با chrome.scripting.executeScript مقدار window.getSelection() را داخل همان صفحه می‌خوانیم.

استفاده از try/catch مهم است؛ صفحات داخلی Chrome یا بعضی صفحات محافظت‌شده اجازه اجرای اسکریپت را نمی‌دهند. همچنین اگر متن خالی باشد، به‌جای نمایش یک Popup خالی، پیام قابل فهمی به کاربر نشان می‌دهیم.

چه زمانی به Content Script نیاز داریم؟

برای مثال فعلی اجرای یک تابع کوتاه کافی است. اگر قرار است افزونه دائماً تغییرات صفحه را دنبال کند، روی عناصر DOM رویداد بگذارد یا کد بیشتری را مدیریت کند، Content Script انتخاب مناسب‌تری است. در آن حالت باید فایل را در بخش content_scripts Manifest معرفی کنید و دامنه‌های هدف را با دقت تعیین کنید.

بارگذاری افزونه و خطایابی آن

برای آزمایش، به chrome://extensions بروید، Developer mode را روشن کنید و روی Load unpacked بزنید. پوشه پروژه را انتخاب کنید. اگر همه فایل‌ها درست باشند، کارت افزونه نمایش داده می‌شود و آیکن آن را می‌توانید در نوار ابزار Pin کنید.

یک صفحه معمولی باز کنید و چند کلمه را انتخاب کنید.
روی آیکن افزونه کلیک و سپس دکمه خواندن را انتخاب کنید.
اگر فایل‌ها را تغییر دادید، در صفحه Extensions روی Reload بزنید.
برای خطاهای Popup، گزینه Inspect views را باز کنید.

پیام‌هایی مانند «Cannot access contents of url» معمولاً به صفحه‌ای مربوط‌اند که Chrome اجازه دسترسی به آن را نمی‌دهد. خطای JSON نیز اغلب از یک ویرگول اضافی یا کوتیشن نادرست در Manifest ناشی می‌شود. Console مرورگر و خط قرمز کنار فایل، سریع‌ترین مسیر تشخیص مشکل هستند.

مقایسه راه‌های ارتباط با صفحه

روش	کاربرد اصلی	مزیت	محدودیت
executeScript	اجرای یک کار کوتاه پس از کلیک	کد کم و مجوز محدود	برای منطق دائمی مناسب نیست
Content Script	تعامل مداوم با DOM صفحه	کنترل بهتر رویدادها	تنظیم دامنه و مجوز دقیق لازم دارد
Service Worker	رویدادهای پس‌زمینه و پیام‌رسانی	مدیریت چرخه عمر افزونه	پس از بی‌کاری متوقف می‌شود و state باید ذخیره شود

اگر این پروژه را به یک ابزار خلاصه‌سازی یا ترجمه تبدیل می‌کنید، منطق دریافت متن را از منطق نمایش نتیجه جدا نگه دارید. نتیجه را می‌توان در یک API ارسال کرد، اما پیش از آن باید درباره حریم خصوصی، کلید API و نمایش رضایت کاربر تصمیم بگیرید. برای آشنایی با ساخت یک API پایتونی، مطالعه آموزش ساخت ابزار خط فرمان حرفه‌ای با Rich در پایتون هم می‌تواند مسیر خوبی برای تمرین معماری کد باشد.

امنیت و آماده‌سازی برای انتشار

قبل از انتشار، کدهای اضافه را حذف کنید و توضیح دهید افزونه چه داده‌ای می‌خواند. هرگز کلید خصوصی یا رمز عبور را داخل JavaScript قرار ندهید. اگر اطلاعات به سرور ارسال می‌شود، فقط HTTPS استفاده کنید و متن انتخاب‌شده را بدون رضایت کاربر ذخیره نکنید.

نام، آیکن، توضیحات و تصاویر فروشگاه باید با عملکرد واقعی یکسان باشند. افزونه را روی چند نوع سایت آزمایش کنید؛ صفحه‌ای با متن راست‌به‌چپ، یک فرم، محتوای iframe و یک صفحه با انتخاب غیرفعال، خطاهای پنهان را آشکار می‌کنند. برای پروژه‌های جدی نیز نسخه‌ها را با Git مدیریت و مجوزهای جدید را مستند کنید.

ایده‌های توسعه پروژه

افزودن دکمه کپی متن و پاک‌کردن نتیجه
ذخیره آخرین یادداشت در chrome.storage
نمایش شمارش کلمات و زمان تقریبی خواندن
افزودن میانبر صفحه‌کلید برای اجرای سریع
اتصال اختیاری به یک سرویس ترجمه یا خلاصه‌سازی

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

جمع‌بندی

برای ساخت اولین افزونه کروم لازم نیست با ابزارهای پیچیده شروع کنید. Manifest V3، یک Popup ساده و چند خط JavaScript امکان می‌دهند متن انتخاب‌شده را از صفحه بگیرید و در محیطی مستقل نمایش دهید. پس از تسلط بر این نمونه، Content Script، Service Worker و ذخیره‌سازی محلی را به‌صورت مرحله‌ای اضافه کنید و همیشه دسترسی‌ها را به اندازه نیاز نگه دارید.

سوالات متداول

آیا برای ساخت افزونه کروم باید Node.js نصب کنیم؟

خیر. برای افزونه ساده این آموزش، Chrome و یک ویرایشگر متن کافی است. Node.js زمانی مفید می‌شود که بخواهید از TypeScript، فریم‌ورک یا ابزارهای build استفاده کنید.

چرا افزونه روی بعضی صفحات کار نمی‌کند؟

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

تفاوت Manifest V2 و V3 چیست؟

Manifest V3 مدل جدید تعریف مجوزها و اجرای کارهای پس‌زمینه است و از Service Worker استفاده می‌کند. برای افزونه‌های تازه، از ابتدا Manifest V3 را انتخاب کنید.

آموزش ساخت افزونه کروم با جاوااسکریپت و Manifest V3؛ از صفر تا اجرا