شروع کار با ساخت برنامه های افزودنی کروم با استفاده از React و TypeScript

Summarize this content to 400 words in Persian Lang

سلام، انجمن توسعه دهندگان!من DEVLOKER هستم، امروز می‌خواهم پروژه اخیرم را به اشتراک بگذارم: یک برنامه افزودنی Chrome که به کاربران امکان می‌دهد بین تم‌های تیره و روشن در هر صفحه وب جابجا شوند. پیچ و تاب؟ مهم نیست که صفحه در اصل از حالت تاریک پشتیبانی می‌کند یا خیر، برنامه افزودنی از یک فیلتر CSS استفاده می‌کند: برای دستیابی به اثر، معکوس کنید. من هیجان زده هستم که شما را از طریق آن راهنمایی کنم!

ایدهایده اصلی ساده بود: ایجاد یک افزونه کروم که می تواند صفحه وب را بین حالت تاریک و روشن تغییر دهد. این می تواند به ویژه برای کاربرانی مفید باشد که خواندن در حالت تاریک را ترجیح می دهند اما از وب سایت هایی بازدید می کنند که پشتیبانی داخلی برای آن ندارند.

می توانید کد کامل را در مخزن GitHub من پیدا کنید.

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

manifest.json

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

manifest_version: نسخه فرمت فایل مانیفست را مشخص می کند. در اینجا از نسخه 3 استفاده شده است که آخرین استاندارد افزونه های کروم است.

نام و شرح: نام و توضیح مختصری از برنامه افزودنی ارائه دهید. این فیلدها به کاربران کمک می کند تا هدف برنامه افزودنی را درک کنند.

نسخه: نشان دهنده نسخه فعلی برنامه افزودنی است. این برای مدیریت نسخه و به روز رسانی مفید است.

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

مجوزها: مجوزهای درخواست شده توسط افزونه را فهرست می کند:

زبانه ها: به برنامه افزودنی اجازه می دهد تا با برگه های مرورگر تعامل داشته باشد.

فعال تب: به برگه فعال فعلی دسترسی می دهد.

ذخیره سازی: استفاده از API ذخیره سازی Chrome را برای ذخیره تنظیمات برگزیده کاربر فعال می کند.

اسکریپت نویسی: به برنامه افزودنی اجازه می دهد تا اسکریپت ها را در زمینه صفحات وب اجرا کند.

زمینه: کارگر سرویس پس‌زمینه را که وظایف پس‌زمینه و شنوندگان رویداد را مدیریت می‌کند، پیکربندی می‌کند.

نوع: “module” اجازه می دهد تا از ماژول های ES6 در اسکریپت پس زمینه استفاده کنید.

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

محتوا_اسکریپت ها: اسکریپت هایی را که به صفحات وب تزریق می شوند را تعریف می کند:

مسابقات: تعیین می کند که اسکریپت محتوا به کدام URL ها تزریق شود. تضمین می کند که در تمام صفحات اجرا می شود.

js: فایل های جاوا اسکریپتی که باید تزریق شوند را فهرست می کند. در اینجا content.js منطق اعمال سبک های حالت تاریک/روشن را در خود دارد.

نوع: “module” نشان می دهد که اسکریپت یک ماژول ES6 است.

عمل: پنجره پیش فرضی را مشخص می کند که با کلیک روی نماد برنامه افزودنی ظاهر می شود. index.html فایل HTML پاپ آپ است.

