0Pricing
Lua Academy · Lekcja

Pakowanie pluginu

Nada Pan/Pani pluginowi strukturę i udostępni go innym.

Pakowanie pluginu to bezpłatna lekcja Lua Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Lua Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Lua Academy zawiera 4 lekcji w sumie.

Układ katalogów wtyczki

Wtyczka Neovim to po prostu katalog znajdujący się na runtimepath. Konwencjonalny układ zawiera katalogi najwyższego poziomu, które Neovim traktuje w specjalny sposób.

Najważniejsze katalogi to: lua/ na moduły, plugin/ na automatycznie ładowaną konfigurację, ftplugin/ na skrypty typów plików, doc/ na pomoc oraz after/ na późniejsze nadpisania.

-- myplugin/
--   lua/myplugin/init.lua
--   plugin/myplugin.lua
--   doc/myplugin.txt

Katalog lua/

Pliki w katalogu lua/ są dostępne za pomocą require. Moduł w lua/myplugin/init.lua jest ładowany jako require('myplugin').

Zagnieżdżenie odpowiada ścieżkom rozdzielanym kropkami: lua/myplugin/config.lua staje się require('myplugin.config'). W ten sposób wtyczki udostępniają przejrzystą publiczną przestrzeń nazw.

-- in lua/myplugin/init.lua
local M = {}
function M.hello() print('hi') end
return M

Zwracanie tabeli modułu

Idiomatyczny wzorzec modułu polega na zadeklarowaniu lokalnej tabeli M, dołączeniu do niej funkcji i zwróceniu jej. Kod wywołujący może wtedy użyć require('myplugin').hello().

Wewnętrzne funkcje pomocnicze należy pozostawić jako zwykłe zmienne lokalne, aby publiczna była tylko zamierzona część interfejsu. Odzwierciedla to hermetyzację modułów znaną z innych ekosystemów.

local M = {}
local function private() end
function M.run() private() end
return M

Konwencja setup()

Większość wtyczek udostępnia funkcję setup(opts). Łączy ona opcje użytkownika z wartościami domyślnymi i wykonuje inicjalizację, taką jak tworzenie poleceń oraz autokomend.

Należy użyć vim.tbl_deep_extend('force', defaults, opts or {}), aby częściowa konfiguracja użytkownika nadal otrzymała wszystkie wartości domyślne.

local M = {}
local defaults = { width = 40 }
function M.setup(opts)
  M.config = vim.tbl_deep_extend('force', defaults, opts or {})
end
return M

Katalog plugin/

Skrypty w katalogu plugin/ uruchamiają się automatycznie podczas startu Neovim, po zbudowaniu runtimepath. Należy utrzymywać je w niewielkim rozmiarze.

Typowym zadaniem jest rejestrowanie poleceń lub zabezpieczenia, dzięki któremu ciężkie moduły są ładowane leniwie. Należy unikać kosztownych operacji w tym miejscu; lepiej odroczyć je do setup lub autokomend, aby zachować krótki czas uruchamiania.

-- in plugin/myplugin.lua
if vim.g.loaded_myplugin then return end
vim.g.loaded_myplugin = true

Zabezpieczenia ładowania

Zabezpieczenie ładowania zapobiega wielokrotnej inicjalizacji, gdy plik zostanie wczytany dwa razy. Należy ustawić flagę vim.g.loaded_* i zakończyć działanie przy ponownym wejściu.

Jest to niezbędne, ponieważ menedżery wtyczek i :runtime mogą ponownie wczytywać pliki, a zduplikowane polecenia lub autokomendy prowadzą do trudnych do wykrycia błędów.

if vim.g.loaded_myplugin == 1 then return end
vim.g.loaded_myplugin = 1

Leniwe ładowanie

Szybki start oznacza ładowanie kodu tylko wtedy, gdy jest potrzebny. Należy zarejestrować lekkie polecenie w katalogu plugin/, które przy pierwszym użyciu załaduje ciężki moduł za pomocą require.

