سیستم پلاگین در Hyprland: راهنمای کامل hyprpm

سیستم پلاگین در Hyprland: راهنمای کامل hyprpm

Hyprland برخلاف بسیاری از کامپوزیتورهای Wayland، از یک سیستم پلاگین بومی پشتیبانی می‌کند. این پلاگین‌ها که به زبان C++ نوشته می‌شوند، به صورت مستقیم درون فرآیند Hyprland اجرا می‌شوند و می‌توانند قابلیت‌های جدیدی مانند چیدمان‌های جایگزین، مدیریت پیشرفته‌ی ورک‌اسپیس، افکت‌های بصری و میانبرهای هوشمند را به کامپوزیتور اضافه کنند. مدیریت این پلاگین‌ها از طریق ابزار رسمی hyprpm انجام می‌شود که نصب، فعال‌سازی و به‌روزرسانی آن‌ها را بسیار ساده می‌کند.

---

هشدارهای امنیتی (بسیار مهم)

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

• همیشه سورس‌کد پلاگین را بررسی کنید و از منبع آن مطمئن شوید.
• هرگز فایل‌های .so ناشناس را که از افراد دیگر دریافت می‌کنید، بارگذاری نکنید.
• فقط از مخازن رسمی یا شناخته‌شده (مانند hyprwm/hyprland-plugins) پلاگین نصب کنید.

---

نصب پیش‌نیازها

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

sudo pacman -S cpio cmake git meson gcc

نکته: اگر از سیستم مدیریت مجوزها (Permission Management) در Hyprland استفاده می‌کنید، باید به hyprpm اجازهٔ بارگذاری پلاگین بدهید. خط زیر را به پیکربندی Lua خود اضافه کنید تا هر بار پنجرهٔ درخواست مجوز نمایش داده نشود:

hl.permission("/usr/(bin|local/bin)/hyprpm", "plugin", "allow")

---

کار با hyprpm (مدیر پلاگین Hyprland)

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

افزودن یک مخزن پلاگین

ابتدا باید یک مخزن (Repository) حاوی پلاگین‌ها را اضافه کنید. مخزن رسمی Hyprland شامل چند پلاگین پایه است:

hyprpm add https://github.com/hyprwm/hyprland-plugins

پس از اجرای این دستور، hyprpm سورس‌کد را دریافت و پلاگین‌ها را کامپایل می‌کند. این فرآیند ممکن است چند دقیقه طول بکشد.

مشاهدهٔ پلاگین‌های موجود

hyprpm list

این دستور لیست تمام پلاگین‌های نصب‌شده از مخازن اضافه‌شده را نمایش می‌دهد.

فعال‌سازی و غیرفعال‌سازی پلاگین

# فعال‌سازی یک پلاگین
hyprpm enable <plugin-name>

# غیرفعال‌سازی یک پلاگین
hyprpm disable <plugin-name>

بارگذاری پلاگین‌ها در Hyprland

پس از فعال‌سازی، باید پلاگین‌ها را در نشست فعلی Hyprland بارگذاری کنید:

hyprpm reload

برای اینکه پلاگین‌ها در هر بار راه‌اندازی به صورت خودکار بارگذاری شوند، این خط را به بخش استارتاپ پیکربندی Lua خود اضافه کنید (مثلاً در فایل autostart.lua):

hl.exec_cmd("hyprpm reload -n")

فلگ -n باعث می‌شود یک اعلان (Notification) پس از بارگذاری موفق پلاگین نمایش داده شود.

به‌روزرسانی پلاگین‌ها

hyprpm update

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

مشاهدهٔ پلاگین‌های بارگذاری‌شده در نشست فعلی

hyprctl plugin list

این دستور (توجه کنید که hyprctl است، نه hyprpm) لیست پلاگین‌هایی را که در حال حاضر در Hyprland فعال هستند، نشان می‌دهد.

---

پلاگین‌های پیشنهادی

Hyprland هیچ پلاگین «پیش‌فرض» یا از پیش نصب‌شده‌ای ندارد و باید خودتان پلاگین موردنظر را پیدا و نصب کنید. در ادامه چند پلاگین محبوب و پرکاربرد معرفی می‌شوند:

۱. hy3 — چیدمان دستی شبیه i3/Sway

این پلاگین قابلیت کاشی‌کاری دستی (Manual Tiling) را به Hyprland اضافه می‌کند و به شما اجازه می‌دهد جهت تقسیم پنجره‌ها (افقی یا عمودی) را به صورت دستی کنترل کنید. همچنین یک حالت «کاشی‌کاری خودکار» دارد که بین تقسیم افقی و عمودی جابه‌جا می‌شود.

نصب:

hyprpm add https://github.com/outfoxxed/hy3
hyprpm enable hy3
hyprpm reload

فعال‌سازی چیدمان hy3 در پیکربندی Lua:

hl.config({
    general = {
        layout = "hy3",
    }
})

۲. hyprbars — بازگرداندن نوار عنوان پنجره‌ها

