# 选项

所有入口点（`codeToHtml`、`codeToTokens`、`codeToTokensResult`、`codeToHast`）的第二个参数都是相同的选项数组。只需要 `lang` 和主题。

## `lang`

**必填。** 要用于分词的语言 id 或别名——`php`、`ts`、`js`、`rust`、`python`、`html` 等。特殊值 `'ansi'` 会高亮终端转义序列，而不使用语法（参见 [ANSI](https://shikiphp.inline0.dev/zh/docs/ansi)）。

```php
['lang' => 'php']
```

## `theme`

单个主题 id。必填，除非提供了 `themes`。

```php
['lang' => 'php', 'theme' => 'github-dark']
```

## `themes`

主题 id 映射表，用于通过 CSS 变量生成双主题（或多主题）输出。除非提供了 `theme`，否则必填。

```php
['lang' => 'ts', 'themes' => ['light' => 'github-light', 'dark' => 'github-dark']]
```

## `defaultColor`

`themes` 中哪个键会成为内联默认颜色（其他键将成为 `--shiki-<key>` CSS 变量）。默认为 `'light'`。设为 `false` 时只输出变量，不设内联默认值——适合通过 CSS 控制所有颜色的情况。

```php
['themes' => ['light' => '…', 'dark' => '…'], 'defaultColor' => 'dark']
```

## `transformers`

在处理流程中应用的 `Shikiphp\Transformer\Transformer` 对象列表。参见 [转换器](https://shikiphp.inline0.dev/zh/docs/transformers)。

```php
use Shikiphp\Transformer\Notation\NotationHighlight;

['transformers' => [new NotationHighlight()]]
```

## `decorations`

按行/字符位置将类或属性应用于源代码中的任意范围。每个装饰都为 `{start, end, properties}`，位置采用 `{line, character}`（从零开始）索引。

```php
['decorations' => [
    [
        'start'      => ['line' => 0, 'character' => 0],
        'end'        => ['line' => 0, 'character' => 5],
        'properties' => ['class' => 'highlight'],
    ],
]]
```

## `colorReplacements`

重新映射输出中的颜色。字符串条目会全局替换颜色；以主题名称为键的嵌套条目仅作用于该主题。

```php
['colorReplacements' => [
    '#ffffff'      => '#f8f8f2',          // global
    'github-dark'  => ['#24292e' => '#000'], // only in github-dark
]]
```

## `structure`

`'classic'`（默认）会输出完整的 `pre > code > span.line > span` 结构。
`'inline'` 只输出带换行符的令牌跨度，不使用外层 `pre`/`code`——适用于内联片段。

```php
['structure' => 'inline']
```

## `tabindex`

`<pre>` 元素上的 `tabindex` 属性。默认为 `0`。传入 `false` 可将其省略。

```php
['tabindex' => false]
```

## `cssVariablePrefix`

双主题 CSS 变量所用的前缀。默认为 `'--shiki-'`。

```php
['cssVariablePrefix' => '--my-']
```

## `mergeWhitespaces`

控制空白令牌的处理方式。`true`（默认）会将仅含空白的令牌并入后续令牌；`'never'` 会将每个令牌的前导和尾随空白拆分为独立令牌；`false` 则保持令牌不变。

```php
['mergeWhitespaces' => 'never']
```

## `tokenizeMaxLineLength`

达到此长度或更长的行将跳过分词（并输出单个纯文本令牌），长度单位为 UTF-16 代码单元。默认不设限制。此设置可防止处理异常的超长单行输入。

```php
['tokenizeMaxLineLength' => 1000]
```

## `meta`

通过转换器上下文传递给转换器的任意元数据——例如由 [`MetaHighlight`](https://shikiphp.inline0.dev/zh/docs/transformers#metahighlight) 和 [`MetaWordHighlight`](https://shikiphp.inline0.dev/zh/docs/transformers#metawordhighlight) 使用的代码围栏元字符串。

```php
['meta' => ['__raw' => '{1,3-5}']]
```

## `grammarState`

用于恢复分词的 `Shikiphp\GrammarState`（来自 `getLastGrammarState`）。随状态传递的 `lang` 和 theme(s) 必须匹配。参见 [`getLastGrammarState`](https://shikiphp.inline0.dev/zh/docs/api#shikiphpgetlastgrammarstate)。