Przejdź do treści

API

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: 22946a5

shikiphp udostępnia dwa punkty wejścia: statyczną fasadę Shikiphp dla typowych przypadków oraz instancję Highlighter do wszystkich pozostałych zastosowań (wyjście HAST, niestandardowe gramatyki i motywy, warianty motywów oraz sprawdzanie zawartości pakietu).

Fasada Shikiphp

Shikiphp\Shikiphp to prosta statyczna fasada nad leniwie tworzonym, buforowanym wyróżniaczem zawartym w pakiecie.

Shikiphp::codeToHtml

PHP
public static function codeToHtml(string $code, array $options): string

Tokenizuje $code i renderuje kompletny blok <pre class="shiki …"> HTML. Tablica opcji zawsze zawiera lang oraz mapę theme lub themes, a także dowolne opcje renderowania.

PHP
use Shikiphp\Shikiphp;

echo Shikiphp::codeToHtml($code, ['lang' => 'php', 'theme' => 'github-dark']);

Shikiphp::codeToTokens

PHP
/** @return list<list<ThemedToken>> */
public static function codeToTokens(string $code, array $options): array

Zwraca surową dwuwymiarową siatkę tokenów (jedna lista wewnętrzna na wiersz) obiektów Shikiphp\Render\ThemedToken zamiast HTML.

PHP
use Shikiphp\Shikiphp;

$lines = Shikiphp::codeToTokens($code, ['lang' => 'js', 'theme' => 'nord']);

foreach ($lines as $line) {
    foreach ($line as $token) {
        // $token->content, $token->color, $token->fontStyle,
        // $token->bgColor, $token->htmlStyle, $token->offset
    }
}

Shikiphp::codeToTokensBase

PHP
/** @return list<list<ThemedToken>> */
public static function codeToTokensBase(string $code, array $options): array

Alias codeToTokens zgodny z nazwą codeToTokensBase w Shiki.

Shikiphp::codeToTokensResult

PHP
public static function codeToTokensResult(string $code, array $options): TokensResult

Zwraca rozbudowany wynik odpowiadający najwyższemu poziomowi codeToTokens w Shiki: siatkę tokenów wraz z rozwiązanymi kolorami, nazwą motywu, głównym stylem dualnego motywu i końcowym stanem gramatyki. Zobacz niżej: TokensResult.

PHP
use Shikiphp\Shikiphp;

