Gå til indhold

API

Vis som Markdown Rediger på GitHub Dokumentation hos 22946a5

shikiphp har to indgangspunkter: den statiske Shikiphp-facade til de almindelige tilfælde og instansen Highlighter til alt andet (HAST-output, brugerdefinerede grammatikker og temaer, temavarianter samt indsigt i pakken).

Facaden Shikiphp

Shikiphp\Shikiphp er en enkel statisk facade over en bundtet fremhæver, der oprettes efter behov og gemmes i cache.

Shikiphp::codeToHtml

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

Tokeniserer $code og gengiver en komplet <pre class="shiki …"> HTML-blok. Options-arrayet indeholder altid en lang samt enten et theme- eller et themes-kort og alle gengivelses-options.

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

Returnerer det rå 2D-tokenraster (én indre liste pr. linje) med Shikiphp\Render\ThemedToken-objekter i stedet for 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

Et alias for codeToTokens, der svarer til navnet Shikis codeToTokensBase.

Shikiphp::codeToTokensResult

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

Returnerer det omfattende resultat, der afspejler Shikis overordnede codeToTokens: tokenrasteret samt de fastlagte farver, temanavnet, rodtypografien for dobbelte temaer og den endelige grammatiktilstand. Se TokensResult nedenfor.

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

Tokeniserer $code og returnerer grammatiktilstanden ved slutningen (Shikis getLastGrammarState). Send den tilbage via indstillingen grammarState for at fortsætte tokeniseringen af et senere fragment fra samme tilstand — nyttigt til inkrementel fremhævning. Kaster en fejl, hvis lang er 'ansi' (ANSI har ingen grammatiktilstand).

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

Returnerer den delte, bundtede Highlighter og opretter den ved første brug. Brug den til at få adgang til instansmetoderne nedenfor.

Shikiphp::use og Shikiphp::reset

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

use udskifter den aktuelle Highlighter med en brugerdefineret (for eksempel en, du har indlæst brugerdefinerede grammatikker eller temaer i), så facaden videresender kald til den. reset rydder den cachelagrede instans, så næste kald genopbygger standardfremhæveren fra pakken.

Highlighter

Shikiphp\Highlighter indeholder hele funktionsfladen. Hent den delte, bundtede instans med Shikiphp::highlighter(), eller opret en eksplicit:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Den implementerer codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult og getLastGrammarState med samme signaturer som facaden samt følgende.

Highlighter::codeToHast

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

Bygger det pre.shiki > code > (span.line > span)* HAST-træ Shiki bygger, klar til at blive gennemgået, ændret eller serialiseret. Det er det, codeToHtml serialiserer internt.

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

Tokeniserer én gang pr. tema og fletter resultatet til variants pr. token, indekseret efter temanøgle, som afspejler Shikis codeToTokensWithThemes. Kræver et themes-kort.

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 og Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Registrer en brugerdefineret grammatik af typen TextMate eller et tema af typen VS Code fra afkodet JSON. Se Brugerdefinerede sprog og temaer.

Indsigt i pakken

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 viser alle ID'er, der kan bruges i øjeblikket (fra pakken samt brugerdefinerede, som du har registreret). bundledLanguages/bundledThemes viser kun de ID'er, der følger med pakken. Se Sprog og Temaer.

Værdiobjekter

ThemedToken

Shikiphp\Render\ThemedToken er et formateret tekstafsnit:

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 er en bitmaske fra Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult er resultatet fra 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 indeholder tokenizerens regelstak (indekseret efter temanavn), så fremhævning kan fortsætte fra et mellemliggende punkt.

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