Pāriet uz saturu

API

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 22946a5

shikiphp piedāvā divus ievades punktus: statisko fasādi Shikiphp biežākajiem lietošanas gadījumiem un instanci Highlighter visam pārējam (HAST izvadei, pielāgotām gramatikām un tēmām, tēmu variantiem un pakotnes satura izpētei).

Fasāde Shikiphp

Shikiphp\Shikiphp ir plāna statiska fasāde, kas nodrošina piekļuvi pēc vajadzības izveidotam kešotam komplektētam iezīmētājam.

Shikiphp::codeToHtml

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

Tokenizē $code un attēlo pilnu <pre class="shiki …"> HTML bloku. Opciju masīvā vienmēr ir lang, kā arī vai nu theme, vai themes karte un jebkura no attēlošanas opcijām.

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

Atgriež vienkāršu 2D tokenu režģi (pa vienam iekšējam sarakstam katrai rindai) ar Shikiphp\Render\ThemedToken objektiem, nevis 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

codeToTokens aizstājvārds ar nosaukumu, kas atbilst Shiki codeToTokensBase nosaukumam.

Shikiphp::codeToTokensResult

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

Atgriež bagātinātu rezultātu, kas atspoguļo Shiki augstākā līmeņa codeToTokens: tokenu režģi, atrisinātās krāsas, tēmas nosaukumu, duālās tēmas saknes stilu un galīgo gramatikas stāvokli. Skatiet tālāk sadaļu 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

Tokenizē $code un atgriež beigās sasniegto gramatikas stāvokli (Shiki getLastGrammarState). Nododiet to tālāk, izmantojot opciju grammarState, lai atsāktu vēlākas daļas tokenizēšanu no tā paša stāvokļa — noderīgi pakāpeniskai iezīmēšanai. Rada izņēmumu, ja lang ir 'ansi' (ANSI nav gramatikas stāvokļa).

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

Atgriež koplietoto komplektēto Highlighter, izveidojot to pirmajā izsaukšanas reizē. Izmantojiet to, lai piekļūtu tālāk aprakstītajām instances metodēm.

Shikiphp::use un Shikiphp::reset

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

use nomaina instanci pret pielāgotu Highlighter (piemēram, tādu, kurā esat ielādējis pielāgotas gramatikas vai tēmas), lai fasāde to izmantotu. reset notīra kešoto instanci, tāpēc nākamais izsaukums no jauna izveido noklusējuma komplektēto iezīmētāju.

Highlighter

Shikiphp\Highlighter nodrošina visu funkcionalitāti. Iegūstiet koplietoto komplektēto instanci ar Shikiphp::highlighter() vai izveidojiet to skaidri norādītā veidā:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Tas īsteno codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult un getLastGrammarState ar tādām pašām parakstu signatūrām kā fasādei, kā arī tālāk minētās iespējas.

Highlighter::codeToHast

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

Izveido pre.shiki > code > (span.line > span)* HAST koku, ko veido Shiki, lai jūs varētu tajā pārvietoties, to mainīt vai serializēt. Tieši šādi codeToHtml to serializē iekšēji.

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

Tokenizē vienreiz katrai tēmai un apvieno rezultātu katra tokena variants, kas indeksēta pēc tēmas atslēgas, atspoguļojot Shiki codeToTokensWithThemes. Nepieciešama themes karte.

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

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

public function loadTheme(array $rawTheme): void

Reģistrējiet pielāgotu TextMate gramatiku vai VS Code tēmu no atkodēta JSON. Skatiet Pielāgotas valodas un tēmas.

Pakotnes satura izpēte

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 ziņo par visiem pašlaik izmantojamajiem ID (komplektētajiem un jūsu reģistrētajiem pielāgotajiem). bundledLanguages/bundledThemes ziņo tikai par komplektācijā iekļautajiem ID. Skatiet sadaļas Valodas un Tēmas.

Vērtību objekti

ThemedToken

Shikiphp\Render\ThemedToken ir viens stilizēts teksta fragments:

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 ir bitu maska no Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult ir codeToTokensResult atgrieztā vērtība:

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 glabā tokenizētāja noteikumu steku (sakārtotu pēc tēmas nosaukuma), lai iezīmēšanu varētu atsākt no starppunkta.

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