شخصی‌سازی پیشرفته با Lua: رویدادها، اسکریپت‌نویسی و انیمیشن‌های سفارشی در Hyprland

آخرین به‌روزرسانی: ۲۲ آبان ۱۴۰۵ · نسخهٔ ۲ · ۵ بازدید

این مقاله مستندات رسمی Arch Linux نیست؛ برای موارد حساس به ArchWiki مراجعه کنید.

شخصی‌سازی پیشرفته با Lua: رویدادها، اسکریپت‌نویسی و انیمیشن‌های سفارشی در Hyprland

محیط Hyprland شخصی‌سازی‌شده با اسکریپت‌های Lua و انیمیشن‌های سفارشی

در مقالات پیشین از آرچی ها قوانین، دیسپچرها و گروه‌بندی پنجره‌ها را بررسی کردیم. اکنون به لایه‌ای می‌رسیم که Hyprland را از یک کامپوزیتور معمولی متمایز می‌کند: قابلیت اسکریپت‌نویسی با Lua. از نسخهٔ 0.55 به بعد، Hyprland نه‌فقط پیکربندی، بلکه منطق پویا را نیز در اختیار شما قرار می‌دهد. با توابع utility، رویدادها (events)، تایمرها و انیمیشن‌های سفارشی، می‌توانید دسکتاپ خود را دقیقاً مطابق رفتار و سلیقهٔ خود برنامه‌ریزی کنید.

---

توابع کمکی Lua (Lua Utilities)

Hyprland مجموعه‌ای از توابع آماده را در اختیار شما قرار می‌دهد که دسترسی به وضعیت کامپوزیتور و تغییر آن را بسیار ساده می‌کنند.

توابع دسترسی به وضعیت (Getters)

| تابع | خروجی |
| :--- | :--- |
| hl.get_active_window() | پنجرهٔ فعال |
| hl.get_windows() | لیست تمام پنجره‌ها |
| hl.get_workspaces() | لیست ورک‌اسپیس‌ها |
| hl.get_active_workspace() | ورک‌اسپیس فعال |
| hl.get_monitors({ all = true }) | لیست مانیتورها |
| hl.get_active_monitor() | مانیتور فعال |
| hl.get_cursor_pos() | موقعیت فعلی نشانگر ماوس |
| hl.get_config("general.layout") | مقدار فعلی یک گزینهٔ پیکربندی |
| hl.version() | نسخهٔ Hyprland |
| hl.get_loaded_plugins() | پلاگین‌های بارگذاری‌شده |
| hl.is_key_down("SUPER") | بررسی فشرده بودن یک کلید |

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

مثال: بایندی که رفتار شرطی دارد

-- اگر پنجرهٔ فعال htop باشد، فقط شناور شود؛ در غیر این صورت حالت شناور toggle شود
hl.bind("SUPER + X", function()
    local w = hl.get_active_window()
    if w ~= nil and w.***** == "htop" then
        hl.dispatch(hl.dsp.window.float({ action = "set" }))
    else
        hl.dispatch(hl.dsp.window.float({ action = "toggle" }))
    end
end)

اجرای دستور به‌صورت آсинхрон

تابع hl.exec_cmd() یک فرآیند را به‌صورت آсинхрон (asynchronous) اجرا می‌کند؛ بنابراین نیازی به افزودن & یا disown در انتهای دستور نیست.

hl.exec_cmd("kitty")

---

رویدادها (Events): واکنش به تغییرات کامپوزیتور

با تابع hl.on(event, callback) می‌توانید برای رویدادهای مختلف Hyprland پاسخ (callback) تعریف کنید. این قابلیت به شما اجازه می‌دهد اسکریپت‌هایی بنویسید که به‌طور خودکار به تغییرات دسکتاپ واکنش نشان دهند.

ساختار پایه

hl.on("window.active", function(w)
    hl.notification.create({
        text = "Window focused: " .. w.*****,
        timeout = 3000,
        icon = "ok",
    })
end)

رویدادهای پرکاربرد

مثال: اجرای خودکار برنامه‌ها با `hyprland.start`

همان‌طور که در مقالهٔ اکوسیستم دیدیم، استفاده از hl.on("hyprland.start", ...) از اجرای تکراری برنامه‌ها در زمان reload پیکربندی جلوگیری می‌کند.

hl.on("hyprland.start", function()
    hl.exec_cmd("waybar")
    hl.exec_cmd("hyprpaper")
    hl.exec_cmd("hypridle")
end)

---

تغییر پویا (Dynamic) پیکربندی

یکی از قدرتمندترین قابلیت‌های Lua این است که می‌توانید گزینه‌های پیکربندی را در زمان اجرا و بدون نیاز به بارگذاری مجدد، تغییر دهید.

