Μετάβαση στο περιεχόμενο

API

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο 22946a5

Το shikiphp παρέχει δύο σημεία εισόδου: τη στατική πρόσοψη Shikiphp για τις συνήθεις περιπτώσεις και το στιγμιότυπο Highlighter για όλα τα υπόλοιπα (έξοδο HAST, προσαρμοσμένες γραμματικές και θέματα, παραλλαγές θεμάτων και διερεύνηση πακέτου).

Η πρόσοψη Shikiphp

Το Shikiphp\Shikiphp είναι μια λεπτή στατική πρόσοψη πάνω από ένα αποθηκευμένο επισημαντή που περιλαμβάνεται στο πακέτο και δημιουργείται αργά.

Shikiphp::codeToHtml

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

Κατακερματίζει το $code και αποδίδει ένα πλήρες block <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

Επιστρέφει το βασικό δισδιάστατο πλέγμα διακριτικών (μία εσωτερική λίστα ανά γραμμή) από αντικείμενα 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 με τις ίδιες υπογραφές με το facade, καθώς και τα εξής.

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

Δημιουργεί τα token μία φορά ανά θέμα και συγχωνεύει το αποτέλεσμα σε variants ανά token, με κλειδί το όνομα του θέματος, όπως και το Shiki codeToTokensWithThemes. Απαιτεί map 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. Δείτε Προσαρμοσμένες γλώσσες και θέματα.

Επισκόπηση του 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 εμφανίζουν κάθε διαθέσιμο 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 είναι μάσκα bit από το 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 περιέχει τη στοίβα κανόνων του tokenizer (με κλειδί το όνομα του θέματος), ώστε να μπορεί να συνεχιστεί η επισήμανση από ένα ενδιάμεσο σημείο.

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