host_permissions: به برنامه افزودنی اجازه می دهد برای همه هاست ها مجوز درخواست کند (:///*). این برای تعامل با هر صفحه وب مورد نیاز است.

پنجره بازشو

پنجره بازشو رابط کاربری افزونه کروم است که وقتی کاربر روی نماد برنامه افزودنی در نوار ابزار مرورگر کلیک می کند ظاهر می شود. معمولاً برای ارائه راهی سریع برای تعامل کاربران با برنامه افزودنی استفاده می‌شود.

چرخه عمر پاپ آپ در مقایسه با سایر اجزا کوتاه مدت است.
پایدار نیست و هر بار که باز می شود دوباره ایجاد می شود.
ارتباط با سایر بخش های برنامه افزودنی معمولاً با استفاده از آن انجام می شود chrome.runtime.sendMessage و chrome.runtime.onMessage.

چرخه زندگی

مقداردهی اولیه**: وقتی کاربر روی نماد برنامه افزودنی کلیک می کند، Chrome یک پنجره بازشو جدید ایجاد می کند و HTML، CSS و جاوا اسکریپت مشخص شده برای پنجره بازشو را بارگیری می کند. manifest.json.

فعال: در حالی که پنجره باز است، اسکریپت های آن (JS) فعال هستند و می توانند با DOM تعامل داشته باشند و بر اساس ورودی کاربر اقداماتی را انجام دهند.

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

اسکریپت پس زمینه

اسکریپت پس‌زمینه در پس‌زمینه اجرا می‌شود و مسئول رسیدگی به رویدادهایی است که بر برنامه افزودنی به‌طور کلی تأثیر می‌گذارند، مانند اقدامات مرورگر، هشدارها یا درخواست‌های شبکه. همچنین می‌تواند حالت گسترده را مدیریت کند و کارهایی را که باید به طور مداوم در دسترس باشند، انجام دهد.

این می تواند یک صفحه پس زمینه دائمی (مدل قدیمی) یا یک کارگر خدماتی (مدل جدید) باشد.
این برای کارهای طولانی مدت، رسیدگی به رویدادها و مدیریت وضعیت جهانی ایده آل است.
ارتباط اغلب با استفاده از chrome.runtime.sendMessage و chrome.runtime.onMessage، یا chrome.storage برای مدیریت دولت

چرخه زندگی

مقداردهی اولیه: اسکریپت پس‌زمینه زمانی شروع می‌شود که برنامه افزودنی برای اولین بار نصب می‌شود یا زمانی که Chrome راه‌اندازی می‌شود. در تمام جلسات مرورگر (در صورت استفاده از صفحات پس‌زمینه مداوم) ادامه می‌یابد یا هر بار (در صورت استفاده از سرویس‌دهندگان) دوباره ایجاد می‌شود.

فعال: در حین اجرا، رویدادها و پیام‌های بخش‌های دیگر برنامه افزودنی را کنترل می‌کند و می‌تواند با API مرورگر تعامل داشته باشد.

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

اسکریپت های محتوا

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

آنها در محیط های ایزوله اجرا می شوند و به DOM صفحه وب دسترسی دارند، اما به سایر بخش های برنامه افزودنی یا Chrome API مستقیماً دسترسی ندارند (به جز موارد محدود chrome.runtime و chrome.storage).
آنها را می توان برای اجرا در زمان های مختلف (مثلاً زمانی که DOM به طور کامل بارگذاری می شود) با استفاده از آن مشخص کرد run_at که در manifest.json.

چرخه زندگی

مقداردهی اولیه: اسکریپت های محتوا بر اساس قوانین مشخص شده در صفحات وب تزریق می شوند manifest.json (به عنوان مثال، الگوهای URL). آنها زمانی شروع می شوند که صفحه ای مطابق با الگوهای مشخص شده بارگذاری شود.

فعال: آنها کد خود را در زمینه صفحه اجرا می کنند و می توانند با DOM صفحه تعامل داشته باشند. آنها همچنین می توانند با استفاده از اسکریپت پس زمینه ارتباط برقرار کنند chrome.runtime.sendMessage و chrome.runtime.onMessage.

خاتمه دادن: اسکریپت های محتوا به طور خودکار زمانی که کاربر از صفحه دور می شود یا صفحه به روز می شود حذف می شوند.

چرا React و TypeScript را انتخاب کنیم؟

استفاده از React و TypeScript برای توسعه افزونه کروم مزایای زیادی به همراه داشت. معماری مبتنی بر کامپوننت و رندر کارآمد React، همراه با ایمنی نوع TypeScript و تجربه توسعه‌دهنده بهبود یافته، منجر به توسعه پایدارتر، مقیاس‌پذیرتر و قوی‌تر شد. این ابزارها نه تنها روند توسعه را بهبود می بخشند، بلکه تضمین می کنند که برنامه افزودنی قابل اعتماد و کارآمد برای کاربران است.

ساختار پوشه پروژه

هنگام تنظیم یک افزونه کروم با React و TypeScript با استفاده از Vite، ساختار پوشه پروژه به خوبی سازماندهی شده بسیار مهم است. در اینجا یک نمای کلی از ساختار پوشه آورده شده است:

my-chrome-extension/
│
├── public/
│ ├── icons/
│ │ ├── icon-16.png
│ │ ├── icon-32.png
│ │ ├── icon-48.png
│ │ └── icon-128.png
│ └── manifest.json
│
├── src/
│ ├── scripts/
│ │ ├── service-worker/
│ │ │ └── background.ts
│ │ ├── injection/
│ │ │ └── content.ts
│ ├── types/
│ │ ├── TMessage.ts
│ │ └── TTheme.ts
│ ├── utils/
│ │ ├── helpers.ts
│ ├── constants/
│ │ └── theme.ts
│ ├── features/
│ │ └── Popup.tsx
│ ├── styles/
│ │ └── styles.css
│ ├── index.html
│ ├── index.tsx
│
├── dist/
│
├── .gitignore
├── package.json
├── tsconfig.json
└── vite.config.ts

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

حال بیایید مهم ترین اجزای افزونه کروم (پاپ آپ، پس زمینه، محتوا) را توضیح دهیم:

مؤلفه بازشو (Popup.tsx)

کامپوننت پاپ آپ رابط کاربری برنامه افزودنی است که با کلیک روی نماد برنامه افزودنی ظاهر می شود. این امکان را به کاربران می دهد که بین تم های تیره و روشن جابجا شوند و مسئول موارد زیر است:

راه اندازی تم: پس از باز کردن، پنجره بازشو یک پیام ارسال می کندINIT_THEMEبرای دریافت تم فعلی و تنظیم آن به اسکریپت پس‌زمینه پیام دهید.

نمایش تم فعلی: پنجره بازشو تم فعلی (تاریک یا روشن) را بر اساس وضعیت مدیریت شده در مؤلفه نمایش می دهد.

مدیریت ورودی کاربر: هنگامی که کاربر موضوع دیگری را انتخاب می کند، پنجره بازشو وضعیت را به روز می کند و یک “” ارسال می کند.APPLY_THEME” برای اعمال تم جدید به اسکریپت پس زمینه پیام دهید.

اسکریپت پس زمینه (background.ts)

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

راه اندازی تم: هنگامی که اسکریپت بازشو یا محتوا یک ” را ارسال می کندINIT_THEMEپیام، اسکریپت پس‌زمینه، طرح زمینه ذخیره‌شده را از فضای ذخیره‌سازی مرورگر بارگیری می‌کند، نشان برنامه افزودنی را به‌روزرسانی می‌کند و طرح زمینه را به فرستنده باز می‌فرستد.

اعمال تم: هنگامی که کاربر تم را در پنجره بازشو تغییر می دهد، اسکریپت پس زمینه “” را دریافت می کند.APPLY_THEMEسپس از اسکریپت محتوا می‌خواهد که تم جدید را در صفحه وب فعلی اعمال کند، نشان را به‌روزرسانی می‌کند تا موضوع جدید را منعکس کند، و طرح زمینه را در حافظه مرورگر ذخیره می‌کند.

به روز رسانی نشان: متن نشان و رنگ روی نماد برنامه افزودنی بر اساس موضوع فعلی (تاریک یا روشن) به‌روزرسانی می‌شوند تا نشانه‌ای بصری از طرح زمینه فعال ارائه کنند.

اسکریپت محتوا (content.ts)

اسکریپت محتوا به تمام صفحات وب مشخص شده در مانیفست تزریق می شود. مستقیماً با صفحات وب در تعامل است و مسئول موارد زیر است:

اعمال تم: هنگامی که اسکریپت محتوا برای اولین بار بارگذاری می شود، یک ” ارسال می کند.INIT_THEMEبرای دریافت تم فعلی به اسکریپت پس زمینه پیام دهید. پس از دریافت تم، سبک های مناسب را در صفحه وب اعمال می کند.

گوش دادن به تغییرات تم: اسکریپت محتوا گوش می دهد برای “APPLY_THEME”پیام‌ها از اسکریپت پس‌زمینه. هنگامی که یک تغییر تم شناسایی می‌شود، سبک‌های صفحه وب را متناسب با آن به‌روزرسانی می‌کند.

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

پیکربندی vite.config.ts برای Building

این بخش نقاط ورودی برای فرآیند ساخت را مشخص می کند. هر نقطه ورودی مربوط به بخش متفاوتی از افزونه Chrome است:

popup: فایل HTML که به عنوان نقطه ورودی پنجره بازشو عمل می کند.
پس زمینه: فایل TypeScript برای اسکریپت پس زمینه.
content: فایل TypeScript برای اسکریپت محتوا.

این بخش نام فایل های خروجی را بر اساس نام نقطه ورودی سفارشی می کند:

اگر نام قطعه “popup” باشد، به صورت “popup.js” خروجی می شود.
اگر نام قطعه “background” باشد، به صورت “background.js” خروجی می شود.
اگر نام قطعه “content” باشد، به صورت “content.js” خروجی می شود.
در غیر این صورت، از قرارداد نامگذاری پیش فرض استفاده می کند [name]js.

import { defineConfig } from “vite”;
import react from “@vitejs/plugin-react”;
import { resolve } from “path”;

// https://vitejs.dev/config/
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
“@”: resolve(__dirname, “src”),
},
},
build: {
rollupOptions: {
input: {
popup: resolve(__dirname, “index.html”),
background: resolve(
__dirname,
“src”,
“scripts”,
“service-worker”,
“background.ts”
),
content: resolve(
__dirname,
“src”,
“scripts”,
“injection”,
“content.ts”
),
},
output: {
entryFileNames: (chunk) => {
if (chunk.name === “popup”) {
return “popup.js”;
}
if (chunk.name === “background”) {
return “background.js”;
}
if (chunk.name === “content”) {
return “content.js”;
}
return “[name].js”;
},
},
},
},
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

