Zasoby i CSS

Użyj folderu pakietu, gdy motyw potrzebuje zasobów poza theme.jsonc. Kompletny przykład Graphite Grid zawiera:

graphite-grid/
  theme.jsonc
  theme.css
  images/
    grid.svg

Deklarowanie zasobów

{
  "version": 2,
  "name": "Graphite Grid",
  "appearance": "adaptive",
  "common": {
    "backgrounds": {
      "terminal": {
        "image": "images/grid.svg",
        "opacity": 0.08,
        "size": "32px 32px",
        "repeat": "repeat"
      }
    },
    "plugins": {
      "example.workspace-info": { "surface": "var(--color-surface)" }
    }
  },
  "resources": {
    "stylesheets": ["theme.css"],
    "assets": { "grid": "images/grid.svg" }
  }
}

backgrounds.terminal.image jest ścieżką względem pakietu, nie aliasem zasobu. resources.assets.grid deklaruje ten sam obraz jako nazwany zasób. Udostępnia go w CSS jako --asset-grid i obejmuje kontrolą gotowości zasobów.

Obraz terminala korzysta z osobnej warstwy tła. Jego opacity nie zmniejsza widoczności tekstu terminala.

Arkusze stylów

.workspace-info {
  border: 1px solid var(--color-outline);
  border-radius: var(--radius-control);
  background-color: var(--plugin-example-dworkspace-hinfo-surface, var(--color-surface));
  background-image: var(--asset-grid);
}

Ten arkusz zmienia wygląd przykładu workspace-info. Korzysta z istniejących zmiennych semantycznych oraz tokenu pluginu z wartością zapasową. --asset-grid zawiera już url(...), więc używaj bezpośrednio var(--asset-grid).

Arkusze są stosowane w kolejności podanej w resources.stylesheets. Adresy zapisane wewnątrz CSS są rozwiązywane względem tego arkusza, również dla @import. Plik css/theme.css odwołujący się do sąsiedniego katalogu obrazów użyje więc ../images/grid.svg. Ścieżki w manifeście JSONC pozostają względne wobec głównego folderu pakietu.

Fonty

Umieść lokalne pliki fontów w pakiecie. Wymagane fonty zadeklaruj w resources.assets, a w CSS odwołaj się do nich przez @font-face:

