Pereiti prie turinio

API

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: 22946a5

shikiphp pateikia du įėjimo taškus: statinį Shikiphp fasadą įprastiems atvejams ir Highlighter egzempliorių visiems kitiems atvejams (HAST išvestis, pasirinktinės gramatikos ir temos, temų variantai ir paketo apžvalga).

Fasadą Shikiphp

Shikiphp\Shikiphp yra plonas statinis fasadas, apgaubiantis pagal poreikį sukuriamą ir talpykloje laikomą paryškintuvą iš paketo.

Shikiphp::codeToHtml

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

Tokenizuoja $code ir atvaizduoja visą <pre class="shiki …"> HTML bloką. Parinkčių masyve visada yra lang, taip pat arba theme, arba themes žemėlapis ir bet kurios atvaizdavimo parinktys.

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

Grąžina paprastą 2D žetonų tinklelį (po vieną vidinį sąrašą eilutei) iš Shikiphp\Render\ThemedToken objektų, o ne 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 slapyvardis, atitinkantis Shiki pavadinimą codeToTokensBase.

Shikiphp::codeToTokensResult

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

Grąžina išsamų rezultatą, atitinkantį aukščiausio lygio codeToTokens lauką objekte Shiki: žetonų tinklelį, išspręstas spalvas, temos pavadinimą, pagrindinį dviejų temų stilių ir galutinę gramatikos būseną. Žr. toliau 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

Tokenizuoja $code ir grąžina pabaigoje pasiektą gramatikos būseną (Shiki getLastGrammarState). Perduokite ją per parinktį grammarState, kad galėtumėte tęsti vėlesnio fragmento tokenizavimą nuo tos pačios būsenos — tai naudinga paryškinant palaipsniui. Išmeta klaidą, jei lang yra 'ansi' (ANSI gramatikos būsenos neturi).

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

Grąžina bendrą susietą Highlighter ir sukuria jį pirmą kartą panaudojus. Naudokite jį toliau pateiktiems egzemplioriaus metodams pasiekti.

Shikiphp::use ir Shikiphp::reset

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

use pakeičia egzempliorių pasirinktiniu Highlighter (pavyzdžiui, tokiu, į kurį įkėlėte pasirinktas gramatikas ar temas), tad fasadas perduoda užklausas jam. reset išvalo talpykloje esantį egzempliorių, todėl kito iškvietimo metu iš naujo sukuriamas numatytasis paryškintuvas iš paketo.

Highlighter

Shikiphp\Highlighter apima visą sąsają. Bendrinamą egzempliorių iš paketo gaukite naudodami Shikiphp::highlighter() arba sukurkite jį tiesiogiai:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Jis įgyvendina codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult ir getLastGrammarState su tokiomis pačiomis signatūromis kaip fasado, taip pat toliau išvardytus metodus.

Highlighter::codeToHast

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

Sukuria tokį patį pre.shiki > code > (span.line > span)* HAST medį, kokį sukuria Shiki, kad galėtumėte jį patys pereiti, keisti ar serializuoti. Būtent šį medį viduje serializuoja codeToHtml.

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

Po kartą tokenizuoja kiekvienai temai ir sujungia rezultatus į kiekvieno žetono variants, susietą su temos raktu, kaip ir Shiki codeToTokensWithThemes. Reikalingas themes žemėlapis.

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

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

public function loadTheme(array $rawTheme): void

Registruokite pasirinktinę TextMate gramatiką arba VS Code temą iš iškoduoto JSON. Žr. Pasirinktinės kalbos ir temos.

Paketo apžvalga

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 pateikia visus šiuo metu naudojamus ID (įtrauktus į paketą ir jūsų užregistruotus pasirinktinius). bundledLanguages/bundledThemes pateikia tik tuos ID, kurie yra įtraukti į paketą. Žr. Kalbos ir Temos.

Reikšmių objektai

ThemedToken

Shikiphp\Render\ThemedToken yra vienas stilizuotas teksto fragmentas:

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 yra bitų kaukė iš Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult yra codeToTokensResult grąžinama reikšmė:

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 saugo tokenizatoriaus taisyklių steką (sugrupuotą pagal temos pavadinimą), kad paryškinimą būtų galima tęsti nuo tarpinio taško.

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