Manifest pluginu

plugin.json opisuje pakiet przed uruchomieniem kodu. Musi być poprawnym JSON-em. Nieznane pola są odrzucane, również $schema i dependencies. Schemat JSON przypisz do pliku w ustawieniach edytora.

Kompletny przykład manifestu

Poniższy manifest pokazuje wszystkie rodzaje deklaracji. Aby go zbudować, potrzebujesz implementacji widoku, komendy i fill oraz plików view.css i theme/theme.jsonc dołączonych do assets. Rejestrację komendy i przycisku znajdziesz na stronie Komendy i elementy interfejsu.

{
  "schemaVersion": 1,
  "hostApi": 1,
  "id": "example.workspace-info",
  "name": "Workspace info",
  "version": "0.1.0",
  "description": "Show the active project and workspace.",
  "entry": "dist/index.js",
  "activation": "startup",
  "stylesheets": [
    "view.css"
  ],
  "contributes": {
    "views": [
      {
        "id": "example.workspace-info.view",
        "title": "Workspace info",
        "placement": "central",
        "multiple": false,
        "stateVersion": 1
      }
    ],
    "commands": [
      {
        "id": "example.workspace-info.open",
        "label": "Workspace info",
        "description": "Open workspace information.",
        "context": {
          "workspace": true
        }
      }
    ],
    "keybindings": [
      {
        "command": "example.workspace-info.open",
        "shortcut": "Ctrl+Alt+KeyI"
      }
    ],
    "fills": [
      {
        "id": "example.workspace-info.status",
        "slot": "statusbar",
        "label": "Open workspace information"
      }
    ],
    "themes": [
      {
        "id": "example.workspace-info.theme",
        "path": "theme"
      }
    ]
  }
}

Pola główne

Pole	Wymagane	Znaczenie
schemaVersion	Tak	Wersja formatu manifestu. Musi wynosić 1.
hostApi	Tak	Wersja API aplikacji. Musi wynosić 1.
id	Tak	Identyfikator pakietu z przestrzenią nazw, do 100 znaków.
name	Tak	Wyświetlana nazwa, do 160 znaków.
version	Tak	major.minor.patch z opcjonalnym sufiksem wydania wstępnego. Do 80 znaków.
description	Tak	Niepusty opis, do 2000 znaków.
entry	Dla elementów wykonywalnych	Względna ścieżka do gotowego modułu ESM .js lub .mjs.
activation	Nie	Domyślnie lazy, opcjonalnie startup.
stylesheets	Nie	Do 16 różnych względnych ścieżek do plików .css.
contributes	Nie	Deklaracje widoków, komend, skrótów, elementów interfejsu i motywów.

Parser wersji akceptuje 1.2.3 i 1.2.3-beta.1. Nie przyjmuje metadanych buildu, takich jak 1.2.3+build.4.

Identyfikatory

Używaj małych liter i co najmniej jednej kropki, na przykład example.workspace-info. Każdy człon oddzielony kropką zaczyna się literą i może zawierać małe litery, cyfry oraz łączniki.

Identyfikator elementu musi zaczynać się pełnym ID pakietu i dodatkową kropką. example.workspace-info.panel należy więc do example.workspace-info. ID elementów mają limit 160 znaków i muszą być unikalne między widokami, komendami, elementami interfejsu i motywami. Skrót wskazuje istniejące ID komendy. Jedna komenda może mieć jeden skrót zadeklarowany w manifeście.

Deklarowane elementy

Każda z poniższych list przyjmuje maksymalnie 128 wpisów.

Lista	Pola
views	id, title, placement, multiple, stateVersion
commands	id, label, description, opcjonalnie context
keybindings	command, shortcut
fills	id, slot, label
themes	id, path

Widok używa placement: "central" lub "sidebar". Panel boczny wymaga multiple: false. stateVersion to liczba całkowita od 1 do 1000. Musi dokładnie odpowiadać wersji zapisanej w odtwarzanym panelu.

Kontekst komendy przyjmuje workspace, viewTypes i textInput. Reguły wykonania oraz składnię skrótów opisuje strona Komendy i elementy interfejsu.