@font-face {
  font-family: "My Mono";
  src: url("fonts/my-mono.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
}

Przykład zakłada theme.css w głównym katalogu pakietu i istniejący plik fonts/my-mono.woff2. Dodaj odpowiednią deklarację zasobu, a następnie ustaw editor.fontFamily, terminal.fontFamily lub właściwy token fontu na "My Mono", monospace. Dołącz font, który możesz legalnie udostępniać.

Zasoby sieciowe są blokowane przez politykę bezpieczeństwa treści aplikacji. Nieudany zagnieżdżony import CSS nie zawsze jest zgłaszany przez zdarzenie ładowania zewnętrznego arkusza. Wymagane obrazy i fonty deklaruj więc jawnie.

Tokeny pluginów

Deklaracja common.plugins z przykładu tworzy:

--plugin-example-dworkspace-hinfo-surface: var(--color-surface);

Nazwa składa się z --plugin-, zakodowanego właściciela i nazwy tokenu. Zamień - na -h, a następnie . na -d. Dzięki temu różne identyfikatory właściciela pozostają rozróżnialne. Nazwa tokenu zaczyna się małą literą i używa małych liter, cyfr lub łączników.

Kolejność stosowania wartości

Dla motywów kolorów kolejność jest następująca:

1. Wbudowane wartości bazowe wybranego wyglądu.
2. Mapowanie kolorów zaimportowanego motywu VS Code, jeśli istnieje.
3. Wartości common.
4. Wartości pasującego light lub dark.
5. Lokalne arkusze w kolejności manifestu, z uwzględnieniem kaskady CSS.
6. Ustawienia wyglądu terminala wybrane przez użytkownika.

Usunięcie nadpisania przywraca wartość dziedziczoną. Własne ustawienia terminala są stosowane jako style inline z !important. CSS może też nadpisywać publiczne zmienne składni --syntax-<name>-color, -font-style, -font-weight i -text-decoration.

CSS może ukryć lub uszkodzić kontrolki aplikacji. Nie stanowi granicy bezpieczeństwa. Ograniczaj zakres zmian i sprawdzaj oba tryby wyglądu przed udostępnieniem pakietu.

Ścieżki i rozmiary

Zasoby muszą pozostać wewnątrz pakietu. Odrzucane są dowiązania symboliczne, wyjście poza folder, ścieżki absolutne, kodowane separatory, zastrzeżone nazwy Windows i alternatywne strumienie. Natywny pakiet motywu ma limit 64 MiB, 8192 wpisów plików i katalogów, 16 poziomów katalogów oraz 20 MiB na zasób. Manifest motywu ma osobny limit 256 KiB.

Silnik przygotowuje wymagane zasoby przed zastąpieniem działającego wyglądu. Brak pliku lub błąd wymaganego arkusza pozostawia ostatni działający motyw i wyświetla błąd.

Obsługiwane pliki i pełna deklaracja fontu

Protokół zasobów obsługuje CSS; obrazy PNG, JPG/JPEG, WebP, GIF, SVG, AVIF i ICO; fonty WOFF, WOFF2, TTF i OTF. Wymagany arkusz musi być zapisany w UTF-8 i mieć najwyżej 256 KiB, mimo że pozostałe zasoby mają limit 20 MiB. Obsługiwane rozszerzenie nie gwarantuje poprawnego obrazu lub fontu.

Dla powyższego @font-face po dodaniu rzeczywistego pliku fontu połącz ten fragment z głównym poziomem dokumentu:

{
  "resources": {
    "stylesheets": ["theme.css"],
    "assets": { "my-mono": "fonts/my-mono.woff2" }
  },
  "common": {
    "editor": { "fontFamily": "\"My Mono\", monospace" },
    "terminal": { "fontFamily": "\"My Mono\", monospace" }
  }
}

Przy łączeniu zachowaj dotychczasowe zasoby; nie dodawaj drugiego klucza resources. Deklaracja zasobu sprawdza dostępność fontu, a @font-face przypisuje mu rodzinę CSS. Obie części mają osobne zadanie.

Zachowanie tła

backgrounds używa osobnych warstw obrazu w siedmiu obsługiwanych obszarach. Rozmycie jest podawane w pikselach, a krycie w zakresie 0-1. Zacznij od małego krycia i sprawdź kontrast tekstu oraz zaznaczeń na każdej powierzchni. Do tapety użyj size: "cover", a do wzoru stałego rozmiaru kafelka i repeat: "repeat".

Ścieżki manifestu używają ukośnika /, np. images/grid.svg, bez ./. URL-e w CSS i ścieżki dokumentu ikon mają osobne reguły i mogą zawierać ../ tylko w obrębie pakietu. Zachowaj dokładną wielkość liter w nazwach plików.

Utrzymanie własnego CSS

Do zmian aplikacji preferuj tokeny i obsługiwane opcje layout. Selektor .workspace-info z przykładu należy do tego pluginu; selektory wewnętrznych elementów aplikacji mogą się zmieniać. styles przyjmuje mapy deklaracji, a nie pełny tekst CSS, zagnieżdżone reguły lub bloki @media. Umieść je w arkuszu i użyj [data-appearance="light"] lub [data-appearance="dark"], aby stylować faktyczny tryb Lomi.

Unikaj zdalnych importów fontów, skryptów i zależności od plików poza pakietem. Załadowanie głównego CSS nie dowodzi załadowania każdego zasobu zagnieżdżonego. Sprawdź rezultat wizualnie i jawnie zadeklaruj wymagane zasoby.

Kod źródłowy: ładowanie zasobów i generowanie CSS, natywne limity pakietów.