Lua Academy · درس

واجهة Lua البرمجية في Neovim

تعرّف على كيفية ربط الإضافات

واجهة Lua البرمجية في Neovim درس مجاني في Lua Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Lua Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Lua Academy 4 دروس في المجموع.

لماذا تُستخدم Lua في Neovim

يضمّن Neovim بيئة تشغيل LuaJIT، ما يجعل Lua لغة البرمجة النصية الأصلية إلى جانب Vimscript. ويفضّل مؤلفو الإضافات Lua بسبب سرعتها، وهياكل البيانات الحقيقية فيها، ونظام الوحدات النظيف.

الجدول العام vim هو البوابة إلى كل شيء: حالة المحرر، وواجهة API، والخيارات، ومساعدات المكتبة القياسية. ويُعد إتقانه أساس تطوير الإضافات الحديثة.

print(vim.inspect(vim.version()))

طبقة vim.api

تكشف vim.api واجهة API البعيدة منخفضة المستوى: كل دالة مسبوقة بـ nvim_. وهذه هي الاستدعاءات نفسها التي يستخدمها العملاء الخارجيون عبر RPC، لكنها تعمل فورًا داخل العملية.

تمنحكم دوال مثل nvim_get_current_buf وnvim_buf_set_lines وnvim_command تحكمًا دقيقًا. وهي مستقرة وموثقة جيدًا، وتشكل العمود الفقري للإضافات الجادة.

local buf = vim.api.nvim_get_current_buf()
local name = vim.api.nvim_buf_get_name(buf)
print(name)

vim.fn — استدعاء دوال Vimscript

تصل vim.fn بدوال Vimscript المضمنة. وكل ما يمكن استدعاؤه في Vimscript، مثل expand() أو fnamemodify()، يمكن الوصول إليه عبر vim.fn.expand(...).

وهذا مفيد للغاية عندما لا تتوفر واجهة API أصلية بعد. إذ تُحوّل الوسائط والقيم المعادة تلقائيًا بين أنواع Lua وVimscript.

local path = vim.fn.expand('%:p')
local tail = vim.fn.fnamemodify(path, ':t')
print(tail)

الخيارات: vim.o وvim.bo وvim.wo

تُضبط الخيارات عبر الجداول الوصفية. يستهدف vim.o الخيارات العامة، وvim.bo الخيارات المحلية للمخزن المؤقت، وvim.wo الخيارات المحلية للنافذة.

ولا يتطلب التعيين أكثر من كتابة حقل. وهذا يحل محل استدعاءات nvim_set_option المطوّلة، ويجعل كود الإعداد أكثر طبيعية عند قراءته.

vim.o.number = true
vim.bo.shiftwidth = 2
vim.wo.wrap = false

vim.g والمتغيرات العامة

يقرأ vim.g متغيرات Vim العامة ويكتبها. وتعرض الإضافات عادةً مفاتيح تبديل الإعدادات هنا، مثل vim.g.myplugin_enabled.

تُعيد قراءة متغير غير مُعيّن nil، لذا احرصوا على استخدام قيم افتراضية. وتتوافر أيضًا الصيغتان المحليتان للمخزن المؤقت والنافذة، وهما vim.b وvim.w.

vim.g.mapleader = ' '
local enabled = vim.g.myplugin_enabled or false
print(enabled)

الإشعارات وعرض الرسائل

استخدموا vim.notify لإظهار الرسائل للمستخدم. وهي تقبل سلسلة رسالة ومستوى سجل اختياريًا من vim.log.levels.

يمكن لمديري الإضافات مثل noice أو notify اعتراض هذه الرسائل لعرضها في واجهة مستخدم أفضل. ويفضَّل استخدام vim.notify بدلًا من print الخام للمخرجات الموجهة إلى المستخدم.

vim.notify('Plugin loaded', vim.log.levels.INFO)
vim.notify('Missing config', vim.log.levels.WARN)

الجدولة باستخدام vim.schedule