Elementy fills trafiają do statusbar, sidebar-actions lub view-actions. Ich label powinno opisywać kontrolkę. Pole path motywu wskazuje folder zawierający theme.jsonc lub obsługiwany starszy theme.json.

Pakiet zawierający wyłącznie motywy może pominąć entry. Widoki, komendy, skróty i elementy interfejsu wymagają punktu wejścia. Deklaracja elementu nie rejestruje jego implementacji: activate() musi wywołać odpowiednią metodę SDK.

Referencja pól elementów

Element i pole	Typ / limit	Znaczenie
views[].id	ID, 160 znaków	Używane przez registerView() i openView()
views[].title	Niepusty tekst, 160 znaków	Początkowy tytuł panelu
views[].placement	central albo sidebar	Miejsce widoku
views[].multiple	Boolean, wymagany	Czy tworzyć nowe instancje; sidebar wymaga false
views[].stateVersion	Liczba całkowita 1-1000	Wersja formatu stanu tego widoku
commands[].id	ID, 160 znaków	Używane przez rejestrację, skróty i wykonanie
commands[].label	Niepusty tekst, 160 znaków	Nazwa komendy w interfejsie
commands[].description	Niepusty tekst, 2000 znaków	Wyjaśnienie działania komendy
commands[].context.workspace	Opcjonalny boolean	true wymaga workspace
commands[].context.viewTypes	Do 128 tekstów, każdy do 160 znaków	Dozwolone typy aktywnego panelu; pominięcie nie ogranicza typu
commands[].context.textInput	Opcjonalny boolean	true dopuszcza skrót podczas pisania w polu
keybindings[].command	ID własnej zadeklarowanej komendy	Jedno domyślne przypisanie na komendę
keybindings[].shortcut	Poprawny skrót lub null	null oznacza brak domyślnego skrótu
fills[].id	ID, 160 znaków	Używane przez registerFill()
fills[].slot	Jedna z trzech obsługiwanych nazw	Miejsce kontrolki
fills[].label	Niepusty tekst, 160 znaków	Etykieta elementu; przycisk nadal potrzebuje własnej nazwy
themes[].id	ID, 160 znaków	Tożsamość dostarczanego motywu
themes[].path	Względna ścieżka, 512 znaków	Katalog motywu w paczce

Nazwy i opisy nie mogą zawierać znaków sterujących. Nieznane pola są odrzucane również wewnątrz deklaracji. Każda lista w contributes jest opcjonalna. Pełny parser sprawdza powiązania, których samo podświetlenie błędów JSON Schema w edytorze nie wystarcza zweryfikować.

Cztery niezależne wersje

• schemaVersion określa format plugin.json.
• hostApi określa kontrakt aplikacji.
• version to numer wydania całego pluginu.
• stateVersion określa format stanu pojedynczego rodzaju widoku.

Wersja paczki SDK jest jeszcze innym numerem. Zwiększenie wersji pluginu nie zmienia API ani nie migruje stanu. Zachowuj ID pomiędzy wydaniami; to ono wiąże pakiet z zapisanymi panelami i przypisaniami skrótów.

Schemat w edytorze

Generator tworzy .vscode/settings.json z powiązaniem do schematu z zainstalowanego SDK. W projekcie ręcznym dodaj:

{
  "json.schemas": [
    {
      "fileMatch": ["plugin.json"],
      "url": "./node_modules/@lomi-dev/plugin-sdk/plugin.schema.json"
    }
  ]
}

Zależności npm deklaruj w package.json. Manifest v1 nie ma permissions, zależności między pluginami ani przedziału wersji aplikacji. Nie dodawaj takich pól samodzielnie. Narzędzia i natywny importer uzupełniają walidację schematu.

Ścieżki w pakiecie

Używaj ścieżek względnych z /, takich jak dist/index.js i themes/graphite. Odrzucane są ścieżki absolutne, człony . i .., odwrotne ukośniki, kodowane ścieżki, dowiązania symboliczne, zastrzeżone nazwy Windows i alternatywne strumienie plików. Limit ścieżki wynosi 512 znaków. Importer sprawdza, czy wskazane pliki wejścia, CSS i motywów istnieją.

Kod źródłowy: walidacja manifestu, walidacja natywna.