Перейти до вмісту

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 і будь-які параметри відображення з розділу параметри.

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

Повертає звичайну двовимірну сітку токенів (один внутрішній список на рядок) з об’єктів 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, що відповідає назві Shiki codeToTokensBase.

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 і повертає стан граматики наприкінці (Shiki для getLastGrammarState). Передайте його назад через опцію 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 pre.shiki > code > (span.line > span)*, яке будує Shiki, готове до обходу, зміни чи самостійної серіалізації. Саме його 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 повертають усі доступні на цей момент ідентифікатори (вбудовані та зареєстровані власноруч). bundledLanguages/bundledThemes повертають лише ідентифікатори, включені до пакета. Див. Мови та Теми.

Об’єкти-значення

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