بسیاری از مدیرهای پنجره مدرن نوار عنوان (***** Bar) را حذف کرده‌اند. hyprbars این ویژگی سنتی را با گزینه‌های سفارشی‌سازی کامل (ارتفاع، رنگ، فونت و…) به Hyprland بازمی‌گرداند.

نصب (از مخزن رسمی):

hyprpm add https://github.com/hyprwm/hyprland-plugins
hyprpm enable hyprbars
hyprpm reload

۳. split-monitor-workspaces — ورک‌اسپیس‌های مجزا برای هر مانیتور

در حالت پیش‌فرض، Hyprland یک مجموعه ورک‌اسپیس مشترک بین همهٔ مانیتورها دارد. این پلاگین به هر مانیتور مجموعهٔ ورک‌اسپیس مستقل خودش را می‌دهد (رفتاری شبیه AwesomeWM). این پلاگین به زبان Lua نوشته شده و با پیکربندی Lua هماهنگی کامل دارد.

نصب:

hyprpm add https://github.com/Duckonaut/split-monitor-workspaces
hyprpm enable split-monitor-workspaces
hyprpm reload

پیکربندی نمونه (Lua):

local smw = require("split-monitor-workspaces")

smw.setup({
    workspace_count = 5, -- تعداد ورک‌اسپیس‌های هر مانیتور
    mainMod = "SUPER",
})

۴. hyprspace — نمای کلی ورک‌اسپیس‌ها (Workspace Overview)

این پلاگین یک نمای کلی (Overview) شبیه به GNOME یا macOS Mission Control به Hyprland اضافه می‌کند که به شما اجازه می‌دهد تمام ورک‌اسپیس‌ها و پنجره‌ها را یکجا ببینید.

نصب:

hyprpm add https://github.com/KZDKM/Hyprspace
hyprpm enable hyprspace
hyprpm reload

۵. hyprtasking — مدیریت پیشرفته‌ی ورک‌اسپیس

این پلاگین مجموعه‌ای از قابلیت‌های پیشرفته برای مدیریت ورک‌اسپیس‌ها (مانند ورک‌اسپیس‌های پایدار، ورک‌اسپیس‌های نام‌گذاری‌شده و…) را فراهم می‌کند.

۶. hyprland-easymotion — ناوبری سریع با کیبورد

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

---

استفاده از پلاگین‌ها در پیکربندی Lua

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

if hl.plugin.hy3 ~= nil then
    -- پیکربندی مخصوص پلاگین hy3
    hl.config({
        plugin = {
            hy3 = {
                -- تنظیمات دلخواه
            }
        }
    })
end

این الگو (بررسی ~= nil) از بروز خطا در زمان راه‌اندازی، پیش از بارگذاری کامل پلاگین، جلوگیری می‌کند.

---

عیب‌یابی پلاگین‌ها

Hyprland کرش می‌کند

اگر پس از فعال‌سازی یک پلاگین، Hyprland کرش کرد یا رفتار عجیبی داشت، احتمالاً آن پلاگین با نسخهٔ Hyprland شما سازگار نیست. با غیرفعال کردن آن مشکل را برطرف کنید:

hyprpm disable <plugin-name>
hyprpm reload

پلاگین بارگذاری نمی‌شود

• مطمئن شوید که پیش‌نیازهای کامپایل (cmake، meson، gcc و…) نصب هستند.
• بررسی کنید که مخزن پلاگین به درستی اضافه شده باشد: hyprpm list
• پس از هر به‌روزرسانی Hyprland، حتماً hyprpm update را اجرا کنید تا پلاگین‌ها با نسخهٔ جدید سازگار شوند.

خطای مجوز (Permission)

اگر با خطای عدم دسترسی مواجه شدید، خط hl.permission(...) را که در بخش پیش‌نیازها ذکر شد به پیکربندی Lua اضافه کنید.

مشاهدهٔ پلاگین‌های بارگذاری‌شده

hyprctl plugin list

---

منابع و لینک‌های مرتبط

• ویکی رسمی Hyprland — استفاده از پلاگین‌ها: https://wiki.hypr.land/Plugins/Using-Plugins/
• فهرست پلاگین‌های معرفی‌شده: https://hypr.land/plugins/
• مخزن رسمی پلاگین‌های Hyprland: https://github.com/hyprwm/hyprland-plugins
• پلاگین hy3: https://github.com/outfoxxed/hy3
• پلاگین split-monitor-workspaces: https://github.com/Duckonaut/split-monitor-workspaces
• پلاگین hyprspace: https://github.com/KZDKM/Hyprspace
• مجموعهٔ Awesome-Hyprland (منابع جامعه): https://github.com/hyprland-community/awesome-hyprland

---

این مقاله بر اساس مستندات رسمی Hyprland (نسخه‌های 0.55 تا 0.56) و منابع جامعه گردآوری شده و برای جامعهٔ ARCHIHA تهیه شده است. آخرین به‌روزرسانی: نوامبر 2026.