Перейти к содержимому

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 и возвращает состояние грамматики на его конце (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 для каждого токена, сгруппированные по ключу темы, как в Shiki codeToTokensWithThemes. Требуется карта 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;
}