SDK i cykl życia

Typy, HostContext i useHostContext() importuj z @lomi-dev/plugin-sdk. Dokumentacja opisuje SDK 1.1.0-alpha.1 i API hosta 1 z lokalnego zestawu Lomi. Instalację tego zestawu opisuje Pierwszy plugin. Główny eksport SDK wymaga runtime aplikacji; nie uruchamiaj go bezpośrednio w Node.

Moduł wejściowy

Moduł wskazany przez entry musi eksportować nazwaną funkcję activate:

import type { PluginContext } from '@lomi-dev/plugin-sdk';

export function activate(context: PluginContext) {
  context.subscribe('context', (snapshot) => {
    console.log(snapshot.workspaceName);
  });
}

activate(context) może nie zwracać wartości, zwrócić funkcję sprzątającą albo obietnicę jednego z tych wyników. Moduł może też eksportować deactivate(): void | Promise<void>.

Aktywacja lazy następuje przy otwarciu zadeklarowanego widoku lub wykonaniu komendy. startup uruchamia plugin po przygotowaniu głównego obszaru aplikacji. Równoczesne wywołania współdzielą jedną aktywację. Sam import nie aktywuje pakietu, a tryb bezpieczny blokuje aktywację.

Etapy działania

Stan	Znaczenie
discovered	Poprawny, włączony pakiet czeka na aktywację
incompatible	Metadane lub kontrakt nie pozwalają użyć pakietu
disabled	Kod jest wyłączony, także w trybie bezpiecznym
activating	Host przygotowuje rewizję, ładuje CSS i moduł oraz czeka na activate()
active	Aktywacja zakończyła się powodzeniem
failed	Aktywacja nie powiodła się; sprawdź błąd i możliwość ponowienia
deactivating	Host sprząta zasoby

Włączony plugin lazy może długo pozostawać w stanie discovered; to prawidłowe. Błąd późniejszej komendy, timera lub renderowania może zostać zapisany przy nadal aktywnym pluginie. Status i komunikat błędu należy czytać razem.

W activate() rejestruj elementy i przygotowuj zasoby. Nie czekaj tam na wykonanie własnej komendy przez executeCommand(): ta metoda czeka na zakończenie aktywacji. Wykonuj ją z późniejszej akcji użytkownika. Unikaj też cyklicznego wywoływania komend dwóch pluginów podczas aktywacji.

PluginContext

Element	Kontrakt
id	ID pakietu tylko do odczytu.
signal	AbortSignal przerywany przy dezaktywacji lub nieudanej aktywacji.
snapshot()	Zwraca aktualny HostSnapshot.
registerView(id, component)	Rejestruje zadeklarowany widok React otrzymujący ViewProps. Zwraca Dispose.
registerCommand(id, handler)	Rejestruje zadeklarowaną komendę () => void | Promise<void>. Zwraca Dispose.
registerFill(id, component)	Rejestruje zadeklarowany komponent React w miejscu rozszerzeń interfejsu. Zwraca Dispose.
registerDirtyView(panelId, view)	Rejestruje obsługę niezapisanej pracy dla istniejącego panelu tego pluginu. Zwraca Dispose.
openView(id, state?)	Otwiera własny zadeklarowany widok. Zwraca Promise<string> z ID panelu. Pominięty stan to null.
executeCommand(id)	Wykonuje komendę pluginu po aktywacji i kontroli kontekstu. Zwraca Promise<void>.
subscribe(event, handler)	Subskrybuje zdarzenie aplikacji. Zwraca Dispose.
interval(callback, milliseconds)	Rejestruje timer o odstępie od 50 do 2147483647 ms. Zwraca Dispose.
add(dispose)	Rejestruje sprzątanie własnego zasobu. Zwraca idempotentny Dispose.
assetUrl(path)	Zwraca adres zasobu wewnątrz zainstalowanej rewizji pakietu.

Dispose ma postać () => void. Wywołaj tę funkcję, kiedy rejestracja przestaje być potrzebna. Kolejne wywołanie niczego nie zmienia. Aplikacja uruchamia pozostałe funkcje sprzątające podczas dezaktywacji. Ponowna rejestracja tego samego elementu, użycie niezadeklarowanego ID lub rejestrowanie po dezaktywacji kończy się wyjątkiem.

openView() otwiera wyłącznie własne widoki pluginu i wymaga otwartego obszaru roboczego. executeCommand() może wywoływać zadeklarowane komendy pluginów, także innego pluginu. Wbudowane akcje aplikacji nie należą do publicznego kontraktu tej metody.

Aktualny kontekst

useHostContext() subskrybuje w komponencie React ten sam bieżący kontekst, który zwraca snapshot():

Pole	Typ i znaczenie
projectPath	string lub null: folder aktywnego projektu.
workspaceName	string lub null: nazwa aktywnego obszaru roboczego.
activePanelId	string lub null: aktywny panel, również panel boczny pluginu mający fokus.
viewType	string lub null: typ wbudowanego panelu albo ID widoku pluginu.
appearance	light lub dark.
themeRevision	Liczba identyfikująca natywną rewizję źródeł motywu.