خواندن مقدار فعلی

local gaps = hl.get_config("general.gaps_in")
-- خروجی: table { top = 3, left = 3, right = 3, bottom = 3 }

تغییر مقدار با یک بایند

-- تغییر gaps_in بین 0 و 3 با یک کلید
hl.bind("SUPER + SHIFT + G", function()
    if hl.get_config("general.gaps_in").top == 3 then
        hl.config({ ["general.gaps_in"] = 0 })
    else
        hl.config({ ["general.gaps_in"] = 3 })
    end
end)

هشدار دربارهٔ Prop Refresh

Hyprland به‌طور خودکار یک رویداد prop_refresh را در انتهای هر تابع Lua زمان‌بندی می‌کند تا از به‌روزرسانی‌های تکراری جلوگیری کند. این بدان معناست که اگر در همان تابع بلافاصله پس از تغییر یک گزینه، مقدار جدید را بخوانید، ممکن است مقدار قدیمی را دریافت کنید. برای اجرای فوری، از hl.exec_scheduled_prop_refresh_immediately() استفاده کنید، اما توجه داشته باشید که استفادهٔ بیش از حد از آن می‌تواند باعث کندی شود.

---

تایمرها (Timers)

با hl.timer() می‌توانید تایمرهای تکرارشونده یا یک‌باره ایجاد کنید. این قابلیت برای کارهایی مانند به‌روزرسانی دوره‌ای وضعیت، اجرای زمان‌بندی‌شدهٔ دستورات یا مدیریت چرخه‌های UI بسیار مفید است.

-- ایجاد یک تایمر که هر ۱ ثانیه اجرا می‌شود
local myTimer = hl.timer(function()
    print("hello from timer")
end, { timeout = 1000, type = "repeat" })

-- غیرفعال کردن تایمر
myTimer:set_enabled(false)

-- تغییر وضعیت تایمر با یک کلید
hl.bind("SUPER + T", function()
    myTimer:set_enabled(not myTimer:is_enabled())
end)

---

متغیرهای محیطی (Environment Variables)

Hyprland با تابع hl.env() به شما اجازه می‌دهد متغیرهای محیطی را پیش از راه‌اندازی سرور نمایش تنظیم کنید. این کار برای پیکربندی بک‌اندهای Wayland، تم‌ها و درایورهای گرافیکی ضروری است.

متغیرهای مهم Hyprland

hl.env("HYPRLAND_TRACE", "1")          -- لاگ‌های پرجزئیات
hl.env("HYPRLAND_NO_RT", "1")          -- غیرفعال کردن اولویت realtime
hl.env("HYPRLAND_NO_SD_NOTIFY", "1")   -- غیرفعال کردن sd_notify در systemd

متغیرهای Aquamarine (بک‌اند رندر)

hl.env("AQ_TRACE", "1")                     -- لاگ پرجزئیات
hl.env("AQ_DRM_DEVICES", "/dev/dri/card1:/dev/dri/card0")  -- انتخاب GPU
hl.env("AQ_NO_MODIFIERS", "1")              -- رفع مشکلات برخی مانیتورها

متغیرهای Toolkit (GTK، Qt، SDL)

hl.env("GDK_BACKEND", "wayland,x11,*")      -- GTK: Wayland اولویت
hl.env("QT_QPA_PLATFORM", "wayland;xcb")     -- Qt: Wayland اولویت
hl.env("SDL_VIDEODRIVER", "wayland")         -- SDL2: Wayland
hl.env("CLUTTER_BACKEND", "wayland")         -- Clutter: Wayland

متغیرهای NVIDIA

hl.env("GBM_BACKEND", "nvidia-drm")
hl.env("__GLX_VENDOR_LIBRARY_NAME", "nvidia")
hl.env("LIBVA_DRIVER_NAME", "nvidia")        -- شتاب سخت‌افزاری ویدیو

متغیرهای تم

hl.env("GTK_THEME", "Nord")
hl.env("XCURSOR_THEME", "Bibata-Modern-Classic")
hl.env("XCURSOR_SIZE", "24")

نکتهٔ مهم برای کاربران uwsm: اگر از uwsm استفاده می‌کنید، متغیرهای محیطی را به‌جای hyprland.lua در ~/.config/uwsm/env و ~/.config/uwsm/env-hyprland قرار دهید.

---

ژست‌های تاچ‌پد (Gestures)

Hyprland از ژست‌های ۱:۱ برای تاچ‌پد پشتیبانی می‌کند. با تابع hl.gesture() می‌توانید حرکات چند انگشتی را به اقدامات مختلف متصل کنید.

