İçeriğe geç

API

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 22946a5

shikiphp iki giriş noktası sunar: yaygın durumlar için statik Shikiphp arayüzü ve diğer her şey (HAST çıktısı, özel dilbilgileri ve temalar, tema varyantları ve paket incelemesi) için Highlighter örneği.

Shikiphp arayüzü

Shikiphp\Shikiphp, tembel oluşturulan ve önbelleğe alınan paketlenmiş bir vurgulayıcının ince bir statik arayüzüdür.

Shikiphp::codeToHtml

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

$code belirteçlere ayırır ve eksiksiz bir <pre class="shiki …"> HTML bloğu oluşturur. Seçenekler dizisi her zaman bir lang ve ayrıca bir theme veya themes eşlemesi ile isteğe bağlı oluşturma seçeneklerini içerir.

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

HTML yerine Shikiphp\Render\ThemedToken nesnelerinden oluşan yalın 2B belirteç ızgarasını (her satır için bir iç liste) döndürür.

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

Shiki'ın codeToTokensBase adıyla eşleşen codeToTokens diğer adı.

Shikiphp::codeToTokensResult

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

Shiki üst düzey codeToTokens nesnesini yansıtan zengin sonucu döndürür: belirteç ızgarası ile çözümlenmiş renkler, tema adı, çift tema kök stili ve son dilbilgisi durumu. Aşağıdaki TokensResult bölümüne bakın.

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 belirteçlere ayırır ve son noktada ulaşılan dilbilgisi durumunu (Shiki'ın getLastGrammarState değerini) döndürür. Daha sonraki bir parçayı aynı durumdan belirteçlere ayırmaya devam etmek için grammarState seçeneğiyle geri verin; bu, artımlı vurgulamada işe yarar. lang değeri 'ansi' ise hata verir (ANSI'de dilbilgisi durumu yoktur).

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

Paylaşılan paketlenmiş Highlighter öğesini, ilk kullanımda oluşturarak döndürür. Aşağıdaki örnek yöntemlere erişmek için bunu kullanın.

Shikiphp::use ve Shikiphp::reset

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

use, özel bir Highlighter örneğini devreye alarak arayüzün ona yönlendirme yapmasını sağlar (örneğin, özel dilbilgileri veya temalar yüklediğiniz bir örnek). reset, önbelleğe alınmış örneği temizler; böylece bir sonraki çağrıda varsayılan paketlenmiş vurgulayıcı yeniden oluşturulur.

Highlighter

Shikiphp\Highlighter, tüm özellikleri sunar. Paylaşılan paketlenmiş örneği Shikiphp::highlighter() ile alın veya açıkça bir örnek oluşturun:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Aynı imzalarla codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult ve getLastGrammarState uygular; ayrıca aşağıdakileri sunar.

Highlighter::codeToHast

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

Shiki tarafından oluşturulan pre.shiki > code > (span.line > span)* HAST ağacını, üzerinde gezinmeye, değiştirmeye veya serileştirmeye hazır şekilde oluşturur. codeToHtml içeride bunu serileştirir.

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

Her tema için bir kez belirteçlere ayırır ve sonucu tema anahtarına göre anahtarlanmış belirteç başına variants içinde birleştirerek Shiki'ın codeToTokensWithThemes değerini yansıtır. Bir themes eşlemesi gerekir.

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

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

public function loadTheme(array $rawTheme): void

Çözümlenmiş JSON içinden özel bir TextMate dilbilgisi veya VS Code teması kaydedin. Özel diller ve temalar bölümüne bakın.

Paket incelemesi

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 şu anda kullanılabilen tüm kimlikleri (paketlenmiş olanlar ve kaydettiğiniz özel kimlikler dâhil) bildirir. bundledLanguages/bundledThemes ise yalnızca pakete dâhil gelen kimlikleri bildirir. Diller ve Temalar bölümlerine bakın.

Değer nesneleri

ThemedToken

Shikiphp\Render\ThemedToken, biçimlendirilmiş bir metin parçasıdır:

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 içinden gelen bir bit maskesidir (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult, codeToTokensResult çağrısının dönüş değeridir:

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, vurgulamanın ara bir noktadan devam edebilmesi için belirteç ayırıcının kural yığınını (tema adına göre anahtarlanmış) tutar.

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