To aktywny kontekst aplikacji, a nie stałe przypisanie projektu do każdego zamontowanego widoku. Ścieżkę konkretnego dokumentu przechowuj we własnym modelu danych.

Zdarzenia

Zdarzenie	Dane
context	HostSnapshot.
theme	{ revision: number, appearance: 'light' | 'dark' }.
contributions	{ owner: string }.

Zdarzenie theme używa lokalnej rewizji zastosowanego wyglądu. Może zmienić się po wyborze trybu jasnego lub podglądu bez zmiany snapshot().themeRevision. Nie traktuj tych liczników zamiennie. Magistrala zdarzeń nie przesyła wyjścia terminala.

Subskrypcja nie wysyła od razu aktualnego snapshotu. Użyj snapshot() przy inicjalizacji, a subscribe('context', ...) do kolejnych zmian. contributions informuje o zakończonej aktywacji lub dezaktywacji właściciela; nie jest powiadomieniem o każdym pliku czy każdej zmianie stanu panelu.

Sprzątanie i błędy

Aplikacja przerywa signal, uruchamia zarejestrowane funkcje sprzątające w odwrotnej kolejności i wywołuje opcjonalne deactivate() modułu. Błąd jednej funkcji sprzątającej nie zatrzymuje pozostałych.

Do zasobów obsługiwanych przez aplikację używaj context.interval() i context.subscribe(). Nasłuchiwanie zdarzenia przeglądarki wymaga własnego sprzątania:

const onResize = () => {
  // Update plugin-owned layout measurements here.
};
window.addEventListener('resize', onResize);
context.add(() => window.removeEventListener('resize', onResize));

Ten fragment umieść wewnątrz activate(). Za zasoby tworzone poza kontekstem odpowiada autor. Obsługuj odrzucone obietnice i błędy własnych zdarzeń. Granica błędów React przechwytuje problemy renderowania, ale nie dowolne zadania asynchroniczne. Nieskończona pętla blokuje główny wątek JavaScript; limit czasu obietnicy jej nie przerwie.

Publiczne SDK nie udostępnia usług systemu plików, terminala, HTTP, powiadomień ani magazynu sekretów. Nie traktuj wewnętrznych importów aplikacji i komend natywnych jako stabilnych metod SDK.

Zadania asynchroniczne

Przekazuj context.signal do operacji wspierających AbortSignal, np. przeglądarkowego fetch. Po await sprawdź context.signal.aborted przed zmianą własnego modelu lub rejestracją kolejnych elementów. Obsłuż oczekiwane przerwanie bez pokazywania go jako awarii użytkownikowi.

context.interval() i subskrypcje raportują błędy callbacków, ale timer nie czeka na poprzedni asynchroniczny przebieg. Jeśli operacja trwa długo, pilnuj, by kolejne przebiegi się nie nakładały. context.add() przyjmuje synchroniczny Dispose; do asynchronicznego kończenia pracy modułu służy deactivate().

Dezaktywacja nie usuwa modułu z pamięci silnika ESM. Przy ponownej aktywacji tej samej rewizji zmienne modułowe mogą nadal istnieć. Inicjalizuj i sprzątaj je świadomie; nie zachowuj starego PluginContext, którego signal został już przerwany.

Eksporty SDK dla narzędzi autora

Import	Dostępne elementy / przeznaczenie
@lomi-dev/plugin-sdk	Typy: Json, Dispose, HostSnapshot, PanelDescriptor, ViewProps, DirtyView, CommandContext, PluginManifest, HostEvents, PluginContext, PluginModule; runtime: HostContext, useHostContext()
@lomi-dev/plugin-sdk/manifest	parsePlugin(value) zwraca manifest lub rzuca błąd; packagePath(value) i jsonState(value) walidują przez wyjątek; także pluginId i validShortcut
@lomi-dev/plugin-sdk/shortcuts	validShortcut(value): boolean, kolejność modifiers i słownik keyNames
@lomi-dev/plugin-sdk/compatibility	Obiekty compatibility i limits, m.in. API, runtime, zgodne wersje i limity paczki
@lomi-dev/plugin-sdk/build	buildPlugin(options): Promise<string>, czyli folder z gotowym wynikiem; tylko Node
@lomi-dev/plugin-sdk/package	safePath(root, path), packageFiles(root), validatePackage(root); asynchroniczne kontrole plików w Node
@lomi-dev/plugin-sdk/plugin.schema.json	Schemat dla edytora
@lomi-dev/plugin-sdk/contract-fixtures.json	Przypadki zgodności dla integratorów hosta i narzędzi
@lomi-dev/plugin-sdk/package.json	Metadane zainstalowanej wersji

packageFiles() zwraca mapę względnych nazw na bajty, a validatePackage() zwraca { manifest, files }. safePath() sprawdza istniejącą ścieżkę, dowiązania i zawieranie w katalogu. Te funkcje mogą odrzucić obietnicę.

Walidatory manifestu i skrótów nie wymagają uruchomionej aplikacji. W samym kodzie pluginu build udostępnia tylko główny eksport runtime SDK; podścieżki narzędziowe importuj w skryptach autora, nie w kodzie pluginu. Szczegóły budowania bez CLI są w ręcznym przykładzie.

Kod źródłowy: pełne deklaracje typów, implementacja hosta.