Menedżery wtyczek, takie jak lazy.nvim, formalizują ten mechanizm za pomocą wyzwalaczy cmd, ft i keys, dzięki czemu moduł nie jest dotykany, dopóki nie zostanie wywołany.

vim.api.nvim_create_user_command('MyStart', function()
  require('myplugin').run()
end, {})

runtimepath i packpath

Neovim wykrywa wtyczki, skanując runtimepath. Natywny system pakietów automatycznie ładuje katalogi znajdujące się w pack/*/start/, a katalogi pack/*/opt/ ładuje na żądanie za pomocą :packadd.

Większość użytkowników korzysta z menedżera, ale zrozumienie działania runtimepath wyjaśnia, w jaki sposób odnajdywane są katalogi.

print(vim.o.runtimepath:sub(1, 60))
-- :packadd loads an opt plugin manually

Kontrole stanu

Należy dostarczyć plik lua/myplugin/health.lua z funkcją check, aby użytkownicy mogli uruchomić :checkhealth myplugin. Stan należy zgłaszać za pomocą interfejsu API vim.health.

Użyj vim.health.start, vim.health.ok, vim.health.warn i vim.health.error, aby jasno wskazywać brakujące zależności.

local M = {}
function M.check()
  vim.health.start('myplugin')
  vim.health.ok('all good')
end
return M

Dokumentacja i tagi

Należy dołączyć plik pomocy doc/myplugin.txt. Uruchom :helptags doc/ (lub pozwól, aby zrobił to menedżer), aby wygenerować indeks tagów i umożliwić działanie :help myplugin.

Dobra dokumentacja zawiera listę poleceń, opcji setup oraz domyślnych mapowań klawiszy, dzięki czemu wtyczkę można znaleźć bezpośrednio w Neovim.

-- generate tags from the doc directory
vim.cmd('helptags ' .. vim.fn.expand('%:p:h'))

Wersjonowanie i publikowanie

Wtyczkę należy umieścić w repozytorium git; użytkownicy instalują ją za pomocą ścieżki owner/repo. Wydania należy oznaczać zgodnie z wersjonowaniem semantycznym, aby menedżery mogły przypinać konkretne wersje.

README powinien zawierać przykłady instalacji dla popularnych menedżerów, licencję oraz minimalny przykład konfiguracji, aby ułatwić rozpoczęcie korzystania z wtyczki.

-- lazy.nvim spec
-- { 'owner/myplugin', config = function()
--     require('myplugin').setup({})
--   end }

Szybki test

Sprawdźmy, czy rozumieją Państwo pakowanie wtyczek.

Podsumowanie: pakowanie wtyczki

Wtyczka to katalog na runtimepath zawierający moduły w lua/, automatycznie uruchamiany skrypt w plugin/ oraz opcjonalne pliki w katalogach doc/ i ftplugin/>, a także pliki diagnostyczne.

Należy zwracać tabele modułów, udostępniać funkcję setup łączącą wartości domyślne, zabezpieczać się przed wielokrotnym ładowaniem, ładować ciężki kod leniwie, tworzyć dokumentację za pomocą helptags oraz publikować wtyczkę w git z semantycznymi tagami wersji.

Często zadawane pytania

Czy lekcja „Pakowanie pluginu” jest bezpłatna?

Tak — pełny tekst „Pakowanie pluginu” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Lua Academy, przejdź na CoddyKit PRO. Kurs Lua Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Pakowanie pluginu”?

Nada Pan/Pani pluginowi strukturę i udostępni go innym. Ćwiczysz Lua Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Lua Academy?

Nie wymagamy żadnego doświadczenia. Lua Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Pakowanie pluginu”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Lua Academy?

Tak. Każda lekcja Lua Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. API Lua Neovima
  2. Polecenia i mapowania klawiszy
  3. Bufory i okna
  4. Pakowanie pluginu
← Powrót do Lua Academy