$result = Shikiphp::codeToTokensResult($code, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

$result->tokens;       // list<list<ThemedToken>>
$result->fg;           // "#e1e4e8"
$result->bg;           // "#24292e"
$result->themeName;    // "github-dark"
$result->grammarState; // GrammarState

Shikiphp::getLastGrammarState

PHP
public static function getLastGrammarState(string $code, array $options): GrammarState

Tokenizuje $code i zwraca stan gramatyki osiągnięty na końcu (getLastGrammarState Shiki). Przekaż go ponownie za pomocą opcji grammarState, aby wznowić tokenizację późniejszego fragmentu z tego samego stanu — przydatne przy stopniowym wyróżnianiu. Zgłasza wyjątek, jeśli lang ma wartość 'ansi' (ANSI nie ma stanu gramatyki).

PHP
use Shikiphp\Shikiphp;

$state = Shikiphp::getLastGrammarState("/* unterminated comment", [
    'lang'  => 'js',
    'theme' => 'nord',
]);

$html = Shikiphp::codeToHtml("still inside the comment */", [
    'lang'         => 'js',
    'theme'        => 'nord',
    'grammarState' => $state,
]);

Shikiphp::highlighter

PHP
public static function highlighter(): Highlighter

Zwraca współdzielony, dołączony pakiet Highlighter, tworząc go przy pierwszym użyciu. Użyj tego, aby uzyskać dostęp do poniższych metod instancji.

Shikiphp::use i Shikiphp::reset

PHP
public static function use(Highlighter $highlighter): void
public static function reset(): void

use podmienia niestandardowy Highlighter (na przykład taki, do którego wczytano niestandardowe gramatyki lub motywy), aby fasada przekazywała do niego wywołania. reset usuwa buforowaną instancję, dzięki czemu przy następnym wywołaniu zostanie ponownie utworzony domyślny wyróżniacz z pakietu.

Highlighter

Shikiphp\Highlighter obejmuje pełny zakres funkcji. Pobierz współdzieloną instancję z pakietu za pomocą Shikiphp::highlighter() lub utwórz ją jawnie:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Implementuje codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult i getLastGrammarState z takimi samymi sygnaturami jak fasada, a ponadto udostępnia poniższe elementy.

Highlighter::codeToHast

PHP
public function codeToHast(string $code, array $options): \Shikiphp\Hast\Element

Buduje drzewo HAST pre.shiki > code > (span.line > span)* Shiki, gotowe do samodzielnego przechodzenia, modyfikowania lub serializacji. To właśnie to codeToHtml serializuje wewnętrznie.

PHP
use Shikiphp\Shikiphp;

$hast = Shikiphp::highlighter()->codeToHast($code, [
    'lang'  => 'rust',
    'theme' => 'nord',
]);

Highlighter::codeToTokensWithThemes

PHP
/** @return list<list<ThemedTokenWithVariants>> */
public function codeToTokensWithThemes(string $code, array $options): array

Tokenizuje raz dla każdego motywu i łączy wynik w variants dla każdego tokenu, indeksowane kluczem motywu, zgodnie z ShikicodeToTokensWithThemes. Wymaga mapy themes.

PHP
use Shikiphp\Shikiphp;

$lines = Shikiphp::highlighter()->codeToTokensWithThemes($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);

$lines[0][0]->content;            // token text
$lines[0][0]->variants['light'];  // ThemedTokenStyle for the light theme
$lines[0][0]->variants['dark'];   // ThemedTokenStyle for the dark theme

Highlighter::loadGrammar i Highlighter::loadTheme

PHP
public function loadGrammar(
    array $rawTmLanguage,
    ?string $langId = null,
    array $aliases = [],
    array $embedded = [],
): void

public function loadTheme(array $rawTheme): void

Zarejestruj własną gramatykę TextMate lub motyw VS Code z dekodowanego JSON. Zobacz Własne języki i motywy.

Analiza zawartości pakietu

PHP
/** @return list<string> */ public function loadedLanguages(): array
/** @return list<string> */ public function loadedThemes(): array
/** @return list<string> */ public function bundledLanguages(): array
/** @return list<string> */ public function bundledThemes(): array

loadedLanguages/loadedThemes zwracają wszystkie identyfikatory, których można obecnie używać (wbudowane oraz zarejestrowane przez Ciebie). bundledLanguages/bundledThemes zwracają tylko identyfikatory dołączone do pakietu. Zobacz Języki i Motywy.

Obiekty wartości

ThemedToken

Shikiphp\Render\ThemedToken to pojedynczy stylizowany fragment tekstu:

PHP
final class ThemedToken
{
    public readonly string $content;
    public readonly ?string $color;
    public readonly int $fontStyle;      // FontStyle bitmask
    public readonly ?string $bgColor;
    public readonly ?string $htmlStyle;  // pre-built inline style (dual themes / ANSI)
    public readonly int $offset;         // UTF-16 code-unit offset into the source
}

fontStyle to maska bitowa z Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult to wartość zwracana przez codeToTokensResult:

PHP
final class TokensResult
{
    public readonly array $tokens;             // list<list<ThemedToken>>
    public readonly ?string $fg;               // resolved foreground
    public readonly ?string $bg;               // resolved background
    public readonly ?string $themeName;        // single id, or "shiki-themes …"
    public readonly string|false|null $rootStyle; // dual-theme root style (or null)
    public readonly ?GrammarState $grammarState;
}

GrammarState

Shikiphp\GrammarState przechowuje stos reguł tokenizatora (indeksowany nazwą motywu), dzięki czemu podświetlanie można wznowić od pośredniego punktu.

PHP
final class GrammarState
{
    public readonly string $lang;

    public function theme(): string;          // first theme name
    public function themes(): array;          // list<string>
    public function getScopes(?string $theme = null): array; // scopes in effect, innermost first
    public function withTheme(string $theme): self;
}