ساختار پایه

hl.gesture({
    fingers = 3,
    direction = "horizontal",
    action = "workspace",
})

جهت‌های پشتیبانی‌شده

اکشن‌های پشتیبانی‌شده

مثال‌های کاربردی

تغییر ورک‌اسپیس با کشیدن سه انگشت:

hl.gesture({
    fingers = 3,
    direction = "horizontal",
    action = "workspace",
})

بستن پنجره با کشیدن سه انگشت به پایین (همراه با ALT):

hl.gesture({
    fingers = 3,
    direction = "down",
    mods = "ALT",
    action = "close",
})

تمام‌صفحه کردن با کشیدن سه انگشت به بالا (همراه با SUPER و سرعت ۱.۵ برابر):

hl.gesture({
    fingers = 3,
    direction = "up",
    mods = "SUPER",
    scale = 1.5,
    action = "fullscreen",
})

بزرگ‌نمایی زنده با پینچ دو انگشتی:

hl.gesture({
    fingers = 2,
    direction = "pinch",
    action = "cursorZoom",
    zoom_level = 1,
    mode = "live",
})

اجرای تابع Lua سفارشی با ژست

می‌توانید یک تابع Lua (لامبدا یا نام‌دار) را به‌عنوان اکشن ژست تعریف کنید.

hl.gesture({
    fingers = 3,
    direction = "up",
    action = function()
        hl.notification.create({
            text = "ژست سه انگشتی به بالا!",
            timeout = 5000,
            icon = "ok",
        })
    end,
})

---

انیمیشن‌ها و منحنی‌های سفارشی (Animations & Curves)

Hyprland از یک سیستم انیمیشن درختی استفاده می‌کند که در آن هر انیمیشن می‌تواند مقادیر خود را از والدش به ارث ببرد. با hl.animation() و hl.curve() می‌توانید ظاهر و احساس دسکتاپ خود را کاملاً سفارشی کنید.

تعریف انیمیشن

hl.animation({
    leaf = "workspaces",       -- شاخهٔ انیمیشن
    enabled = true,
    speed = 8,                 -- واحد ds (1ds = 100ms)
    curve = "my_bezier",       -- نام منحنی
    style = "slide",           -- سبک (اختیاری)
})

شاخه‌های مهم انیمیشن

تعریف منحنی بزیه (Bezier)

hl.curve("my_bezier", {
    type = "bezier",
    points = { {0.5, 0.9}, {0.1, 1.1} },
})

برای طراحی منحنی خودتان می‌توانید از cssportal.com یا easings.net استفاده کنید.

تعریف منحنی فنری (Spring)

منحنی فنری (Spring) رفتار طبیعی‌تری نسبت به بزیه دارد و در سیستم‌های Apple رایج است. پارامترها عبارت‌اند از mass (جرم)، stiffness (سختی) و dampening (میرایی). توصیه می‌شود mass را روی 1 نگه دارید و فقط دو پارامتر دیگر را تنظیم کنید.

hl.curve("my_spring", {
    type = "spring",
    mass = 1,
    stiffness = 70,
    dampening = 10,
})

مثال: انیمیشن با منحنی سفارشی

hl.animation({
    leaf = "windows",
    enabled = true,
    speed = 10,
    curve = "my_spring",
    style = "popin 80%",
})

هشدار دربارهٔ `borderangle` با سبک `loop`

استفاده از سبک loop برای borderangle باعث می‌شود Hyprland مدام فریم‌های جدیدی با نرخ نوسازی مانیتور رندر کند که می‌تواند به CPU/GPU فشار آورده و باتری را مصرف کند. این اتفاق حتی در صورت غیرفعال بودن انیمیشن‌ها نیز رخ می‌دهد.

---

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

Lua Utilities: https://wiki.hypr.land/configuring/core/advanced-configuration/lua-utilities/
Lua Events: https://wiki.hypr.land/configuring/core/advanced-configuration/lua-events/
Environment Variables: https://wiki.hypr.land/Configuring/Advanced-and-Cool/Environment-variables/
Gestures: https://wiki.hypr.land/Configuring/Advanced-and-Cool/Gestures/
Animations: https://wiki.hypr.land/Configuring/Advanced-and-Cool/Animations/
Core Configuration (Lua Style): https://wiki.hypr.land/configuring/core/

مطالب مرتبط در سایت آرچی ها

ویکی سایت آرچی ها: https://archiha.ir/wiki
صفحه اصلی سایت آرچی ها: https://archiha.ir

---

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

شخصی‌سازی پیشرفته با Lua: رویدادها، اسکریپت‌نویسی و انیمیشن‌های سفارشی در Hyprland