Treci la conținut

API

Vizualizați ca Markdown Editați pe GitHub Documentație la 22946a5

shikiphp oferă două puncte de intrare: fațada statică Shikiphp pentru cazurile obișnuite și instanța Highlighter pentru orice altceva (ieșire HAST, gramatici și teme personalizate, variante de teme și inspectarea pachetului).

Fațada Shikiphp

Shikiphp\Shikiphp este o fațadă statică simplă peste un highlighter inclus în pachet, creat la cerere și păstrat în cache.

Shikiphp::codeToHtml

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

Tokenizează $code și redă un bloc <pre class="shiki …"> HTML complet. Tabloul de opțiuni include întotdeauna un lang, plus fie theme, fie o mapare themes și oricare dintre opțiunile de redare.

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

Returnează grila de tokenuri 2D simplă (o listă internă pentru fiecare linie) de obiecte Shikiphp\Render\ThemedToken în loc de 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

Un alias pentru codeToTokens, cu același nume ca Shiki codeToTokensBase.

Shikiphp::codeToTokensResult

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

Returnează rezultatul detaliat, care reflectă codeToTokens de nivel superior din Shiki: grila de tokenuri, culorile rezolvate, numele temei, stilul rădăcină pentru tema duală și starea finală a gramaticii. Consultați TokensResult mai jos.

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

Tokenizează $code și returnează starea gramaticii la final (getLastGrammarState Shiki). Transmiteți-o din nou prin opțiunea grammarState pentru a relua tokenizarea unui fragment ulterior din aceeași stare — util pentru evidențiere incrementală. Generează o excepție dacă lang este 'ansi' (ANSI nu are stare gramaticală).

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

Returnează Highlighter comun inclus în pachet, creându-l la prima utilizare. Folosiți-l pentru a accesa metodele instanței de mai jos.

Shikiphp::use și Shikiphp::reset

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

use înlocuiește instanța cu un Highlighter personalizat (de exemplu, unul în care ați încărcat gramatici sau teme personalizate), astfel încât fațada să îi delege operațiile. reset șterge instanța din cache, pentru ca următorul apel să reconstruiască highlighterul implicit inclus în pachet.

Highlighter

Shikiphp\Highlighter oferă întreaga interfață. Obțineți instanța comună inclusă în pachet cu Shikiphp::highlighter() sau creați una explicit:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Implementează codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult și getLastGrammarState cu aceleași semnături ca fațada, plus următoarele.

Highlighter::codeToHast

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

Construiește arborele HAST pre.shiki > code > (span.line > span)* Shiki, gata să îl parcurgeți, modificați sau serializați. Acesta este arborele pe care codeToHtml îl serializează intern.

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

Tokenizează o dată pentru fiecare temă și combină rezultatul într-o structură variants per token, indexată după cheia temei, după modelul Shiki codeToTokensWithThemes. Necesită o mapare 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

Înregistrați o gramatică TextMate personalizată sau o temă VS Code din JSON decodat. Consultați Limbi și teme personalizate.

Inspectarea pachetului

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 raportează toate ID-urile utilizabile în prezent (incluse în pachet și personalizate, dacă ați înregistrat). bundledLanguages/bundledThemes raportează doar ID-urile incluse în pachet. Consultați Limbi și Teme.

Obiecte valoare

ThemedToken

Shikiphp\Render\ThemedToken este o secvență de text cu un singur stil:

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 este o mască de biți din Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult este valoarea returnată de 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 păstrează stiva de reguli a tokenizerului, indexată după numele temei, pentru ca evidențierea să poată fi reluată dintr-un punct intermediar.

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;
}