Komendy i elementy interfejsu

Komendy

Zadeklaruj każdą komendę w contributes.commands, a w activate() zarejestruj jej funkcję. Przykładowy plugin robi to dla example.workspace-info.open.

Zadeklarowane komendy pojawiają się w Commands i Settings > Keybinds przed aktywacją lazy. Aplikacja aktywuje plugin przy wykonaniu komendy. Deklaracja bez zarejestrowanej funkcji kończy się błędem The plugin did not register this command.

Kontekst określa dostępność komendy:

Pole	Zachowanie
workspace: true	Wymaga aktywnego obszaru roboczego. Pominięte pole lub false nie dodaje tego warunku.
viewTypes: [...]	Wymaga zgodności typu aktywnego panelu z jedną z wartości. Użyj wbudowanego typu, np. terminal, albo pełnego ID widoku pluginu. Pusta tablica nie pasuje do niczego.
textInput: true	Pozwala wykonać skrót podczas pisania w polu tekstowym. Domyślnie taki kontekst klawiatury jest blokowany.

textInput: false nie zabrania wywołania komendy z kodu. context.executeCommand(id) używa ścieżki programowej SDK, która nie odczytuje samodzielnie, czy fokus znajduje się w polu tekstowym.

Skróty klawiszowe

Ten fragment umieść wewnątrz contributes:

{
  "keybindings": [
    {
      "command": "example.workspace-info.open",
      "shortcut": "Ctrl+Alt+KeyI"
    }
  ]
}

Używaj kodów klawiszy, takich jak KeyI, Digit1, Enter lub F6, zamiast wyświetlanych oznaczeń typu I. Kolejność modyfikatorów to Ctrl, Alt, Meta, Shift. Pomiń nieużywane. Poza klawiszami funkcyjnymi od F1 do F24 skrót wymaga modyfikatora innego niż Shift. Wartość null pozostawia komendę bez domyślnego skrótu.

Na macOS domyślne skróty z Ctrl zmieniają się na Meta, pokazywane jako Cmd. Użytkownik może je zmienić lub wyłączyć w Keybinds. Domyślny skrót powodujący konflikt pozostaje nieprzypisany. Nie przejmuje skrótu innej komendy. Własne przypisania użytkownika są zachowywane według ID także wtedy, gdy plugin jest nieobecny.

Miejsca rozszerzeń interfejsu

Slot	Miejsce
statusbar	Pasek stanu głównego okna.
sidebar-actions	Obszar akcji paneli bocznych pluginów.
view-actions	Nagłówek paneli pluginów.

Zadeklaruj element fill z id, slot i label, a następnie wywołaj registerFill(id, Component). Elementy są sortowane po ID. Dotyczą całego danego slotu, a nie automatycznie tylko widoków własnego pluginu. Użyj useHostContext(), jeśli kontrolka ma zależeć od aktywnego widoku lub obszaru roboczego.

Przypisz dostępną nazwę do właściwego przycisku lub pola. Etykieta manifestu nie zastępuje nazwy dostępnej kontrolki.

Komponenty fill pojawiają się dopiero po aktywacji. Plugin dodający przycisk stanu od razu po przygotowaniu aplikacji potrzebuje activation: "startup". Plugin lazy zawierający wyłącznie fill nie ma widoku ani komendy, które wywołałyby aktywację.

Przykład: komenda i przycisk na pasku stanu

Zacznij od szablonu panel z ID example.workspace-info. Zmień activation na startup, a w contributes dopisz:

{
  "fills": [
    {
      "id": "example.workspace-info.status",
      "slot": "statusbar",
      "label": "Open workspace information"
    }
  ]
}

Zachowaj istniejące deklaracje views i commands. Zastąp src/index.tsx poniższą wersją:

import { useState } from 'react';
import {
  useHostContext,
  type PluginContext,
  type ViewProps,
} from '@lomi-dev/plugin-sdk';

function WorkspaceInfo({ panel }: ViewProps) {
  const host = useHostContext();
  return (
    <section className="lomi-workspace-info">
      <h2>{host.workspaceName ?? 'No workspace selected'}</h2>
      <p>{host.projectPath ?? 'No project selected'}</p>
      <small>Panel: {panel.id}</small>
    </section>
  );
}

export function activate(context: PluginContext) {
  context.registerView('example.workspace-info.view', WorkspaceInfo);
  context.registerCommand('example.workspace-info.open', async () => {
    await context.openView('example.workspace-info.view');
  });

  function OpenButton() {
    const host = useHostContext();
    const [error, setError] = useState('');
    async function open() {
      setError('');
      try { await context.executeCommand('example.workspace-info.open'); }
      catch (error) {
        setError(error instanceof Error ? error.message : String(error));
      }
    }
    return (
      <span className="lomi-workspace-info-action">
        <button type="button" disabled={!host.workspaceName} onClick={open}>
          Workspace info
        </button>
        {error && <span role="alert">{error}</span>}
      </span>
    );
  }
  context.registerFill('example.workspace-info.status', OpenButton);
}

Przycisk jest niedostępny bez workspace, a błąd wykonania trafia do czytelnego komunikatu. Zarejestrowane widoki, komendy i fill usuwa host podczas dezaktywacji. Dopasuj przykład generatora do zmienionego widoku. Ten przykład nie zawiera checkboxa Show project path.

Jeśli chcesz ograniczyć kontrolkę do własnego aktywnego widoku, sprawdź host.viewType === 'example.workspace-info.view'. Slot nie przekazuje ViewProps ani ID panelu, przy którym akurat renderuje kontrolkę; snapshot opisuje aktywny panel aplikacji.

Komendy innych pluginów

executeCommand() może wywołać zadeklarowaną komendę innego pluginu, ale nie instaluje go i nie zatwierdza zaufania. Brak pakietu, wyłączenie, niezgodny kontekst lub nieudana aktywacja odrzucają obietnicę. Obsłuż ten przypadek w interfejsie. Manifest v1 nie wymusza zależności między pluginami, a SDK nie przekazuje argumentów ani wyniku komendy.

Nie przechwytuj samodzielnie globalnego keydown, żeby ominąć konflikt skrótu. Użyj deklaracji i Settings > Keybinds. Poprawne przykłady to Ctrl+Alt+KeyI, Meta+Shift+Digit1 i F6. Cmd+I, Ctrl+I, Shift+KeyI, zduplikowane modyfikatory i wieloetapowe sekwencje są nieprawidłowe.

Style przycisku i pliki graficzne opisuje osobna strona Style i zasoby.

Kod źródłowy: wykonywanie komend, skróty, renderowanie slotów.