تجهيز إضافة
نظّمها وشاركها
تجهيز إضافة درس مجاني في Lua Academy على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Lua Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Lua Academy 4 دروس في المجموع.
بنية مجلدات الإضافة
إضافة Neovim ليست سوى مجلد موجود ضمن runtimepath. وتتضمن البنية المتعارف عليها مجلدات رئيسية يتعامل معها Neovim بطريقة خاصة.
المجلدات الأساسية هي: lua/ للوحدات، وplugin/ للإعداد الذي يُحمّل تلقائيًا، وftplugin/ لبرامج نوع الملف، وdoc/ للمساعدة، وafter/ للتجاوزات المتأخرة.
-- myplugin/
-- lua/myplugin/init.lua
-- plugin/myplugin.lua
-- doc/myplugin.txtمجلد lua/
يمكن الوصول إلى الملفات الموجودة ضمن lua/ باستخدام require. ويُحمّل الملف الموجود في lua/myplugin/init.lua باستخدام require('myplugin').
يتوافق التداخل في المجلدات مع المسارات المنقوطة: إذ يصبح lua/myplugin/config.lua هو require('myplugin.config'). وهكذا تكشف الإضافات عن مساحة أسماء عامة ومنظمة.
-- in lua/myplugin/init.lua
local M = {}
function M.hello() print('hi') end
return Mإرجاع جدول الوحدة
يعرّف نمط الوحدات المتّبع جدولًا محليًا باسم M، ثم يضيف إليه الدوال ويعيده. بعد ذلك يمكن للجهات المستدعية الوصول إلى require('myplugin').hello().
اجعل الدوال المساعدة الداخلية محلية عادية، حتى لا تكون الواجهة العامة سوى الجزء المقصود. ويشبه ذلك تغليف الوحدات في الأنظمة البرمجية الأخرى.
local M = {}
local function private() end
function M.run() private() end
return Mاصطلاح setup()
توفّر معظم الإضافات دالة باسم setup(opts). تدمج هذه الدالة خيارات المستخدم مع الإعدادات الافتراضية، وتنفذ مهام التهيئة مثل إنشاء الأوامر والأوامر التلقائية.
استخدم vim.tbl_deep_extend('force', defaults, opts or {}) حتى تستمر الإعدادات الافتراضية كلها عند تقديم المستخدم جزءًا فقط من الإعدادات.
local M = {}
local defaults = { width = 40 }
function M.setup(opts)
M.config = vim.tbl_deep_extend('force', defaults, opts or {})
end
return Mمجلد plugin/
تُشغّل البرامج النصية الموجودة في plugin/ تلقائيًا عند بدء تشغيل Neovim، بعد بناء runtimepath. احرص على أن تكون صغيرة.
من المهام الشائعة تسجيل الأوامر أو إضافة حارس لتحميل الوحدات الثقيلة بطريقة مؤجلة. تجنب تنفيذ العمليات المكلفة هنا؛ وأجّلها إلى setup أو الأوامر التلقائية للحفاظ على سرعة بدء التشغيل.
-- in plugin/myplugin.lua
if vim.g.loaded_myplugin then return end
vim.g.loaded_myplugin = trueحواجز التحميل
يمنع حاجز التحميل تكرار التهيئة إذا جرى تحميل الملف المصدر مرتين. عيّن علامة vim.g.loaded_* واخرج مبكرًا عند إعادة الدخول.
هذا أمر أساسي لأن مديري الإضافات و:runtime قد يعيدان تحميل الملفات المصدر، كما أن تكرار الأوامر أو الأوامر التلقائية يسبب أخطاء دقيقة يصعب اكتشافها.
if vim.g.loaded_myplugin == 1 then return end
vim.g.loaded_myplugin = 1التحميل المؤجل
تعني سرعة بدء التشغيل تحميل الشيفرة عند الحاجة فقط. سجّل أمرًا خفيفًا في plugin/ يتطلب الوحدة الثقيلة عند أول استخدام.
يطبّق مديرو الإضافات مثل lazy.nvim هذا الأسلوب رسميًا باستخدام محفزات cmd وft وkeys، بحيث لا تُلمس وحدتك حتى استدعائها.
vim.api.nvim_create_user_command('MyStart', function()
require('myplugin').run()
end, {})runtimepath وpackpath
يكتشف Neovim الإضافات من خلال فحص runtimepath. ويحمّل نظام الحزم الأصلي المجلدات الموجودة ضمن pack/*/start/ تلقائيًا، بينما يحمّل pack/*/opt/ عند الطلب عبر :packadd.
يعتمد معظم المستخدمين على مدير للإضافات، لكن فهم runtimepath يوضح كيفية العثور على مجلداتك.
print(vim.o.runtimepath:sub(1, 60))
-- :packadd loads an opt plugin manuallyفحوصات السلامة
وفّر ملفًا باسم lua/myplugin/health.lua يحتوي على دالة check، حتى يتمكن المستخدمون من تشغيل :checkhealth myplugin. أبلغ عن الحالة باستخدام واجهة برمجة التطبيقات vim.health.
استخدم vim.health.start وvim.health.ok وvim.health.warn وvim.health.error لعرض التبعيات المفقودة بوضوح.
local M = {}
function M.check()
vim.health.start('myplugin')
vim.health.ok('all good')
end
return Mالتوثيق والوسوم
أرفق ملف مساعدة باسم doc/myplugin.txt. شغّل :helptags doc/، أو اترك المهمة للمدير، لإنشاء فهرس الوسوم حتى يعمل الأمر :help myplugin.
يسرد التوثيق الجيد الأوامر وخيارات setup وخرائط المفاتيح الافتراضية، مما يجعل العثور على إضافتك ممكنًا من داخل Neovim.
-- generate tags from the doc directory
vim.cmd('helptags ' .. vim.fn.expand('%:p:h'))إدارة الإصدارات والنشر
استضف الإضافة في مستودع git؛ إذ يثبّتها المستخدمون باستخدام المسار owner/repo. أنشئ وسومًا دلالية للإصدارات حتى يتمكن المديرون من تثبيت إصدارات محددة.
ضمّن ملف README يحتوي على مقاطع تثبيت لمديري الإضافات الشائعين، وترخيصًا، ومثالًا بسيطًا على الإعداد لتسهيل اعتماد الإضافة.
-- lazy.nvim spec
-- { 'owner/myplugin', config = function()
-- require('myplugin').setup({})
-- end }مراجعة سريعة
تأكد من فهمك لتغليف الإضافات.
مراجعة: تغليف إضافة
الإضافة هي مجلد ضمن runtimepath يحتوي على وحدات lua/، وبرنامج نصي plugin/ يُشغّل تلقائيًا، وملفات اختيارية مثل doc/ وftplugin/ وملفات فحوصات السلامة.
أعد جداول الوحدات، ووفّر دالة setup تدمج الإعدادات الافتراضية، واحمِ الإضافة من التحميل المزدوج، وحمّل الشيفرة الثقيلة مؤجلًا، ووثّقها باستخدام helptags، وانشرها عبر git مع وسوم إصدارات دلالية.
تعلم Lua مع معلم ذكاء اصطناعي — مجانًا
اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.
- الدورات
- 40
- الدروس
- 159
الأسئلة الشائعة
هل درس «تجهيز إضافة» مجاني؟
نعم — نص درس «تجهيز إضافة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Lua Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Lua Academy 4 دروس في المجموع.
ماذا ستتعلم في «تجهيز إضافة»؟
نظّمها وشاركها تتمرن على Lua Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Lua Academy؟
لا تُشترط خبرة سابقة. Lua Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.
كم من الوقت يستغرق درس «تجهيز إضافة»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Lua Academy هذا؟
نعم. كل درس في Lua Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.