Lewati ke konten

API

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 22946a5

shikiphp menyediakan dua titik masuk: facade statis Shikiphp untuk kasus umum, dan instance Highlighter untuk kebutuhan lainnya (output HAST, grammar dan tema khusus, varian tema, serta introspeksi bundle).

Facade Shikiphp

Shikiphp\Shikiphp adalah facade statis tipis di atas highlighter bundle yang dibuat secara malas dan di-cache.

Shikiphp::codeToHtml

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

Melakukan tokenisasi $code dan merender blok <pre class="shiki …"> HTML lengkap. Array opsi selalu memuat lang, ditambah salah satu dari theme atau peta themes, serta opsiperenderan apa pun.

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

Mengembalikan grid token 2D mentah (satu daftar bagian dalam per baris) yang berisi objek Shikiphp\Render\ThemedToken, bukan 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

Alias codeToTokens yang sesuai dengan nama codeToTokensBase milik Shiki.

Shikiphp::codeToTokensResult

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

Mengembalikan hasil lengkap yang mencerminkan codeToTokens tingkat teratas milik Shiki: grid token beserta warna yang telah ditentukan, nama tema, gaya root tema ganda, dan status grammar akhir. Lihat TokensResult di bawah.

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

Melakukan tokenisasi $code dan mengembalikan status grammar yang dicapai di akhir (getLastGrammarState milik Shiki). Teruskan kembali melalui opsi grammarState untuk melanjutkan tokenisasi fragmen berikutnya dari status yang sama — berguna untuk penyorotan inkremental. Menghasilkan error jika lang adalah 'ansi' (ANSI tidak memiliki status grammar).

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

Mengembalikan Highlighter bundle bersama, membuatnya saat pertama kali digunakan. Gunakan ini untuk mengakses metode instance di bawah.

Shikiphp::use dan Shikiphp::reset

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

use mengganti instance dengan Highlighter khusus (misalnya, instance yang telah Anda muati dengan grammar atau tema khusus) agar facade meneruskan panggilan kepadanya. reset menghapus instance yang di-cache agar panggilan berikutnya membangun ulang highlighter bundle default.

Highlighter

Shikiphp\Highlighter memiliki cakupan lengkap. Dapatkan instance bundle bersama melalui Shikiphp::highlighter(), atau buat satu instance secara eksplisit:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Ini mengimplementasikan codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult, dan getLastGrammarState dengan signature yang sama seperti facade, serta hal-hal berikut.

Highlighter::codeToHast

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

Membangun pohon HAST Shiki pre.shiki > code > (span.line > span)* yang tepat, siap untuk ditelusuri, diubah, atau diserialisasi sendiri. Inilah yang diserialisasi secara internal oleh 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

Melakukan tokenisasi sekali untuk tiap tema, lalu menggabungkan hasilnya ke dalam variants per token yang dikunci berdasarkan kunci tema, sesuai dengan codeToTokensWithThemes milik Shiki. Memerlukan peta 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 dan Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Daftarkan grammar TextMate khusus atau tema VS Code khusus dari JSON yang telah didekode. Lihat Bahasa dan tema khusus.

Introspeksi bundle

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 melaporkan semua ID yang saat ini dapat digunakan (bawaan bundle ditambah yang Anda daftarkan sendiri). bundledLanguages/bundledThemes hanya melaporkan ID yang disertakan dalam bundle. Lihat Bahasa dan Tema.

Objek nilai

ThemedToken

Shikiphp\Render\ThemedToken adalah satu rentang teks dengan gaya tertentu:

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 adalah bitmask dari Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult adalah nilai kembalian 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 menyimpan tumpukan aturan tokenizer (yang dikunci berdasarkan nama tema) agar penyorotan dapat dilanjutkan dari titik antara.

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