تُحظر بعض استدعاءات API في سياقات الأحداث السريعة، مثل استدعائها داخل بعض دوال الاستدعاء. تؤجل vim.schedule دالةً إلى الحلقة الرئيسية، حيث تكون واجهة API الكاملة آمنة.

وهذا يتجنب أخطاء E5560 المرعبة عند تعديل المخازن المؤقتة من سياقات غير متزامنة أو سياقات الأوامر التلقائية.

vim.schedule(function()
  vim.api.nvim_buf_set_lines(0, 0, 0, false, {'Hello'})
end)

الأوامر التلقائية في Lua

تسجّل nvim_create_autocmd معالجات الأحداث. اجمعوا هذه المعالجات باستخدام nvim_create_augroup واضبطوا clear = true لتجنب التكرارات عند إعادة التحميل.

تتلقى دالة الاستدعاء جدول حدث يحتوي على حقول مثل buf وmatch، ما يمنح المعالج سياقًا دقيقًا.

local grp = vim.api.nvim_create_augroup('MyGrp', { clear = true })
vim.api.nvim_create_autocmd('BufWritePost', {
  group = grp,
  pattern = '*.lua',
  callback = function(ev) print('saved ' .. ev.file) end,
})

vim.tbl ومساعدات السلاسل النصية

توفّر Neovim مكتبة قياسية غنية. وتغطي vim.tbl_extend وvim.tbl_keys وvim.split العمليات الشائعة على الجداول والسلاسل النصية.

تُعد vim.tbl_deep_extend('force', defaults, opts) الطريقة المعتمدة لدمج إعدادات المستخدم فوق الإعدادات الافتراضية للإضافة.

local defaults = { width = 40, border = 'single' }
local opts = { width = 60 }
local cfg = vim.tbl_deep_extend('force', defaults, opts)
print(cfg.width, cfg.border)

vim.inspect لتصحيح الأخطاء

تحوّل vim.inspect أي قيمة Lua إلى سلسلة نصية سهلة القراءة، بما في ذلك الجداول المتداخلة. وهي أسرع طريقة لفهم أشكال القيم المعادة من API.

استخدموها مع :lua print(vim.inspect(...)) أو :lua= expr في الإصدارات الحديثة من Neovim لفحص القيم سريعًا أثناء التطوير.

local info = vim.api.nvim_get_mode()
print(vim.inspect(info))

المفاضلة بين API وVimscript

فضّلوا vim.api للعمليات المنظمة والمستقرة. وانتقلوا إلى vim.fn أو vim.cmd عندما لا تتوفر دالة أصلية.

تشغّل vim.cmd أوامر Ex كسلاسل نصية، وتفيد في العمليات السريعة مثل vim.cmd('highlight ...')، لكنها أقل قابلية للفحص من استدعاءات API المعيّنة الأنواع.

vim.cmd('syntax on')
vim.cmd.colorscheme('habamax')

اختبار سريع

اختبروا فهمكم لواجهة Lua البرمجية في Neovim.

خلاصة: واجهة Lua البرمجية

تعرفون الآن الواجهات الأساسية: vim.api لواجهة API الأصلية المعيّنة الأنواع، وvim.fn لدوال Vimscript، وvim.cmd لأوامر Ex.

تُدار الخيارات عبر vim.o/bo/wo، والمتغيرات عبر vim.g/b/w، وتكمل أدوات مثل vim.tbl_deep_extend وvim.notify وvim.schedule مجموعة أدوات مؤلف الإضافات.

الأسئلة الشائعة

هل درس «واجهة Lua البرمجية في Neovim» مجاني؟

نعم — نص درس «واجهة Lua البرمجية في Neovim» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Lua Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Lua Academy 4 دروس في المجموع.

ماذا ستتعلم في «واجهة Lua البرمجية في Neovim»؟

تعرّف على كيفية ربط الإضافات تتمرن على Lua Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Lua Academy؟

لا تُشترط خبرة سابقة. Lua Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «واجهة Lua البرمجية في Neovim»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Lua Academy هذا؟

نعم. كل درس في Lua Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Lua Academy