ساخت پسوند

برای ساخت افزونه، دستور زیر را اجرا کنید: npm run buildاین دستور Vite را برای کامپایل و بسته بندی کد برنامه افزودنی فعال می کند و فایل های خروجی را در دور پوشه

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

کروم را باز کنید و به chrome://extensions/.
فعال کردن “حالت توسعه دهندهبا جابجایی سوئیچ در گوشه بالا سمت راست.
کلیک کنید روی “بارگیری بدون بسته بندی” دکمه.
انتخاب کنید دور پوشه ای که در فرآیند ساخت ایجاد شده است. این افزونه بدون بسته بندی را در کروم بارگیری می کند و به شما امکان می دهد عملکرد آن را مستقیماً در مرورگر آزمایش کنید.

اکنون، بیایید هر وب سایتی را برای آزمایش باز کنیم (به عنوان مثال: https://www.google.com)، و این نتایج برای google light/dark است:

می توانید کد کامل را در مخزن GitHub من پیدا کنید. به راحتی آن را بررسی کنید، مشارکت کنید یا از آن به عنوان مرجع برای پروژه های خود استفاده کنید.این پروژه در مورد توسعه برنامه افزودنی کروم، ادغام React با APIهای مرورگر و مدیریت پویا CSS به من آموخت. امیدوارم توسعه دهندگان همکار را ترغیب کند تا برنامه های افزودنی Chrome را آزمایش کنند و راه حل های خلاقانه ای برای مشکلات روزمره کشف کنند.

ایجاد یک افزونه کروم با React و TypeScript راهی قوی برای ساخت ابزارهای وب مدرن ارائه می دهد. این راهنما توسعه افزونه‌ای را پوشش می‌دهد که با استفاده از این فناوری‌ها بین حالت‌های تاریک و روشن سوئیچ می‌کند. معماری مبتنی بر مؤلفه React و بررسی نوع TypeScript قابلیت نگهداری و مقیاس‌پذیری کد را افزایش می‌دهد.

ما همچنین پروژه را با استفاده از Vite راه اندازی کردیم و روند توسعه و ساخت را ساده کردیم. پیکربندی vite.config.ts برای بسته بندی صحیح پنجره بازشو، اسکریپت پس زمینه و اسکریپت محتوا ضروری بود.

در حالی که روش معکوس راهی سریع برای پیاده سازی حالت تاریک ارائه می دهد، اما همیشه نتایج کاملی ایجاد نمی کند، زیرا ممکن است برخی از عناصر به درستی معکوس نشوند. با وجود این، در اکثر موارد موثر باقی می ماند.

برای ساخت و آزمایش، از سرور توسعه Vite و رابط مدیریت برنامه افزودنی Chrome استفاده کردیم که امکان اشکال زدایی و تکرار کارآمد را فراهم می کند.

به طور خلاصه، استفاده از React و TypeScript برای توسعه افزونه‌های Chrome، نقاط قوت توسعه وب مدرن را ترکیب می‌کند و افزونه‌های قدرتمندی را ارائه می‌کند که تجربه کاربر را افزایش می‌دهد. به اصلاح تکنیک های خود ادامه دهید تا بر محدودیت هایی مانند وارونگی رنگ غلبه کنید و از فرآیند ایجاد ابزارهای تاثیرگذار لذت ببرید. کد نویسی مبارک!

با تشکر برای خواندن، و کد نویسی مبارک!

my-chrome-extension/
│
├── public/
│   ├── icons/
│   │   ├── icon-16.png
│   │   ├── icon-32.png
│   │   ├── icon-48.png
│   │   └── icon-128.png
│   └── manifest.json
│
├── src/
│   ├── scripts/
│   │   ├── service-worker/
│   │   │   └── background.ts
│   │   ├── injection/
│   │   │   └── content.ts
│   ├── types/
│   │   ├── TMessage.ts
│   │   └── TTheme.ts
│   ├── utils/
│   │   ├── helpers.ts
│   ├── constants/
│   │   └── theme.ts
│   ├── features/
│   │   └── Popup.tsx
│   ├── styles/
│   │   └── styles.css
│   ├── index.html
│   ├── index.tsx
│
├── dist/
│
├── .gitignore
├── package.json
├── tsconfig.json
└── vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { resolve } from "path";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [react()],
    resolve: {
        alias: {
            "@": resolve(__dirname, "src"),
        },
    },
    build: {
        rollupOptions: {
            input: {
                popup: resolve(__dirname, "index.html"),
                background: resolve(
                    __dirname,
                    "src",
                    "scripts",
                    "service-worker",
                    "background.ts"
                ),
                content: resolve(
                    __dirname,
                    "src",
                    "scripts",
                    "injection",
                    "content.ts"
                ),
            },
            output: {
                entryFileNames: (chunk) => {
                    if (chunk.name === "popup") {
                        return "popup.js";
                    }
                    if (chunk.name === "background") {
                        return "background.js";
                    }
                    if (chunk.name === "content") {
                        return "content.js";
                    }
                    return "[name].js";
                },
            },
        },
    },
});