Siirry sisältöön

API

Näytä Markdown-muodossa Muokkaa palvelussa GitHub Dokumentaatio: 22946a5

shikiphp tarjoaa kaksi sisääntulokohtaa: staattisen Shikiphp-julkisivun yleisiin tapauksiin ja Highlighter-instanssin kaikkeen muuhun (HAST-tuloste, mukautetut kieliopit ja teemat, teemamuunnelmat sekä paketin sisällön tarkastelu).

Shikiphp-julkisivu

Shikiphp\Shikiphp on kevyt staattinen julkisivu, jonka taustalla on laiskasti luotu ja välimuistiin tallennettu pakettiin kuuluva korostin.

Shikiphp::codeToHtml

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

Tokenisoi $code-sisällön ja muodostaa kokonaisen <pre class="shiki …"> HTML-lohkon. Asetustaulukossa on aina lang sekä joko theme tai themes-kartta ja mitkä tahansa piirtoasetuksista asetukset.

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

Palauttaa pelkän 2D-tunnisteiden ruudukon (yksi sisäkkäinen luettelo riviä kohti) muodossa Shikiphp\Render\ThemedToken-oliot eikä muodossa 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-nimen alias, joka vastaa Shiki-kohteen nimeä codeToTokensBase.

Shikiphp::codeToTokensResult

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

Palauttaa kattavan tuloksen, joka vastaa kohteen Shiki ylätason codeToTokens-arvoa: tokeniruudukon sekä ratkaistut värit, teeman nimen, kaksoisteeman juurityylin ja lopullisen kielioppitilan. Katso TokensResult alta.

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

Tokenisoi $code-sisällön ja palauttaa lopussa saavutetun kielioppitilan (Shiki-kohteen getLastGrammarState). Anna se takaisin grammarState-asetuksen kautta, jotta myöhempi katkelma tokenisoidaan samasta tilasta jatkaen — hyödyllistä inkrementaalisessa korostuksessa. Heittää virheen, jos lang on 'ansi' (ANSI-tilassa ei ole kielioppitilaa).

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

Palauttaa jaetun pakettiin kuuluvan Highlighter-korostimen ja luo sen ensimmäisellä käyttökerralla. Käytä tätä päästäksesi alla oleviin instanssimetodeihin.

Shikiphp::use ja Shikiphp::reset

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

use vaihtaa tilalle mukautetun Highlighter-instanssin (esimerkiksi sellaisen, johon olet ladannut mukautettuja kielioppeja tai teemoja), jolloin julkisivu delegoi kutsut sille. reset tyhjentää välimuisti-instanssin, jotta seuraava kutsu rakentaa oletusarvoisen pakettiin kuuluvan korostimen uudelleen.

Highlighter

Shikiphp\Highlighter tarjoaa koko rajapinnan. Hae jaettu pakettiin kuuluva instanssi komennolla Shikiphp::highlighter() tai rakenna sellainen itse:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Se toteuttaa codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult ja getLastGrammarState samalla allekirjoituksella kuin julkisivu sekä seuraavat ominaisuudet.

Highlighter::codeToHast

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

Rakentaa pre.shiki > code > (span.line > span)*n HAST-puun, jonka Shiki rakentaa, valmiina itse läpikäytäväksi, muokattavaksi tai sarjoitettavaksi. Tätä codeToHtml sarjoittaa sisäisesti.

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

Tokenisoi kerran teemaa kohti ja yhdistää tuloksen tokenikohtaiseksi variants-rakenteeksi, jonka avaimina ovat teema-avaimet ja joka vastaa Shiki-kohteen codeToTokensWithThemes-rakennetta. Edellyttää themes-karttaa.

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

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

public function loadTheme(array $rawTheme): void

Rekisteröi mukautettu TextMate-kielioppi tai VS Code-teema dekoodatusta JSON-sisällöstä. Katso Mukautetut kielet ja teemat.

Paketin sisällön tarkastelu

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 luettelevat kaikki parhaillaan käytettävissä olevat tunnukset (pakettiin kuuluvat ja rekisteröimäsi mukautetut). bundledLanguages/bundledThemes luettelevat vain toimitettuun pakettiin kuuluvat tunnukset. Katso Kielet ja Teemat.

Arvo-oliot

ThemedToken

Shikiphp\Render\ThemedToken on yksi tyylitelty tekstijakso:

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 on bittimaski, jonka arvot ovat Shikiphp\Theme\FontStyle-joukosta (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult on metodin codeToTokensResult palautusarvo:

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 tallentaa jäsentimen sääntöpinoon (teeman nimen mukaan), jotta korostusta voidaan jatkaa välikohdasta.

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