Към съдържанието

API

Преглед като Markdown Редактиране в GitHub Документация за 22946a5

shikiphp предоставя две входни точки: статичната фасада Shikiphp за обичайните случаи и екземпляра Highlighter за всичко останало (изход HAST, персонализирани граматики и теми, варианти на теми и проверка на съдържанието на пакета).

Фасадата Shikiphp

Shikiphp\Shikiphp е тънка статична фасада върху създаван при нужда кеширан осветител на синтаксис от пакета.

Shikiphp::codeToHtml

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

Токенизира $code и изобразява пълен блок <pre class="shiki …"> HTML. Масивът с опции винаги съдържа lang, както и карта theme или themes, плюс всяка от опциите за изобразяване 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

Връща голата 2D мрежа от токени (по един вътрешен списък на ред) от обекти Shikiphp\Render\ThemedToken вместо 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, съответстващ на името codeToTokensBase на Shiki.

Shikiphp::codeToTokensResult

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

Връща богат резултат, съответстващ на най-горното codeToTokens на Shiki: мрежата от токени заедно с разрешените цветове, името на темата, кореновия стил за две теми и крайното състояние на граматиката. Вижте 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

Токенизира $code и връща състоянието на граматиката в края (getLastGrammarState на Shiki). Подайте го обратно чрез опцията grammarState, за да продължите токенизирането на следващ фрагмент от същото състояние — полезно за постепенно оцветяване. Извежда грешка, ако lang е 'ansi' (ANSI няма състояние на граматиката).

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

Връща споделения обединен Highlighter, като го създава при първо използване. Използвайте го за достъп до методите на екземпляра по-долу.

Shikiphp::use и Shikiphp::reset

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

use заменя персонализирания Highlighter (например такъв, в който сте заредили персонализирани граматики или теми), така че фасадата да го използва. reset изчиства кеширания екземпляр, за да създаде следващото извикване осветителя на синтаксис по подразбиране от пакета.

Highlighter

Shikiphp\Highlighter предоставя пълния интерфейс. Вземете споделения екземпляр от пакета чрез Shikiphp::highlighter() или създайте свой изрично:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Той реализира codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult и getLastGrammarState със същите сигнатури като фасадата, плюс следното.

Highlighter::codeToHast

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

Изгражда дървото HAST Shiki, което създава pre.shiki > code > (span.line > span)*, готово за обхождане, промяна или сериализация от вас. Това сериализира вътрешно 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

Токенизира веднъж за всяка тема и обединява резултата в variants за всеки токен, индексиран по ключа на темата, както прави codeToTokensWithThemes на Shiki. Изисква карта 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 и Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Регистрира персонализирана граматика на TextMate или тема на VS Code от декодиран JSON. Вижте Персонализирани езици и теми.

Проверка на съдържанието на пакета

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 показват всички ID, които могат да се използват в момента (включени в пакета и всички регистрирани от вас). bundledLanguages/bundledThemes показват само ID-тата, включени в пакета. Вижте Езици и Теми.

Обекти със стойности

ThemedToken

Shikiphp\Render\ThemedToken е един стилизиран откъс текст:

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 е битова маска от Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult е върнатата стойност на 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 съхранява стека с правила на токенизатора (индексиран по име на тема), за да може оцветяването да продължи от междинна точка.

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